-------------------------------- DirectXTK - the DirectX Tool Kit -------------------------------- Copyright (c) Microsoft Corporation. All rights reserved. March 27, 2015 This package contains the "DirectX Tool Kit", a collection of helper classes for writing Direct3D 11 C++ code for Windows Store apps, Windows phone 8.x applications, Xbox One exclusive apps, Xbox One hub apps, Windows 8.x Win32 desktop applications, Windows 7 applications, and Windows Vista Direct3D 11.0 applications. This code is designed to build with Visual Studio 2010, 2012, or 2013. It requires the Windows 8.x SDK for functionality such as the DirectXMath library and the DXGI 1.2 headers. Visual Studio 2012 and 2013 already include the appropriate Windows SDK, but Visual Studio 2010 users must install the standalone Windows 8.1 SDK. Details on using the Windows 8.1 SDK with VS 2010 are described on the Visual C++ Team Blog: <http://blogs.msdn.com/b/vcblog/archive/2012/11/23/using-the-windows-8-sdk-with-visual-studio-2010-configuring-multiple-projects.aspx> These components are designed to work without requiring any content from the DirectX SDK. For details, see "Where is the DirectX SDK?" <http://msdn.microsoft.com/en-us/library/ee663275.aspx>. Inc\ Public Header Files (in the DirectX C++ namespace): Audio.h - low-level audio API using XAudio2 (DirectXTK for Audio public header) CommonStates.h - factory providing commonly used D3D state objects DirectXHelpers.h - misc C++ helpers for D3D programming DDSTextureLoader.h - light-weight DDS file texture loader Effects.h - set of built-in shaders for common rendering tasks GamePad.h - gamepad controller helper using XInput GeometricPrimitive.h - draws basic shapes such as cubes and spheres Model.h - draws meshes loaded from .CMO, .SDKMESH, or .VBO files PrimitiveBatch.h - simple and efficient way to draw user primitives ScreenGrab.h - light-weight screen shot saver SimpleMath.h - simplified C++ wrapper for DirectXMath SpriteBatch.h - simple & efficient 2D sprite rendering SpriteFont.h - bitmap based text rendering VertexTypes.h - structures for commonly used vertex data formats WICTextureLoader.h - WIC-based image file texture loader XboxDDSTextureLoader.h - Xbox One exclusive apps variant of DDSTextureLoader Src\ DirectXTK source files and internal implementation headers Audio\ DirectXTK for Audio source files and internal implementation headers MakeSpriteFont\ Command line tool used to generate binary resources for use with SpriteFont XWBTool\ Command line tool for building XACT-style wave banks for use with DirectXTK for Audio's WaveBank class All content and source code for this package are subject to the terms of the MIT License. <http://opensource.org/licenses/MIT>. For the latest version of DirectXTK, more detailed documentation, discussion forums, bug reports and feature requests, please visit the Codeplex site. http://go.microsoft.com/fwlink/?LinkId=248929 Note: Xbox One exclusive apps developers using the Xbox One XDK need to generate the Src\Shaders\Compiled\XboxOne*.inc files to build the library as they are not included in the distribution package. They are built by running the script in Src\Shaders - "CompileShaders xbox", and should be generated with the matching FXC compiler from the Xbox One XDK. While they will continue to work if outdated, a mismatch will cause runtime compilation overhead that would otherwise be avoided. ----------- SpriteBatch ----------- This is a native D3D11 implementation of the SpriteBatch helper from XNA Game Studio, providing identical functionality and API. During initialization: std::unique_ptr<SpriteBatch> spriteBatch(new SpriteBatch(deviceContext)); Simple drawing: spriteBatch->Begin(); spriteBatch->Draw(texture, XMFLOAT2(x, y)); spriteBatch->End(); The Draw method has many overloads with parameters controlling: - Specify position as XMFLOAT2, XMVECTOR or RECT - Optional source rectangle for drawing just part of a sprite sheet - Tint color - Rotation (in radians) - Origin point (position, scaling and rotation are relative to this) - Scale - SpriteEffects enum (for horizontal or vertical mirroring) - Layer depth (for sorting) Sorting: The first parameter to SpriteBatch::Begin is a SpriteSortMode enum. For most efficient rendering, use SpriteSortMode_Deferred (which batches up sprites, then submits them all to the GPU during the End call), and manually draw everything in texture order. If it is not possible to draw in texture order, the second most efficient approach is to use SpriteSortMode_Texture, which will automatically sort on your behalf. When drawing scenes with multiple depth layers, SpriteSortMode_BackToFront or SpriteSortMode_FrontToBack will sort by the layerDepth parameter specified to each Draw call. SpriteSortMode_Immediate disables all batching, submitting a separate D3D draw call for each sprite. This is expensive, but convenient in rare cases when you need to set shader constants differently per sprite. Multiple SpriteBatch instances are lightweight. It is reasonable to create several, Begin them at the same time with different sort modes, submit sprites to different batches in arbitrary orders as you traverse a scene, then End the batches in whatever order you want these groups of sprites to be drawn. Alpha blending: Alpha blending defaults to using premultiplied alpha. To make use of 'straight' alpha textures, override the blending mode via the optional callback: CommonStates states(device); spriteBatch->Begin(SpriteSortMode_Deferred, nullptr, nullptr, nullptr, nullptr, [=] { deviceContext->OMSetBlendState( states.NonPremultiplied(), nullptr, 0xFFFFFFFF); }); Custom render states: By default SpriteBatch uses premultiplied alpha blending, no depth buffer, counter clockwise culling, and linear filtering with clamp texture addressing. You can change this by passing custom state objects to SpriteBatch::Begin. Pass null for any parameters that should use their default state. To use SpriteBatch with a custom pixel shader (handy for 2D postprocessing effects such as bloom or blur) or even a custom vertex shader, use the setCustomShaders parameter to specify a state setting callback function: spriteBatch->Begin(SpriteSortMode_Deferred, nullptr, nullptr, nullptr, nullptr, [=] { deviceContext->PSSetShader(...); deviceContext->PSSetConstantBuffers(...); deviceContext->PSSetShaderResources(...); }); SpriteBatch automatically sets pixel shader resource #0 to the texture specified by each Draw call, so you only need to call PSSetResources for any additional textures required by your shader. SpriteBatch::Begin also has a transformMatrix parameter, which can be used for global transforms such as scaling or translation of an entire scene. Threading model: Creation is fully asynchronous, so you can instantiate multiple SpriteBatch instances at the same time on different threads. Each SpriteBatch instance only supports drawing from one thread at a time, but you can simultaneously submit sprites on multiple threads if you create a separate SpriteBatch instance per D3D11 deferred context. Orientation: For phones, laptops, and tablets the orientation of the display can be changed by the user. For Windows Store apps, DirectX applications are encouraged to handle the rotation internally rather than relying on DXGI's auto-rotation handling. In older versions of DirectXTK, you had to handle orientation changes via the custom transform matrix on Begin(). In the latest version of DirectXTK, you can handle it via a rotation setting (which is applied after any custom transformation). Windows Store apps for Windows 8: DXGI_MODE_ROTATION rotation = DXGI_MODE_ROTATION_UNSPECIFIED; switch (m_orientation) { case DisplayOrientations::Landscape: rotation = DXGI_MODE_ROTATION_IDENTITY; break; case DisplayOrientations::Portrait: rotation = DXGI_MODE_ROTATION_ROTATE270; break; case DisplayOrientations::LandscapeFlipped: rotation = DXGI_MODE_ROTATION_ROTATE180; break; case DisplayOrientations::PortraitFlipped: rotation = DXGI_MODE_ROTATION_ROTATE90; break; } spriteBatch->SetRotation( rotation ); Windows phone 8.0 apps (see http://www.catalinzima.com/2012/12/handling-orientation-in-a-windows-phone-8-game/): DXGI_MODE_ROTATION rotation = DXGI_MODE_ROTATION_UNSPECIFIED; switch (m_orientation) { case DisplayOrientations::Portrait: rotation = DXGI_MODE_ROTATION_IDENTITY; break; case DisplayOrientations::Landscape: rotation = DXGI_MODE_ROTATION_ROTATE90; break; case DisplayOrientations::PortraitFlipped: rotation = DXGI_MODE_ROTATION_ROTATE180; break; case DisplayOrientations::LandscapeFlipped: rotation = DXGI_MODE_ROTATION_ROTATE270; break; } spriteBatch->SetRotation( rotation ); Windows Store apps for Windows 8.1: spriteBatch->SetRotation( m_deviceResources->ComputeDisplayRotation() ); 3D sprites: As explained in this article, you can use SpriteBatch to render particles and billboard text in 3D as well as the default 2D behavior. http://blogs.msdn.com/b/shawnhar/archive/2011/01/12/spritebatch-billboards-in-a-3d-world.aspx To simplify this application, you can set the rotation mode so that SpriteBatch doesn't apply a view transform matrix internally and assumes the full transform is accomplished by Begin's matrix parameter. spriteBatch->SetRotation( DXGI_MODE_ROTATION_UNSPECIFIED ); Further reading: http://www.shawnhargreaves.com/blogindex.html#spritebatch http://blogs.msdn.com/b/shawnhar/archive/2010/06/18/spritebatch-and-renderstates-in-xna-game-studio-4-0.aspx http://www.shawnhargreaves.com/blogindex.html#premultipliedalpha ---------- SpriteFont ---------- 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. Command-line options for the MakeSpriteFont tool: /CharacterRegion:<region> Specifies which Unicode codepoints to include in the font. Can be repeated to include more than one region. If not specified, the default ASCII range (32-126) is used. Examples: /CharacterRegion:a-z /CharacterRegion:0x1200-0x1250 /CharacterRegion:0x1234 /DefaultCharacter:<value> Fallback character substituted in place of codepoints that are not included in the font. If zero, missing characters throw exceptions. /FontSize:<value> /FontStyle:<value> Size and style (bold or italic) for TrueType fonts. Ignored when converting a bitmap font. /LineSpacing:<value> /CharacterSpacing:<value> Spacing overrides. Zero is default spacing, negative closer together, positive further apart. /Sharp Selects sharp antialising mode for TrueType rasterization. Otherwise, a smoother looking (but more blurry) antialiasing mode is used. /TextureFormat:<value> What format should the output texture be? Options: Auto The default. Chooses between CompressedMono and Rgba32 depending on whether the font data is monochromatic or multicolored. Rgba32 High quality and supports multicolored fonts, but wastes space. Bgra4444 Good choice for color fonts on Windows Store apps and Windows phone platforms, as this format requires the DirectX 11.1 Runtime and a WDDM 1.2 driver. CompressedMono The smallest format, and works on all D3D platforms, but it only supports monochromatic font data. This uses a special BC2 encoder: see comments in SpriteFontWriter.cs for details. /NoPremultiply By default, font textures use premultiplied alpha format. Pass this flag if you want interpolative/straight alpha instead. /DebugOutputSpriteSheet:<filename> Dumps the generated texture to a bitmap file (useful when debugging the MakeSpriteFont tool, not so much if you are just trying to use it). Further reading: http://blogs.msdn.com/b/shawnhar/archive/2007/04/26/bitmap-fonts-in-xna.aspx http://create.msdn.com/en-US/education/catalog/utility/bitmap_font_maker ------- Effects ------- This is a native D3D11 implementation of the five built-in effects from XNA Game Studio, providing identical functionality and API: - BasicEffect supports texture mapping, vertex coloring, directional lighting, and fog - AlphaTestEffect supports per-pixel alpha testing - DualTextureEffect supports two layer multitexturing (for lightmaps or detail textures) - EnvironmentMapEffect supports cubic environment mapping - SkinnedEffect supports skinned animation The library also includes support for the Visual Studio Shader Designer (DGSL) shaders - DGSLEffect supports both rigid and skinned animation with up to 8 textures. During initialization: std::unique_ptr<BasicEffect> effect(new BasicEffect(device)); Set effect parameters: effect->SetWorld(world); effect->SetView(view); effect->SetProjection(projection); effect->SetTexture(cat); effect->SetTextureEnabled(true); effect->EnableDefaultLighting(); Draw using the effect: effect->Apply(deviceContext); deviceContext->IASetInputLayout(...); deviceContext->IASetVertexBuffers(...); deviceContext->IASetIndexBuffer(...); deviceContext->IASetPrimitiveTopology(...); deviceContext->DrawIndexed(...); To create an input layout matching the effect vertex shader input signature: // First, configure effect parameters the way you will be using it. Turning // lighting, texture map, or vertex color on/off alters which vertex shader // is used, so GetVertexShaderBytecode will return a different blob after // you alter these parameters. If you create an input layout using a // BasicEffect that had lighting disabled, but then later enable lighting, // that input layout will no longer match as it will not include the // now-necessary normal vector. void const* shaderByteCode; size_t byteCodeLength; effect->GetVertexShaderBytecode(&shaderByteCode, &byteCodeLength); device->CreateInputLayout(VertexPositionNormalTexture::InputElements, VertexPositionNormalTexture::InputElementCount, shaderByteCode, byteCodeLength, pInputLayout); Coordinate systems: The built-in effects work equally well for both right-handed and left-handed coordinate systems. The one difference is that the fog settings start & end for left-handed coordinate systems need to be negated (i.e. SetFogStart(6), SetFogEnd(8) for right-handed coordinates becomes SetFogStart(-6), SetFogEnd(-8) for left-handed coordinates). Threading model: Creation is fully asynchronous, so you can instantiate multiple effect instances at the same time on different threads. Each instance only supports drawing from one thread at a time, but you can simultaneously draw on multiple threads if you create a separate effect instance per D3D11 deferred context. Further reading: http://blogs.msdn.com/b/shawnhar/archive/2010/04/28/new-built-in-effects-in-xna-game-studio-4-0.aspx http://blogs.msdn.com/b/shawnhar/archive/2010/04/30/built-in-effects-permutations-and-performance.aspx http://blogs.msdn.com/b/shawnhar/archive/2010/04/25/basiceffect-optimizations-in-xna-game-studio-4-0.aspx http://blogs.msdn.com/b/shawnhar/archive/2008/08/22/basiceffect-a-misnomer.aspx http://blogs.msdn.com/b/shawnhar/archive/2010/08/04/dualtextureeffect.aspx http://blogs.msdn.com/b/shawnhar/archive/2010/08/09/environmentmapeffect.aspx -------------- PrimitiveBatch -------------- This is a helper for easily and efficiently drawing dynamically generated geometry such as lines or trianges. It fills the same role as the legacy D3D9 APIs DrawPrimitiveUP and DrawIndexedPrimitiveUP. Dynamic submission is a highly effective pattern for drawing procedural geometry, and convenient for debug rendering, but is not nearly as efficient as static vertex buffers. Excessive dynamic submission is a common source of performance problems in apps. 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)); The default values assume that your maximum batch size is 2048 vertices arranged in triangles. If you want to use larger batches, you need to provide the additional constructor parameters. To set up a suitable BasicEffect and input layout: std::unique_ptr<BasicEffect> basicEffect(new BasicEffect(device)); basicEffect->SetProjection(XMMatrixOrthographicOffCenterRH(0, screenHeight, screenWidth, 0, 0, 1)); basicEffect->SetVertexColorEnabled(true); void const* shaderByteCode; size_t byteCodeLength; basicEffect->GetVertexShaderBytecode(&shaderByteCode, &byteCodeLength); ComPtr<ID3D11InputLayout> inputLayout; device->CreateInputLayout(VertexPositionColor::InputElements, VertexPositionColor::InputElementCount, shaderByteCode, byteCodeLength, &inputLayout); To draw a line: CommonStates states(device); deviceContext->OMSetBlendState( states.Opaque(), nullptr, 0xFFFFFFFF ); deviceContext->OMSetDepthStencilState( states.DepthNone(), 0 ); deviceContext->RSSetState( states.CullCounterClockwise() ); basicEffect->Apply(deviceContext); deviceContext->IASetInputLayout(inputLayout.Get()); 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) Optimization: For best performance, draw as much as possible inside the fewest separate Begin/End blocks. This will reduce overhead and maximize potential for batching. The PrimitiveBatch constructor allows you to specify what size index and vertex buffers to allocate. You may want to tweak these values to fit your workload, or if you only intend to draw non-indexed geometry, specify maxIndices = 0 to entirely skip creating the index buffer. Threading model: Each PrimitiveBatch instance only supports drawing from one thread at a time, but you can simultaneously submit primitives on multiple threads if you create a separate PrimitiveBatch instance per D3D11 deferred context. ------------------ GeometricPrimitive ------------------ This is a helper for drawing simple geometric shapes: - Cube (aka hexahedron) - Sphere - Geodesic Sphere - Cylinder - Cone - Torus - Tetrahedron - Octahedron - Dodecahedron - Icosahedron - Teapot Initialization: std::unique_ptr<GeometricPrimitive> shape(GeometricPrimitive::CreateTeapot(deviceContext)); Simple drawing: shape->Draw(world, view, projection, Colors::CornflowerBlue); The draw method accepts an optional texture parameter, wireframe flag, and a callback function which can be used to override the default rendering state: shape->Draw(world, view, projection, Colors::White, catTexture, false, [=] { deviceContext->OMSetBlendState(...); }); This makes use of a BasicEffect shared by all geometric primitives drawn on that device context. Advanced drawing: IEffect* myeffect = ... Microsoft::WRL::ComPtr<ID3D11InputLayout> inputLayout; shape->CreateInputLayout( myeffect, &inputLayout ); shape->Draw( myeffect, inputLayout.Get() ); Coordinate Systems: These geometric primitives (based on the XNA Game Studio conventions) use right-handed coordinates. They can be used with left-handed coordinates by setting the rhcoords parameter on the factory methods to 'false' to reverse the winding ordering (the parameter defaults to 'true'). Alpha blending: Alpha blending defaults to using premultiplied alpha. To make use of 'straight' alpha textures, override the blending mode via the optional callback: CommonStates states(device); shape->Draw(world, view, projection, Colors::White, catTexture, false, [=] { deviceContext->OMSetBlendState( states.NonPremultiplied(), nullptr, 0xFFFFFFFF); }); ----- Model ----- This is a class hierarchy for drawing simple meshes with support for loading rigid models from Visual Studio 3D Starter Kit .CMO files, legacy DirectX SDK .SDKMESH files, and .VBO files. It is an implementation of a mesh renderer similar to the XNA Game Studio Model, ModelMesh, ModelMeshPart design. NOTE: Support for loading keyframe animations is not yet included. A Model consists of one or more ModelMesh instances. The ModelMesh instances can be shared by multiple instances of Model. A ModelMesh instance consists of one or more ModelMeshPart instances. Each ModelMeshPart references an index buffer, a vertex buffer, an input layout, an Effects instance, and includes various metadata for drawing the geometry. Each ModelMeshPart represents a single material to be drawn at the same time (i.e. a submesh). Initialization: Model instances can be loaded from .CMO, .SDKMESH, or .VBO files, or from custom file formats. The Model loaders take an EffectFactory instance to facilitate the sharing of Effects and textures between models. For simplicity, provided Model loaders always return built-in Effect instances. Any references to specific shaders in the runtime mesh files are ignored. NOTE: EffectFactory and DGSLEffectFactory are declared in the Effects.h header. Visual Studio 2012 and 2013 include a built-in content pipeline that can generate .CMO files from an Autodesk FBX, as well as DDS texture files from various bitmap image formats, as part of the build process. See the Visual Studio 3D Starter Kit for details. http://code.msdn.microsoft.com/windowsapps/Visual-Studio-3D-Starter-455a15f1 EffectFactory fx( device ); auto teapot = Model::CreateFromCMO( device, L"teapot.cmo", fx ); The legacy DirectX SDK has an exporter that will generate .SDKMESH files from an Autodesk FBX. The latest version of this exporter tool can be obtained from: http://go.microsoft.com/fwlink/?LinkId=226208 auto tiny = Model::CreateFromSDKMESH( device, L"tiny.sdkmesh", fx ); The VBO file format is a very simple geometry format containing a index buffer and a vertex buffer. It was originally introduced in the Windows 8.0 ResourceLoading sample, but can be generated by DirectXMesh's meshconvert utility: http://go.microsoft.com/fwlink/?LinkID=324981 auto ship = Model::CreateFromVBO( device, L"ship.vbo" ); A Model instance also contains a name (a wide-character string) for tracking and application logic. Model can be copied to create a new Model instance which will have shared references to the same set of ModelMesh instances (i.e. a 'shallow' copy). Simple drawing: The Model::Draw functions provides a high-level, easy to use method for drawing models. CommonStates states(device); XMMATRIX local = XMMatrixTranslation( 1.f, 1.f, 1.f ); local = XMMatrixMultiply( world, local ); tiny->Draw( context, states, local, view, projection ); There are optional parameters for rendering in wireframe and to provide a custom state override callback. Advanced drawing: Rather than using the standard Model::Draw, the ModelMesh::Draw method can be used on each mesh in turn listed in the Model::meshes collection. ModelMesh::Draw can be used to draw all the opaque parts or the alpha parts individually. The ModelMesh::PrepareForRendering method can be used as a helper to setup common render state, or the developer can set up the state directly before calling ModelMesh::Draw. More detailed control over rendering can be had by skipping the use of Model::Draw and ModelMesh::Draw in favor of the ModelMeshPart::Draw method. Each Model::meshes collection can be scanned for each ModelMesh::meshParts collection to enumerate all ModelMeshPart instances. For this version of draw, the ModelMeshPart::effect and ModelMeshPart::inputLayout can be used, or a custom effect override can be used instead (be sure to create the appropriate matching input layout for the custom effect beforehand using ModelMeshPart::CreateInputLayout). Effects control: The Model loaders create an appropriate Effects instance for each ModelMeshPart in a mesh. Generally all effects in a mesh should use the same lighting and fog settings, which is facilitated by the Model::UpdateEffects method. This calls back for each unique effect in the ModelMesh once. tiny->UpdateEffects([&](IEffect* effect) { auto lights = dynamic_cast<IEffectLights*>(effect); if ( lights ) { XMVECTOR dir = XMVector3Rotate( g_XMOne, quat ); lights->SetLightDirection( 0, dir ); } auto fog = dynamic_cast<IEffectFog*>(effect); if ( fog ) { fog->SetFogEnabled(true); fog->SetFogStart(6); // assuming RH coordinates fog->SetFogEnd(8); fog->SetFogColor(Colors::CornflowerBlue); } }); It is also possible to change the Effects instance used by a given part (such as when overriding the default effect put in place from a Model loader) by calling ModelMeshPart::ModifyEffect. This will regenerate the ModelMeshPart::inputLayout appropriately. Be sure to call Model::Modified on all Model instances that reference the impacted ModelMesh instance to ensure the cache used by UpdateEffects is correctly updated. Model::Modified should also be called whenever a Model::meshes or ModelMesh::meshParts collection is modified. As noted above, it is also possible to render part or all of a model using a custom effect as an override, rather than changing the effect referenced by the ModelMeshPart::effect directly. Alpha blending: Proper drawing of alpha-blended models can be a complicated procedure. Each ModelMeshPart has a bool value to indicate if the associated part is fully opaque (isAlpha is false), or has some level of alpha transparency (isAlpha is true). The Model::Draw routine handles some basic logic for the rendering, first rendering the opaque parts, then rendering the alpha parts. More detailed control is provided by the ModelMesh::Draw method which can be used to draw all opaque parts of all meshes first, then go back and draw all alpha parts of all meshes second. To indicate the use of �straight� alpha vs. �premultiplied� alpha blending modes, ModelMesh::pmalpha is set by the various loaders functions controlled by a default parameter (which defaults false to indicate the texture files are using 'straight' alpha). If you make use of DirectXTex's texconv tool with the -pmalpha switch, you should use pmalpha=true instead. Custom render states: All the various Draw method provide a setCustomState callback which can be used to change the state just before the geometry is drawn. tiny->Draw( context, states, local, view, projection, false, [&]() { ID3D11ShaderResourceView* srv = nullptr; context->PSSetShaderResources( 0, 1, &srv ); }); Coordinate systems: Meshes are authored in a specific winding order, typically using the standard counter-clockwise winding common in graphics. The choice of viewing handedness (right-handed vs. left-handed coordinates) is largely a matter of preference and convenience, but it impacts how the models are built and/or exported. The Visual Studio 3D Starter Kit�s .CMO files assume the developer is using right-handed coordinates. DirectXTK�s default parameters assume you are using right-handed coordinates as well, so the �ccw� parameter defaults to true. If using a .CMO with left-handed coordinates, you should pass false for the �ccw� parameter which will use clockwise winding instead. This makes the geometry visible, but could make textures on the model appear �flipped� in U. The legacy DirectX SDK�s .SDKMESH files assume the developer is using left-handed coordinates. DirectXTK�s default parameters assume you are using right-handed coordinates, so the �ccw� parameter defaults to false which will use clockwise winding and potentially have the �flipped in U� texture problem. If using a .SDKMESH with left-handed coordinates, you should pass true for the �ccw� parameter. Feature Level Notes: If any ModelMeshPart makes use of 32-bit indices (i.e. ModelMeshPart:: indexFormat equals DXGI_FORMAT_R32_UINT) rather than 16-bit indices (DXGI_FORMAT_R16_UINT), then that model requires Feature Level 9.2 or greater. If any ModelMeshPart uses adjacency (i.e. ModelMeshPart::primitiveType equals D3D_PRIMITIVE_TOPOLOGY_*_ADJ), then that model requires Feature Level 10.0 or greater. If using tessellation (i.e. D3D_PRIMITIVE_TOPOLOGY_?_CONTROL_POINT_PATCHLIST), then that model requires Feature Level 11.0 or greater. Keep in mind that there are maximum primitive count limits per ModelMeshPart based on feature level as well (65535 for Feature Level 9.1, 1048575 or Feature Level 9.2 and 9.3, and 4294967295 for Feature Level 10.0 or greater). Threading model: The ModelMeshPart is tied to a device, but not a device context. This means that Model creation/loading is �free threaded�. Drawing can be done on the immediate context or by a deferred context, but keep in mind device contexts are not �free threaded�. ------------ CommonStates ------------ The CommonStates class is a factory which simplifies setting the most common combinations of D3D rendering states. During initialization: std::unique_ptr<CommonStates> states(new CommonStates(device)); Using this helper to set device state: deviceContext->OMSetBlendState(states->Opaque(), Colors::Black, 0xFFFFFFFF); deviceContext->OMSetDepthStencilState(states->DepthDefault(), 0); deviceContext->RSSetState(states->CullCounterClockwise()); auto samplerState = states->LinearWrap(); deviceContext->PSSetSamplers(0, 1, &samplerState); Available states: ID3D11BlendState* Opaque(); ID3D11BlendState* AlphaBlend(); ID3D11BlendState* Additive(); ID3D11BlendState* NonPremultiplied(); ID3D11DepthStencilState* DepthNone(); ID3D11DepthStencilState* DepthDefault(); ID3D11DepthStencilState* DepthRead(); ID3D11RasterizerState* CullNone(); ID3D11RasterizerState* CullClockwise(); ID3D11RasterizerState* CullCounterClockwise(); ID3D11RasterizerState* Wireframe(); ID3D11SamplerState* PointWrap(); ID3D11SamplerState* PointClamp(); ID3D11SamplerState* LinearWrap(); ID3D11SamplerState* LinearClamp(); ID3D11SamplerState* AnisotropicWrap(); ID3D11SamplerState* AnisotropicClamp(); -------------- DirectXHelpers -------------- C++ helpers for writing D3D code. Exception-safe Direct3D 11 resource locking: Modern C++ development strongly encourages use of the RAII pattern for exception-safe resource management, ensuring that resources are properly cleaned up if C++ exceptions are thrown. Even without exception handling, it's generally cleaner code to use RAII and rely on the C++ scope variables rules to handle cleanup. Most of these cases are handled by the STL classes such as std::unique_ptr, std::shared_ptr, etc. and the recommended COM smart pointer Microsoft::WRL::ComPtr for Direct3D reference counted objects. One case that isn't so easily managed with existing classes is when you are mapping staging/dynamic Direct3D 11 resources. MapGuard solves this problem, and is modeled after std::lock_mutex. MapGuard map( context.Get(), tex.Get(), 0, D3D11_MAP_WRITE, 0 ); for( size_t j = 0; j < 128; ++j ) { auto ptr = map.scanline(j); ... } Debug object naming: To help track down resource leaks, the Direct3D 11 debug layer allows you to provide ASCII debug names to Direct3D 11 objects. This is done with a specific GUID and the SetPrivateData method. Since you typically want to exclude this for release builds, it can get somewhat messy to add these to code. The SetDebugObjectName template greatly simplifies this for static debug name strings. SetDebugObjectName( tex.Get(), "MyTexture" ); ----------- VertexTypes ----------- VertexTypes.h defines these commonly used vertex data structures: - VertexPositionColor - VertexPositionTexture - VertexPositionNormal - VertexPositionColorTexture - VertexPositionNormalColor - VertexPositionNormalTexture - VertexPositionNormalColorTexture - VertexPositionNormalTangentColorTexture - VertexPositionNormalTangentColorTextureSkinning Each type also provides a D3D11_INPUT_ELEMENT_DESC array which can be used to create a matching input layout, for example: device->CreateInputLayout(VertexPositionColorTexture::InputElements, VertexPositionColorTexture::InputElementCount, vertexShaderCode, vertexShaderCodeSize, &inputLayout); ---------------- DDSTextureLoader ---------------- DDSTextureLoader.h contains a simple light-weight loader for .dds files. It supports 1D and 2D textures, texture arrays, cubemaps, volume maps, and mipmap levels. This version performs no legacy conversions, so the .dds file must directly map to a DXGI_FORMAT (i.e. legacy 24 bpp .dds files will fail to load). It does support both 'legacy' and 'DX10' extension file header format .dds files. For a full-featured DDS file reader, writer, and texture processing pipeline see the 'Texconv' sample and the 'DirectXTex' library CreateDDSTextureFromFile and CreateDDSTextureFromMemory can be called requesting only a 'texture' resource (i.e. textureView is null), requesting only a shader resource view (i.e. texture is null), or both. If maxsize is non-zero, then any mipmap level larger than the maxsize present in the file will be ignored and only smaller mipmap levels (if present) will be used. This can be used to scale the content at load-time. Note this requires the .dds file contain mipmaps to retry with a smaller size. If maxsize is 0 and the initial attempt to create the texture fails, it will attempt to trim off any mipmap levels larger than the minimum required size for the given device Feature Level and retry. Note this requires the .dds file contains mipmaps to retry with a smaller size. If a Direct3D 11 context is provided and a shader resource view is requested (i.e. textureView is non-null), then the texture will be created to support auto-generated mipmaps and will have GenerateMips called on it before returning. If no context is provided (i.e. d3dContext is null) or the pixel format is unsupported for auto-gen mips by the current device, then the resulting texture will have only a single level. DDSTextureLoader will load BGR 5:6:5 and BGRA 5:5:5:1 DDS files, but these formats will fail to create on a system with DirectX 11.0 Runtime. The DXGI 1.2 version of DDSTextureLoader will load BGRA 4:4:4:4 DDS files using DXGI_FORMAT_B4G4R4A4_UNORM. The DirectX 11.1 Runtime, DXGI 1.2 headers, and WDDM 1.2 drivers are required to support 16bpp pixel formats on all feature levels. Threading model: Resource creation with Direct3D 11 is thread-safe. CreateDDSTextureFromFile blocks the calling thread for reading the file data. CreateDDSTextureFromMemory can be used to implement asynchronous loading. Further reading: http://go.microsoft.com/fwlink/?LinkId=248926 http://blogs.msdn.com/b/chuckw/archive/2011/10/28/directxtex.aspx http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx ---------------- WICTextureLoader ---------------- WICTextureLoader.h contains a loader for BMP, JPEG, PNG, TIFF, GIF, HD Photo, and other WIC-supported image formats. This performs any required pixel format conversions or image resizing using WIC at load time as well. NOTE: WICTextureLoader is not supported on Windows phone 8.0 because WIC is not available on that platform. It is available on Windows phone starting in version 8.1. NOTE: WICTextureLoader cannot load .TGA files unless the system has a 3rd party WIC codec installed. You must use the DirectXTex library for TGA file format support without relying on an add-on WIC codec. CreateWICTextureFromFile and CreateWICTextureFromMemory can be called requesting only a 'texture' resource (i.e. textureView is null), requesting only a shader resource view (i.e. texture is null), or both. If maxsize is non-zero, then if the image is larger than maxsize it will be resized so that the largest dimension matches 'maxsize' (the other dimension will be derived respecting the original aspect-ratio of the image). If the maxsize is 0, then the maxsize will be implicitly set to the minimum required supported texture size based on the device's current feature level (2k, 4k, 8k, or 16k). If a Direct3D 11 context is provided and a shader resource view is requested (i.e. textureView is non-null), then the texture will be created to support auto-generated mipmaps and will have GenerateMips called on it before returning. If no context is provided (i.e. d3dContext is null) or the pixel format is unsupported for auto-gen mips by the current device, then the resulting texture will have only a single level. This loader does not support array textures, 1D textures, 3D volume textures, or cubemaps. For these scenarios, use the .dds file format and DDSTextureLoader instead. The DXGI 1.2 version of WICTextureLoader will load 16bpp pixel images as 5:6:5 or 5:5:5:1 rather than expand them to 32bpp RGBA. The DirectX 11.1 Runtime, DXGI 1.2 headers, and WDDM 1.2 drivers are required to support 16bpp pixel formats on all feature levels. Threading model: Resource creation with Direct3D 11 is thread-safe. CreateWICTextureFromFile blocks the calling thread for reading the file data. CreateWICTextureFromMemory can be used to implement asynchronous loading. Any use of either function with a ID3D11DeviceContext to support auto-gen of mipmaps is not thread-safe. Further reading: http://go.microsoft.com/fwlink/?LinkId=248926 http://blogs.msdn.com/b/chuckw/archive/2011/10/28/directxtex.aspx ---------- ScreenGrab ---------- ScreenGrab.h contains routines for writing out a texture, usually a render-target, to either a .dds file or a WIC-supported bitmap file (BMP, JPEG, PNG, TIFF, etc.). SaveDDSTextureToFile and SaveWICTextureToFile will save a texture to a file, which is a 'screen shot' when used with a render target texture. Only 2D textures are supported, and the routines will fail for 1D and 3D textures (aka volume maps). For 2D array textures and cubemaps, only the first image is written to disk. Mipmap levels are ignored by both routines. MSAA textures are resolved before being written. NOTE: For a complete DDS texture dump routine that supports all dimensions, arrays, cubemaps, and mipmaps use the 'DirectXTex' library. SaveDDSTextureToFile will store the data in the format of the original resource (i.e. performs no conversions), but will prefer using legacy .dds file headers when possible over the newer 'DX10' header extension for better tools support. The DXGI 1.2 version supports writing 16bpp pixel formats. SaveWICTextureToFile will convert the pixel data if needed, and prefers to use a non-alpha format (alpha channels in render targets can result in some strange looking screenshot files). The caller can also provide a specific pixel target format GUID to use as well. The caller provides the GUID of the specific file container format to use. NOTE: SaveWICTextureToFile is not supported on Windows phone 8.0 because WIC is not available on that platform. It is available on Windows phone starting in version 8.1. Capturing a screenshot: WRL::ComPtr<ID3D11Texture2D> backBuffer; hr = pSwapChain->GetBuffer( 0, __uuidof( ID3D11Texture2D ), ( LPVOID* )&backBuffer ); if ( SUCCEEDED(hr) ) { hr = SaveWICTextureToFile( pContext, backBuffer, GUID_ContainerFormatBmp, L"SCREENSHOT.BMP" ) ); } Threading model: Since these functions use ID3D11DeviceContext, they are not thread-safe. Further reading: http://go.microsoft.com/fwlink/?LinkId=248926 http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx ---------- SimpleMath ---------- SimpleMath.h 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 - Quaternion - Plane - Ray - Color 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. You should use SimpleMath if you are: - Looking for a C++ math library with similar API to the C# XNA 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 needed to express algorithms in raw SIMD 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. ------------------- GamePad ------------------- This is a helper for simplified access to gamepad controllers through the XInput API modeled after the XNA C# GamePad class. GamePad is supported on Windows and Xbox One. On Windows Phone 8.x, you can create and query the GamePad class, but it will always report no devices are connected since gamepads are not currently supported by the Windows Phone platform. Initialization: GamePad is a singleton. std::unique_ptr<GamePad> gamePad( new GamePad ); Basic use: GetState queries the controller status given a player index. If connected, it returns the status of the buttons (A, B, X, Y, left & right stick, left & right shoulder, back, and start), the directional pad (DPAD), the left & right thumb sticks, and the left & right triggers. auto state = gamePad->GetState( 0 ); if ( state.IsConnected() ) { if ( state.IsAPressed() ) // Do action for button A being down if ( state.buttons.y ) // Do action for button Y being down if ( state.IsDPadLeftPressed() ) // Do action for DPAD Left being down if ( state.dpad.up || state.dpad.down || state.dpad.left || state.dpad.right ) // Do action based on any DPAD change float posx = state.thumbSticks.leftX; float posy = state.thumbSticks.leftY; // These values are normalized to -1 to 1 float throttle = state.triggers.right; // This value is normalized 0 -> 1 if ( state.IsLeftTriggerPressed() ) // Do action based on a left trigger pressed more than halfway if ( state.IsViewPressed() ) // This is an alias for the Xbox 360 'Back' button // which is called 'View' on the Xbox One Controller. } Vibration: Many controllers include vibration motors to provide force-feedback to the user, which can be controlled with SetVibration and the player index. The motor values range from 0 to 1. if ( gamePad->SetVibration( 0, 0.5f, 0.25f ) ) // If true, the vibration was successfully set. Note: The trigger impulse motors on the Xbox One Controller are not accessible via XInput on Windows, and these motors are not present on the Xbox 360 Common Controller. Device capabilities: The GamePad class provides a simplified model for the device capabilties. auto caps = gamePad->GetCapabilities( 0 ); if ( caps.IsConnected() ) { if ( caps.gamepadType == GamePad::Capabilities::FLIGHT_STICK ) // Use specific controller layout based on a flight stick controller else // Default to treating any unknown type as a standard gamepad } Button state tracker: A common pattern for gamepads is to trigger an event when a button is pressed or released, but that you don't want to trigger the event every single frame if the button is held down for more than a single frame. This helper class simplifies this. std::unique_ptr<GamePad::ButtonStateTracker> tracker( new GamePad::ButtonStateTracker ); ... auto state = gamdPad->GetState( 0 ); if ( state.IsConnected() ) { tracker->Update( state ); if ( tracker->a == GamePad::ButtonStateTracker::PRESSED ) // Take an action when Button A is first pressed, but don't do it again until // the button is released and then pressed again } Each button is reported by the tracker with a state UP, HELD, PRESSED, or RELEASED. When resuming from a pause or suspend, be sure to call Reset() on the tracker object to clear the state history. Threading model: The GamePad class provides no special synchronziation above the underlying API. XInput on Windows is thread-safe through a internal global lock, so performance is best when only a single thread accesses the controller. Further reading: http://blogs.msdn.com/b/chuckw/archive/2012/04/26/xinput-and-windows-8-consumer-preview.aspx ------------------- DirectXTK for Audio ------------------- The DirectXTK for Audio components implement a low-level audio API similar to XNA Game Studio's Microsoft.Xna.Framework.Audio. This consists of the following classes all declared in the Audio.h header (in the Inc folder of the distribution): AudioEngine - This class represents an XAudio2 audio graph, device, and mastering voice SoundEffect - A container class for sound resources which can be loaded from .wav files SoundEffectInstance - Provides a single playing, paused, or stopped instance of a sound DynamicSoundEffectInstance - SoundEffectInstance where the application provides the audio data on demand WaveBank - A container class for sound resources packaged into an XACT-style .xwb wave bank AudioListener, AudioEmitter - Utility classes used with SoundEffectInstance::Apply3D Note: DirectXTK for Audio uses XAudio 2.8 or XAudio 2.7. It does not make use of the legacy XACT Engine, XACT Cue, or XACT SoundBank. During initialization: The first step in using DirectXTK for Audio is to create the AudioEngine, which creates an XAudio2 interface, an XAudio2 mastering voice, and other global resources. // This is only needed in Win32 desktop apps CoInitializeEx( nullptr, COINIT_MULTITHREADED ); AUDIO_ENGINE_FLAGS eflags = AudioEngine_Default; #ifdef _DEBUG eflags = eflags | AudioEngine_Debug; #endif std::unique_ptr<AudioEngine> audEngine( new AudioEngine( eflags ) ); Per-frame processing: The application should call Update() every frame to allow for per-frame engine updates, such as one-shot voice management. This could also be done in a worker thread rather than on the main rendering thread. if ( !audEngine->Update() ) { // No audio device is active if ( audEngine->IsCriticalError() ) { ... } } Update() returns false if no audio is actually playing (either due to there being no audio device on the system at the time AudioEngine was created, or because XAudio2 encountered a Critical Error--typically due to speakers being unplugged). Calls to various DirectXTK for Audio methods can still be made in this state but no actual audio processing will take place. Loading and a playing a looping sound: Creating SoundEffectInstances allows full control over the playback, and are provided with a dedicated XAudio2 source voice. This allows control of playback, looping, volume control, panning, and pitch-shifting. std::unique_ptr<SoundEffect> soundEffect( new SoundEffect( audEngine.get(), L"Sound.wav" ) ); auto effect = soundEffect->CreateInstance(); ... effect->Play( true ); Playing one-shots: A common way to play sounds is to trigger them in a 'fire-and-forget' mode. This is done by calling SoundEffect::Play() rather than creating a SoundEffectInstance. These use XAudio2 source voices managed by AudioEngine, are cleaned up automatically when they finish playing, and can overlap in time. One-shot sounds cannot be looped or have 3D positional effects. std::unique_ptr<SoundEffect> soundEffect( new SoundEffect( audEngine.get(), L"Explosion.wav" ) ); soundEffect->Play(); ... soundEffect->Play(); Applying 3D audio effects to a sound: DirectXTK for Audio supports 3D positional audio with optional environmental reverb effects using X3DAudio. AUDIO_ENGINE_FLAGS eflags = AudioEngine_EnvironmentalReverb | AudioEngine_ReverbUseFilters; #ifdef _DEBUG eflags = eflags | AudioEngine_Debug; #endif std::unique_ptr<AudioEngine> audEngine( new AudioEngine( eflags ) ); audEngine->SetReverb( Reverb_ConcertHall ); std::unique_ptr<SoundEffect> soundEffect( new SoundEffect( audEngine.get(), L"Sound.wav" ) ); auto effect = soundEffect->CreateInstance( SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters ); ... effect->Play(true); ... AudioListener listener; listener.SetPosition( ... ); AudioEmitter emitter; emitter.SetPosition( ... ); effect->Apply3D( listener, emitter ); Note: A C++ exception is thrown if you call Apply3D for a SoundEffectInstance that was not created with SoundEffectInstance_Use3D Using wave banks: Rather than loading individual .wav files, a more efficient method is to package them into a "wave bank". This allows for more efficient loading and memory organization. DirectXTK for Audio's WaveBank class can be used to play one-shots or to create SoundEffectInstances from 'in-memory' wave banks. std::unique_ptr<WaveBank> wb( new WaveBank( audEngine.get(), L"wavebank.xwb" ) ); A SoundEffectInstance can be created from a wavebank referencing a particular wave in the bank: auto effect = wb->CreateInstance( 10 ); if ( !effect ) // Error (invalid index for wave bank) ... effect->Play( true ); One-shot sounds can also be played directly from the wave bank. wb->Play( 2 ); wb->Play( 6 ); XACT3-style "wave banks" can be created by using the XWBTool command-line tool, or they can be authored using XACT3 in the DirectX SDK. Note that the XWBTool will not perform any format conversions or compression, so more full-featured options are better handled with the XACT3 GUI or XACTBLD, or it can be used on .wav files already compressed by adpcmencode.exe, xwmaencode.exe, xma2encode.exe, etc. xwbtool -o wavebank.xwb Sound.wav Explosion.wav Music.wav DirectXTK for Audio does not make use of the XACT engine, nor does it make use of XACT "sound banks" .xsb or "cues". We only use .xwb wave banks as a method for packing .wav data. Command-line options for the XWBTool: -s Creates as streaming wave bank, otherwise defaults to in-memory wave bank -o <filename> Sets output filename for .xwb file. Otherwise, it defaults to the same base name as the first input .wav file -h <h-filename> Generates a C/C++ header file with #defines for each of the sounds in the bank matched to their index -n Disables the default warning of overwriting an existing .xwb file -c / -nc Forces creation or prevents use of compact wave banks. By default, it will try to use a compact wave bank if possible. -f Includes entry friendly name strings in the wave bank for use with 'string' based versions of WaveBank::Play() and WaveBank::CreateInstance() rather than index-based versions. Voice management Each instance of a SoundEffectInstance will allocate it's own source voice when played, which won't be released until it is destroyed. Each time a one-shot sound is played from a SoundEffect or a WaveBank, a voice will be created or a previously used one-shot voice will be reused if possible. SetDefaultSampleRate() is used to control the sample rate for voices in the one-shot pool. This should be the same rate as used by the majority of your content. It defaults to 44100 Hz. TrimVoicePool() can be used to free up any source voices in the 'idle' list for one-shots, and will cause all non-playing SoundEffectInstance objects to release their source voice. This is used for keeping the total source voice count under a limit for performance or when switching sections where audio content formats change dramatically. SetMaxVoicePool() can be used to set a limit on the number of one-shot source voices allocated and/or to put a limit on the source voices available for SoundEffectInstance. If there are insufficient one-shot voices, those sounds will not be heard. If there are insufficient voices for a SoundEffectInstance to play, then a C++ exception is thrown. These values default to 'unlimited'. Platform support: Windows 8.x, Windows Store apps, Windows phone 8.x, and Xbox One all include XAudio 2.8. Therefore, the standard DirectXTK.lib includes DirectXTK for Audio for all these platforms. * DirectXTK_Windows81 * DirectXTK_Windows8 * DirectXTK_WindowsPhone81 * DirectXTK_XAMLSilverlight_WindowsPhone81 * DirectXTK_WindowsPhone8 * DirectXTK_XboxOneXDK * DirectXTK_XboxOneADK For Win32 desktop applications targeting Windows 8.x or later, you can make use of XAudio 2.8. The DirectXTKAudioWin8.lib contains the XAudio 2.8 version of DirectXTK for Audio, while DirectXTK.lib for Win32 desktop contains only the math/graphics components. To support Win32 desktop applications on Windows 7 and Windows Vista, we must make use XAudio 2.7, the legacy DirectX SDK, and the legacy DirectX End-User Runtime Redistribution packages (aka DirectSetup). The DirectXTKAudioDX.lib is the XAudio 2.7 version of DirectXTK for Audio. * DirectXTK_Desktop_201x + Audio\DirectXTKAudio_Desktop_201x_Win8 * DirectXTK_Desktop_201x + Audio\DirectXTKAudio_Desktop_201x_DXSDK VS 2010 Note: We only support DirectXTK for Audio with the legacy DirectX SDK due to some issues with using the VS 2010 toolset and the Windows 8.x SDK WinRT headers. http://msdn.microsoft.com/en-us/library/windows/desktop/ee415802.aspx http://support.microsoft.com/kb/2728613 http://msdn.microsoft.com/en-us/library/windows/desktop/ee663275.aspx DirectXTK for Audio supports wave content in PCM and a variant of MS-ADPCM formats. When built for Xbox One or using XAudio 2.7, it also supports xWMA. XMA2 is supported by the Xbox One XDK version only. DirectXTK makes use of the latest Direct3D 11.1 headers available in the Windows 8.x SDK, and there are a number of file conflicts between the Windows 8.x SDK and the legacy DirectX SDK. Therefore, when building for down-level support with XAudio 2.7, Audio.h explicitly includes the DirectX SDK version of XAudio2 headers with a full path name. These reflect the default install locations, and if you have installed it elsewhere you will need to update this header. The *_DXSDK.vcxproj files use the DXSDK_DIR environment variable, so only the Audio.h references need updating for an alternative location. Threading model: The DirectXTK for Audio methods assume it is always called from a single thread. This is generally either the main thread or a worker thread dedicated to audio processing. The XAudio2 engine itself makes use of lock-free mechanism to make it 'thread-safe'. Note that IVoiceNotify::OnBufferEnd is called from XAudio2's thread, so the callback must be very fast and use thread-safe operations. Further reading: http://blogs.msdn.com/b/chuckw/archive/2012/05/15/learning-xaudio2.aspx http://blogs.msdn.com/b/chuckw/archive/2012/04/02/xaudio2-and-windows-8-consumer-preview.aspx --------------- RELEASE HISTORY --------------- March 27, 2015 Added projects for Windows apps Technical Preview - GamePad temporarily uses 'null' device for universal Windows applicaton platform February 25, 2015 DirectXTK for Audio updates - *breaking change* pitch now defined as -1 to 1 with 0 as the default - One-shot Play method with volume, pitch, and pan - GetMasterVolume/SetMasterVolume method for AudioEngine - Fix for compact wavebank validation - Improved voice cleanup and shutdown Minor code cleanup and C++11 =default/=delete usage January 26, 2015 GamePad class: emulate XInputEnable behavior for XInput 9.1.0 DirectXTK for Audio fix for Stop followed by Play doing a proper restart DirectXTK for Audio fix when using XAudio 2.7 on a system with no audio device Updates for Xbox One platform support Minor code cleanup and C99 printf string conformance November 24, 2014 SimpleMath fix for Matrix operator != DirectXTK for Audio workaround for XAudio 2.7 on Windows 7 problem Updates for Windows phone 8.1 platform support Updates for Visual Studio 2015 Technical Preview Minor code cleanup October 28, 2014 Model support for loading from VBO files Model render now sets samplers on slots 0,1 by default for dual-texture effects Updates for Xbox One platform support Minor code cleanup September 5, 2014 GamePad class: gamepad controller helper using XInput on Windows, IGamepad for Xbox One SimpleMath updates; Matrix billboard methods; breaking change: Matrix::Identity() -> Matrix::Identity SpriteBatch new optional SetViewport method SpriteFont fix for white-space character rendering optimization DDSTextureLoader fix for auto-gen mipmaps for volume textures Explicit calling-convention annotation for public headers Updates for Xbox One platform support Minor code and project cleanup July 15, 2014 DirectXTK for Audio and XWBTool fixes Updates to Xbox One platform support April 3, 2014 Windows phone 8.1 platform support February 24, 2014 DirectXHelper: new utility header with MapGuard and public version of SetDebugObjectName template DDSTextureLoader: Optional support for auto-gen mipmaps DDSTextureLoader/ScreenGrab: support for Direct3D 11 video formats including legacy "YUY2" DDS files GeometricPrimtive: Handedness fix for tetrahedron, octahedron, dodecahedron, and icosahedron SpriteBatch::SetRotation(DXGI_MODE_ROTATION_UNSPECIFIED) to disable viewport matrix XboxDDSTextureLoader: optional forceSRGB parameter January 24, 2014 DirectXTK for Audio updated with voice management and optional mastering volume limiter Added orientation rotation support to SpriteBatch Fixed a resource leak with GetDefaultTexture() used by some Effects Code cleanup (removed DXGI_1_2_FORMATS control define; d2d1.h workaround not needed; ScopedObject typedef removed) December 24, 2013 DirectXTK for Audio Xbox One platform support MakeSpriteFont tool updated with more progress feedback when capturing large fonts Minor updates for .SDKMESH Model loader Fixed bug in .CMO Model loader when handling multiple textures Improved debugging output October 28, 2013 Updated for Visual Studio 2013 and Windows 8.1 SDK RTM Added DGSLEffect, DGSLEffectFactory, VertexPositionNormalTangentColorTexture, and VertexPositionNormalTangentColorTextureSkinning Model loading and effect factories support loading skinned models MakeSpriteFont now has a smooth vs. sharp antialiasing option: /sharp Model loading from CMOs now handles UV transforms for texture coordinates A number of small fixes for EffectFactory Minor code and project cleanup Added NO_D3D11_DEBUG_NAME compilation define to control population of Direct3D debug layer names for debug builds July 1, 2013 VS 2013 Preview projects added and updates for DirectXMath 3.05 __vectorcall Added use of sRGB WIC metadata for JPEG, PNG, and TIFF SaveToWIC functions updated with new optional setCustomProps parameter and error check with optional targetFormat May 30, 2013 Added more GeometricPrimitives: Cone, Tetrahedron, Octahedron, Dodecahedron, Icosahedron Updated to support loading new metadata from DDS files (if present) Fixed bug with loading of WIC 32bpp RGBE format images Fixed bug when skipping mipmaps in a 1D or 2D array texture DDS file February 22, 2013 Added SimpleMath header Fixed bug that prevented properly overriding EffectFactory::CreateTexture Fixed forceSRGB logic in DDSTextureLoader and WICTextureLoader Break circular reference chains when using SpriteBatch with a setCustomShaders lambda Updated projects with /fp:fast for all configs, /arch:SSE2 for Win32 configs Sensibly named .pdb output files Added WIC_USE_FACTORY_PROXY build option (uses WindowsCodecs.dll entrypoint rather than CoCreateInstance) January 25, 2013 GeometricPrimitive support for left-handed coordinates and drawing with custom effects Model, ModelMesh, and ModelMeshPart added with loading of rigid non-animating models from .CMO and .SDKMESH files EffectFactory helper class added December 11, 2012 Ex versions of DDSTextureLoader and WICTextureLoader Removed use of ATL's CComPtr in favor of WRL's ComPtr for all platforms to support VS Express editions Updated VS 2010 project for official 'property sheet' integration for Windows 8.0 SDK Minor fix to CommonStates for Feature Level 9.1 Tweaked AlphaTestEffect.cpp to work around ARM NEON compiler codegen bug Added dxguid.lib as a default library for Debug builds to resolve GUID link issues November 15, 2012 Added support for WIC2 when available on Windows 8 and Windows 7 with KB 2670838 Cleaned up warning level 4 warnings October 30, 2012 Added project files for Windows phone 8 October 12, 2012 Added PrimitiveBatch for drawing user primitives Debug object names for all D3D resources (for PIX and debug layer leak reporting) October 2, 2012 Added ScreenGrab module Added CreateGeoSphere for drawing a geodesic sphere Put DDSTextureLoader and WICTextureLoader into the DirectX C++ namespace September 7, 2012 Renamed project files for better naming consistency Updated WICTextureLoader for Windows 8 96bpp floating-point formats Win32 desktop projects updated to use Windows Vista (0x0600) rather than Windows 7 (0x0601) APIs Tweaked SpriteBatch.cpp to workaround ARM NEON compiler codegen bug May 31, 2012 Updated Metro project for Visual Studio 2012 Release Candidate changes Cleaned up x64 Debug configuration warnings and switched to use "_DEBUG" instead of "DEBUG" Minor fix for DDSTextureLoader's retry fallback that can happen with 10level9 feature levels May 2, 2012 Added SpriteFont implementation and the MakeSpriteFont utility March 29, 2012 WICTextureLoader updated with Windows 8 WIC native pixel formats March 6, 2012 Fix for too much temp memory used by WICTextureLoader Add separate Visual Studio 11 projects for Desktop vs. Metro builds March 5, 2012 Bug fix for SpriteBatch with batches > 2048 February 24, 2012 Original release