Shawn Hargreaves Blog

SimpleMath is now part of the DirectX ToolKit

Shawn Hargreaves - MSFT — Fri, 22 Feb 2013 22:16:46 GMT

Just a quick note to let y'all know that the SimpleMath header has been merged into the DirectX Tool Kit on CodePlex.

DirectXTK now supports loading and drawing 3D models

Shawn Hargreaves - MSFT — Sat, 26 Jan 2013 04:27:00 GMT

Chuck, awesome fellow that he is, has been slaving away on a 3D model loading solution for the DirectX Tool Kit. Documentation here. I won't bother to repeat all the details in this post, but as a quick summary:

This is an implementation of a mesh renderer similar to the XNA Game Studio Model, ModelMesh, ModelMeshPart design. It can load data from two different model formats:

The .cmo format used by the Visual Studio 3D Starter Kit. This is a basic format with an extremely simplistic material system, but can be handy because the ability to convert from .fbx to .cmo is built into Visual Studio 2012.

The .sdkmesh format used by the legacy DirectX SDK. This is a more advanced format than .cmo, with a richer feature set. You can get a .fbx to .sdkmesh converter here.

Note: Model currently only supports rigid models. Support for animation, skinning, and frame hierarchy is on our radar for the future, but not yet implemented.

Check it out, let us know what you think, and a big thank you to Chuck for filling what until today was the biggest hole in our little toolkit!

Where should SimpleMath live?

Shawn Hargreaves - MSFT — Tue, 15 Jan 2013 20:03:00 GMT

Feb 2013 update: in response to overwhelming popular opinion, SimpleMath has now been merged into the DirectX Tool Kit on Codeplex.

---

I am curious what folks think is the right long term home for the SimpleMath helper code?

A post on my blog is fine
The MSDN code gallery
Merge it into DirectXTK (seems kinda weird to me, as SimpleMath isn't really a DirectX graphics helper like the other code in there)
A standalone CodePlex project (also seems kinda weird, as SimpleMath is so small)
Other?

SimpleMath - a simplified wrapper for DirectXMath

Shawn Hargreaves - MSFT — Tue, 08 Jan 2013 22:39:00 GMT

Feb 2013 update: SimpleMath has now been merged into the DirectX Tool Kit on Codeplex.

---

SimpleMath, created by my colleague Chuck Walbourn, is a header file that wraps the DirectXMath SIMD vector/matrix math API with an easier to use C++ interface. It provides the following types, with similar names, methods, and operator overloads to the XNA Game Studio math API:

Vector2
Vector3
Vector4
Matrix
Color
Plane
Quaternion
Ray
BoundingSphere
BoundingBox

Download SimpleMath here.

Why wrap DirectXMath?

DirectXMath provides highly optimized vector and matrix math functions, which take advantage of SSE SIMD intrinsics when compiled for x86/x64, or the ARM NEON instruction set when compiled for an ARM platform such as Windows RT or Windows Phone. The downside of being designed for efficient SIMD usage is that DirectXMath can be somewhat complicated to work with. Developers must be aware of correct type usage (understanding the difference between SIMD register types such as XMVECTOR vs. memory storage types such as XMFLOAT4), must take care to maintain correct alignment for SIMD heap allocations, and must carefully structure their code to avoid accessing individual components from a SIMD register. This complexity is necessary for optimal SIMD performance, but sometimes you just want to get stuff working without so much hassle!

Enter SimpleMath...

These types derive from the equivalent DirectXMath memory storage types (for instance Vector3 is derived from XMFLOAT3), so they can be stored in arbitrary locations without worrying about SIMD alignment, and individual components can be accessed without bothering to call SIMD accessor functions. But unlike XMFLOAT3, the Vector3 type defines a rich set of methods and overloaded operators, so it can be directly manipulated without having to first load its value into an XMVECTOR. Vector3 also defines an operator for automatic conversion to XMVECTOR, so it can be passed directly to methods that were written to use the lower level DirectXMath types.

If that sounds horribly confusing, the short version is that the SimpleMath types pretty much Just Work™ the way you would expect them to.

By now you must be wondering, where is the catch? And of course there is one. SimpleMath hides the complexities of SIMD programming by automatically converting back and forth between memory and SIMD register types, which tends to generate additional load and store instructions. This can add significant overhead compared to the lower level DirectXMath approach, where SIMD loads and stores are under explicit control of the programmer.

Who is SimpleMath for?

You should use SimpleMath if you are:

Looking for a C++ math library with similar API to the C# Microsoft.Xna.Framework types
Porting existing XNA code from C# to C++
Wanting to optimize for programmer efficiency (simplicity, readability, development speed) at the expense of runtime efficiency

You should go straight to the underlying DirectXMath API if you:

Want to create the fastest possible code
Enjoy the lateral thinking sometimes needed to express an algorithm in terms of SIMD operations

This need not be a global either/or decision. The SimpleMath types know how to convert themselves to and from the corresponding DirectXMath types, so it is easy to mix and match. You can use SimpleMath for the parts of your program where readability and development time matter most, then drop down to DirectXMath for performance hotspots where runtime efficiency is more important.

Example

Here is a simple object movement calculation, implemented using DirectXMath. Note the skullduggery to make sure the PlayerCat instance will always be 16 byte aligned (and I didn't even include the implementation of the AlignedNew helper here!)

    #include <DirectXMath.h>

    using namespace DirectX;


    __declspec(align(16)) class PlayerCat : public AlignedNew<PlayerCat>
    {
    public:
        void Update()
        {
            const float cFriction = 0.99f;

            XMVECTOR pos = XMLoadFloat3A(&mPosition);
            XMVECTOR vel = XMLoadFloat3A(&mVelocity);

            XMStoreFloat3A(&mPosition, pos + vel);
            XMStoreFloat3A(&mVelocity, vel * cFriction);
        }

    private:
        XMFLOAT3A mPosition;
        XMFLOAT3A mVelocity;
    };

Using SimpleMath, the same math is, well, a little more simple :-)

    #include "SimpleMath.h"

    using namespace DirectX::SimpleMath;


    class PlayerCat
    {
    public:
        void Update()
        {
            const float cFriction = 0.99f;

            mPosition += mVelocity;
            mVelocity *= cFriction;
        }

    private:
        Vector3 mPosition;
        Vector3 mVelocity;
    };

Here is the x86 SSE code generated for the DirectXMath version of the Update method:

     movaps      xmm2,xmmword ptr [ecx+10h]
     movaps      xmm1,xmmword ptr [ecx]
     andps       xmm2,xmmword ptr [?g_XMMask3@DirectX@@3UXMVECTORI32@1@B]
     andps       xmm1,xmmword ptr [?g_XMMask3@DirectX@@3UXMVECTORI32@1@B]
     movaps      xmm0,xmmword ptr [__xmm@3f7d70a43f7d70a43f7d70a43f7d70a4]
     addps       xmm1,xmm2
     mulps       xmm0,xmm2
     movq        mmword ptr [ecx],xmm1
     shufps      xmm1,xmm1,0AAh
     movss       dword ptr [ecx+8],xmm1
     movq        mmword ptr [ecx+10h],xmm0
     shufps      xmm0,xmm0,0AAh
     movss       dword ptr [ecx+18h],xmm0
     ret

The SimpleMath version generates slightly more than twice as many machine instructions:

     movss       xmm2,dword ptr [ecx]
     movss       xmm0,dword ptr [ecx+4]
     movss       xmm1,dword ptr [ecx+0Ch]
     unpcklps    xmm2,xmm0
     movss       xmm0,dword ptr [ecx+8]
     movlhps     xmm2,xmm0
     movss       xmm0,dword ptr [ecx+10h]
     unpcklps    xmm1,xmm0
     movss       xmm0,dword ptr [ecx+14h]
     movlhps     xmm1,xmm0
     addps       xmm2,xmm1
     movss       dword ptr [ecx],xmm2
     movaps      xmm0,xmm2
     shufps      xmm0,xmm2,55h
     movss       dword ptr [ecx+4],xmm0
     shufps      xmm2,xmm2,0AAh
     movss       dword ptr [ecx+8],xmm2
     movss       xmm1,dword ptr [ecx+0Ch]
     movss       xmm0,dword ptr [ecx+10h]
     unpcklps    xmm1,xmm0
     movss       xmm0,dword ptr [ecx+14h]
     movlhps     xmm1,xmm0
     mulps       xmm1,xmmword ptr [__xmm@3f7d70a43f7d70a43f7d70a43f7d70a4]
     movaps      xmm0,xmm1
     movss       dword ptr [ecx+0Ch],xmm1
     shufps      xmm0,xmm1,55h
     shufps      xmm1,xmm1,0AAh
     movss       dword ptr [ecx+10h],xmm0
     movss       dword ptr [ecx+14h],xmm1
     ret

Most of this difference is because I was able to used aligned loads and stores in the DirectXMath version, while the SimpleMath code must do extra work to handle memory locations that might not be properly aligned. Also note how the SimpleMath version loads the mVelocity value from memory into SIMD registers twice, while the extra control offered by DirectXMath allowed me to do this just once.

But hey, sometimes performance isn't the most important goal. If you care more about optimizing for developer efficiency, SimpleMath could be for you.

Resources

A brewing puzzle: solution

Shawn Hargreaves - MSFT — Tue, 04 Dec 2012 17:52:50 GMT

Kudos to Clayton, mantis, and MannekinPis, who were on the right track about how to make beer in 17th century Germany. The trick to exactly hitting arbitrary temperatures without a thermometer lies in the fact that boiling water is always 212 °F.

Ice is not relevant here, though. For one thing, ice does not have a single fixed temperature, and can be much colder than freezing point. For another, Hans does not have a freezer, electricity, or any other way to make ice!

A traditional brewing technique is:

Take 10 gallons of water from the well. Underground temperatures are extremely steady throughout the year, so this will not vary by more than a degree or two. Hans must learn by trial and error what temperature his particular well happens to produce. Let’s say this is 50 °F.
Measure out 6.3 gallons, and bring it to a boil.
Mix everything back together. 3.7 gallons at 50 °F plus 6.3 gallons at 212 °F = the desired 152 °F.

There is no need to worry about heat loss once the mash is at the desired temperature. Five or ten gallons of hot liquid has a lot of thermal inertia, and can sit long enough for the enzymes to do their work without cooling too much.

More complex mashes (used to make various kinds of beer) require a series of different temperatures, which can be achieved by repeatedly boiling the appropriate portion of the liquid and then mixing back together. The measurement could be done by weight, but volume was more often used. It’s trivial to do this by ratio (“1 scoop into the small kettle, 2 into the big… 1 in the small, 2 in the big…”) without needing any dedicated measuring equipment at all. And having counted out the scoops once, future batches can hit the exact same temperatures just by remembering how close to the top each kettle was filled.

I think it’s pretty amazing that, armed with nothing more than two kettles, a ladle, and a fire, uneducated farmers were able to follow complex mashing schedules such as:

20 minutes at 109 °F (acid rest: phytase enzymes alter pH while beta-glucanase breaks down gums)
20 minutes at 122 °F (protein rest: proteolytic enzymes split up the longer protein chains)
30 minutes at 149 °F (saccharification rest: beta-amylase enzymes convert starch to sugar)
30 minutes at 158 °F (saccharification rest: alpha-amylase enzymes convert starch to sugar)
10 minutes at 168 °F (mash out: denatures all enzymes, freezing the mash chemistry in its current form)

and consistently get within a few degrees of each target temperature.

But what really blows my mind is how anyone managed to figure out the right temperatures to make great beer, long before we understood enzymes or starch molecules! Those medieval monks must have had a LOT of spare time to experiment :-)

A brewing puzzle

Shawn Hargreaves - MSFT — Tue, 04 Dec 2012 00:43:59 GMT

Warning: this post is not about programming. Andy suggested I should sneak some homebrewing material onto my blog, and I thought hmm, why not? If you violently object, let me know in the comments and I won't do it again :-)

Yesterday I brewed a traditional German hefeweizen, which was the first time I tried a decoction mash. This got me thinking about how incredibly accurate traditional brewers managed to be, long before the arrival of chemistry, biology, or scientific measuring tools. This particular trick might be obvious to people with a stronger background in physics, but I thought it was pretty amazing. So, a puzzle...

Hans is a 17th century German brewer. He wants to attract a loyal customer base who will seek out his beer in preference to that of competitors. To achieve this, he must:

Make beer that people like to drink
Make it the same way every time, so customers come to trust the quality of his product

One of the key steps in brewing is heating a mix of water and crushed malted barley (called the "mash") to 152 °F, where amylase enzymes will convert starch molecules into sugars that yeast can later ferment into alcohol. But Hans does not have access to a thermometer, so he has no way to accurately hit the right temperature. He can estimate by sticking his finger in the mash, but even with lots of practice this is horribly inaccurate. Sometimes he ends up at 148 °F, which produces a dry, thin beer. Other days he ends up at 158 °F, which gives a thick, syrupy end result. One time he overshot all the way to 170 °F, which accidentally denatured the enzymes, leaving him with a couple of tons of watery grain that could no longer be used to make beer at all!

Is it possible to do better? How can Hans heat his mash to exactly 152 °F without the use of a thermometer?

Debugging Direct3D programs: a taxonomy of error conditions

Shawn Hargreaves - MSFT — Tue, 27 Nov 2012 23:01:16 GMT

Eric Lippert wrote a fantastic article that categorizes C# exceptions into four categories:

Exogenous exceptions occur due to the messy nature of reality. Filesystems can run out of space. Network connections can drop. These things are rare, but they do happen and robust code needs to be ready to deal with them.
Boneheaded exceptions, as Eric puts it, "are your own darn fault, you could have prevented them and therefore they are bugs in your code. You should not catch them; doing so is hiding a bug in your code. Rather, you should write your code so that the exception cannot possibly happen in the first place".
Fatal exceptions occur when something truly unexpected went wrong (memory corruption, thread abort, etc.). Again in Eric's words, "not your fault, you cannot prevent them, and you cannot sensibly clean up from them. They almost always happen because the process is deeply diseased and is about to be put out of its misery".
Finally, Vexing exceptions are caused by design flaws where someone foolishly decided to throw an exception in response to a situation that was not truly exceptional. Sometimes you are forced to catch these in order to use the offending API, but ideally that API should be changed to report non-exceptional results in some other way (e.g. as return values).

At this point the attentive reader may be wondering, what on earth does C# exception handling have to do with D3D? In a COM based C++ API such as D3D, errors are reported via HRESULT return values, not exceptions, right?

Not so fast...

D3D actually has three different mechanisms for reporting errors, which exactly correlate to the first three of Eric's exception categories. There is no equivalent of vexing exceptions, because the D3D API does not use exceptions.

Exogenous errors In D3D

D3D reports exogenous errors by returning failure HRESULT codes. You should always check these return values and handle any failures.

Note that some D3D methods have a return type of void instead of HRESULT. This is because not all methods have any exogenous failure paths. For instance the ID3D11Device::CreateBlendState method returns an HRESULT (which you should check and handle) but ID3D11DeviceContext::OMSetBlendState returns void. This does not mean it is impossible for OMSetBlendState to fail, but that there is no point checking a return value because all the possible OMSetBlendState failures are boneheaded or fatal. You could pass a null pointer or try to set a state object that had previously been released, but as long as you specify valid parameters OMSetBlendState will always succeed.

Boneheaded errors in D3D

By default, D3D does not bother to check for boneheaded errors at all. This is because it takes some time to validate everything, and hey, this should be unnecessary as long as you don't have any bugs in your program, right? :-)

If you do make a boneheaded error calling into D3D, the result is undefined behavior. You might get lucky and the call happens to work like you expect in spite of the mistake, or it might work on one computer but not on others, or it might crash, or it might mess things up so some other call crashes later on, or you might just get weird rendering results. This is not good.

D3D provides an optional debug layer to help you find and fix such problems. This is enabled if you pass the D3D11_CREATE_DEVICE_DEBUG flag when creating your D3D device. It adds detailed parameter and state validation, which slows things down but will print nice messages back to the debugger output pane if it finds any boneheaded errors.

If you used the Windows 8 or Windows Phone 8 project templates as a starting point for your D3D app, the debug layer will be turned on by default in debug builds. The Direct3DBase::CreateDeviceResources method does this like so:

      UINT creationFlags = D3D11_CREATE_DEVICE_BGRA_SUPPORT;

  #if defined(_DEBUG)
      // If the project is in a debug build, enable debugging via SDK Layers with this flag.
      creationFlags |= D3D11_CREATE_DEVICE_DEBUG;
  #endif

It's always a good idea to test with the debug layer turned on, keep an eye on the output pane in Visual Studio, and fix any issues it complains about.

Fatal errors in D3D

Unexpected, non-recoverable D3D errors can (rarely) occur for several reasons:

The GPU hardware could hang due to a driver bug, hardware fault, overheating, etc. It must then be reset (basically rebooting the GPU) before rendering can continue. This is referred to as a TDR, which stands for Timeout Detection and Recovery.
The GPU could have been physically removed from the computer (which happens when undocking certain laptop models) or its driver could have been updated on the fly.
The driver could have a bug that got it into a messed up state.
The driver or D3D runtime could run out of memory in a place that isn't recoverable. Some allocation failures (for instance not having enough room to create a new texture) are easy to report back to the caller, but others (for instance failing to allocate an internal renamed resource while flushing a command buffer) could leave things in an ambiguous partial state where some amount of rendering might already have taken place yet other work cannot be completed. There is no good way to describe such a situation to the caller, and not really anything they could do to continue past the problem.
A boneheaded error could have gone unnoticed (especially if the debug D3D layer was not in use) so the D3D runtime passed invalid parameters through to the driver. What happens next is entirely up to the driver (this is undefined behavior!) but one likely outcome is for the driver to become horribly confused, fling its hands in the air, and shout huh? you want me to do whaaaat???

In all these cases things have gone badly wrong, and not in a clean way where D3D could report back that any single method call was rejected. We know the D3D device has ended up in a different state to what the program intended, but cannot describe exactly how things are different or what needs to happen to get everything back in sync. At this point D3D switches into a special "device removed" state. You can still call D3D methods, but they will be ignored and nothing will actually be rendered. When you eventually come to call Present, it will return one of the error codes:

DXGI_ERROR_DEVICE_REMOVED
DXGI_ERROR_DEVICE_RESET
DXGI_ERROR_DEVICE_HUNG
DXGI_ERROR_DRIVER_INTERNAL_ERROR

The only way to recover from device removed state is to destroy the broken D3D device, destroy all its associated resources, create a new device, and reload a whole new set of fresh resources. Some apps go to great pains to robustly handle this situation, but many (most?) games don't bother, and will just crash in response, or stop rendering and need to be killed by the user.

Note that D3D11 device removed state is different from the old D3D9 device lost behavior, which occurred any time the monitor switched between windowed and fullscreen mode (e.g. when pressing alt+tab). This was a common occurrence, so all D3D9 apps had to handle device lost. In D3D11, display mode switches are handled by the runtime without any special effort from the app. Device removed is reserved for situations where the state of the device is not well defined and thus no automatic recovery is possible, which is much rarer.

If you frequently run into device removed errors, the first step is to check the debug D3D layer to make sure these are not just knock-on consequences of an earlier boneheaded error.

Catalin Zima on converting textures to .dds

Shawn Hargreaves - MSFT — Thu, 15 Nov 2012 18:30:45 GMT

Catalin has a great article on how to convert textures to .dds format, which is the most efficient way to load images for use with Direct3D. He describes how to integrate the texconv tool (from DirectXTex) into Visual Studio using MSBuild, so textures can be automatically converted every time you build your project.

There's lots of other great stuff on his blog, too. You should subscribe, if you haven't already :-)

Beware of D3D feature level 11 in the Windows Phone emulator

Shawn Hargreaves - MSFT — Tue, 06 Nov 2012 16:58:36 GMT

Windows Phone 8 devices support Direct3D 11.1 feature level 9.3, but our emulator uses the WARP rasterizer, which can handle all the way up to feature level 11. This means that, if you aren't careful, it is possible to accidentally use more advanced D3D features while developing in the emulator, only to get an unpleasant surprise when these things don't work on an actual device.

Q: how to avoid unpleasant surprises?

A: make sure you explicitly select feature level 9.3, even when running in the emulator.

Starting with the Windows Phone Direct3D App project template, open up Direct3DBase.cpp, find this code in the CreateDeviceResources method:

    D3D_FEATURE_LEVEL featureLevels[] =
    {
        D3D_FEATURE_LEVEL_11_1,
        D3D_FEATURE_LEVEL_11_0,
        D3D_FEATURE_LEVEL_10_1,
        D3D_FEATURE_LEVEL_10_0,
        D3D_FEATURE_LEVEL_9_3
    };

and change it to:

    D3D_FEATURE_LEVEL featureLevels[] =
    {
        D3D_FEATURE_LEVEL_9_3
    };

Tada! Now you will be using 9.3 in the emulator, the same as on actual device hardware.

Right above this code, notice how the template turns on D3D11_CREATE_DEVICE_DEBUG only if the _DEBUG define is set? This enables extra validation to give more useful error messages if you make a mistake in your D3D API usage. But that validation is not free, so we only enable it in debug builds.

Speed: in which MSDOS meets Windows Phone 8

Shawn Hargreaves - MSFT — Thu, 01 Nov 2012 18:46:26 GMT

Inspired by long standing XNA team tradition, the Windows Phone graphics team recently spent some time using our product and trying to build some apps. One of our goals in supporting native C++ was to make it easier to port existing software and frameworks to the platform, so I thought, what is the most legacy thing I could possibly try to port? For App Week I took a game called Speed, which I wrote 13 years ago (last century!) in C (yep, that's C, not C++) using an MSDOS library called Allegro, and ported it to Windows Phone 8.

Check it out:

If you want to play this yourself, or look at the code, you can download it here:

Speed.zip

You'll need a copy of DirectXTK to build it (unzip into a folder named DirectXTK in the same location as the Speed.sln file). Although it runs ok in the Windows Phone emulator, you really need an actual device to play this properly. Touch input using left, right and center of the screen, not to mention tilt sensor input, doesn't work so well via a mouse!

Porting this turned out to be pleasingly straightforward. The OriginalGame folder contains, can you guess? Yup, that's the original C code, almost entirely unchanged since 1999. Meanwhile, allegro.h and allegro.cpp (in the PhonePort folder) provide an emulation layer which translates the necessary subset of the old Allegro API into D3D11, XAudio2 and WinRT calls. It uses DirectXTK SpriteFont for the text rendering, PrimitiveBatch and BasicEffect for all other graphics, XAudio2 for the music and sound effects, and WinRT ThreadPool::RunAsync to emulate Allegro timer interrupts.

A silly-but-I-think-kinda-neat thing about this game is that the music is entirely procedural. The init_music() function (in OriginalGame\sound.c) generates a set of single cycle waveform samples using sine, square, and sawtooth waves. Then the music_player() function is installed as a custom timer interrupt handler. This walks through a set of tables describing the pitch and duration of each note, and calls the Allegro voice functions to trigger or stop playback as appropriate. I didn't change this code at all, yet my emulation layer is good enough to play the music exactly as it sounded in the original.

For bonus points I added a bloom postprocess (implemented in PhonePort\Game.cpp) because, hey, this is 2012 after all :-)

DirectX Tool Kit now supports Windows Phone 8

Shawn Hargreaves - MSFT — Tue, 30 Oct 2012 23:42:14 GMT

I suspect this will come as no surprise to anyone who's been paying attention to what I've been working on recently...

The latest version of DirectXTK adds support for Windows Phone 8. In fact, DirectXTK pretty much already worked on WP8, which uses the same D3D11 API as Windows 8. The only changes in this release are:

Added project and solution files for use with the newly released Windows Phone SDK
Updated WICTextureLoader and SaveWICTextureToFile to indicate that these are not available on Windows Phone (which does not support WIC)
Updated the readme to match

Apollo has landed

Shawn Hargreaves - MSFT — Tue, 30 Oct 2012 23:41:00 GMT

The developer SDK for Windows Phone 8 (codename Apollo) is now available for download from an internet near you. Which means I can finally talk about what I’ve been working on this past year! I am dev lead for graphics, so I’ll probably have most to say about that area, but knowing me I’m sure I’ll find other topics to write about too.

This first post is basically just a bullet list summarizing the graphics capabilities of the platform:

Write games in high performance native C++
Or you can interop between XAML and C++/D3D, similar to the Silverlight/XNA interop feature in Mango
Graphics APIs are a subset of Windows 8, so it’s easy to move code back and forth between phones, tablets, and desktop PCs
Direct3D 11.1 API, targeting feature level 9.3 hardware capabilities
DirectXMath provides high performance SIMD vector math, optimized for SSE and NEON
XAudio2 provides game focused audio playback, mixing, and effects (ok, you got me, this one isn't graphics)
Not all Windows graphics components are supported on phone
- No WIC - use DirectXTex to preconvert textures to .dds format, then DirectXTK to load them
- No Direct2D or DirectWrite - use DirectXTK instead
- No legacy features such as GDI, D3DX, or fixed function - parts of these can be replaced with DirectXTK

What does D3D11 feature level 9.3 give you?

Shader model 4_0_level_9_3
Max texture size 4096
BC1-BC3 texture compression
Floating point texture formats
Conditional non-power-of-2 textures (can’t use wrap addressing or have mipmaps)
Multiple rendertargets
Hardware instancing
Occlusion queries
Separate alpha blend

Yes, you read that right. Shader model 4_0_level_9_3 means that programmable shaders are now fully supported on Windows Phone. But what is this 4_0_level_9_3 thing, you may well ask?

Not quite the same as D3D9 shader model 2.0
Uses HLSL 4.0 syntax
Similar features to vs_2_a and ps_2_b (think of it as 2.0 turned up to 11 :-)
Long pixel shaders (512 instructions)
Dynamic flow control
Gradient instructions

So what notable D3D11 features are NOT included in feature level 9.3?

No geometry shaders
No hull/domain shaders
No DirectCompute
No resource arrays
No BC4–BC7 compression
No vertex texture fetch

Another way to think of this: feature level 9.3 is basically the same as the XNA HiDef profile, except without vertex texture fetch.

Anything else important you should know?

Windows Phone 8 uses a tiled GPU architecture, so for best performance you'll need to understand how to use the D3D11_MAP_WRITE and D3D11_COPY flags to specify DISCARD and NOOVERWRITE behaviors, and when to call ID3D11DeviceContext1::DiscardView (ooh, good topic for future articles)
Native D3D apps handle their own rotation: this isn’t automatic like in XNA.
Windows Phone 8 device manufacturers can choose one of three screen resolutions:
- 480x800
- 720x1280
- 768x1280
Windows Phone 8 includes the same hardware scaler feature as WP7. Use this to draw at the same resolution on all devices (simplifying development) or to draw fewer pixels for better performance. Use the new DXGI_SCALING_ASPECT_RATIO_STRETCHED mode.

I think this is a pretty exciting set of capabilities, and am looking forward to seeing what y’all will be able to do with it. To whet your appetite, check out these screenshots from an HDR rendering demo created by my colleague Adrian. It's crazy that this does on a phone what would have been impossible on a high end gaming console of just 10 years ago, and at a higher resolution to boot!

DirectXTK PrimitiveBatch helper makes it easy to draw user primitives with D3D11

Shawn Hargreaves - MSFT — Sat, 13 Oct 2012 00:45:07 GMT

The latest version of DirectXTK adds a PrimitiveBatch helper, for easily and efficiently drawing dynamically generated geometry such as lines or triangles. This fills the same role as the legacy D3D9 APIs DrawPrimitiveUP and DrawIndexedPrimitiveUP. PrimitiveBatch manages the vertex and index buffers for you, using DISCARD and NO_OVERWRITE hints to avoid stalling the GPU pipeline. It automatically merges adjacent draw requests, so if you call DrawLine 100 times in a row, only a single GPU draw call will be generated.

PrimitiveBatch is responsible for setting the vertex buffer, index buffer, and primitive topology, then issuing the final draw call. Unlike the higher level SpriteBatch helper, it does not provide shaders, set the input layout, or set any state objects. PrimitiveBatch is often used in conjunction with BasicEffect and the structures from VertexTypes.h, but it can work with any other shader or vertex formats of your own.

To initialize a PrimitiveBatch for drawing VertexPositionColor data:

    std::unique_ptr<PrimitiveBatch<VertexPositionColor>> primitiveBatch(new PrimitiveBatch<VertexPositionColor>(deviceContext));

To draw a line:

    basicEffect->Apply(deviceContext);

    deviceContext->IASetInputLayout(inputLayout);

    primitiveBatch->Begin();
    primitiveBatch->DrawLine(VertexPositionColor(...), VertexPositionColor(...));
    primitiveBatch->End();

PrimitiveBatch provides five drawing methods:

DrawLine(v1, v2)
DrawTriangle(v1, v2, v3)
DrawQuad(v1, v2, v3, v4)
Draw(topology, vertices, vertexCount)
DrawIndexed(topology, indices, indexCount, vertices, vertexCount)

DirectXTK October 2012 release

Shawn Hargreaves - MSFT — Tue, 02 Oct 2012 23:58:04 GMT

The DirectX Tool Kit has been updated with two new features:

Added a ScreenGrab module for easily saving rendertarget contents into .dds or other image formats
Extended GeometricPrimitive.h with a new CreateGeoSphere method (thanks to my colleague Adrian Tsai for contributing this code!)

There are also some minor tweaks and bugfixes:

Moved DDSTextureLoader and WICTextureLoader into the DirectX C++ namespace
Renamed project files for better consistency
Extended WICTextureLoader to support Windows 8 96bpp floating point formats
Updated Win32 desktop projects to use Windows Vista (0x0600) rather than Windows 7 (0x0601) APIs
Tweaked SpriteBatch.cpp to workaround an ARM NEON compiler codegen bug

So what is this GeoSphere thingie, you may well ask, and why might it be better than a plain old fashioned UV sphere primitive? Shamelessly plagiarizing an explanation from Adrian:

Generally speaking, geospheres are more efficient than non-geodesic spheres (which are typically generated by using rings of vertices along the latitudes/longitudes of the sphere). In an ideal geosphere each triangle has the same area, which means an even distribution of vertices around the sphere. This means geospheres can give better visual quality at the same vertex count.

My implementation approximates an ideal geosphere by recursively subdividing a starting shape – in this case an octahedron. Almost any regular polyhedron can be used, but octahedrons or icosahedrons typically give best results. Starting with an icosahedron would give slightly more accurate results (i.e. it would produce an output closer to an ideal geosphere) but would make the implementation more complex.

Each successive subdivision increases the number of vertices by a factor of four. Hence the total number of vertices is approximately 4^(N+1), where N is the number of tessellations specified in CreateGeoSphere. A value of 3 or 4 is usually enough to give good results.

CreateSphere
Tessellation = 11
276 vertices

CreateGeoSphere
Tessellation = 3
277 vertices

DirectXTK samples?

Shawn Hargreaves - MSFT — Sat, 07 Jul 2012 17:31:16 GMT

Lots of people asking for samples for the DirectX Tool Kit - sorry I haven't had a chance to work on such a thing yet (I'm kinda busy right now getting Windows Phone 8 finished :-)

Would appreciate feedback on what platform you most want to see samples for (Win8 Metro? Classic Desktop?) and which areas of DirectXTK to prioritize (SpriteBatch? BasicEffect? DDS loading? other?)

Thanks!

DirectX Tool Kit is now on CodePlex

Shawn Hargreaves - MSFT — Mon, 18 Jun 2012 21:57:43 GMT

DirectX Tool Kit (aka DirectXTK) is a collection of helper classes for writing Direct3D 11 code for Metro style apps, Windows 8 Desktop, and Windows 7 'classic' applications in C++.

Features:

SpriteBatch - simple & efficient 2D sprite rendering
SpriteFont - bitmap based text rendering
Effects - set of built-in shaders for common rendering tasks
GeometricPrimitive - draws basic shapes such as cubes and spheres
CommonStates - factory providing commonly used D3D state objects
VertexTypes - structures for commonly used vertex data formats
DDSTextureLoader - light-weight DDS file texture loader
WICTextureLoader - WIC-based image file texture loader

http://directxtk.codeplex.com/

DirectXTex is a shared source library for reading and writing DDS files, and performing various texture content processing operations including resizing, format conversion, mip-map generation, block compression for Direct3D runtime texture resources, and height-map to normal-map conversion. This library makes use of the Windows Image Component (WIC) APIs. It also includes a simple .TGA reader and writer since this image file format is commonly used for texture content processing pipelines, but is not currently supported by a built-in WIC codec.

http://directxtex.codeplex.com/

DirectXTK now includes SpriteFont

Shawn Hargreaves - MSFT — Thu, 03 May 2012 00:32:00 GMT

The DirectX Tool Kit (DirectXTK) has been updated with the addition of a SpriteFont implementation, similar to the one in XNA.

Get it here: DirectXTK

Shamelessly plagiarizing the readme file:

This is a native D3D11 implementation of a bitmap font renderer, similar to the SpriteFont type from XNA Game Studio, plus a command line tool (MakeSpriteFont) for building fonts into bitmap format. It is less fully featured than Direct2D and DirectWrite, but may be useful for those who want something simpler and lighter weight.

At build time:

    MakeSpriteFont.exe "Comic Sans" myfile.spritefont /FontSize:16

During initialization:

    std::unique_ptr<SpriteBatch> spriteBatch(new SpriteBatch(deviceContext));

    std::unique_ptr<SpriteFont> spriteFont(new SpriteFont(device, L"myfile.spritefont"));

Simple drawing:

    spriteBatch->Begin();

    spriteFont->DrawString(spriteBatch.get(), L"Hello, world!", XMFLOAT2(x, y));

    spriteBatch->End();

The Draw method has several overloads with parameters controlling color, rotation, origin point, scaling, horizontal or vertical mirroring, and layer depth. These work the same way as the equivalent SpriteBatch::Draw parameters.

SpriteFont has three constructors:

Pass a filename string to read a binary file created by MakeSpriteFont
Pass a buffer containing a MakeSpriteFont binary that was already loaded some other way
Pass an array of Glyph structs if you prefer to entirely bypass MakeSpriteFont

If you try to draw or call MeasureString with a character that is not included in the font, by default you will get an exception. Use SetDefaultCharacter to specify some other character that will be automatically substituted in place of any that are missing.

This implementation supports sparse fonts, so if you are localizing into languages such as Chinese, Japanese, or Korean, you can build a spritefont including only the specific characters needed by your program. This is usually a good idea for CJK languages, as a complete CJK character set is too large to fit in a Direct3D texture! (if you need full CJK support, Direct2D or DirectWrite would be a better choice). SpriteFont does not support combining characters or right-to-left (RTL) layout, so it will not work for languages with complex layout requirements such as Arabic or Thai.

The MakeSpriteFont tool can process any TrueType font that is installed on your system (using GDI+ to rasterize them into a bitmap) or it can import character glyphs from a specially formatted bitmap file. This latter option allows you to create multicolored fonts, drawing special effects such as gradients or drop shadows directly into your glyph textures. Characters should be arranged in a grid ordered from top left to bottom right. Monochrome fonts should use white for solid areas and black for transparent areas. To include multicolored characters, add an alpha channel to the bitmap and use that to control which parts of each character are solid. The spaces between characters and around the edges of the grid should be filled with bright pink (red=255, green=0, blue=255). It doesn't matter if your grid includes lots of wasted space, because the converter will rearrange characters, packing everything as tightly as possible.

See readme.txt for a list of MakeSpriteFont command line options.

A reusable, reflection based command-line parser

Shawn Hargreaves - MSFT — Fri, 20 Apr 2012 23:55:09 GMT

I often find myself writing little throwaway utilities to help with other tasks, and many of these utilities need to parse command lines. There are myriad ways to do this in C#, ranging from the quick and dirty to the infinitely flexible and confusing. The middle ground approach shown here is not especially unique, but I have found it useful over the years, and thought I would post it here in case you do too.

Get it here.

Use it like so:

    public enum CatSpecies
    {
        Tabby,
        Siamese,
        Alley,
    }


    public class Options
    {
        public int NumberOfCats = 23;
        public CatSpecies Species = CatSpecies.Siamese;
        public bool ChaseTheCats;
        public bool PostToYouTube;
    }


    class Program
    {
        static int Main(string[] args)
        {
            var options = new Options();
            var parser = new CommandLineParser(options);

            if (!parser.ParseCommandLine(args))
                return 1;

            DoStuff(options);

            return 0;
        }
    }

You can run this program like so:

    MyProgram /NumberOfCats:10 /species:alley /posttoyoutube

It automatically generates usage help if you pass invalid values:

    > MyProgram /foo
    Unknown option 'foo'

    Usage: MyProgram

    Options:
        /NumberOfCats:value
        /Species:value
        /ChaseTheCats
        /PostToYouTube

You can mark some options as required:

    public class Options
    {
        [CommandLineParser.Required]
        public int NumberOfCats;

        [CommandLineParser.Required]
        public CatSpecies Species;

        public bool ChaseTheCats;
        public bool PostToYouTube;
    }

Required options are specified without the /ParameterName: prefix:

    MyProgram 10 alley /posttoyoutube

Of course you will get an error if any required parameters are not specified.

The parser also supports list types, which allow a single parameter to be specified more than once (each entry will be appended to the list). For instance:

    public class Options
    {
        [CommandLineParser.Required]
        public readonly List<string> Names = new List<string>();

        [CommandLineParser.Name("Color")]
        public readonly List<System.Drawing.Color> Colors = new List<System.Drawing.Color>();
    }

This allows you to call:

    MyProgram shawn tracy rhys boo kess finch /color:red /color:white

Note that I was able to specify System.Drawing.Color values by string name (eg. "red"). This works because the parser uses TypeDescriptor/TypeConverter to convert string arguments into whatever types it finds in the Options object. If you have custom types, just write a matching TypeConverter and you'll be able to specify them directly as argument values.

Enjoy!

CreateThread for Windows 8 Metro

Shawn Hargreaves - MSFT — Mon, 12 Mar 2012 20:13:00 GMT

The WinRT programming environment, which is used to create Metro applications for Windows 8, replaces the old Win32 threading APIs such as CreateThread with a new ThreadPool::RunAsync API. This is generally a good thing (ThreadPool is better than CreateThread for several reasons) but it can be a pain when trying to port existing code that depends on those older APIs.

Porting shim to the rescue! This code emulates a subset of the Win32 threading APIs as a wrapper on top of WinRT ThreadPool:

CreateThread
CREATE_SUSPENDED and ResumeThread
Partial support for SetThreadPriority (see comments in the header for details)
Sleep
Thread local storage (TlsAlloc, TlsFree, TlsGetValue, TlsSetValue, plus see header comments about TlsShutdown)

Get it here: ThreadEmulation.zip

I recommend only using this for porting legacy code. When writing new Metro applications, it is better to directly use WinRT ThreadPool.

SpriteBatch and BasicEffect for C++ Direct3D 11

Shawn Hargreaves - MSFT — Fri, 02 Mar 2012 21:38:00 GMT

Over the Christmas break I spent some time porting the built-in XNA effects (BasicEffect, SkinnedEffect, etc.) to native C++ using Direct3D 11. Finding that strangely enjoyable, I went on to make a C++ version of SpriteBatch, and also ported the XNA Primitives 3D sample, built-in state objects, and helper vertex types. And my colleague Chuck Walbourn chimed in with some code for easily loading Direct3D 11 textures.

Get it here: DirectXTK

Changelog:

3/5 - fixed bug in SpriteBatch with > 2048 sprites in a batch (thanks Pete Lewis!)
3/8 - added separate project files for Win8 Metro builds (thanks George Clingerman!)
5/2 - added SpriteFont implementation

Supported operating systems:

Windows 8 Consumer Preview (both Metro and Desktop)
Windows 7
Windows Vista with DirectX 11 update

Supported compilers:

Visual Studio 11 (currently in beta)
Visual Studio 2010 plus the standalone Windows 8.0 SDK (you need the SDK to get the latest version of DirectXMath, which this code depends on)

How to use it:

Unzip, load the solution into Visual Studio, and build it
Link your program with the resulting static lib
Add the Inc folder to your include path

To draw sprites:

    #include "SpriteBatch.h"

    using namespace DirectX;

    std::unique_ptr<SpriteBatch> spriteBatch(new SpriteBatch(deviceContext));

    spriteBatch->Begin();
    spriteBatch->Draw(texture, XMFLOAT2(x, y));
    spriteBatch->End();

To draw geometry using BasicEffect:

    #include "BasicEffect.h"

    using namespace DirectX;

    std::unique_ptr<BasicEffect> effect(new BasicEffect(device));

    effect->SetWorld(world);
    effect->SetView(view);
    effect->SetProjection(projection);

    effect->SetTexture(cat);
    effect->SetTextureEnabled(true);

    effect->EnableDefaultLighting();

    effect->Apply(deviceContext);

    deviceContext->IASetInputLayout(...);
    deviceContext->IASetVertexBuffers(...);
    deviceContext->IASetIndexBuffer(...);
    deviceContext->IASetPrimitiveTopology(...);

    deviceContext->DrawIndexed(...);

To draw geometric primitives:

    #include "GeometricPrimitive.h"

    using namespace DirectX;

    std::unique_ptr<GeometricPrimitive> teapot(GeometricPrimitive::CreateTeapot(deviceContext));

    teapot->Draw(world, view, projection, Colors::CornflowerBlue);

See the readme inside the zip for more info.

Bloom on Windows Phone

Shawn Hargreaves - MSFT — Fri, 20 Jan 2012 01:04:11 GMT

Ok, silliness aside, is it possible to implement an efficient bloom effect on Windows Phone without custom shaders?

Bloom consists of three operations:

Identify which parts of the image should be bloomed
Blur those parts
Combine blurred bloomy bits with the original image

There are many choices for how each operation should be implemented, the combination of which determines the visual result. In the XNA bloom sample:

Bright areas are identified by subtracting a threshold value, then scaling back up to preserve full color range: (value - threshold) / (1 - threshold)
Blur is applied using a two pass separable Gaussian filter
To avoid excessively bright areas, the final combine operation is: (base * (1 – bloom)) + bloom (done in a pixel shader that also provides brightness and saturation adjustment for both images)

There is no good way to adjust saturation without shaders, but everything else in this design can be done with simple alpha blending operations:

using System;
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;

namespace BloomPostprocess
{
    public class BloomComponent : DrawableGameComponent
    {
        // Adjust these values to change visual appearance.
        const float BloomThreshold = 0.25f;
        const float BloomIntensity = 1.5f;
        const int BlurPasses = 4;


        // result = source - destination
        static BlendState extractBrightColors = new BlendState
        {
            ColorSourceBlend = Blend.One,
            AlphaSourceBlend = Blend.One,

            ColorDestinationBlend = Blend.One,
            AlphaDestinationBlend = Blend.One,

            ColorBlendFunction = BlendFunction.Subtract,
            AlphaBlendFunction = BlendFunction.Subtract,
        };


        // result = source + destination
        static BlendState additiveBlur = new BlendState
        {
            ColorSourceBlend = Blend.One,
            AlphaSourceBlend = Blend.One,

            ColorDestinationBlend = Blend.One,
            AlphaDestinationBlend = Blend.One,
        };


        // result = source + (destination * (1 - source))
        static BlendState combineFinalResult = new BlendState
        {
            ColorSourceBlend = Blend.One,
            AlphaSourceBlend = Blend.One,

            ColorDestinationBlend = Blend.InverseSourceColor,
            AlphaDestinationBlend = Blend.InverseSourceColor,
        };


        SpriteBatch spriteBatch;

        RenderTarget2D scene;
        RenderTarget2D halfSize;
        RenderTarget2D quarterSize;
        RenderTarget2D quarterSize2;


        public BloomComponent(Game game)
            : base(game)
        { }


        protected override void LoadContent()
        {
            spriteBatch = new SpriteBatch(GraphicsDevice);

            PresentationParameters pp = GraphicsDevice.PresentationParameters;

            int w = pp.BackBufferWidth;
            int h = pp.BackBufferHeight;

            scene = new RenderTarget2D(GraphicsDevice, w, h, false, pp.BackBufferFormat, pp.DepthStencilFormat, pp.MultiSampleCount, RenderTargetUsage.DiscardContents);
            halfSize = new RenderTarget2D(GraphicsDevice, w / 2, h / 2, false, pp.BackBufferFormat, DepthFormat.None);
            quarterSize = new RenderTarget2D(GraphicsDevice, w / 4, h / 4, false, pp.BackBufferFormat, DepthFormat.None);
            quarterSize2 = new RenderTarget2D(GraphicsDevice, w / 4, h / 4, false, pp.BackBufferFormat, DepthFormat.None);
        }


        public void BeginDraw()
        {
            if (Visible)
            {
                GraphicsDevice.SetRenderTarget(scene);
            }
        }


        public override void Draw(GameTime gameTime)
        {
            // Shrink to half size.
            GraphicsDevice.SetRenderTarget(halfSize);
            DrawSprite(scene, BlendState.Opaque);

            // Shrink again to quarter size, at the same time applying the threshold subtraction.
            GraphicsDevice.SetRenderTarget(quarterSize);
            GraphicsDevice.Clear(new Color(BloomThreshold, BloomThreshold, BloomThreshold));
            DrawSprite(halfSize, extractBrightColors);

            // Kawase blur filter (see http://developer.amd.com/media/gpu_assets/Oat-ScenePostprocessing.pdf)
            for (int i = 0; i < BlurPasses; i++)
            {
                GraphicsDevice.SetRenderTarget(quarterSize2);
                GraphicsDevice.Clear(Color.Black);

                int w = quarterSize.Width;
                int h = quarterSize.Height;

                float brightness = 0.25f;

                // On the first pass, scale brightness to restore full range after the threshold subtraction.
                if (i == 0)
                    brightness /= (1 - BloomThreshold);

                // On the final pass, apply tweakable intensity adjustment.
                if (i == BlurPasses - 1)
                    brightness *= BloomIntensity;

                Color tint = new Color(brightness, brightness, brightness);

                spriteBatch.Begin(0, additiveBlur);

                spriteBatch.Draw(quarterSize, new Vector2(0.5f, 0.5f), new Rectangle(i + 1, i + 1, w, h), tint);
                spriteBatch.Draw(quarterSize, new Vector2(0.5f, 0.5f), new Rectangle(-i, i + 1, w, h), tint);
                spriteBatch.Draw(quarterSize, new Vector2(0.5f, 0.5f), new Rectangle(i + 1, -i, w, h), tint);
                spriteBatch.Draw(quarterSize, new Vector2(0.5f, 0.5f), new Rectangle(-i, -i, w, h), tint);
                
                spriteBatch.End();

                Swap(ref quarterSize, ref quarterSize2);
            }

            // Combine the original scene and bloom images.
            GraphicsDevice.SetRenderTarget(null);
            DrawSprite(scene, BlendState.Opaque);
            DrawSprite(quarterSize, combineFinalResult);
        }


        void DrawSprite(Texture2D source, BlendState blendState)
        {
            spriteBatch.Begin(0, blendState);
            spriteBatch.Draw(source, GraphicsDevice.Viewport.Bounds, Color.White);
            spriteBatch.End();
        }


        static void Swap<T>(ref T a, ref T b)
        {
            T tmp = a;
            a = b;
            b = tmp;
        }
    }
}

Notes:

High quality blur filters can be expensive, so most bloom implementations do a cheap bilinear downsample to lower resolution before the ‘real’ blur. The original XNA sample operates at half resolution, but in a nod to the limited bandwidth of mobile GPUs, I made this version shrink to quarter size.
It is possible to implement Gaussian blur (or indeed any multi-tap filter) as a series of additive and subtractive blends with suitable offsets, but that gets expensive for large filter kernels. Instead I chose a Kawase blur (originally developed by Masaki Kawase for the Xbox1 game Wreckless), which cunningly exploits GPU bilinear filtering to get a not-quite-as-good-but-still-ok result more cheaply.
The threshold subtraction is perhaps the least intuitive operation. We want (source - threshold), but the alpha blending hardware only gives us (source - destination). So, we simply clear the destination rendertarget to our desired threshold value before drawing the source image!
There are two scaling operations in this bloom design: one to preserve full color range after the threshold subtraction, and a second after the blur to adjust intensity of the bloom. For efficiency, I apply these adjustments during the first and last blur passes, getting them for free as a side effect of drawing work that was already taking place.

So how does it look?

With BloomThreshold = 0.25f, BloomIntensity = 1.5f, BlurPasses = 4:

With BloomThreshold = 0.5f, BloomIntensity = 3, BlurPasses = 6:

With BloomThreshold = 0, BloomIntensity = 1.5f, BlurPasses = 3:

Voting results are in!

Shawn Hargreaves - MSFT — Thu, 19 Jan 2012 20:04:00 GMT

Thanks for the comments about what I should write about next. Hopefully I managed to count these more accurately than the Iowa Republican party :-)

C++ 16

How GPU’s work 11

3D math 10

Game design 10

SIMD optimization 3

Of course my blog is not a democracy, so I’m not promising to actually cover these topics in that order! But it is useful to know that for instance I have more readers interested in C++ than in SIMD optimization.

There were also several write-in nominations:

Specifics of how XNA is implemented. It does seem like there should be a couple of interesting articles to be had here. I will have to think about exactly what they might be.
Managed <-> native interop (esp. WinRT). Hmm. My immediate reaction is I don’t know enough about this topic, but I will mull it over and see if anything worthwhile comes to mind.
A couple of requests to talk about future XNA plans. Sorry, no can do. Not my team any more!
Single-vote requests to write about input, component based entities, and XACT garbage. Unlikely (due to lack of knowledge / opinions / info to share) but I will bear them in mind.

Thank you all!

Is SpriteBatch Turing complete?

Shawn Hargreaves - MSFT — Thu, 29 Dec 2011 22:58:56 GMT

Time for some end-of-year silliness...

Inspired by this recent Twitter exchange:

Scionwest - @shawnhargreaves @nickgravelyn How about post processing for WP7? I've seen people do Bloom effects and thought P.P. was not part of WP7?

nickgravelyn - @Scionwest Shaders aren't available, but I've seen some clever post-processing done without custom shaders. You theoretically could do CPU based "shaders", but you can also use blend states in fun ways to achieve effects

(which is actually an interesting topic that I may someday return to)

I found myself thinking "well, of course you could implement bloom, because the no-programmable-shaders Reach graphics subset on Windows Phone is Turing complete, so can do anything you can imagine given sufficient ingenuity. It might not be easy, efficient, or sensible, but anything is possible..."

And then I found myself thinking, is that really true?

We can add and subtract via blend states, and perform comparisons with AlphaTestEffect, which seems like it should be enough to enable arbitrary algorithms (at least if we ignore mundane practicalities such as time and space constraints :-) But can I prove that XNA on Windows Phone is enough to enable Turing complete GPU computation?

Conway's Game of Life is already proven to be a form of universal Turing machine, so I set out to see if I could implement that on the GPU without custom shaders.

Starting with the default Game template, I declared two rendertargets to hold the state of my simulation:

    const int width = 256;
    const int height = 128;

    RenderTarget2D currentState;
    RenderTarget2D nextState;

Plus two helper objects:

    AlphaTestEffect alphaTestEffect;

    Texture2D singleWhitePixel;

These are initialized in LoadContent:

    currentState = new RenderTarget2D(GraphicsDevice, width, height, false, SurfaceFormat.Color, DepthFormat.Depth24Stencil8);
    nextState    = new RenderTarget2D(GraphicsDevice, width, height, false, SurfaceFormat.Color, DepthFormat.Depth24Stencil8);

    alphaTestEffect = new AlphaTestEffect(GraphicsDevice);

    singleWhitePixel = new Texture2D(GraphicsDevice, 1, 1);

    singleWhitePixel.SetData(new Color[] { Color.White });

In order for it to do anything interesting, the Game of Life must be initialized to more than just zeros. This code (at the end of LoadContent) creates a single glider that will move diagonally across the screen:

    Color[] initialData = new Color[width * height];

    initialData[3 + 1 * width] = Color.White;
    initialData[3 + 2 * width] = Color.White;
    initialData[3 + 3 * width] = Color.White;
    initialData[2 + 3 * width] = Color.White;
    initialData[1 + 2 * width] = Color.White;

    currentState.SetData(initialData);

For a more interesting initial state, add this (before the currentState.SetData call) to randomize the cells:

    Random random = new Random();

    for (int i = 0; i < 10000; i++)
    {
        initialData[random.Next(width * height)] = Color.White;
    }

My Draw code is simple. It uses SamplerState.PointClamp to scale up the current simulation state to fill the entire screen, without any filtering:

    SimulateLife();

    GraphicsDevice.Clear(Color.CornflowerBlue);

    spriteBatch.Begin(SpriteSortMode.Deferred, null, SamplerState.PointClamp, null, null);
    spriteBatch.Draw(currentState, GraphicsDevice.Viewport.Bounds, Color.White);
    spriteBatch.End();

Ok, that's the boilerplate taken care of. How are we actually going to implement this SimulateLife method? Wikipedia defines the rules as:

Any live cell with fewer than two live neighbours dies, as if caused by under-population
Any live cell with two or three live neighbours lives on to the next generation
Any live cell with more than three live neighbours dies, as if by overcrowding
Any dead cell with exactly three live neighbours becomes a live cell, as if by reproduction

But I found it useful to rearrange this to a different (equivalent) form:

Rule 1: If there are two live neighbours, preserve the current state of the cell
Rule 2: If there are three live neighbours, set the cell to alive
Rule 3: Otherwise set the cell to dead

Ok, let's do it! SimulateLife starts by drawing onto the nextState rendertarget, and setting up the AlphaTestEffect to only accept pixels with alpha greater than 128, i.e.. cells that are currently alive:

    GraphicsDevice.SetRenderTarget(nextState);

    GraphicsDevice.Clear(Color.Transparent);

    Viewport viewport = GraphicsDevice.Viewport;

    Matrix projection = Matrix.CreateOrthographicOffCenter(0, viewport.Width, viewport.Height, 0, 0, 1);
    Matrix halfPixelOffset = Matrix.CreateTranslation(-0.5f, -0.5f, 0);

    alphaTestEffect.Projection = halfPixelOffset * projection;

    alphaTestEffect.AlphaFunction = CompareFunction.Greater;
    alphaTestEffect.ReferenceAlpha = 128;

We are going to count how many alive neighbours each cell has, accumulating this value in the stencil buffer (which was previously cleared to zero). We do this by drawing the current simulation state texture 8 times, shifted one pixel to the top left, top, top right, left, etc. We use a blend state that prevents drawing anything to the color buffer, because we are only interested in generating stencil values. This code combines AlphaTestEffect (which rejects dead neighbour pixels) and the stencil buffer (which counts how many neighbour pixels pass the alpha test):

    spriteBatch.Begin(SpriteSortMode.Deferred, blendNone, null, stencilAdd, null, alphaTestEffect);

    spriteBatch.Draw(currentState, new Vector2(-1, -1), Color.White);
    spriteBatch.Draw(currentState, new Vector2( 0, -1), Color.White);
    spriteBatch.Draw(currentState, new Vector2( 1, -1), Color.White);
    spriteBatch.Draw(currentState, new Vector2(-1,  0), Color.White);
    spriteBatch.Draw(currentState, new Vector2( 1,  0), Color.White);
    spriteBatch.Draw(currentState, new Vector2(-1,  1), Color.White);
    spriteBatch.Draw(currentState, new Vector2( 0,  1), Color.White);
    spriteBatch.Draw(currentState, new Vector2( 1,  1), Color.White);

    spriteBatch.End();

This uses two custom state objects:

    static readonly BlendState blendNone = new BlendState
    {
        ColorSourceBlend = Blend.Zero,
        ColorDestinationBlend = Blend.One,

        AlphaSourceBlend = Blend.Zero,
        AlphaDestinationBlend = Blend.One,

        ColorWriteChannels = ColorWriteChannels.None,
    };

    static readonly DepthStencilState stencilAdd = new DepthStencilState
    {
        DepthBufferEnable = false,
        StencilEnable = true,
        StencilFunction = CompareFunction.Always,
        StencilPass = StencilOperation.Increment,
    };

We now have our rendertarget cleared to zero (which means all dead, so we have already implemented rule #3), while stencil contains a count of live neighbour cells. It is but the work of a moment to draw a copy of the current simulation state, using stencil to only accept cells that have 2 live neighbours, thus implementing rule #1:

    spriteBatch.Begin(SpriteSortMode.Deferred, BlendState.Opaque, null, stencilDrawIf2, null);
    spriteBatch.Draw(currentState, Vector2.Zero, Color.White);
    spriteBatch.End();

The last draw call implements rule #2 by rendering solid white (which means alive) over only those cells which have 3 live neighbours:

    spriteBatch.Begin(SpriteSortMode.Deferred, BlendState.Opaque, null, stencilDrawIf3, null);
    spriteBatch.Draw(singleWhitePixel, viewport.Bounds, Color.White);
    spriteBatch.End();

This requires two new state objects:

    static readonly DepthStencilState stencilDrawIf2 = new DepthStencilState
    {
        DepthBufferEnable = false,
        StencilEnable = true,
        StencilFunction = CompareFunction.Equal,
        ReferenceStencil = 2,
    };

    static readonly DepthStencilState stencilDrawIf3 = new DepthStencilState
    {
        DepthBufferEnable = false,
        StencilEnable = true,
        StencilFunction = CompareFunction.Equal,
        ReferenceStencil = 3,
    };

Finally, the end of SimulateLife unsets our output rendertarget, then swap the two rendertargets, replacing the current state with the new one we just computed:

    GraphicsDevice.SetRenderTarget(null);

    Swap(ref currentState, ref nextState);

Swap is a handy little helper, implemented like so:

    static void Swap<T>(ref T a, ref T b)
    {
        T temp = a;
        a = b;
        b = temp;
    }

So, does it work?

Tada! SpriteBatch is Turing complete :-)

Exercise for the reader: is it possible to do the same thing without using stencil?

What should I write about next?

Shawn Hargreaves - MSFT — Thu, 29 Dec 2011 19:34:46 GMT

I have a couple more articles planned about aliasing and motion blur, but am curious to hear where you would like me to take this blog next.

Some topics I am considering:

C++. Dirty secret: although I've mostly blogged about C# programming, much of XNA itself is written in C++, so I've actually been straddling both worlds for years. And interesting things are happening in C++ land right now, with the arrival of C++11 and maturity of the standard library affecting best practices and recommended style. But are my readers interested in such things? You tell me!

More about how GPU's work. Tiling, swizzling, caching, parallelism, predication, etc.

3D Math. Vectors, matrices, what really is an orientation, how to think in multiple coordinate spaces, and why rotation angles are Teh Evil.

Game design. What makes it fun? What makes a good AI? How does one persuade customers to try/buy your work? I've been reluctant to cover these topics because it's not really my area of expertise, but I do have some opinions about it so who knows, maybe a few worthwhile articles to be had here.

SIMD optimization, SSE, DirectXMath.

Other?

From games to telephones

Shawn Hargreaves - MSFT — Wed, 14 Dec 2011 00:22:45 GMT

After six years working on XNA, I decided it was time to take on a new challenge. I am moving to the Windows Phone team, where I will be working on things I'm not sure how much I can say about here (leaking future business plans on MSDN might not be the best way to endear myself to my new boss :-)

Writing this post is a bittersweet moment for me. I'm excited by what the future holds for Windows Phone, and looking forward to my chance to be part of that, but also sad to leave a team and product that have given me so much satisfaction. There'll be no going back once I hit that Publish button a few minutes from now...

I feel an urge to wax nostalgic about some of my favorite times with XNA:

Staying up all night to watch Michael purchase the first ever Creators Club subscription.
The first Dream Build Play competition, when we got to see the first actual games made with our technology (Dishwasher FTW!)
On stage with Mitch at Gamefest, where I wrote a network game 'from scratch' (if you ignore some minor snippet cheating :-) in less than an hour. I'm still blown away by the fact that our APIs were simple enough to make this possible. Also amazed that the demo actually worked, considering what an unstable early build we were using! Unfortunately there is no video of this, and the slides don't do it justice since the whole point was the live coding demo.
On stage once more at MIX, demonstrating XNA graphics on the new Windows Phone with a frighteningly last minute demo cobbled together just a few days earlier using a hot-off-the-presses build of XNA on an even more experimental frankenbuild of the phone OS. Then rushing back to my hotel room to blog about the new features coming in XNA 4.0 (which, modesty aside, I still think is some of the best design work I have done to date).
Trying to decide, of all the lines of code I have written in my life, which one has been executed the most times? I think it must be the default SpriteBatch pixel shader.
Last but not least, spending time with y'all on forums and this blog, where I got to know so many great people and see the amazing things you create.

I'm not yet sure what this means for my blog. I want to keep writing, but will probably cover more general graphics and game development topics, and will obviously no longer have inside scoop on XNA implementation details. I'm also not sure how much time I will have for writing, especially in the early months as I settle into the new job, but I will do my best.

Ok, I'm off now to meet some new people and learn my way around a whole new product.

CreateSphere Tessellation = 11 276 vertices		CreateGeoSphere Tessellation = 3 277 vertices

C++	16
How GPU’s work	11
3D math	10
Game design	10
SIMD optimization	3