<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Anthony Kleine on Medium]]></title>
        <description><![CDATA[Stories by Anthony Kleine on Medium]]></description>
        <link>https://medium.com/@tomysshadow?source=rss-2f7e0af662a3------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/2*wtFUKNnS_-g9lK78UuMQWw.png</url>
            <title>Stories by Anthony Kleine on Medium</title>
            <link>https://medium.com/@tomysshadow?source=rss-2f7e0af662a3------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 13:21:06 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@tomysshadow/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Fixing the Loading in Myst IV: Revelation (Part 2)]]></title>
            <link>https://medium.com/@tomysshadow/fixing-the-loading-in-myst-iv-revelation-part-2-2882cf5f50a5?source=rss-2f7e0af662a3------2</link>
            <guid isPermaLink="false">https://medium.com/p/2882cf5f50a5</guid>
            <category><![CDATA[videogames]]></category>
            <category><![CDATA[cpp-programming]]></category>
            <category><![CDATA[myst]]></category>
            <category><![CDATA[hacking]]></category>
            <category><![CDATA[graphics-programming]]></category>
            <dc:creator><![CDATA[Anthony Kleine]]></dc:creator>
            <pubDate>Sat, 07 Dec 2024 21:39:05 GMT</pubDate>
            <atom:updated>2025-05-26T14:15:34.570Z</atom:updated>
            <content:encoded><![CDATA[<p>This is a continuation of the story of how I fixed the loading in Myst IV: Revelation. If you haven’t read <a href="https://medium.com/@tomysshadow/fixing-the-loading-in-myst-iv-revelation-86e2814afbf8">Part 1</a> yet, please go and read that first.</p><h3>Image Loading Rewrite</h3><p>So, I had the idea to try and load the image directly into the buffer where it was intended to go. Still, if something as basic as a memcpy was the main slowdown, I knew margins were going to be tight. I was going to need a fast image library.</p><h4>The Requirements</h4><p>LEADTOOLS is the third party image library that Myst IV uses, but it’s not used directly. Rather, Myst IV has a custom wrapper around it called Gfx Tools. Gfx Tools is a small 124 KB DLL, and most of the important functions are exported meaning they have names to aid in the reverse engineering.</p><p>I felt that it would be a better idea to insert my replacement on the level of Gfx Tools rather than trying to replicate the LEADTOOLS API, which would’ve inherently locked me into loading the image row by row and copying the data unnecessarily, both things I wanted to avoid.</p><p>By inspecting the DLL imports for Gfx Tools, I could see that it also imported <a href="https://www.leadtools.com/help/sdk/v21/main/api/l-sizebitmap.html">L_SizeBitmap</a> from LEADTOOLS. This meant that in addition to loading, I was also going to need the ability to resize images. At this point in time, I was not yet sure in what scenario Gfx Tools would resize an image, I only knew that it could.</p><p>Bizarrely, I also saw that Gfx Tools implemented saving images. The method that did so was in a vtable, so I couldn’t easily see if anything else in the game used it, and it was a public method. So, I decided I would have to implement saving just in case (which turned out to be necessary, as we’ll see later.)</p><p>At this point, I had a slightly weird set of requirements for the image library:</p><ul><li>it needed to be fast (this is the obvious one)</li><li>I needed to be able to link it to my C++ program (so no Python, Java, etc.)</li><li>it needed to support all the image formats the game used: JPEG, PNG and Targa</li><li>it needed to be able to load images directly into my buffer, not allocate one by itself (because that’s the whole point)</li><li>it needed to work on x86, because this is an x86 game. If a library was x64 only it was out of the question</li><li>not only did it need to work for x86, it needed to be optimized for it. Several libraries I found would compile for x86 but only had fast SIMD code for x64</li><li>I needed the ability to load images as 8-bit luminance for masks</li><li>I needed to be able to resize images (ideally a bilinear resize, since that would match what Myst IV does)</li><li>I needed the ability to save images</li></ul><h4>Choosing an Image Library</h4><p>Now I’m not a graphics programmer, so I actually had no idea what would be conventional to use for this purpose. I knew that choosing the right library would be absolutely essential to what I wanted to do, and that hollow claims a library is “fast” by some guy in marketing was not enough here.</p><p>So I tried the naive thing first, and simply Googled for “fast image library” to see what would come up. I would pit anything I found claiming to be fast against each other in a test. After all, there was no point in going to all this effort of replacing the image loading code if I couldn’t actually load the same number of images faster. I set up a test where I took all of the images for a particular screen in the game (about 500 images total, all around 128x128 in size,) read them all into memory, then saw how fast they could be decoded and resized with whatever library I was testing.</p><p>The first library I tried was the one I kept seeing mentioned over and over as being the fastest, <a href="https://www.libvips.org/">VIPS.</a> According to <a href="https://github.com/libvips/libvips/wiki/Speed-and-memory-use">their own benchmark,</a> VIPS is faster than many other image libraries, including ImageMagick, the only one I was previously familiar with. It also supports resizing. So I added it to my benchmark.</p><p>With VIPS, it took almost a full second to load and resize the images — not nearly good enough. This was surprising to me, considering how fast it was touted to be. To my knowledge I wasn’t doing anything that would’ve hampered it — I was building for Release mode, and even used the method the documentation recommended as the fastest, <a href="https://www.libvips.org/API/current/libvips-resample.html#vips-thumbnail-buffer">vips_thumbnail_buffer.</a></p><blockquote>Shrinking is done in three stages: using any shrink-on-load features available in the file import library, using a block shrink, and using a lanczos3 shrink. At least the final 200% is done with lanczos3. The output should be high quality, and the operation should be quick.</blockquote><p>VIPS seemingly uses the same pattern as LEADTOOLS, expecting you to copy the data off of its VipsImage object with vips_image_write_to_memory, when what I really wanted was to just acquire ownership of it. Now, I can’t say for certain this is why I experienced slowness, because the creator of VIPS alludes to the idea that the image is only processed when you get its data so actually there is no redundant copy.</p><p>At the end of the day I’m unsure why it was so slow, I only know that it wasn’t even in the ballpark I needed it to be in. Maybe it’s because it uses Lanczos which is kind of overkill for what I need (but <a href="https://www.libvips.org/API/current/libvips-resample.html#vips-affine">vips_affine</a> with bilinear interpolation wasn’t significantly faster,) or maybe it just doesn’t like MSVC. In any case, VIPS was a no go, and that also disqualifies the other libraries that were slower than it in their benchmark.</p><p>Next I tried a library Matt recommended to me, <a href="https://github.com/nothings/stb">STB.</a> This is apparently a pretty commonplace image library for gamedev, and it supports loading, saving and resizing. Sounds fit for the purpose, so I added it to my test. It took a total of 300 milliseconds, which is certainly an improvement, but would still be a noticeable delay. However, nearly all of that time was being spent on resizing. Removing that requirement made it take 60 milliseconds, which would be quite reasonable (that’s about four frames at 60 FPS.)</p><p>I knew I could expect resizing to take some amount of time, so I still wanted to squeeze down the loading time as much as possible to allow more time for resizing, but at this point I decided not to worry about resizing for now and to find a separate fast resizing library later.</p><p>However, not taken into account in this time is the fact that STB needs to allocate the buffer itself. It cannot load an image into an existing buffer, defeating the purpose. The owner’s suggestion is to <a href="https://github.com/nothings/stb/issues/372">just do a memcpy,</a> which is how we got in this mess in the first place and is not an acceptable solution here.</p><p>Next, I discovered a blog post claiming <a href="https://blog.gibson.sh/2015/03/23/comparing-performance-stb_image-vs-libjpeg-turbo-libpng-and-lodepng/">STB was slower</a> than using <a href="http://www.libpng.org/pub/png/libpng.html">libpng</a> and <a href="https://libjpeg-turbo.org/">libjpeg-turbo</a> directly. libpng and libjpeg are the standard, official reference libraries for reading PNG and JPEG. Given, this is a ten year old blog post so it was entirely possible it was outdated information, and I also kind of wanted to avoid writing bespoke code for every format, but I could resort to that if I had to. So, I tested.</p><p>[I didn’t bother testing Targa, as there are only a couple Targa images in the game anyway, so while it needed to be supported it wasn’t priority.]</p><p>For libjpeg-turbo, this turned out to be true. It took about 45 milliseconds to load all of the images, which is properly fast (over ten images per millisecond!) For libpng however (performing the same test but with all the images converted to PNG now) it was significantly slower than STB. Either STB has gotten faster in new versions, or libpng has gotten slower, or both.</p><p>Then, while trying to figure out if I had somehow made a mistake that would make libpng slower, I ran across yet another library claiming to be the fastest kid on the block: <a href="https://nigeltao.github.io/blog/2021/fastest-safest-png-decoder.html">wuffs</a> by Nigel Tao, the image library used by Google Chrome. Interestingly, a big performance increase Tao cites is decoding the entire image at once instead of row by row, so it turns out there is actual evidence to back what I had anecdotally experienced was slower.</p><p>wuffs did not end up being of much use to me. While it could be compiled for x86, it was only optimized for x64, disqualifying it for my purpose. I also couldn’t get it to load a JPEG, even though it claimed to be able to, and the fact it was transpiled from a custom scripting language made it difficult to debug why.</p><p>However, it was while reading through a Reddit thread discussing wuffs that I discovered the library I decided to actually use, a relatively new and little known library called <a href="https://github.com/t0rakka/mango">mango.</a></p><p>It was perfect: it supported a plethora of formats, including luminance formats, and had SIMD support on x86. While its basic Bitmap class allocates its own buffer, you can opt to instead use its more advanced Surface class, which provides the ability to specify your own output buffer.</p><p>Most importantly, it was insanely fast, outpacing both STB and libpng for PNG and on par with libjpeg-turbo for JPEG. It likely would’ve been even faster on x64, where it can use AVX, but that instruction set simply doesn’t exist on x86 so we settle for SSE4, the fastest we can get there. Even with this crutch, it still outperforms any other library I tried. So mango was the obvious pick.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/894/1*HUEKnLqh94zhu1gMPf3UFg.jpeg" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/894/1*ZeprLCNH1IxWf5_-1Q0MLw.jpeg" /><figcaption>mango’s own benchmarks reveal that it is capable of loading images at mind-boggling speeds.</figcaption></figure><p>The only thing it didn’t have was resizing — while it had a blitter, it could only do what is essentially the equivalent of a BitBlt, not a StretchBlt, so I still needed some other library for resizing.</p><p>Thankfully in this case my work was cut out for me: I discovered a semi-recent (2019) blog called <a href="https://hpjansson.org/blag/2019/07/08/image-scaling-on-the-cpu/">Battle of the Bilerps,</a> wherein various resizing libraries are compared in terms of speed. The blog is ostensibly meant to promote the author’s own resizing solution, called smolscale, but it is not well fit for my use case for a couple reasons: it can only resize 24 and 32-bit images when I needed support for 8-bit luminance, and by his own admission it is not optimized for x86.</p><p>So, I went with his second place pick, which was <a href="https://www.pixman.org/">Pixman.</a> The blog author mentioned having miscoloured pixels near the edges of the image in the resized result, but I think that might just be because he forgot to use PIXMAN_REPEAT_PAD as the repeat mode, as is evident from looking at his test code. ;)</p><p>Pixman expects that the image data is already loaded into memory — it has no method of loading it from image files. So, I knew I was going to have to use it in combination with mango.</p><h4>Keeping mango and Pixman Happy</h4><p>Picking a fast library is one thing, but ensuring your use of that library is optimal is another. The next thing I did was to determine the best way to use the two libraries together.</p><p>Both mango and Pixman support several different colour formats. This means, for instance, that even if the game requests a BGRA image, I could load, resize, and blit it as BGRA, or I could load it as RGBA with mango, then have Pixman resize it as an RGBA image, but blit it to BGRA. Similarly, for 8-bit luminance images, I could load the image as an 8-bit image with mango, then have Pixman resize it and blit it as an 8-bit image, keeping it 8-bit all the way through. But I could instead load it as 32-bit with mango, then have Pixman resize it as 32-bit but blit it to an 8-bit result.</p><p>I wanted to know if these kinds of details mattered for performance. What was the rule? Well, as it turns out, both mango and Pixman have certain requirements that must be met for them to be at their fastest. These requirements initially seem to be at odds with each other, but with a little cleverness can be made compatible.</p><p><strong>For mango:</strong> mango provides a suggested “direct” format that it really wants you to use — usually RGBA, but sometimes BGRA, depending on the underlying format of the image. If you use the suggested format, mango will be able to directly copy the data to you, which is the fastest path. However, if you don’t use the suggested format, it will need to first decode the image and secondly blit it to the format you requested. This is a huge performance hit with mango, taking up to roughly 1.5x as long as if it were loaded direct.</p><p><strong>For Pixman:</strong> Pixman always likes to operate in BGRA or BGRX.* Resizing any other source format (such as RGBA, or using 8-bit luminance images as the input) is significantly slower, as it must first perform its own internal conversion to BGRA. However, the destination format does not seem to have as much of an impact.</p><p>At first glance, it seems we cannot always satisfy both. mango usually wants to use RGBA, sometimes BGRA, but Pixman always wants BGRA. The key realization is that for the purpose of resizing an image bilinearly, the colour order doesn’t actually matter.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/622/1*SJXigCiqPlKFVjV1iwuWQA.jpeg" /><figcaption>A table illustrating the formats used for each resize. Because the colour order doesn’t matter for the resize, we can tell Pixman an RGBA image is “BGRA,” so that it doesn’t need to perform its own conversion, saving time.</figcaption></figure><p>The red channel value of one pixel will be interpolated to the red channel value of the next, the green channel to the next green channel, the blue to the next blue and the alpha to the next alpha. The exact same operation is done to each channel, so it does not matter that what Pixman believes is red is actually red. The only time the colour order would matter is if we were compositing two images of different formats, but we are not. So, we can simply “lie” to Pixman and tell it our images are always BGRA. Then it doesn’t need to do its own conversion, and it produces the exact same result, but is much faster.</p><p>For the luminance format, mango can be convinced into loading them in XXXL format — that is, to put the luminance channel where alpha normally would be, and leave the RGB channels alone. This does mean that mango cannot import the format direct, but this is still faster than giving Pixman 8-bit data. Then we tell Pixman it is BGRA, but set the destination format as alpha only. Pixman resizes the image as if it were BGRA, then discards all but the “alpha” channel, leaving only the 8-bit luminance.</p><p><strong><em>*</em></strong><em>mango uses the byte array convention for colour formats, such that RGBA can be imagined as a byte array where the first element is the R channel, the second is the G channel, and so on — so endianness has no impact on the order. Pixman uses the packed pixels convention for colour formats, where each channel is expressed as if they were within a 32-bit integer and accessed by bitshift operations, so they are written “backwards” because they are little endian. I’ve decided to stick with mango’s byte array convention for everything here, and to assume the processor is little endian since I only care about x86 for this project.</em></p><h4>Go Forth and Premultiply</h4><p>Something that the Battle of the Bilerps blog mentioned is that Pixman only operates on premultiplied data. What does “premultiplied” mean? I had no idea, but since I was using Pixman I was going to have to deal with it.</p><p>I was brought up to speed by a blog called <a href="https://www.realtimerendering.com/blog/gpus-prefer-premultiplication/">GPUs prefer premultiplication,</a> explaining the conundrum and why premultiplication is sometimes necessary to resize images. I will briefly summarize that blog here.</p><p>As you likely already know, 32-bit images have four channels: R, G, B, and A, which are for red, green, blue and alpha respectively. The alpha channel controls how transparent parts of the image are. If alpha is zero, that part of the image is fully transparent.</p><p>What is a bit unintuitive is that, even if a pixel is fully transparent, it still has R, G and B channels. So a pixel can be transparent black (0, 0, 0, 0) or transparent white (255, 255, 255, 0) or transparent red (255, 0, 0, 0.) It doesn’t really matter because they are fully transparent, so you can’t see the colour anyway. But if you turned the alpha up for that pixel, it’d reveal the colour.</p><p>To demonstrate how this can cause problems, let’s look at what could happen if we resize an image without premultiplying.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/228/1*K4kNstHhU3D1rr0zYBXr-Q.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/310/1*cJ3sUwDaLwZl3ssgZnnFWQ.png" /><figcaption>Left: an image of a mushroom, with a checkerboard pattern representing transparency, which we want to resize. Right: the resized image seen in-game, which now has a black border around it. (image credit: Eric Haines, used with permission.)</figcaption></figure><p>As you can see, the resized mushroom image has a black border around it. Why does this happen? Well, when we resize the image, since we aren’t nearest neighbour scaling, we are going to smoothly fade (interpolate) from one colour to another, creating a sort of gradient between colours. That’s where the problem occurs.</p><p>On the edge of the mushroom, the alpha is fading from opaque (alpha 255) to transparent (alpha 0.) So we insert an inbetween value, alpha 128.</p><p>For the RGB channels, we are fading from red, to a colour that was never actually visible before! because it was hidden by the alpha before. In this case, we fade to black. So we end up with this ugly semi-transparent black border around the fringe of the object.</p><p>To properly resize the image, we have to <em>premultiply</em> the alpha channel. This means getting the image into a format where the alpha is the “ceiling” for the RGB channels. So for example, a half transparent white (0xFFFFFF80) becomes 0x80808080. A quarter transparent white (0xFFFFFF40) becomes 0x40404040. A half transparent red (0xFF000080) becomes 0x80000080. And a half transparent gray (0x80808080) becomes 0x40404080. So the alpha is the max value, that the other channels can’t go above, and they scale to be relative to the alpha.**</p><p>So you go through the whole image, applying this multiplication, and only after you’ve done that can you interpolate the colours and they’ll be properly “weighted” so they won’t fade to colours you couldn’t see before. Then after resizing, you unpremultiply them to get the result.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/364/1*ngJB0clav7bIywrPxlL7XQ.png" /><figcaption>The mushroom image, premultiplied so there is no black border. (image credit: Eric Haines, used with permission.)</figcaption></figure><p><em>**As a disclaimer, I must state that this is just what premultiplied means as it applies to us in this context. </em><a href="https://community.adobe.com/t5/photoshop-ecosystem-discussions/change-in-exr-open-from-cs2-to-cs3-can-this-be-fixed/m-p/1521042/page/4#M918"><em>Graphics people get really annoyed</em></a><em> when this oversimplified definition is used in general, but for our purposes this is accurate.</em></p><h4>Implementing Premultiplication With Pixman</h4><p>Now, the aforementioned blog goes on to explain how to take advantage of OpenGL and WebGL features to premultiply colours, but the nature of our situation is that we need to do it on the CPU. Pixman has no built in method for premultiplication, but after thinking about it for a bit I realized it could be coerced into doing it with a little bit of trickery.</p><p>Here’s the basic idea. First, we create the Pixman source image in BGRX format, meaning that it will only use the BGR channels, and the alpha channel will be ignored. Next, we create a Pixman mask image in BGRA format, using the same image data. Because this is a mask image, only the alpha channel will be used, and the BGR channels will be ignored.</p><p>Therefore, when we composite the source image with the mask image, it will have the effect of multiplying the BGR channels of the source by the alpha channel of the mask, while leaving the alpha channel itself alone, which is exactly what we want. The mask image doubles as the destination, since we do care about the alpha for when we perform the actual resize, which it will later be used as the source for.</p><pre>pixman_image_t* sourceImage = pixman_image_create_bits(<br> PIXMAN_x8r8g8b8,<br> width, height,<br> (uint32_t*)image,<br> (int)stride<br>);<br><br>if (!sourceImage) {<br> throw std::bad_alloc();<br>}<br><br>pixman_image_t* maskImage = pixman_image_create_bits(<br> PIXMAN_a8r8g8b8,<br> width, height,<br> (uint32_t*)image,<br> (int)stride<br>);<br><br>if (!maskImage) {<br> throw std::bad_alloc();<br>}<br><br>pixman_image_composite(<br> PIXMAN_OP_SRC,<br> sourceImage, maskImage, maskImage,<br> 0, 0, 0, 0, 0, 0,<br> width, height<br>);</pre><p>I’ve omitted the cleanup code here, so don’t forget to call pixman_image_unref (preferably in a deconstructor or scope exit so they’ll still be freed if an exception occurs.)</p><p>This does leave the question: is it valid to create two separate Pixman images using the same underlying image data? Well, Pixman’s only form of documentation is its headers, and nothing in the headers seems to suggest this isn’t permitted, so I’m assuming that Pixman operates on the principle of “if it works” here.</p><p>Importantly, this does work, and much faster than anything else I could come up with, likely because it can take advantage of the optimizations described in the paper <a href="https://arxiv.org/abs/2202.02864">Alpha Blending with No Division Operations</a> (the fast FbByteMul macro that the paper mentions Pixman uses is still there, it’s just been <a href="https://gitlab.freedesktop.org/pixman/pixman/-/commit/8339a4abc4edcaee6fafbde1a147ba7fcaa9c108">renamed to something else</a> more verbose in the intervening time.)</p><p>Unfortunately, as far as I can tell Pixman can’t be tricked into going the opposite direction and unpremultiplying, so we must write the code to do this ourselves. The interesting question once again isn’t about how to do it, because it’s pretty straightforward to understand what we need to do. Rather, it’s how can we make it fast — or more specifically, how can we avoid dividing?</p><p>As any good programmer knows, division is slow, it’s a serializing instruction, and we want to avoid it as much as possible. The favourite programmer tricks to avoid division are to use bit shifts (for division by multiples of two) or flip it into a multiplication — for example, to multiply by 0.333 instead of dividing by 3. In this case though, we are dividing by the alpha, so we can’t know what number we will be dividing by in advance.</p><p>However, because the channels are 8-bit, we will only ever be dividing numbers from 1 to 255 (yes, some values will be zero — but we sure won’t be dividing by them then!) That means there are only about 65K possible combinations, so we can use another classic solution: a lookup table! This is a perfect place to use constexpr to bake the array directly into the compiled result.</p><p>Note that there is a bug in IntelliSense where it’ll give a red underline to a constexpr std::array if it has this exact size. This is an <a href="https://github.com/microsoft/vscode-cpptools/issues/5833">IntelliSense bug,</a> it compiles fine (IntelliSense don’t be stupid challenge: impossible)</p><pre>typedef std::array&lt;unsigned char, USHRT_MAX + 1&gt; UNPREMULTIPLIER_ARRAY;<br><br>constexpr UNPREMULTIPLIER_ARRAY createChannelUnpremultiplierArray() {<br>    UNPREMULTIPLIER_ARRAY channelUnpremultiplierArray = {};<br><br>    // note: the alpha, divided by two, is added to the channel<br>    // so the channel is scaled instead of stripped (it works out to rounding the number, instead of flooring)<br>    // alpha starts at one, since if it&#39;s zero the colour is invisible anyway (and thus would be a divide by zero)<br>    const size_t DIVIDE_BY_TWO = 1;<br><br>    unsigned short tmp = 0;<br><br>    for (unsigned short channel = 0; channel &lt;= UCHAR_MAX; channel++) {<br>        for (unsigned short alpha = 1; alpha &lt;= UCHAR_MAX; alpha++) {<br>            tmp = ((channel * UCHAR_MAX) + (alpha &gt;&gt; DIVIDE_BY_TWO)) / alpha;<br>            channelUnpremultiplierArray[(channel &lt;&lt; CHAR_BIT) | alpha] = __min(tmp, UCHAR_MAX);<br>        }<br>    }<br>    return channelUnpremultiplierArray;<br>}<br><br>// aligned to nearest 64 bytes so it is on cache lines<br>// note: there is a specific IntelliSense error that it only shows for a std::array of size 65536 bytes<br>// this is an IntelliSense bug, it compiles correctly: https://github.com/microsoft/vscode-cpptools/issues/5833<br>alignas(64) static constexpr UNPREMULTIPLIER_ARRAY CHANNEL_UNPREMULTIPLIER_ARRAY = createChannelUnpremultiplierArray();</pre><p>Once the array is created, we can use it to unpremultiply all the colours in a loop. This code assumes 32-bit colour.</p><pre>struct Color32 {<br> unsigned char channels[4] = {};<br>};<br><br>#define UNPREMULTIPLY_CHANNEL(channel, alpha) (CHANNEL_UNPREMULTIPLIER_ARRAY[((channel) &lt;&lt; CHAR_BIT) | (alpha)])<br><br>void unpremultiplyColors(<br>    Color32* colorPointer,<br>    size_t width,<br>    size_t height,<br>    size_t stride<br>) {<br>    const size_t CHANNEL_ALPHA = 3;<br><br>    unsigned char* rowPointer = (unsigned char*)colorPointer;<br><br>    for (size_t i = 0; i &lt; height; i++) {<br>        for (size_t j = 0; j &lt; width; j++) {<br>            const unsigned char &amp;ALPHA = colorPointer-&gt;channels[CHANNEL_ALPHA];<br><br>            if (ALPHA) {<br>                colorPointer-&gt;channels[0] = UNPREMULTIPLY_CHANNEL(colorPointer-&gt;channels[0], ALPHA);<br>                colorPointer-&gt;channels[1] = UNPREMULTIPLY_CHANNEL(colorPointer-&gt;channels[1], ALPHA);<br>                colorPointer-&gt;channels[2] = UNPREMULTIPLY_CHANNEL(colorPointer-&gt;channels[2], ALPHA);<br>            }<br><br>            colorPointer++;<br>        }<br><br>        rowPointer += stride;<br>        colorPointer = (Color32*)rowPointer;<br>    }<br>}</pre><p>Premultiplying and unpremultiplying without converting the channels to 16-bit is a lossy operation, which would be a problem if this was for an image editor for example, but since my goal is just to display the texture on screen I don’t have to worry about this.</p><h4>Decompiling Gfx Tools</h4><p>From here on out, it was only a matter of decompiling Gfx Tools. I had the fast image library and just needed to match the shape of it to the API the game was expecting to interact with.</p><p>This was different from most decompilation projects in that I didn’t want to make a perfect recreation — if I did it would just have all the same problems I wanted to fix. I instead only needed to decompile it to the extent that I could document each function signature, what arguments they were expecting and what they were meant to do, well enough to match its behaviour in my recreation.</p><p>At this stage, I also discovered why the game would sometimes resize images. It turns out, in Direct3D 9 there is a max texture size, which can vary by graphics card, as documented in the <a href="https://learn.microsoft.com/en-us/windows/win32/api/d3d9caps/ns-d3d9caps-d3dcaps9">D3D9CAPS</a> structure. So, the game will resize any texture that would be above the max texture size to be smaller. However it does not do this for DDS, so I made sure to go back and implement resizing during the DDS conversion as well.</p><p>This process went reasonably smoothly, and before too long I had replicated the API well enough for the game to link to it. In fact, the game ran without crashing on the first try! Transparency didn’t work, which I quickly fixed, and then it appeared to be fully working.</p><h4>It’s Still Slow (Again)</h4><p>I had completely eliminated the portion of the loading where the animations stood still, corresponding to when it couldn’t update the screen due to the blocking operation. However, movement was still not instant.</p><p>At this point I was truly baffled because by all means it should’ve been well optimized enough, and nothing else was appearing in Luke Stackwalker that seemed to justify such a long wait. So I once again began reversing. Ultimately, in x64dbg I went up in the call stack from the image loading code to the function that gets called whenever you click to move that loads everything, saw that it was still taking about half a second to run, then traced through it until I found the slow call, stepped into that call, and repeat. Eventually I was lead to a class called AiSndTransition.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/494/1*O3qxjuh2dic0aG8xEYxcWg.jpeg" /></figure><p>Interestingly, we can see that it constructs a 550 millisecond timer in AiSndTransition::FadeOutSound.</p><pre>ai::Timer::Stop(timer);<br>ai::Timer::Reset(timer);<br>ai::Timer::SetTick(timer, 550u);<br>ai::Timer::Start(timer);</pre><p>The names of the methods of this class make the intent clear. The idea is that there is an intentional delay in order to crossfade the sounds from one location (or “context”) to another. What I wanted was for the sounds to just cut to the new volume, which would allow for instant movement. Once again, this can’t be turned off normally.</p><p>At first, I disabled this by making yet another edit to data.m4b. In order to know which objects to load, the game relies on a file called binarizer_loader.log, and AiSndTransition is amongst these. By removing it from said file, it effectively becomes a null pointer. The game checks if the object is null and if it is, it doesn’t use it, so this appears to work. I’m not going to explain this approach in further detail though, because as will become apparent later this was a bad way to do it.</p><p>I decided to make this a separate toggle in my tool, since it’s an intentional feature, unlike the loading issue which I would consider a bug. Personally though I prefer the game with it disabled.</p><h3>Testing For Crashes</h3><p>At this point, the tool worked well, and it was only a matter of doing a full playthrough of the game to check for any crashes. As it turns out, there were a few. I’m going to be showing the places in the game where the crashes occurred, so in case you would like to go in completely blind, <em>be aware there are screenshots from later on in the game beyond this point.</em></p><h4>Black Squares</h4><p>One issue I noticed immediately after adding DDS conversion but decided to put off until later was these black squares in the sky.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wX0nELBPhFo6yOf16jNopw.png" /><figcaption>This issue wasn’t super common, but appeared in various random places around Tomahna.</figcaption></figure><p>I knew that if I could just figure out why this occurred, then worst case scenario I could simply not convert those specific textures since the problem was pretty rare, so I kicked the can down the road. Eventually though I had finished recreating Gfx Tools and I had nothing left to do but debug issues like this.</p><p>As it turns out, this is because the game has a table of bitmasks for each pixel format. For example, RGBA would be 0x000000FF for red, 0x0000FF00 for green, 0x00FF0000 for blue, and 0xFF000000 for alpha (remember: little endian, so most significant byte is last.)</p><p>Well, for DXT compression, the red, green, blue and alpha bitmasks are all zero. This makes sense, because it’s compressed, so there isn’t any logical way to express the colour order as a bitmask. However, the game had HasColor and HasAlpha functions which would return true or false based on if their respective bitmasks were non-zero. For a DXT texture, because the bitmask was zero they would return false when the opposite was intuitively true, which caused problems down the line.</p><p>Well, I had conveniently just gone through the effort of recreating Gfx Tools where this table of bitmasks was located, so I simply changed all the bitmasks for DXT compression to have a value (I went with 0x0000000F for DXT1 and 0x000000FF for DXT5 so that it would at least equate to the same number of bits.) While not a technically correct way to describe the colour order, it produced the desired result and didn’t cause any issues, so that’s what I did.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lFA6G_AMfnRi6LyiJEQEiQ.png" /><figcaption>The black squares issue fixed.</figcaption></figure><h4>Solving Any Puzzle</h4><p>At this point, the game appeared to be working until I went to solve the first puzzle, after which it immediately crashed. What’s especially worrisome is I reopened the game to find my save file corrupted (thankfully, I was very early on in the game.)</p><p>Remember when I mentioned Gfx Tools could save images? Yeah, this is why. The game autosaves, and when it does, it takes a picture of the screen to show on the Load Game menu and saves it as a JPEG image in the save file.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Frmj_HnZ3Xmj7EfHmIjQCw.jpeg" /><figcaption>Save games have image previews, which requires having the ability to save a screenshot whenever they are created.</figcaption></figure><p>I had implemented saving as mentioned before, but I got one of the saving related function signatures incorrect when I decompiled Gfx Tools. Fixing this resolved the save file corruption issue, and also explained why saving was necessary. The image saving feature is also used by the in-game camera that allows you to take your own screenshots.</p><h4>The Linking Chamber</h4><p>I started playing the game from the beginning. Things were going well until I made it to this specific spot, at which point the game crashed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FPdWN25jj90JYBCXN9lsIg.jpeg" /></figure><p>It turns out this was a bug in my water code. This is one of the few screens in the game where water may or may not be present depending on the state it is in.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iJ4_btth5Hza_wKuO5CA0Q.jpeg" /><figcaption>After pulling a lever, the linking chamber door closes behind us. In the closed state, not all of the water can be seen behind the door. If we only account for the water that is visible in the closed state, we will miss some of it.</figcaption></figure><p>When you rotate the outer chamber, there is a wall in the way of where the water used to be, so it isn’t there anymore. I had not correctly accounted for a single node having multiple states.</p><p>Fortunately I was most of the way there and was just being dumb about how I stored the data. I had been using std::map’s insert method to insert each “slice map” of water positions, which replaces the previous value if it is already in the map.</p><pre>waterMaskMap.insert({ fileFaceStrMapIterator-&gt;second, Binary::RLE::createSliceMap(inputStream, maskFile.size) });</pre><p>What I needed to be doing instead was joining the slice maps together if it was already in the water mask map, changing the createSliceMap method into a appendToSliceMap method that takes in a reference to accommodate this.</p><pre>Binary::RLE::appendToSliceMap(inputStream, maskFile.size, waterMaskMap[fileFaceStrMapIterator-&gt;second]);</pre><p>A classic mistake that’s easily fixed, and with that the crash was gone. I then played through the entirety of Haven with no issue, began on Spire and before long experienced another crash.</p><p><em>I’ve simplified the code snippet above — thanks to user zetafunction for letting me know that it could be shortened to a one liner!</em></p><h4>The Spire Elevator</h4><p>This next crash is near the first elevator you encounter in Spire.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TFrTEUGk8j9FjRaJdRiAAA.jpeg" /></figure><p>The crash was when loading a texture, which was apparently null. This meant the crash location didn’t tell me much about where the actual problem was, because it was some kind of error that happened prior but didn’t show itself until later. There doesn’t seem to be anything particularly interesting going on with this node either, and I spent a couple hours confused, trying to figure out what was special about it.</p><p>I decided to patch in a null check to just skip over loading for the problem textures, which gave me my first clue: only the top and front sides of the cube were not loading. The rest was fine.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zippEST21JeWF7BrTYrkWQ.jpeg" /><figcaption>Myst IV projects each texture onto a cube. Only the top and front of the cube are not rendering, but the right side with the stairs is fine, causing it to get “cut off.”</figcaption></figure><p>It wasn’t until I decided to extract out the textures to check if there was anything suspicious about them that I happened to mouse over one in Explorer and see that these textures specifically were 128x127 sized, not 128x128 like the majority of the texture slices in the game. Probably by accident.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/322/1*7_GHwboyPzCD2u3mOiJbTg.jpeg" /><figcaption>Noticing this alt text in Explorer likely saved me hours of troubleshooting pain.</figcaption></figure><p>As it turns out, the game assumes that DXT compressed textures are square, using the width of the image as both the width and height. Gfx Tools does not make this assumption, so usually it worked anyway, until I came along and ruined it. So, I added a check if the textures were square, and left them uncompressed if they were not.</p><h4>The Spire Telescope</h4><p>Continuing my playthrough of Spire, I now discovered another location where a crash occurred, when looking through this telescope on Sirrus’ desk.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MBFCEue5M2bGRB4kl0ITkw.jpeg" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QWJJJknlvcD5d1eUxaCEkg.jpeg" /><figcaption>Zooming into this telescope in Spire would cause the game to crash.</figcaption></figure><p>This was, once again, a texture size related issue. This screen had textures that were now 166x166 sized, for whatever reason. As it turns out, the game not only assumes DXT textures are square, but also power of two sized! Really testing my patience, here…</p><p>Anyway, this is again pretty easy to add a check for, and in fact we only need to check the width is a power of two (because we know it’s a square.)</p><pre>// ares assumes all DXT textures are square and power of two sized<br>// so if they are not, we must use RGBA instead<br>const int DEPTH_SQUARE = 1;<br><br>int width = surface.width();<br>int height = surface.height();<br>int depth = surface.depth();<br><br>if (width != height || depth != DEPTH_SQUARE) {<br> return rgba;<br>}<br><br>// only need to check width, because we know it&#39;s the same as the height<br>if (!isPowerOfTwo((unsigned int)width)) {<br> return rgba;<br>}<br>return hasAlpha ? dxt5 : dxt1;</pre><p>In the end, these checks only added a few KB to the overall size of data.m4b, because the vast majority of the textures in the game are correctly sized.</p><h4>The Ending</h4><p>Good thing I played to the end, because it turns out there was a crash all the way at the very end of the game, when getting the bad ending before returning to the menu.</p><p>So, remember when I said they always check if the AiSndTransition object exists, and if it doesn’t they don’t use it? Yeah, well, that’s true everywhere except for at the ending, the one place they didn’t put a null check. This is the single instance in the entire game where sound fading is intentionally disabled — I guess because the main menu is not an actual place so fading the sound here is not realistic? Kind of unnecessary in my opinion, but nonetheless that’s what they do.</p><p>Anyway, this throws a wrench in my plans. Removing the AiSndTransition object from binarizer_loader.log seemed like the intended way to turn it off, but it causes a crash. So, instead I was going to have to resort to binary patching. Fortunately, this can be solved by simply making the AiSndTransition::OnActivate method do nothing. It’s a DLL export, so it’s easy to find, and it is as simple as patching a RET instruction there.</p><p><em>After the fact note: I ended up finding out that this simple patch to </em>AiSndTransition::OnActivate<em> was also a bad idea after releasing my tool since it was not compatible with other, non-Steam releases of the game, and had to change it again to yet another different but similar patch. Such is the life of a programmer…</em></p><h3>Conclusion</h3><p>After fixing the loading I added some other fun stuff like a full screen toggle, but this is already very long and the way that extra stuff is implemented is fairly straightforward, so I won’t bother explaining it here. The good news is, at the end of all this, I finally had a fully working Myst IV: Revelation with instant movement, and it feels like playing a completely different game. And it only took four months of work! Yeah, here I was thinking this would be a one month project at the start. That’s how it tends to go…</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2F2oNy_D9vemE%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D2oNy_D9vemE&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2F2oNy_D9vemE%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/c79dd45d5cdbeaae81fe1c97c8214e0c/href">https://medium.com/media/c79dd45d5cdbeaae81fe1c97c8214e0c/href</a></iframe><p>Hopefully this was interesting and you learned something new. Once again, if you want to use my tool, please go to the <a href="https://github.com/tomysshadow/M4Revolution/">Myst IV: Revolution GitHub</a> to download it.</p><p>I do a lot of game hacking projects like this, though I am only just now trying to get into the habit of writing about them. So, if you liked this and want to see similar content <em>very occasionally,</em> then please consider following me on Medium. Thanks for reading!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2882cf5f50a5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Fixing the Loading in Myst IV: Revelation]]></title>
            <link>https://medium.com/@tomysshadow/fixing-the-loading-in-myst-iv-revelation-86e2814afbf8?source=rss-2f7e0af662a3------2</link>
            <guid isPermaLink="false">https://medium.com/p/86e2814afbf8</guid>
            <category><![CDATA[cpp-programming]]></category>
            <category><![CDATA[myst]]></category>
            <category><![CDATA[hacking]]></category>
            <category><![CDATA[direct3d]]></category>
            <category><![CDATA[videogames]]></category>
            <dc:creator><![CDATA[Anthony Kleine]]></dc:creator>
            <pubDate>Sat, 07 Dec 2024 21:37:51 GMT</pubDate>
            <atom:updated>2024-12-10T08:44:08.632Z</atom:updated>
            <content:encoded><![CDATA[<p>I’ve always been a big fan of Myst. It’s a series of puzzle adventure games where you explore mysterious worlds by pointing and clicking the mouse where you want to go, solve puzzles, and discover their stories. Earlier this year, Cyan released a <a href="https://cyan.com/games/riven/">new remake of Riven,</a> the sequel to Myst. Knowing this will likely reinvigorate interest in the several Myst sequels, I wanted to try my hand at fixing one of the most glaring issues with the fourth game in the series, Myst IV: Revelation.</p><p>Myst IV has a loading issue. Every time you click to navigate somewhere, it takes a solid two seconds to load — and this is not a compatibility bug; the game was always like this, even when it was newly released. This is especially noticeable coming off of the previous entry in the series, Myst III: Exile, a very similar game which doesn’t have any obvious loading throughout.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2F9bn811dGTQk%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D9bn811dGTQk&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2F9bn811dGTQk%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/00e9af7091b5d06adafdddc4b4dd7ea0/href">https://medium.com/media/00e9af7091b5d06adafdddc4b4dd7ea0/href</a></iframe><p>At the time, I saw this loading issue blamed on the fact that the game had to read assets from the DVD, which was too slow to keep up. However, for Myst’s 25th anniversary, Myst IV was released on Steam for the first time, allowing the game to be installed to a fast SSD — and yet, there is no significant speed improvement.</p><p>Because it was such an obvious problem with the game, I always assumed that someone would eventually dig into why it occurs and fix it. So, I waited. And then I waited some more. Finally, my friend Matt became interested in playing the game and didn’t want to put up with the loading times. So, as things tend to go, I decided: fine — I’ll do it myself.</p><p>And so began work on my new tool, Myst IV: Revolution! (clever name, right?) This is gonna be a long read — but that’s fine, I know Myst fans enjoy reading.</p><h3>Quick Note</h3><p>If you just want the tool I made to fix it and don’t care about how this was done, you can head to the <a href="https://github.com/tomysshadow/M4Revolution/">Myst IV: Revolution GitHub</a> to download it.</p><h3>Learning From The Best</h3><p>A few years ago, I read a blog post about how the <a href="https://nee.lv/2021/02/28/How-I-cut-GTA-Online-loading-times-by-70/">loading times were fixed in GTA IV.</a> In that blog, the author explains they used a tool called <a href="https://lukestackwalker.sourceforge.net/">Luke Stackwalker</a> to profile the game during its loading screen in order to discover that almost 70% of the loading time was being spent on JSON parsing. Since I also wanted to fix a loading bug, I figured why reinvent the wheel, so I decided to try the same approach.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/499/1*41auiigIFDLbED-JL-zgKg.jpeg" /><figcaption>A profile captured when idle.</figcaption></figure><p>First, in order to eliminate any potential red herrings, I decided to run a profile during normal gameplay — simply idling around, not loading anything. In the results, I saw that the majority of the time was being spent on <a href="https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject">WaitForSingleObject.</a> Looking up in the stack reveals that it is called from the <a href="https://learn.microsoft.com/en-us/windows/win32/api/d3d9/nf-d3d9-idirect3ddevice9-present">Direct3D Present</a> method, used to draw graphics to the screen. I assume that it calls WaitForSingleObject as a synchronization method, potentially for Vsync (but don’t quote me on that.)</p><p>So we know that WaitForSingleObject is where the majority of CPU time <em>should</em> be spent during normal operation, and we can dismiss anything that appears in this first list as not the source of the problem. Now, I capture another profile while navigating.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/483/1*8_sTwAFWEcI-XuVi1ugAKA.jpeg" /><figcaption>A profile captured during navigation.</figcaption></figure><p>I tried to time the start and end of the session so that it only catches the loading portion. This was somewhat nontrivial, since Luke Stackwalker doesn’t have a hotkey to stop recording, meaning I needed to Alt + Tab out of the game and click the stop button as quickly as possible immediately after the loading completed.</p><p>In this profile, we can see that approximately 50% of the time is spent on WaitForSingleObject, but we know that is a part of the game’s normal rendering loop so we can dismiss it as background noise. However, there are some functions that we see in the loading profile that have shot up to 2nd and 3rd place, that were not even in the idling profile. Namely, L_GetBitmapRow and L_PutBitmapRow.</p><p>Bear in mind that I did not time this profile perfectly, so they likely take up more of the loading time than the roughly 12% shown, too. In fact, the profile is now no longer dominated by D3D9, instead being taken up by various modules with uppercase names, all beginning with “L.” So, what are these functions?</p><h4>LEADTOOLS</h4><p>As it turns out, these are image loading functions which are part of a middleware the game uses called <a href="https://www.leadtools.com/">LEADTOOLS.</a> Lucky for us, LEADTOOLS is still around and we can still see the documentation for <a href="https://www.leadtools.com/help/sdk/v21/main/api/l-getbitmaprow.html">L_GetBitmapRow</a> and <a href="https://www.leadtools.com/help/sdk/v21/main/api/l-putbitmaprow.html">L_PutBitmapRow</a> on their current website. From this we can infer that the game is probably spending the majority of its loading time on loading images.</p><p>On the face of it, it makes sense. Image loading seems like the type of thing that could take a long time because it is a large amount of data to process. On the other hand, CPUs are much faster now than they were when Myst IV released, yet it was still causing a noticeable delay. So the question on my mind, then, was in the modern day of Threadrippers and Ryzens, what kind of throughput should I be expecting? Could it be improved? Was this as fast as I could reasonably ever expect to load however many images were required by the game, or was LEADTOOLS suboptimal in some way?</p><h4>Look Up in The Stack</h4><p>Before digging into the L_GetBitmapRow and L_PutBitmapRow methods to see if they had some obvious problem, I decided to first look up in the stack to get a sense for how the game intended to use them. So I looked where they were referenced in a decompiler, and found the following loop.</p><pre>while ( row &lt; imageInfo.height )<br>{<br> L_GetBitmapRow(bitmapHandlePointer, bufferPointer, row, bytes);<br> bufferPointer += stride;<br> ++row;<br>}</pre><p>By using the documentation, we can label the variables correctly. As we can see, this is a loop that loads the image row by row. This makes sense as LEADTOOLS does not appear to have a method to load an entire image at once, except to some particular formats (like a GDI bitmap handle) which come with some caveats.</p><p>From a design perspective, when creating an image library, it makes sense to only include a function to load an image row by row. If you only want to load a particular row or set of rows, it offers that capability, while being trivial to wrap into a loop to load an entire image.</p><p>However, anecdotally, I’ve noticed that this is a slow pattern. I think it is because it is antithetical to CPU caching — now everything needs to come to a screeching halt at the end of every single row to return back to another DLL, perform some checks, then jump back to the code where the actual memory copying happens. Last year when working on my ExportFile Xtra, I had to convert an image using a similar API, and passing the image data row by row was by far the slowest part of the process. I am not the first to observe that this is slow, either. <em>Foreshadowing.</em></p><p>In any case, I decided to now look up from this function to see where it was called. Upon doing so, I was immediately intrigued by an interesting string comparison.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/723/1*VdRXOxi3HAEB6zWq0qpfdQ.jpeg" /></figure><p>It’s a file extension check, and interestingly, the code seems to call a different function if the extension is “dds.” So, why did this set off alarm bells?</p><h3>What Is DDS?</h3><p>DDS is an image file format created by Microsoft. The name is short for <a href="https://en.wikipedia.org/wiki/DirectDraw_Surface">DirectDraw Surface,</a> and was originally part of the DirectDraw API, which has long been deprecated in favour of… well, no alternative really, but the important thing is that the DDS format was repurposed for use by Direct3D, the graphics rendering API for 3D games on Windows. The reason DDS is interesting is because it can be directly loaded by Direct3D without any processing — that is to say, you can basically just chuck it at the GPU, so they load very fast.</p><p>The tradeoff is that although they load faster, DDS files have a larger filesize than standard compressed image formats. This can be somewhat remedied by using DXT compression, which allows DDS files to be made smaller, though still not as small as a JPEG or PNG.</p><p>This lead me to wonder if the game had originally been written to use DDS, but at some point during development they realized that they would not fit on the DVD, and they had to write an adapter of sorts to use slower, more compressed formats. Of course, now that the game is on Steam there is no such size limitation. So I wanted to test this theory, but I am already getting ahead of myself. I first had to figure out where the game was trying to load these images from.</p><h3>Proprietary Archives</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/625/1*p7-CGGXc2ADb7VaBRuOMww.jpeg" /><figcaption>The install directory for Myst IV: Revelation.</figcaption></figure><p>If you happen to look in the install directory for Myst IV, you will see the files are split into three folders, “bin,” “data,” and “save.” “save” is just for savegames so that’s irrelevant for us. “bin” is short for binary, and contains the executable files for the game. The “data” folder is the most interesting to us at the moment. If you look inside, you will see several files with an M4B filetype extension. This is not a standard format — it’s a proprietary archive.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*J9NKWi-yaIBtZw1ayOhusg.jpeg" /><figcaption>The data folder contains several files with an M4B extension. My media player thinks these are audio files, but they’re not.</figcaption></figure><p>This is a pretty standard practice for games, even still now but especially in the 2000s. Rather than have the game files be sorted into folders, they are instead packed into an archive file — similar to a ZIP or RAR — though often proprietary and custom made for the specific game or engine, and therefore cannot be opened by anything else. There are a variety of advantages to this practice. In fact just last month Code Not Magic did a video about this subject (as it pertains to the Xbox, but it’s the same idea,) so if you’re not familiar with this concept you can just go watch that.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2Fx8zUdtexwTc%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3Dx8zUdtexwTc&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2Fx8zUdtexwTc%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/c3811174fce090001d8d2883f2cd2bd2/href">https://medium.com/media/c3811174fce090001d8d2883f2cd2bd2/href</a></iframe><h4>Prior Work</h4><p>I’m not actually the first to have been in this precise situation. There are already a couple of tools which can use the M4B type files, such as <a href="https://github.com/coderjo/myst4tools">myst4tools,</a> a script to unpack and repack them, and <a href="https://github.com/TomahnaProject/MYSTERAssetExplorer">MYSTER Asset Explorer,</a> a viewer that can open M4B files to display the image assets within.</p><p>Before too long, I was able to extract the images, replace them with DDS files, and run a test to confirm that they were indeed recognized by the game. Notably, any uncompressed images were required to be 32-bit, not 24-bit as is common for colour images without alpha. However, I was planning on using DXT compression, so I probably wouldn’t need to worry about that, right?</p><h3>Converting To DDS</h3><h4>The BigFile Format</h4><p>Digging around in the decompiler revealed that the name of this archive file format is BigFile, meaning that M4B likely stands for Myst 4 BigFile. As far as I’m aware this format was not used again for any games afterward.</p><p>The format itself is fairly straightforward. It begins with the signature UBI_BF_SIG and a version number. In Myst IV, the version number is 1. This is then immediately followed by the directories. Unlike, say, the ZIP format where there is a list of flat paths (like “path/to/file”) in the BigFile format there is a directory tree.</p><p>Each directory struct starts with the number of subdirectories they own, up to a maximum of 255, then for each subdirectory there is another directory struct, on and on. Then there is the number of files in the directory. Each file has a size and position in the archive.</p><p>Interestingly, names for directories and files are optional. Each name is a length followed by a string, but the length may be zero, indicating no name. In this case, the name is a wildcard. This feature is used for the top level directory of each BigFile, allowing the game to “mount” that BigFile’s directory so it can use any name it wants for it. For example, the data.m4b file is mounted at “gamedata,” and the game will recognize paths starting like “gamedata/path/to/file” as a path within data.m4b.</p><p>After the directory tree is the data for all the files themselves, and that’s it. Pretty basic stuff. There wasn’t any padding or anything more complex like that, just directories and files then data. So thankfully this format was fairly easy to read and write.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RBzaopTZWssr3yNpRqwGew.jpeg" /><figcaption>An Ange Albertini-inspired file format diagram of the BigFile format, using a typical archive from the game as an example. In this archive, the unnamed, top level directory contains a subdirectory called <strong>set_default,</strong> and a file called <strong>cube.dsc.</strong> The <strong>set_default</strong> directory contains a file called <strong>back_01_01.jpg.</strong></figcaption></figure><p>All of the sizes and positions in the BigFile format are 32-bit, which means there is an implicit 4 GB limit to the filesize of them. This was slightly concerning for my purpose because I knew I was going to be making the file larger, and I wasn’t sure by exactly how much. The input was 1.44 GB, so there was still plenty of slack, but I wasn’t sure how much of that was images and what exact filesize ratio to expect versus JPEG. I decided to work on the assumption it would be possible and to fix it down the road if a problem arose due to this.</p><p>There was one additional hurdle, and that’s the ZAP format. Many of the images in the game use a custom format specific to this game called ZAP, which consists of two JPEG images: one for colour, and another for alpha. The idea behind this is obvious: combining two JPEG images to get an alpha channel offers smaller filesizes than using a PNG, and from what I’ve heard this is a pretty common trick in old game engines. I didn’t really have to worry about this too much, as my friend Matt threw together a library called <a href="https://github.com/HumanGamer/libzap">libzap</a> to read them, and I just used that.</p><h4>Easy Bonuses: Disabling the Fade Transition</h4><p>At this point, the goal was clear. Read in the BigFile format, look through them for images, convert them to DDS and write them back, updating the sizes and positions in the directory tree. Naturally, this meant I needed to be able to read and write the BigFile format.</p><p>One additional advantage of this approach is that as it turns out, the archive files have settings in them in text files that can be easily manipulated. One such setting was the amount of time for the fade transition which plays every time you navigate. In Myst III: Exile, this setting can be adjusted in the options, but in Myst IV: Revelation it cannot. I personally prefer for this to be off entirely, so I threw in the ability to edit this amount of time.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/256/1*nBSLZURgCxkhy9YmvpXJ3Q.gif" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/256/1*SxoHYCjIRXwIJD5qEj4IkQ.gif" /><figcaption>Comparison of the fade transition: toggled on (left) and off (right.)</figcaption></figure><p>Matt advised that I should write my program in C++ so that I could use <a href="https://developer.nvidia.com/gpu-accelerated-texture-compression">NVIDIA Texture Tools 3</a> to create the DDS files. I was not aware of this, but as it turns out converting to DXT compressed DDS is actually quite CPU intensive. NVIDIA’s solution, called NVIDIA Texture Tools, uses CUDA in order to GPU accelerate the conversion.</p><p>The headers were for C++ and as far as I know there are no bindings for this for other languages, so this unfortunately meant I couldn’t build on the work of the prior extraction utilities, because myst4tools is written in Python, and MYSTER Asset Explorer in C#. Thankfully given the relative simplicity of the format, I was able to do this myself without too much effort. In the first iteration of my tool, the resulting file was about 3 GB, still under the 4 GB limit.</p><h4>In Other News, Water Is Wet</h4><p>So, I wrote the code to read and write the BigFile format. I wrote code to read in the images and convert them to DDS using NVIDIA Texture Tools. I even added multithreading so that the conversion time wouldn’t be unbearably long in the case you didn’t have an NVIDIA graphics card which supports CUDA. I ran it, I opened the game, and it worked — until I rode down an elevator, briefly saw this weird corruption, and then the game crashed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LqactHr_oZYkB_ypX-KkMg.jpeg" /><figcaption>That doesn’t look right, but interestingly it doesn’t seem to affect everything.</figcaption></figure><p>Thankfully, the crashing function had a symbol, providing a clue as to the cause: WaterSlice::CopyToRaster. In fact, something I haven’t mentioned up to this point is that the game is split across multiple DLLs, all of which export the majority of their functions. The whole game is also written in a pretty idiomatic C++ style. If one wanted to decompile an entire game, this would likely be an easy beginner project, however my goal was purely to fix the loading issue.</p><p>Anyway, as the name would imply, this crash was related to water. By inspecting the decompiled code the cause of the crash soon became clear. Throughout the game, there are lots of places that have a water effect with waves that move back and forth. In order to pull this effect, the game wants to directly edit the textures with water on them to basically “mosh them around.”</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/386/1*6eMdWAu7p6TTtHsNQHnWdQ.gif" /><figcaption>The subtle waves of Myst IV’s water are produced by directly manipulating the pixels of each texture with a sinewave-based effect.</figcaption></figure><p>The code that does this assumes the image is in a 32-bit RGBA format, four bytes each dedicated to one channel. Normally LEADTOOLS would be used to decompress the images into this format, but since I’m loading a DDS it gets loaded directly in the DXT compressed format instead. The function was now directly manipulating compressed data, which was also in a much smaller buffer than it expected. This eventually meant it would manipulate data after the end of the buffer, causing a crash.</p><p>Well, if I didn’t DXT compress the textures, the resulting BigFile was way over the 4 GB limit — especially because the textures had to be 32-bit, not 24–bit, as previously mentioned. So that wasn’t going to cut it. I needed to know which specific textures had water on them and only convert those specific ones as uncompressed.</p><p>To accomplish this, I needed to become familiar with the various BIN files the game used. BIN is a generic file format, short for Binary, and basically whenever you see it you know it’s probably some ad-hoc custom thing made for that one game. This is no exception. Myst IV uses these BIN files to define various “resources,” which can be virtually any <em>thing</em> the game has. The hotspots, puzzle states, lighting effects, animations, and indeed the main thing I cared about: water.</p><p>I didn’t implement every resource type that existed, only the bare minimum required to be able to read the water resources. I found and reversed the functions that would read the BIN files for water, which eventually allowed me to access the data specifying where the water effect is meant to be on screen, using which I could ensure their corresponding textures were always converted uncompressed. This actually took quite some time as the format was somewhat convoluted, but at the end all I cared about was knowing which textures were affected.</p><p>After converting the water uncompressed, the filesize increased further to 3.43 GB, uncomfortably close to (but still within) the 4 GB limit. However, at this point I realized I should use DXT1 instead of DXT5 for any textures without alpha, as they are essentially the same format, but in DXT1 alpha can be turned off entirely. This shaved almost a GB off the size of the converted data.m4b, resulting in a 2.67 GB file.</p><h4>It’s Still Slow</h4><p>At this point, my theory that the loading issue was related to images was confirmed, because I could tell that movement was definitely much faster — but it still wasn’t enough. There was still what felt like about a second of delay. It was certainly faster than before, but I wasn’t satisfied. I wanted instant movement!</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FkECcjDagbTw%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DkECcjDagbTw&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FkECcjDagbTw%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/7ad27a4733e85335779a96d1c38d1a5b/href">https://medium.com/media/7ad27a4733e85335779a96d1c38d1a5b/href</a></iframe><p>I knew that more could be done. Some of the images were not possible to convert. Firstly, there are the mask images. For certain effects such as lighting, mist, and so on, black and white mask images are used to indicate where the effect should be visible. These images are required to have a single 8-bit luminance channel, a format not supported by DDS (as of Direct3D 9 — later versions may have added support, but I didn’t have that luxury.)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/384/1*TZ6vKdRwJ2_o2ynbj311yw.jpeg" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EJ9wQKdPGg1DPexvD4tKMQ.jpeg" /><figcaption>This black and white mask is used so the game knows the location of the fence and bridge to prevent the waterfall mist from rendering in front of it.</figcaption></figure><p>Additionally, some of the aforementioned BIN files could contain images, and these images did not go down the same code path that checked for DDS, instead going directly down the LEADTOOLS route. So all of this leads back to a question I really should have answered earlier…</p><h4>What Are L_GetBitmapRow and L_PutBitmapRow?</h4><p>They’re just memcpy.</p><p>That’s right. Technically there are some checks at the beginning of the functions that allow them to load from sources other than memory such as a file on the disk, but as far as Myst IV is concerned, they just call memcpy and that’s it. That’s the main performance bottleneck.</p><p>At first glance, this seemed to me like bad news. memcpy isn’t exactly complex. If I really did need to copy this amount of data, how could I possibly do it any faster?</p><p>And then I realized… why copy the image at all?</p><p>For this purpose, LEADTOOLS is using an object oriented pattern where it doesn’t belong. It expects that you are going to load the image onto a “bitmap handle,” which must imply an internal, private buffer that it owns somewhere, that you must then copy the data off of in order to take ownership of it. This implies the need to first load the data to an inaccessible location and then perform a redundant memory copy before you can use it.</p><p>What really sucks about this is you need to copy the uncompressed data, which is much more data than if you only needed to copy the compressed image. The ideal would be to discard that bitmap handle and simply acquire ownership of that buffer, to do essentially the equivalent of a std::move. But no, the only way to get it is to copy the whole buffer, one singular row at a time. It’s just not good enough.</p><h3>To Be Continued…</h3><p>This is getting quite long! I decided to split this blog into two parts, both to be released at the same time, just because I felt it needed a natural break. So, see the conclusion to this story in <a href="https://medium.com/@tomysshadow/fixing-the-loading-in-myst-iv-revelation-part-2-2882cf5f50a5">Part 2!</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=86e2814afbf8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[strtod: What does it take to convert strings to doubles?]]></title>
            <link>https://medium.com/@tomysshadow/strtod-what-does-it-take-to-convert-strings-to-doubles-851af1fbc340?source=rss-2f7e0af662a3------2</link>
            <guid isPermaLink="false">https://medium.com/p/851af1fbc340</guid>
            <category><![CDATA[c-programming]]></category>
            <category><![CDATA[strings-in-c]]></category>
            <category><![CDATA[floating-point-number]]></category>
            <category><![CDATA[floating-points]]></category>
            <category><![CDATA[c-sharp-programming]]></category>
            <dc:creator><![CDATA[Anthony Kleine]]></dc:creator>
            <pubDate>Sat, 13 Jul 2024 10:59:19 GMT</pubDate>
            <atom:updated>2026-03-10T10:54:59.817Z</atom:updated>
            <content:encoded><![CDATA[<p>Every once in a while, I see this topic brought up on programming related social media circles to surprise new, unsuspecting programmers. In both C#, as well as C (and by extension C++,) trying to parse a string with a double or float is not as simple as it initially appears.</p><p>Let’s start with C#. You may assume that you could use <a href="https://learn.microsoft.com/en-us/dotnet/api/system.double.parse?view=net-8.0">Parse</a>, or more popularly, <a href="https://learn.microsoft.com/en-us/dotnet/api/system.double.tryparse?view=net-8.0">TryParse</a> (with the only difference being that Parse throws an exception on failure, and TryParse returns a boolean representing whether it succeeded.)</p><pre>if (!double.TryParse(str, out double result)) {<br>  Console.WriteLine(&quot;Please enter a valid number.&quot;);<br>}</pre><p>In this case, str contains a number like &quot;1.2345&quot; in string form, and we want to get it as a double — or at least, that is generally the assumption. Indeed, if you have your system language set to American English, it will work that way — but not if you have your system language set to German.</p><p>Why? Because in Germany, numbers are typically written with a comma (,) as the decimal point. In order to get the same output with the system language set to German, we would need the input string to be &quot;1,2345&quot;. This is the default behaviour of Parse and TryParse in C#, which often takes programmers by surprise — especially when parsing data such as numbers in the configuration file included with a software, which is the same regardless of the region.</p><p>The impetus for me writing this article was the most recent post I saw on this subject, which also includes a helpful graphic — though this is far from the first time I’ve seen this topic brought up to a series of shocked responses.</p><iframe src="https://cdn.embedly.com/widgets/media.html?type=text%2Fhtml&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;schema=twitter&amp;url=https%3A//x.com/Phantom_TheGame/status/1810984722698326304%3Ft%3DljNBWoGGgM8f1aOCqRMfAQ%26s%3D19&amp;image=" width="500" height="281" frameborder="0" scrolling="no"><a href="https://medium.com/media/bf83000134b304f3b2202b933d76f96c/href">https://medium.com/media/bf83000134b304f3b2202b933d76f96c/href</a></iframe><p>This has resulted in many bugs, especially in Unity games which are powered by C#. My favourite example of this is the calculator being broken in Pokemon BDSP.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FfB2C8q42X64%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DfB2C8q42X64&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FfB2C8q42X64%2Fhqdefault.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/96a0991d6fa2bfccc7afd1cde421fbf4/href">https://medium.com/media/96a0991d6fa2bfccc7afd1cde421fbf4/href</a></iframe><p>Thankfully, this behaviour is easily worked around. To fix the issue, we can pass the InvariantCulture , which tells Parse or TryParse to parse the number the same regardless of the system language.</p><pre>// specifying CultureInfo.InvariantCulture is what makes this consistent<br>if (!double.TryParse(str, CultureInfo.InvariantCulture, out double result)) {<br>  Console.WriteLine(&quot;Please enter a valid number.&quot;);<br>}</pre><h3>String Cultures, truly riveting stuff…</h3><p>Now, I could write a whole other article about cultures in C#, as they are an entire rabbit hole and this is just scratching the surface. As another example, in C#, <a href="https://learn.microsoft.com/en-us/dotnet/api/system.string.toupper?view=net-8.0">ToUpper</a> also takes the system language into account. For instance, in Turkish it will capitalize the letter i to İ (with a dot, as capital i appears in Turkish) instead of I (as a capital i appears in English.) This causes issues when attempting to capitalize strings in order to compare them case-insensitively (because what if one of them is already capitalized, and uses the other I?)</p><p>A similar bug led to a news story in which an SMS message was misinterpreted, <a href="https://gizmodo.com/a-cellphones-missing-dot-kills-two-people-puts-three-m-382026">leading to the deaths of two people.</a> This is a reminder that our small bugs can have huge real life consequences.</p><p>In this case, the solution is to forego ToUpper or ToLower entirely, and instead use String.Equals with the OrdinalIgnoreCase culture.</p><pre>if (str.Equals(str2, StringComparison.OrdinalIgnoreCase)) {<br>  Console.WriteLine(&quot;Strings are equal.&quot;);<br>}</pre><p>Wait, OrdinalIgnoreCase? What is the difference between “Ordinal” and “Invariant?”</p><p>Ordinal (case-sensitive) and OrdinalIgnoreCase (case-insensitive) perform a simple, fast byte comparison, ensuring that the byte sequence is exactly the same. They are essentially equivalent to strcmp or stricmp in C. It is intended for use with things such as file paths, registry keys, URLs, and other such “programmer” strings. However, the Ordinal culture can’t be used with TryParse as it is purely non-linguistic — it doesn’t enforce regional conventions, it doesn’t entail decisions about things like periods vs. commas. It can only be used in scenarios where the raw bytes are all that matters.</p><p>Invariant (case-sensitive) and InvariantIgnoreCase (case-insensitive) on the other hand, are intended more for user input strings where linguistic details actually matter, and as such, they entail linguistically relevant preferences — for example, interpreting periods as decimal points instead of commas. In other words, they are opinionated about the way strings “should” be in order to try and ensure consistency. So they take Unicode code points into account, not just raw byte comparisons, and are what you want to use in scenarios where you want to consistently <em>interpret</em> input string data.</p><p>As per <a href="https://learn.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings">Microsoft’s Best Practices for Comparing Strings,</a> it is generally a good idea to use the string&#39;s Equals method with Ordinal culture instead of the == operator in C# for string comparisons, because the == operator uses the “current culture” — once again, based on the system language — and compares Unicode code points instead of the raw bytes, which is typically slow and unnecessary for straight comparisons.</p><p>With all that said: the blame for this counterintuitive culture system, that causes many an error a programmer doesn’t catch until after they’ve released their program into the wild, is often placed on C# — but the real point of this article is that it is not the origin of this idea. Indeed, C# simply copied this convention from C (and by extension, C++) which presents the exact same problem with its string to double function: strtod. However, before we even get to talking about the system language problem, we need to talk about strtod’s error handling.</p><h3>Validating Input</h3><p>In C#, TryParse returns a single, boolean, on and off state representing failure. Not so with strtod: it has multiple different failure states for different scenarios. On the one hand, this allows for more robust handling of those different scenarios, but on the other hand, it is fairly overcomplicated to tell if we have successfully converted the number or not.</p><p>As a side note, all of this is also applicable to the related strtof, which converts a string to a float — and to some extent, strtol and strtoul (string to long/unsigned long respectively,) which I’ll discuss separately at the end of the article. There is also C++’s <a href="https://en.cppreference.com/w/cpp/string/byte/strtof">std::strtod</a> which has all the same issues and works exactly the same way.</p><p><a href="https://en.cppreference.com/w/c/string/byte/strtof">cppreference</a> describes the return value of strtod as follows:</p><blockquote>Floating-point value corresponding to the contents of str on success. If the converted value falls out of range of corresponding return type, range error occurs (<a href="https://en.cppreference.com/w/c/error/errno">errno</a> is set to <a href="https://en.cppreference.com/w/c/error/errno_macros">ERANGE</a>) and <a href="https://en.cppreference.com/w/c/numeric/math/HUGE_VAL">HUGE_VAL</a>, <a href="https://en.cppreference.com/w/c/numeric/math/HUGE_VAL">HUGE_VALF</a> or <a href="https://en.cppreference.com/w/c/numeric/math/HUGE_VAL">HUGE_VALL</a> is returned. If no conversion can be performed, ​0​ is returned.</blockquote><p>Reading this, we learn that strtod will return 0 if no conversion can be performed, which raises the question: how can we tell if the input was actually 0, or if the input was invalid and we failed to read it? The answer is that we need to check <a href="https://linux.die.net/man/3/errno">errno.</a></p><p>errno is similar to WinAPI’s GetLastError in that it gives us more precise error information if the previous call failed, except that errno is for standard C functions such as strtod. Technically, the strtod implementation may (but is not required) to set errno for invalid inputs (though any sane implementation does.)</p><p>errno is not a global variable: it is local to the current thread, and is therefore thread safe to use.</p><blockquote><em>errno</em> is thread-local; setting it in one thread does not affect its value in any other thread.</blockquote><p>One important thing that is easy to forget, however, is to clear it before using it in order to ensure it doesn’t have an error value left over from a previous call.</p><pre>// validating strtod - but this isn&#39;t enough!!<br>inline bool stringToDouble(const char* str, double &amp;value) {<br>  errno = 0;<br>  value = strtod(str, 0);<br>  return value || !errno;<br>}</pre><p>We first clear errno to ensure it doesn’t have a previous error left over from something else, then if the result is 0 (indicating an error <em>may</em> have occured) we check errno to determine if one did. (Note that in general it isn’t always a good idea to check a float or double is precisely equal to something, but in this scenario we know it’s exactly zero so it’s fine.) We return a boolean indicating success or failure, like TryParse. So is this enough? <strong>No!</strong></p><p>There’s another problem that can occur: if we pass strtod a string that is empty or whitespace, errno will not be set but it will still return 0. To detect this case, we need to check if the end pointer (the second parameter passed to strtod ) is equal to the start. There is also the issue that str may be null, which we must also check ourselves.</p><p>So here’s a more robust solution. Here I return a size_t with the size of the number in the string. This means that you can know how far to seek if you want to continue reading more in the string after the number. If the number fails to parse, the size will be zero, so you can still use it like the boolean return of C#&#39;s TryParse.</p><p>I make the assumption that if the number fails to parse, you are uninterested in the size of the invalid number. I also make the assumption that you don’t care if there is trailing junk after the end of the number in the string or not— if you do care you need to check that yourself using the returned size.</p><p>Finally, I make the assumption that you don’t really care about the scenario where the number is out of range (smaller/larger than can be represented by a double) and are okay with strtod’s standard behaviour of rounding it off in that case. If instead you do want to treat out of range numbers as invalid, simply change (value || !errno) in the code below to just !errno.</p><pre>// validating strtod - but what about the system language issue?<br>inline size_t stringToDouble(const char* str, double &amp;value) {<br>  value = 0.0;<br>  errno = 0;<br>  <br>  if (!str) {<br>    return 0;<br>  }<br>  <br>  char* endPointer = 0;<br>  value = strtod(str, &amp;endPointer);<br>  <br>  return (value || !errno)<br>    ? (size_t)(endPointer - str)<br>    : 0;<br>}</pre><p>So now, finally, we can detect any invalid input to strtod — but what about the reason we came here? How do we set the “culture” for strtod to use?</p><h3>Locales</h3><p>The simple answer is to use <a href="https://en.cppreference.com/w/c/locale/setlocale">setlocale</a>. It’s also a terrible idea to use setlocale.</p><p>The idea is simple. By running the following code, sometime before the strtod call, we can set the language to American English — using the LC_NUMERIC constant to specify this locale is for number conversion operations — causing it to use the convention of periods instead of commas.</p><pre>setlocale(LC_NUMERIC, &quot;en_US&quot;);</pre><p>It’s simple. It’s one line. It’s crossplatform. And there’s a huge problem with it.</p><p>The main issue is that this is not thread safe. setlocale sets the locale globally for the entire program. If any other thread, perhaps in another library, decides it wants to use German instead of English, and it calls setlocale in the intervening time before our call to strtod, that can override our setting. On Windows, it is possible to set the locale on a per thread basis with <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/configthreadlocale?view=msvc-170">_configthreadlocale,</a> but we actually don’t need to: we can do even better and use <a href="https://man.bsd.lv/DragonFly-5.6.1/strtod_l.3">strtod_l.</a></p><p>strtod_l is like strtod except that it takes the locale to use as an argument. It exists on both Linux and on Windows (where it has an underscore in front, like <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l?view=msvc-170">_strtod_l.</a>) Great! So we can just pass it the string &quot;en_US&quot; right? Well, no. Instead, strtod_l expects the locale in the form of a locale_t (once again, on Windows, _locale_t with an underscore in front.) So how do we create that?</p><h3>Creating a Locale</h3><p>Well, the answer varies depending on the platform. Windows has two functions: <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/create-locale-wcreate-locale?view=msvc-170">_create_locale and _wcreate_locale.</a> These are much like the A and W functions that we see throughout WinAPI: _create_locale expects an ANSI string in the current codepage, while _wcreate_locale expects a wide string. As per usual for Windows, if the string is UTF-8, you’ll need to convert it with <a href="https://learn.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar">MultiByteToWideChar</a> or, preferably, a macro that wraps it like <a href="https://weblogs.asp.net/kennykerr/visual-c-in-short-converting-between-unicode-and-utf-8">CA2W.</a></p><p>Passing the string to _create_locale or _wcreate_locale will give you a locale_t, which is basically a handle that must be freed when you’re done with it using <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/free-locale?view=msvc-170">_free_locale.</a></p><p>_create_locale also expects us to pass one of the LC constants. You may remember we passed LC_NUMERIC to specify we wanted this locale to apply to number operations. Windows defines several of these for different purposes, as can be seen in the <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/create-locale-wcreate-locale?view=msvc-170#remarks">Remarks for _create_locale.</a></p><ul><li>LC_ALL</li><li>LC_COLLATE</li><li>LC_CTYPE</li><li>LC_MONETARY</li><li>LC_NUMERIC</li><li>LC_TIME</li></ul><p>The LC_ALL constant is the combination of all the others, if we want the locale to apply for everything. For our purposes, we mostly only care about LC_NUMERIC.</p><p>Importantly, <strong>these are not a bitmask</strong> and trying to combine them as such will result in invalid or undesired values, causing _create_locale to return NULL or not use the intended category. Only <strong>one</strong> of these LC constants may be selected into a locale at once.</p><p>Meanwhile, Linux has the similar <a href="https://man7.org/linux/man-pages/man3/newlocale.3.html">newlocale and freelocale.</a> In contrast, the LC constants passed to newlocale on Linux <em>are</em> a bitmask and <em>may</em> be combined.</p><p>There is also one more difference between platforms, and it’s an incredibly minor and easy to miss distinction.</p><h3>Underscores vs. Dashes</h3><p>I mentioned before that an appropriate locale to use for our purposes is &quot;en_US&quot;. However, there is no particular guarantee that any locale (aside from the default of &quot;C&quot; , or &quot;POSIX&quot; which is just another alias for the same thing) is available. In fact, the user can have as many or as few locales installed on their system as they want, and if there is no locale matching the requested one, newlocale returns NULL.</p><blockquote>With the notable exception of the standard locale names ‘C’ and ‘POSIX’, locale names are system-specific.</blockquote><p>This means — on Linux — that there is no way to guarantee that strtod will treat commas as decimal points — only periods, which is the default interpretation provided by the “C” locale. Of course, in practice, it’s <em>probably</em> safe to assume everyone has the most common locales installed. (Here is the <a href="https://lh.2xlibre.net/locales/">full list</a> of standard Linux locales, and <a href="https://www.gnu.org/software/libc/manual/html_node/Locale-Names.html">docs</a> on how they work.)</p><p>On Windows, however, we can actually do better. See, Windows does allow for locale names to be input in ISO 15897 format (sometimes described as the <em>language</em>[_<em>country-region</em>[.<em>code-page</em>]] form) — that’s what we&#39;ve been using with &quot;en_US&quot;. Like Linux, Windows makes no particular guarantee that any such locale is available, and if it isn’t then _create_locale returns NULL.</p><p>However, Windows <em>also</em> supports the IETF American English locale, which is always available, in every Windows version, <a href="https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c">all the way back to Windows 3.51.</a> Confusingly, the difference is that that the IETF Language Tags <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/locale-names-languages-and-country-region-strings?view=msvc-170">use a dash instead of an underscore,</a> like &quot;en-US&quot;. As per the documentation, this is preferred over Linux’s ISO 15897 format:</p><blockquote>The <em>language</em>[_<em>country-region</em>[.<em>code-page</em>]] form is stored in the locale setting for a category when a language string, or language string and country or region string, is used to create the locale… We don’t recommend this form for locale strings embedded in code or serialized to storage: These strings are more likely to be changed by an operating system update than the locale name form.</blockquote><p>While the fact that &quot;en-US&quot; is always available is a nice guarantee to have, that we certainly want to take advantage of on Windows, it is incompatible with Linux’s standard.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/624/1*5iQVB2WPk2GBRbOb093_LA.jpeg" /><figcaption>Here’s a table to summarize.</figcaption></figure><p>tl;dr, we should try the locale name with a dash first for Windows, then with an underscore for Linux.</p><p>So, this is the stage where I decided I wanted to write a C++ class to encapsulate all this, and make it simpler to use. I wanted to allow specifying multiple locales to try and use, only falling back on the global locale if none were available. So, I decided to write the Locale class to handle this.</p><h3>The Locale Class</h3><p>The Locale class that I created can be found <a href="https://github.com/tomysshadow/Locale">on my GitHub.</a> Currently it is Windows only. Implementing Linux’s newlocale and freelocale is left as an exercise for the reader.</p><p>While creating my Locale class, I discovered that C++ had an existing class called <a href="https://en.cppreference.com/w/cpp/locale/locale">std::locale,</a> which is also used by some other C++ functions. It is unfortunately not compatible with the locale_t that strtod_l requires. I decided to make my class compatible with both standards — although std::locale allows mixing and matching categories with a bitmask, similar to newlocale, which is not implemented in my Locale class.</p><p>With the Locale class, we can define the default locale to use for string to number conversions as a constant like this.</p><pre>// first tries the IETF name &quot;en-US&quot;, then the ISO 15897 name &quot;en_US&quot;<br>// then tries the global locale (typically &quot;C&quot;) if neither are available<br>static const Locale STRING_TO_NUMBER_LOCALE_EN_US({&quot;en-US&quot;, &quot;en_US&quot;}, LC_NUMERIC, true);</pre><p>The first argument is a vector of locales to try, the next is the LC constant, and the final argument is a boolean for whether or not to try falling back to the global locale (typically &quot;C&quot;) if none of the listed ones are available. If it were false, then an exception would be thrown if no matching locale is found.</p><p>Next, here is our revamped stringToDouble function, using my Locale class. Notice how the Locale class provides operator overloads to automatically cast to std::locale or locale_t for the call to strtod_l.</p><pre>// ensures consistent interpretation of periods and commas in string to number conversions<br>inline const Locale STRING_TO_NUMBER_LOCALE_DEFAULT(&quot;C&quot;, LC_NUMERIC);<br><br>inline size_t stringToDouble(const char* str, double &amp;value,<br> const Locale &amp;locale = STRING_TO_NUMBER_LOCALE_DEFAULT) {<br> value = 0.0;<br> errno = 0;<br><br> if (!str) {<br>  return 0;<br> }<br><br> char* endPointer = 0;<br> value = _strtod_l(str, &amp;endPointer, locale);<br> <br> return (value || !errno)<br>  ? (size_t)(endPointer - str)<br>  : 0;<br>}</pre><p>We can use it like this, and since the locale argument has a default value corresponding to the C locale, it will just work, reliably.</p><pre>double value = 0.0;<br><br>if (!stringToDouble(&quot;3.333&quot;, value)) {<br>  std::cout &lt;&lt; &quot;Please enter a valid number.&quot; &lt;&lt; std::endl;<br>}</pre><p>Beyond encapsulating the create and free functions, the Locale class has copy and assignment constructors taking in a std::string or std::wstring. This allows for simply passing a string such as &quot;de_DE&quot; directly to stringToDouble.</p><pre>double value = 0.0;<br><br>// I want to use commas instead of periods!<br>if (!stringToDouble(&quot;3,333&quot;, value, &quot;de_DE&quot;)) {<br>  std::cout &lt;&lt; &quot;Please enter a valid number.&quot; &lt;&lt; std::endl;<br>}</pre><p>Or, you could even pass a vector of multiple locale names.</p><pre>double value = 0.0;<br><br>// I want to use commas instead of periods...<br>// and try both locale name standards!<br>if (!stringToDouble(&quot;3,333&quot;, value, {&quot;de-DE&quot;, &quot;de_DE&quot;})) {<br>  std::cout &lt;&lt; &quot;Please enter a valid number.&quot; &lt;&lt; std::endl;<br>}</pre><h3>What about strtol and strtoul?</h3><p>The <a href="https://en.cppreference.com/w/c/string/byte/strtol">strtol</a> and <a href="https://en.cppreference.com/w/c/string/byte/strtoul">strtoul</a> functions, for converting a string to a signed long integer or unsigned long integer respectively, are also impacted by the current locale… in theory. However, in practice it has little effect on them, so you can probably still get away with using them raw. To again quote <a href="https://en.cppreference.com/w/c/string/byte/strtol">cppreference:</a></p><blockquote>The valid integer value consists of the following parts:</blockquote><blockquote>- (optional) plus or minus sign</blockquote><blockquote>- (optional) prefix (<strong>0</strong>) indicating octal base (applies only when the base is 8 or ​0​)</blockquote><blockquote>- (optional) prefix (<strong>0x</strong> or <strong>0X</strong>) indicating hexadecimal base (applies only when the base is 16 or ​0​)</blockquote><blockquote>- a sequence of digits</blockquote><p>And…</p><blockquote>Additional numeric formats may be accepted by the currently installed C <a href="https://en.cppreference.com/w/c/locale/setlocale">locale</a>.</blockquote><p>In other words, the current locale may allow “additional numeric formats” to be accepted, but so long as your integer consists of the typical, expected component parts, it will not interfere. However, all of the error handling related details are the same as strtod. If you care about knowing whether zero was entered versus an invalid input, you can certainly write similar functions specifically for integers. (In my Locale repo I use templates so I don’t need so much duplicated code.)</p><pre>inline size_t stringToLong(const char* str, long &amp;value,<br> int base = 0, const Locale &amp;locale = STRING_TO_NUMBER_LOCALE_DEFAULT) {<br> value = 0;<br> errno = 0;<br><br> if (!str) {<br>  return 0;<br> }<br><br> char* endPointer = 0;<br> value = _strtol_l(str, &amp;endPointer, base, locale);<br> <br> return (value || !errno)<br>  ? (size_t)(endPointer - str)<br>  : 0;<br>}<br><br>inline size_t stringToLongUnsigned(const char* str, unsigned long &amp;value,<br> int base = 0, const Locale &amp;locale = STRING_TO_NUMBER_LOCALE_DEFAULT) {<br> value = 0;<br> errno = 0;<br><br> if (!str) {<br>  return 0;<br> }<br><br> char* endPointer = 0;<br> value = _strtoul_l(str, &amp;endPointer, base, locale);<br> <br> return (value || !errno)<br>  ? (size_t)(endPointer - str)<br>  : 0;<br>}</pre><p>Note the additional argument for these, base, which defaults to 0, meaning to detect the base (for example, numbers beginning with 0x are assumed to be base 16.) This is usually handy so users can input whatever format they like, but if you want to force decimal numbers only, you can pass in 10 as the base.</p><p>As a sidenote, another commonly used function to convert strings to integers is <a href="https://en.cppreference.com/w/c/string/byte/atoi">atoi.</a> This function is even less helpful: a failure to parse the string is simply undefined behaviour, so it is certainly not to be trusted with any user input.</p><p>In conclusion, strtod and friends are deceptively simple looking functions that are actually surprisingly convoluted to use in a consistent fashion. Hopefully this article has helped to demystify the concept of C locales!</p><p>The highly pedantic nature of this article means it is likely I’ve made mistakes, especially because it was difficult for me to find any other resources on this subject. It is also quite possible there is an even simpler way to accomplish the same thing afforded by C++ that I missed. If you have any suggestions, let me know in the comments.</p><p>Note: this article has been edited. It previously mistakenly asserted that the “C” locale is based on your system language, but it actually <a href="https://cplusplus.com/reference/clocale/">is independent of that.</a> I also updated the code snippets to be closer to the updated versions in my Locale repo.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=851af1fbc340" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Story Of Shockwave And 3D Webgames]]></title>
            <link>https://medium.com/bluemaximas-flashpoint/the-story-of-shockwave-and-3d-webgames-8f3647865a7?source=rss-2f7e0af662a3------2</link>
            <guid isPermaLink="false">https://medium.com/p/8f3647865a7</guid>
            <category><![CDATA[adobe]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[macromedia]]></category>
            <category><![CDATA[shockwave-3d]]></category>
            <category><![CDATA[directors]]></category>
            <dc:creator><![CDATA[Anthony Kleine]]></dc:creator>
            <pubDate>Wed, 30 Oct 2019 04:23:25 GMT</pubDate>
            <atom:updated>2019-10-30T06:11:33.527Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*MVQ9iDQ4b8O6mtT1xbuvog.png" /></figure><p>Have you ever had the inclination to play a game where you, as Paul Blart, drive around the mall on your segway, catching criminals? Well, if this was <em>somehow</em> your fantasy, you could do it from the convenience of your web browser, in the webgame Paul Blart: Mall Cop.</p><p>Yeah. Advergames are weird… but did you know there’s a <em>secret</em> behind this game? Well, okay, not really. It’s essentially shovelware. On the other hand, the technology which powered many 3D browser games — such as Paul Blart: Mall Cop — does have an interesting story behind it, and it’s a story with a surprising beginning.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*7DpX6YyqduylIkky7hdsIw.png" /><figcaption>Real Pool was the first 3D game on the Shockwave.com games website</figcaption></figure><p>Let’s roll the clock back to Y2K, well before the existence of HTML5. Flash was the hot new browser plugin on the block, and everybody wanted to get their hands on it. However, there was one thing Flash didn’t do well: 3D. Infusing the internet with 3D content was all the rage, and for that, Shockwave was the right tool to use. In fact, one could say that Shockwave was relegated purely to use in 3D applications, while Flash took centre stage for anything else — but it wasn’t always this way!</p><p>Before we begin, I want to bring up <strong>BlueMaxima’s Flashpoint.</strong> If you just want a hassle free way to play Shockwave games, Flashpoint provides a way to do so on modern Windows. For more information, <a href="http://bluemaxima.org/flashpoint/">check out Flashpoint’s website.</a> Now then, let’s continue.</p><h3>Flash Vs. Shockwave</h3><p>At this point, you may be confused about what the difference between Flash and Shockwave actually is — if you’ve ever played any browser games, it’s likely you’ve at least heard of both, or perhaps even thought they were one and the same. I’ve answered the question of how they differ on the internet before, so I am going to largely quote but also elaborate upon what I’ve explained previously.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/915/1*5w5P4pgw73QJyD1oCO9TFw.png" /></figure><p>First, we must take a look back at Macromedia’s earlier history. If you grew up during the multimedia boom, you likely recognize the Made With Macromedia logo from the cover of your favourite rich interactive multimedia CD-ROM videogame experience (is that enough buzzwords?) When you see this logo on the boxart of a game, it means that the game was made using a tool called Macromedia Director.</p><h3>Macromedia Director?</h3><p>Director has existed since 1985, though it originally had the name MacroMind VideoWorks. The MacroMind company later merged with Paracomp to become Macromedia. It was meant for the easy creation of applications without the need to learn a more advanced language like C++, while still remaining powerful and flexible. Director provided a <a href="http://www-it.fmi.uni-sofia.bg/courses/maten/module3/directortutor.html">movie metaphor</a> for application development — assets such as graphics and sound were <em>cast members,</em> and the on-screen interface was the <em>stage,</em> with the <em>score,</em> composed of many <em>frames,</em> controlling what the stage looked like. Interactivity was provided by <em>scripts,</em> which would manipulate the current <em>frame</em> of the movie.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/607/1*qcE3pnthB9fykG8mpvEexg.png" /><figcaption><a href="http://eclass.teiion.gr/modules/document/file.php/EPDO279/1.%20Director%20Basics.pdf"><em>Director’s authoring environment featuring the “movie metaphor”</em></a></figcaption></figure><p>The goal of this metaphor, of course, was to make it easy to understand interface design with little programming knowledge required.</p><p>A great appeal of Director was that it could import many different file formats. Bitmaps, sounds, QuickTime videos, JPEG, MP3, Animated GIFs, you name it, Director could import those files and have them all interact off each other under the same roof — and, it was cross-platform, with both Mac and Windows support.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JEmb0wm8caneu8cqTRExjw.png" /><figcaption>Screenshots of Journeyman Project: Turbo (left) and Spaceship Warlock (right,) games created using Director</figcaption></figure><p>Director was the driving force behind games such as 1991’s <a href="https://obscuritory.com/essay/joe-sparks-interview/">Spaceship Warlock</a> by Mike Saenz and Joe Sparks, or 1993’s <a href="https://en.wikipedia.org/wiki/The_Journeyman_Project">Journeyman Project: Turbo</a> by Presto Studios, both pre-rendered adventure titles. There’s a great deal of interesting history to Director’s development — if you’d like to read more about it, there’s an <a href="http://lingoworkshop.com/Articles/history">extensive history article on Lingo Workshop,</a> but I want to get back to how this relates to Shockwave.</p><h4>The Internet Is A Series Of Tubes</h4><p>Naturally, Macromedia sought to bring this technology to the internet, as a quote from the original creator of Director, Marc Canter, in 1995, reveals.</p><blockquote>It becomes increasingly more apparent that CD-ROM is not the only form for delivery for multimedia content. Various forms of broadband distribution will come into place throughout the world this century, and Director will form a bridge across these platforms to guarantee compatibility and scalability of your creative work.</blockquote><p>They didn’t want Director to just be limited to CD-ROMs, they wanted it in your web browser too. There was just one problem: Director files were big, often many MBs in size — fine for CDs, but a no go for 1995’s internet. The answer? Compression.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/307/1*RYDRNyAFYAYhxN5pLsY1mA.jpeg" /><figcaption>The logo for Macromedia Shockwave</figcaption></figure><p>“Shockwave” was Macromedia’s term which meant “compressed for the web.” The first entry in the Shockwave line of products was Shockwave Director Player — so called because it was a <strong>player</strong> for <strong>Director</strong> content which had been <strong>compressed for the web.</strong> Because it was, at the time, the first and only product in the Shockwave line of products, Shockwave Director Player was often shortened to just “Shockwave.” This will come up again later.</p><h4>Shockwave’s Early Years</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*ohESgVP6Exm-okWxBxp4TA.png" /><figcaption>Toy Story Concentration: the first commercial use of Shockwave</figcaption></figure><p>According to <a href="http://www.dlanemedia.com/">D. Lane Media,</a> “the Toy Story Concentration game produced for Buena Vista Pictures marked the first commercial use of Shockwave on the World Wide Web.” At only 240 KB, the game was simple, but quicker to download thanks to the compression technology.</p><p>Another early adopter was indie developer <a href="https://ezone.com/">Ezone,</a> who used Shockwave for their first game “Lenny in the Dingo’s Den.” Game programmer Simon Edis recalls the story.</p><blockquote>We put it up on our site and registered it with the only search engine around at the time ‘Yahoo’. If you went into the ‘Games’ category on Yahoo I think there were only about 5 links and one of them was for Lenny.</blockquote><p>Ezone went on to make webgames for Universal, Disney and Nickelodeon, and now develop games for the Nintendo Switch.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FR-tOVMRiaxY%3Ffeature%3Doembed&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DR-tOVMRiaxY&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FR-tOVMRiaxY%2Fhqdefault.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/87a06c47769ec2647140e2b201b90d30/href">https://medium.com/media/87a06c47769ec2647140e2b201b90d30/href</a></iframe><p>Things were looking good for Shockwave as the go-to medium to provide interactive experiences over the internet. However, a new, unsuspecting technology was on the horizon — a new tool which, given enough time, would steal the browser plugin spotlight.</p><h3>Macromedia Flash.</h3><p>In the beginning — and by the beginning I mean 1995, the same year that the Shockwave plugin released — there was a company called FutureWave Software. FutureWave had a product called FutureSplash, which was a vector drawing application. FutureWave realized their technology had potential on the web, and they pitched it to Adobe, who turned it down at the time. However, there was another company that was more keen on the idea.</p><p>In the November of 1996, Macromedia acquired FutureSplash, and decided to shorten its name… to Flash. This was well after the introduction of the well established Director with its Shockwave plugin, and Flash had a much smaller scope: it was a simple graphics and animation tool capable of creating buttons, menus, banners and fancy text, and little more. It had basic scripting in the form of ActionScript, but nothing that could match the advanced and powerful Lingo scripting language Director provided.</p><p>Now, Macromedia was faced with a similar problem to what they had with Director. They wanted Flash content to be playable in the browser, but it’d be too slow to download over the internet. So the answer? Compression. It was time to add a new product to the Shockwave line of products.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/1*bGYYbJMKXZXv31gordPspg.jpeg" /></figure><p>So, Macromedia created Shockwave Flash Player. Remember, <em>Shockwave was Macromedia’s word which meant “compressed for the web.”</em> So the Shockwave Flash Player was a <strong>player</strong> for <strong>Flash</strong> content which had been <strong>compressed for the web.</strong> Hence the name, Shockwave Flash Player.</p><p>So there was a Shockwave Director Player for compressed Director content, and a Shockwave Flash Player for compressed Flash content. This naming scheme makes sense when you can see the full picture, but in reality, the majority of people by this point were familiar with Shockwave Director Player as just “Shockwave.” To those uninitiated, it now appeared that there was both a Shockwave AND a Shockwave Flash.</p><p>As a result, Shockwave Flash Player was more often referred to as just Flash, to avoid confusion with what was already being referred to as Shockwave. So when we say Shockwave, we’re referring to the first word in Shockwave Director Player, but when we say Flash, we’re referring to the second word in Shockwave Flash Player.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*o0rTyG2uECtaN9hcXbuXYA.png" /><figcaption>The latest version of Shockwave still references Director in the Add-ons Manager</figcaption></figure><p>When Adobe acquired these names in 2005, they decided to roll with what, by this point, was popular convention, and rename Shockwave Director Player to just Shockwave and Shockwave Flash Player to just Flash. The filetype SWF originally stood for ShockWave Flash, but Adobe now defined it instead as an acronym for <a href="https://www.pcmag.com/encyclopedia/term/55333/swf">Small Web Format,</a> to further avoid confusion.</p><p>There was actually a third Shockwave plugin by Macromedia — the seldom mentioned <a href="https://download.cnet.com/Authorware-Web-Player/3000-2139_4-51364.html">Shockwave Authorware Player,</a> which was primarily used for educational purposes, and was discontinued in 2007, several years after the last release in 2003.</p><h4>Flash Can’t Do Videogames!</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3NxDKpt6mHqpiOtKQ8QWCQ.jpeg" /><figcaption>Alien Hominid, of Newgrounds fame, is one of many games made in Flash — but it wasn’t always obvious Flash was a viable medium for games</figcaption></figure><p>In retrospect, it seems laughable, but around the time period of Flash’s introduction, the prospect of creating a game in Flash seemed impossible. Don’t take my word for it — let’s read some articles that were written during this era.</p><p>In the article <a href="http://director-online.dasdeck.com/buildArticle.php?id=818">Director is Dead?</a> written March 6, 2000, Alan Levine wrote the following.</p><blockquote>Out on my thin limb here, I cannot remotely see how Flash will encroach on the domain of Director and just shake my head at people who do not see the immense differences between these tools. In its present version, Flash is an incredible delivery platform for mostly linear content through an agonizing interface. For making Eyecandy. Okay a bunch of ActionScripted buttons can provide branching, but the ‘programmable’ brains behind is miniscule compared to Lingo. And the script environment will send you screaming into the night.</blockquote><p>Furthermore, in the article <a href="http://director-online.dasdeck.com/buildArticle.php?id=126">Let the eat Java</a> <em>[sic,]</em> written March 9, 1998, Zac Belado commented on the fact that browsers would ship with Flash but not Shockwave.</p><blockquote>It may sound cynical but it’s really the only thoughts you can have when you see a wonderful technology like Shockwave get short shrift compared to Flash. Flash is a very cool technology but aside from smooth looking eyecandy, what can it do? Can you make a database front-end with it? Can you make a game with it? Can you generate a robust website navigation system with it?</blockquote><p>These articles, obviously, have aged poorly, as we now know games, and robust website navigation systems, were in fact completely possible in Flash — or at least, were going to be, with improvements to its scripting language, ActionScript, that were inspired by Flash’s increasing popularity.</p><h3>So What Happened?</h3><p>You may well be aware that Flash Player will be discontinued in 2020. Adobe announced this years in advance, so we could all prepare for when it happened, because the industry was so dependent on Flash for a time. What you may not know is that Shockwave was already <a href="https://helpx.adobe.com/shockwave/shockwave-end-of-life-faq.html">discontinued earlier this year</a> — on April 9, 2019, with one month of notice and little fanfare.</p><p>Why did Flash steal the spotlight? What happened to Shockwave, which looked like such a promising technology at the dawn of the net?</p><p>Well, the answer is that Flash became more popular — vastly more popular — and that’s primarily for three good reasons.</p><p>The first reason is the price tag. Perhaps Macromedia thought that with the advanced capabilities of Director, it was worth the $1000 price tag as opposed to Flash’s $400. The reality of the situation, however, is that people don’t like advanced. People like simple, and Flash was simple to use.</p><p>This naturally coincides with the other reason why Flash was the better choice: it was simpler and more generally useful. Put yourself in the shoes of a web designer during this time: Flash can make banners, menus, buttons, and advertisements. Flash was a one man band. You could create your art and script it too! Director couldn’t do any of that by itself — you needed to import existing media, created using another tool.</p><p>Finally, in combination with these reasons, around the time period of 1998–2000 Macromedia began pushing for deals with OEMs such as Dell and Apple to include Flash with PCs, which meant that a great deal of users had Flash without the need to even download it. However, Director did manage to hold on in one key area…</p><h4>The Single Reason Anyone Used Shockwave After Flash’s Takeover</h4><p>There was one feature Shockwave had that Flash didn’t get until late in its life. It’s a feature that Director never originally had, but that it got in version 8.5 (released in April 2001,) and it was a game changer: Shockwave 3D. Now, Flash did eventually get Stage3D, but it didn’t perform as well, and was very late to the party, since it wasn’t included with Flash until version 11 (in 2011.) Director’s 3D Lingo became a major selling point, to the extent that 3D web content was virtually the primary reason to use Shockwave after Adobe acquired it in December 2005.</p><p>First announced in the summer of 2000 <a href="http://director-online.dasdeck.com/buildArticle.php?id=891">at SIGGRAPH,</a> Shockwave 3D was developed as a joint effort between Macromedia and Intel, based on Intel 3D’s IFX Toolkit. According to <a href="https://www.okino.com/conv/exp_sw3d.htm">Okino,</a> it was highly anticipated.</p><blockquote>Almost every major 3D company bought into the idea of exporting their 3D content to the .w3d file format, for the desired purpose of streaming their 3D data quickly across the Internet to the large installed user base of Shockwave players. Considerable development effort, enthusiasm and marketing was invested in these custom Shockwave-3D exporters and related support software in each major 3D animation product, including Okino’s own software products.</blockquote><p>Well into the mid-2000s, game portals such as Miniclip and AddictingGames made use of Shockwave 3D. Notable developers of Shockwave 3D games include Robotduck, Xform, and Kinelco. <a href="https://www.macworld.com/article/1017332/shockwave.html">MacWorld reported</a> on Shockwave 3D’s exciting future.</p><blockquote>If you’ve been waiting for Shockwave 3D Web content, wait, no longer. It’s here from big names such as CBS Sports, FoxKids, Lego, National Geographic and Shockwave.com.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c8od6DuA3b7bMJld3yh_xw.png" /><figcaption>LEGO Studios Backlot by Templar Studios: an early use of Havok Physics with Shockwave 3D</figcaption></figure><p>The introduction of the Havok Physics Engine to Director was also put to great use. One of the earliest examples of Havok Physics in a Shockwave 3D game was LEGO Studios Backlot from 2002, a Shockwave 3D game by Templar Studios, which has you explore and interact with objects in a LEGO movie set.</p><p>Robotduck produced a total of <a href="http://robotduck.com/gameography">62 games,</a> many of which made use of Shockwave 3D. Notable amongst them is M3Power Jetski Challenge, an advertisement for Gilette which had “over 100 million game plays… making it the most successful advergame on the Internet,” <a href="https://web.archive.org/web/20120214181224/http://corporate.miniclip.com:80/advertising/advergames">according to Miniclip.</a></p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FDftyWZOugdI%3Ffeature%3Doembed&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DDftyWZOugdI&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FDftyWZOugdI%2Fhqdefault.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/0bbaa68971f2e6b2cfcd066b4f21e2fb/href">https://medium.com/media/0bbaa68971f2e6b2cfcd066b4f21e2fb/href</a></iframe><p>Perhaps one of the most ambitious uses of Shockwave 3D was for Burnin’ Rubber 4 by Xform, originally released in 2010. It can be <a href="https://xformgames.itch.io/burnin-rubber-4">purchased on itch.io</a> as of 2018, and is a racing game featuring five large free-roaming worlds.</p><p>Another impressive game was Nick Kang’s <a href="http://rasterwerks.com/game/phosphor/beta2.asp">Phosphor Beta,</a> a multiplayer first person shooter, originally conceived in 2007, which received many updates.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C7WrY_fA9JfU6VyNWIPOtA.png" /><figcaption>Phosphor Beta by Rasterwerks is an advanced display of Shockwave 3D’s capabilities</figcaption></figure><p>What’s ironic about this is that Director was originally used for 2D, pre-rendered, point and click adventures, and as time went on, it fell out of use for that purpose and became almost exclusively for advanced realtime 3D rendered experiences. Paul Blart: Mall Cop and Journeyman Project are built upon the same technology, yet the two couldn’t be more polar opposite.</p><p>Shockwave was never originally meant to be used solely for 3D, and yet, it eventually was, thanks to Flash virtually replacing it for other purposes — and as much as I like 3D games, it feels like Shockwave never reached its full potential.</p><h3>Marc Canter - Storytelling Meme Beings on Twitter</h3><p>Have I told you how much our users still love our products (30 years later) - despite the VCs taking over, never really understanding what the product is about, sucking profits out of the product, selling off the company and then discarding it? This is what VC causes.... https://t.co/ci7s4UCIT5</p><h3>Terry R. Schussler on Twitter</h3><p>Retro animation created in Macromind Director (before Macromedia lost its mind and Adobe choked on the bones) from the genius of @pinot #DirectorIsNotDead https://t.co/PgYQoQIVsK</p><p>Apparently, I’m not alone in that thinking.</p><h4>The Beginning Of The End</h4><p>The latest version before the Adobe acquisition was Director MX 2004 (aka version 10.0) which had originally released in, well, 2004, but continued getting updated — even for a little while after the acquisition — until March 14, 2006 with the final patch, version 10.1.1.16. However, after this final patch to Director MX 2004, there was a long period of silence during which much speculation was had in regards to how Adobe would handle the beloved software.</p><p>A new version of Director would not be seen until Director 11 in 2008. This was Adobe’s first new major Director version release. The biggest change that was made was adding Unicode support — which while certainly useful, was underwhelming as the main selling point of a new major version.</p><p>A more useful update came in the form of <a href="https://www.macworld.com/article/1139581/director.html">Director 11.5</a> in March 2009, which boasted a new audio mixer, byte arrays, H.264 codec playback, and MacOS Leopard support. While this wasn’t enough to warrant a new version number, it seemed that Adobe was still paying Director some attention. Unfortunately, it would not be for long.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C0WLodRkAjk4qlHipSLrdg.jpeg" /><figcaption>The logo for Director 12</figcaption></figure><p>Director 12, released February 11, 2013, was the last Director version, and introduced the ability to publish to iOS and added more advanced 3D features such as stereoscopy. Director never was updated to be 64-bit compatible, and for this reason, Director applications built for Mac are no longer supported as of MacOS Catalina.</p><p>As such, in February 2017, <a href="https://www.ibtimes.com/adobe-ends-macromedia-discontinuing-adobe-director-contribute-shockwave-mac-support-2482677">Director and Shockwave for Mac were discontinued.</a> The Shockwave Player for Windows was maintained until more recently, on April 9, 2019, when it was discontinued as well. Since Shockwave’s EOL, a few very inconvenient bugs have already cropped up.</p><p>Most notably, Shockwave 3D isn’t compatible with newer Nvidia graphics cards on Windows 10, due to a basic <a href="https://gaming.stackexchange.com/questions/339173/how-can-i-play-dcr-shockwave-games/339841#339841">buffer overflow</a> error when reading hardware specifications. There is also a bug in which timestamps are always zero, meaning they now always correspond to the date of January 1, 1970.</p><p>All of this is on top of the fact that mainstream browsers, such as Google Chrome or Mozilla Firefox, no longer support plugins. With browsers no longer supporting plugin-based content, websites that host these games will see a decline in revenue and disappear, as we’ve already begun to observe.</p><h3>This Is Why Flashpoint Is So Important</h3><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FqrU6RJbeKfo%3Ffeature%3Doembed&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DqrU6RJbeKfo&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FqrU6RJbeKfo%2Fhqdefault.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/f737bb4af9870167f79d18a9b8421c14/href">https://medium.com/media/f737bb4af9870167f79d18a9b8421c14/href</a></iframe><p>There is an entire era of gaming at risk of disappearing if we don’t act soon. Shockwave is deader than Flash, webgames are largely seen as a fad that has ended, and if we don’t act quickly to preserve Shockwave games, they will meet a similar fate to that of silent films.</p><p>Thankfully, BlueMaxima’s Flashpoint provides a solution. We have configured over 1000 Shockwave games to be easily playable at the click of a mouse, resolving any compatibility issues and with no additional setup. If our Lingo experts can’t get your Shockwave game running on today’s computers, nobody can.</p><p>In the aftermath of Shockwave’s discontinuation, and with Adobe no longer providing support, Flashpoint is the largest repository of Shockwave content the web has to offer — find us on our <a href="http://bluemaxima.org/flashpoint">official website!</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8f3647865a7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/bluemaximas-flashpoint/the-story-of-shockwave-and-3d-webgames-8f3647865a7">The Story Of Shockwave And 3D Webgames</a> was originally published in <a href="https://medium.com/bluemaximas-flashpoint">BlueMaxima’s Flashpoint</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>