directxtk Wiki Rss Feed

Updated Wiki: GeometricPrimitive

walbourn — Wed, 22 May 2013 22:32:33 GMT

This is a helper for drawing simple geometric shapes including texture coordinates and surface normals.

Cube
Sphere
Geodesic Sphere
Cylinder
Torus
Teapot

Initialization

The GeometryPrimitive class must be created from a factory method which takes the Direct3D 11 device context.

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

For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr

CreateCube( deviceContext, float size = 1)
CreateSphere( deviceContext, float diameter = 1, size_t tessellation = 16)
CreateGeoSphere( deviceContext, float diameter = 1, size_t tessellation = 3)
CreateCylinder( deviceContext, float height = 1, float diameter = 1, size_t tessellation = 32)
CreateTorus( deviceContext, float diameter = 1, float thickness = 0.333f, size_t tessellation = 32)
CreateTeapot( deviceContext, float size = 1, size_t tessellation = 8)

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

This form of drawing makes use of a custom Effects instance. The caller is responsible for using an input layout that matches the effect.

IEffect* myeffect = ...

Microsoft::WRL::ComPtr<ID3D11InputLayout> inputLayout;
shape->CreateInputLayout( myeffect, &inputLayout );

shape->Draw( myeffect, inputLayout.Get() );

This takes an optional parameter for enabling alpha-blending, wireframe, and a callback function which can be used to override the default rendering state.

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').

std::unique_ptr<GeometricPrimitive> shape(
GeometricPrimitive::CreateTeapot( deviceContext, 1.f, 8, false ) );

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(deviceContext);

shape->Draw(world, view, projection, Colors::White, catTexture, false, [=]
{
    deviceContext->OMSetBlendState( states.NonPremultiplied(), nullptr, 0xFFFFFFFF);
});

Feature Level Notes

In order to support all feature levels, the GeometricPrimitive implementation make use of 16-bit indices (DXGI_FORMAT_R16_UINT) which limits to a maximum of 65535 vertices. Feature Level 9.1 is limited to a maximum of 65535 primitives in a single draw.

Threading model

Each GeometricPrimitive instance only supports drawing from one thread at a time, but you can simultaneously submit primitives on multiple threads if you create a separate GeometricPrimitive instance per Direct3D 11 deferred context.
http://msdn.microsoft.com/en-us/library/windows/desktop/ff476892.aspx

Updated Wiki: GeometricPrimitive

walbourn — Wed, 22 May 2013 22:29:11 GMT

This is a helper for drawing simple geometric shapes including texture coordinates and surface normals.

Cube
Sphere
Geodesic Sphere
Cylinder
Torus
Teapot

Initialization

The GeometryPrimitive class must be created from a factory method which takes the Direct3D 11 device context.

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

For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr

CreateCube( deviceContext, float size = 1)
CreateSphere( deviceContext, float diameter = 1, size_t tessellation = 16)
CreateGeoSphere( deviceContext, float diameter = 1, size_t tessellation = 3)
CreateCylinder( deviceContext, float height = 1, float diameter = 1, size_t tessellation = 32)
CreateTorus( deviceContext, float diameter = 1, float thickness = 0.333f, size_t tessellation = 32)
CreateTeapot( deviceContext, float size = 1, size_t tessellation = 8)

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

This form of drawing makes use of a custom Effects instance. The caller is responsible for using an input layout that matches the effect.

IEffect* myeffect = ...

Microsoft::WRL::ComPtr<ID3D11InputLayout> inputLayout;
shape->CreateInputLayout( myeffect, &inputLayout );

shape->Draw( myeffect, inputLayout.Get() );

This takes an optional parameter for enabling alpha-blending, wireframe, and a callback function which can be used to override the default rendering state.

Coordinate systems

std::unique_ptr<GeometricPrimitive> shape(
GeometricPrimitive::CreateTeapot( deviceContext, 1.f, 8, false ) );

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(deviceContext);

shape->Draw(world, view, projection, Colors::White, catTexture, false, [=]
{
    deviceContext->OMSetBlendState( states.NonPremultiplied(), nullptr, 0xFFFFFFFF);
});

Feature Level Notes

Threading model

Updated Wiki: Model

walbourn — Sat, 04 May 2013 03:26:19 GMT

This is a class hierarchy for drawing simple meshes with support for loading rigid models from Visual Studio 3D Starter Kit .CMO files and legacy DirectX SDK .SDKMESH files. It is an implementation of a mesh renderer similar to the XNA Game Studio Model, ModelMesh, ModelMeshPart design.

NOTE: Currently Model only supports rigid models. Support for animation, skinning, and frame hierarchy is not yet implemented.

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 either .CMO files or .SDKMESH 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.

Visual Studio 2012 includes 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 );

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. See ModelMesh for an example.

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). See ModelMeshPart for an example.

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 coordiantes
        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. See ModelMeshPart for an example.

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. See ModelMesh for an example.

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.

// When using LH coordinates
auto teapot = Model::CreateFromCMO( device, L"teapot.cmo", fx, false );

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.

// When using LH coordinates
auto tiny = Model::CreateFromSDKMESH( device, L"tiny.sdkmesh", fx, true );

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).

Content Notes

The SDKMESH exporter http://go.microsoft.com/fwlink/?LinkId=226208 uses Autodesk FBX 2011.3.1.

VS 2012's CMO exporter uses Autodesk FBX 2013.1. Recommended settings for exporting an FBX as a CMO include:

Geometry: Smoothing Groups, TurboSmooth, Convert Deforming Dummies to Bones, Preserve edge orientation
Animation: Bake Animation (Start=0, End=100, Step=1), Deformations, Skins, Morphs
Units: Automatic
Axis conversion: Y-up
FBX File Format: Binary, FBX 2013

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’. See EffectFactory for some additional notes.

Updated Wiki: Model

walbourn — Sat, 04 May 2013 03:24:57 GMT

Initialization

EffectFactory fx( device );

auto teapot = Model::CreateFromCMO( device, L"teapot.cmo", fx );

auto tiny = Model::CreateFromSDKMESH( device, L"tiny.sdkmesh", fx );

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

Effects control

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 coordiantes
        fog->SetFogEnd(8);
        fog->SetFogColor(Colors::CornflowerBlue);
    }
});

Alpha blending

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

// When using LH coordinates
auto teapot = Model::CreateFromCMO( device, L"teapot.cmo", fx, false );

// When using LH coordinates
auto tiny = Model::CreateFromSDKMESH( device, L"tiny.sdkmesh", fx, true );

Feature Level Notes

Content Notes

The SDKMESH exporter http://go.microsoft.com/fwlink/?LinkId=226208 uses Autodesk FBX 2011.3.1.

VS 2012's CMO exporter uses Autodesk FBX 2013.1.

Threading model

Updated Wiki: DirectXTK

walbourn — Sun, 14 Apr 2013 06:01:51 GMT

Headers

Public headers are in the Inc folder of the distribution package.

Namespace

All the functions in the library are in the DirectX C++ namespace.

Modules

SpriteBatch - simple & efficient 2D sprite rendering
SpriteFont - bitmap based text rendering
Effects - set of built-in shaders for common rendering tasks
PrimitiveBatch - simple and efficient way to draw user primitives
GeometricPrimitive - draws basic shapes such as cubes and spheres
Model - draws simple meshes loaded from .CMO or .SDKMESH files
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
ScreenGrab - light-weight screen shot saver
SimpleMath - simplified C++ wrapper for DirectXMath

Tools

MakeSpriteFont

Building

This code is designed to build with either Visual Studio 2012 or Visual Studio 2010. It requires the Windows 8.0 SDK for functionality such as the DirectXMath library and optionally the DXGI 1.2 headers. Visual Studio 2012 already includes this Windows SDK, but Visual Studio 2010 users must install the standalone Windows 8.0 SDK. Details on using the Windows 8.0 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

Adding to a VS Project

In your application's solution, right-click on the Solution and use "Add \ Existing Project..." to add the appropriate .vcxproj file to your solution.

DirectXTK_Windows8 is for Windows Store apps building with VS 2012
DirectXTK_WindowsPhone8 is for Windows phone 8 apps building with VS 2012 and the Windows Phone 8.0 SDK
DirectXTK_Desktop_2012 is for Win32 desktop applications building with VS 2012 Express for Desktop, VS 2012 Professional or higher
DirectXTK_Desktop_2010 is for Win32 desktop applications building with VS 2010 using the Windows 8.0 SDK

In your application's project, right-click on the Project and use "References...", then "Add New Reference...", and then check the DirectXTK project name and click OK. For a Windows Store app, you need to set Reference Assembly Output to false since DirectXTK is a static C++ library and not a WinRT component.

In your application's project settings, on the "C++ / General" page set Configuration to "All Configurations", set Platform to "All Plaforms", and then add the path $(SolutionDir)\DirectXTK\inc; to the Additional Include Directories properties. Click Apply.

Error Handling

DirectXTK makes use of C++ exception handling which should be enabled by the application via the /EHsc compiler switch. In Visual Studio, this is set in the project settings under "C++ / Code Generation" with Enable C++ Exceptions set to "Yes (/EHsc)" for all configurations.

http://msdn.microsoft.com/en-us/library/4t3saedz.aspx
http://msdn.microsoft.com/en-us/library/d14azbfh.aspx
http://blogs.msdn.com/b/chuckw/archive/2012/09/17/dual-use-coding-techniques-for-games.aspx
http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization

Updated Wiki: DDSTextureLoader

walbourn — Thu, 11 Apr 2013 22:44:15 GMT

A streamlined version of the DirectX SDK sample DDSWithoutD3DX11 texture loading code for a simple light-weight runtime .DDS file loader. This version only supports Direct3D 11 and performs no runtime pixel data conversions (see Release Notes for more details). This is ideal for runtime usage, and supports the full complement of Direct3D 11 texture resources (1D, 2D, volume maps, cubemaps, mipmap levels, texture arrays, BC formats, etc.). It supports both legacy and 'DX10' extension header format .dds files.

Also part of DirectXTex http://go.microsoft.com/fwlink/?LinkId=248926

Functions

CreateDDSTextureFromMemory
Loads a .DDS file assuming the image of the file is located in a memory buffer. Creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

CreateDDSTextureFromFile
Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

For both these functions if 'maxsize' parameter non-zero, then all mipmap levels larger than the maxsize are ignored before creating the Direct3D 11 resource. This allows for load-time scaling. If '0', then if the attempt to create the Direct3D 11 resource fails and there are mipmaps present, it will retry assuming a maxsize based on the device's current feature level.

The last optional parameter for both functions is a pointer to return the alpha mode of the DDS file. This can be one of the following values to return information about the alpha channel if present in the file:

DDS_ALPHA_MODE_UNKNOWN (0) - This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_STRAIGHT (1) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. Viewers should use the alpha channel with 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (2) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.
DDS_ALPHA_MODE_CUSTOM (4) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewers should not use the alpha channel for blending, and should instead view it as a distinct image channel.

CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
These versions provide explicit control over the created resource's usage, binding flags, CPU access flags, and miscellaneous flags for advanced / expert scenarios. The standard routines default to D3D11_USAGE_DEFAULT, D3D11_BIND_SHADER_RESOURCE, 0, and 0 respectively. For cubemaps, the miscellaneous flags default to D3D11_RESOURCE_MISC_TEXTURECUBE. There is also a 'forceSRGB' option for working around gamma issues with content that is in the sRGB or similar color space but is not encoded explicitly as an SRGB format. Note that the 'maxsize' parameter is not at the end of the parameter list like it is in the non-Ex version.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11ShaderResourceView> srv;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &srv )
ThrowIfFailed(hr);

Feature Level Notes

In order to support all feature levels, you should make sure your DDS textures are mip-mapped so that they contain a suitably sized image. Non-mipmapped textures will either need explicit feature level association, or be sized less than or equal to 2048 for 1D, 2048 x 2048 for 2D, 512 x 512 for cubemaps, and 256 x 256 x 256 for volume maps.

Texture arrays require Feature Level 10.0 or later. Cubemap arrays requires Feature Level 10.1 or later.

Be sure to review the various format limitations for the different feature levels. To support all feature levels, stick with textures in the following formats:

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: SimpleMath

walbourn — Tue, 26 Mar 2013 20:27:23 GMT

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

To use:

    #include "SimpleMath.h"

    using namespace DirectX::SimpleMath;

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.

Coordinate Systems

Because SimpleMath Is intended to look a lot like like XNA Game Studio's math library, it uses right-handed coordinates by convention for the following Matrix methods:

CreatePerspectiveFieldOfView
CreatePerspective
CreatePerspectiveOffCenter
CreateOrthographic
CreateOrthographicOffCenter
CreateLookAt

If you want to use left-handed coordinates, use the DirectXMath methods directly. For example

// Here's a RH example
Vector3 eye, target, up;
...
Matrix mView = Matrix::CreateLookAt( eye, target, up );

// Here' is a LH example of same thing which relies on
// Vector3 and Matrix conversion operators
Vector3 eye, target, up;
...
Matrix mView = XMMatrixLookAtLH( eye, target, up );

Updated Wiki: SimpleMath

walbourn — Tue, 26 Mar 2013 18:30:34 GMT

Vector2
Vector3
Vector4
Matrix
Quaternion
Plane
Ray
Color

To use:

    #include "SimpleMath.h"

    using namespace DirectX::SimpleMath;

Why wrap DirectXMath?

Enter SimpleMath...

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

Coordinate Systems

Because SimpleMath Is intended to look a lot like like XNA Game Studio's math library, it uses right-handed coordinates by convention for the following Matrix methods:

CreatePerspectiveFieldOfView
CreatePerspective
CreatePerspectiveOffCenter
CreateOrthographic
CreateOrthographicOffCenter
CreateLookAt

If you want to use left-handed coordinates, use the DirectXMath methods directly. For example

// Here's a RH example
Vector3 eye, target, up;
...
Matrix mView = Matrix::CreateLookAt( eye, target, up );

// Here' is a LH example of same thing which relies on Vector3 and Matrix conversion operators
Vector3 eye, target, up;
...
Matrix mView = XMMatrixLookAtLH( eye, target, up );

Updated Wiki: SimpleMath

walbourn — Tue, 26 Mar 2013 18:28:13 GMT

Vector2
Vector3
Vector4
Matrix
Quaternion
Plane
Ray
Color

To use:

    #include "SimpleMath.h"

    using namespace DirectX::SimpleMath;

Why wrap DirectXMath?

Enter SimpleMath...

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

Coordinate Systems

Because SimpleMath Is intended to look a lot like like XNA Game Studio's math library, it uses right-handed coordinates by convention for the following Matrix methods:

CreatePerspectiveFieldOfView
CreatePerspective
CreatePerspectiveOffCenter
CreateOrthographic
CreateOrthographicOffCenter
CreateLookAt

If you want to use left-handed coordinates, use the DirectXMath methods directly. For example

// Here's a RH example
Vector3 eye, target, up;
...
Matrix mView = Matrix::CreateLookAt( eye, target, up );

// Here' is a LH example of same thing which relies on Vector3 and Matrix conversion operators
Vector3 eye, target, up;
...
Matrix mView = XMMatrixLookAtLH( eye, target, up );

Updated Wiki: DDSTextureLoader

walbourn — Sat, 23 Mar 2013 06:31:34 GMT

Functions

DDS_ALPHA_MODE_STRAIGHT (0) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (1) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_4TH_CHANNEL (2) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewers should not use the alpha channel for blending, and should instead view it as a distinct image channel.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11ShaderResourceView> srv;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &srv )
ThrowIfFailed(hr);

Feature Level Notes

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: DDSTextureLoader

walbourn — Sat, 23 Mar 2013 06:26:26 GMT

Functions

DDS_ALPHA_MODE_STRAIGHT (0) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (1) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_TH_CHANNEL (2) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewers should not use the alpha channel for blending, and should instead view it as a distinct image channel.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11ShaderResourceView> srv;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &srv )
ThrowIfFailed(hr);

Feature Level Notes

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: DDSTextureLoader

walbourn — Sat, 23 Mar 2013 06:25:45 GMT

Functions

DDS_ALPHA_MODE_STRAIGHT (0) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (1) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_TH_CHANNEL (2) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewer should not use the alpha channel for blending, and should instead view it as a distinct image channel.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11ShaderResourceView> srv;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &srv )
ThrowIfFailed(hr);

Feature Level Notes

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: DDSTextureLoader

walbourn — Sat, 23 Mar 2013 06:21:51 GMT

Functions

DDS_ALPHA_MODE_STRAIGHT (0) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. This is the default for most .DDS files if the specific metadata isn't present, and it's largely up to the application to know if it's really something else.
DDS_ALPHA_MODE_PREMULTIPLIED}" (1) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha.
* {"DDS_ALPHA_MODE_TH_CHANNEL (2) - This indicates the alpha channel if present does not contain transparency neither straight or premultiplied alpha and instead is encoding some other channel of information.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11ShaderResourceView> srv;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &srv )
ThrowIfFailed(hr);

Feature Level Notes

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: Game Gallery

walbourn — Thu, 14 Mar 2013 18:59:31 GMT

This is a list of known released games that make use of DirectX Tool Kit.

Galactic Reign
http://go.microsoft.com/fwlink/?LinkId=281841
http://go.microsoft.com/fwlink/?LinkId=281840

Updated Wiki: Documentation

walbourn — Thu, 14 Mar 2013 18:58:09 GMT

DirectXTK library

Version History

Samples

Game Gallery

Resources

Updated Wiki: Version History

walbourn — Fri, 22 Feb 2013 22:44:47 GMT

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

Updated Wiki: SimpleMath

ShawnHargreaves — Fri, 22 Feb 2013 22:10:06 GMT

Vector2
Vector3
Vector4
Matrix
Quaternion
Plane
Ray
Color

To use:

    #include "SimpleMath.h"

    using namespace DirectX::SimpleMath;

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

Updated Wiki: SimpleMath

ShawnHargreaves — Fri, 22 Feb 2013 22:09:36 GMT

Vector2
Vector3
Vector4
Matrix
Quaternion
Plane
Ray
Color

To use:

    #include "SimpleMath.h"

    using namespace DirectX::SimpleMath;

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

Updated Wiki: DirectXTK

ShawnHargreaves — Fri, 22 Feb 2013 22:04:48 GMT

Headers

Public headers are in the Inc folder of the distribution package.

Namespace

All the functions in the library are in the DirectX C++ namespace.

Modules

SpriteBatch - simple & efficient 2D sprite rendering
SpriteFont - bitmap based text rendering
Effects - set of built-in shaders for common rendering tasks
PrimitiveBatch - simple and efficient way to draw user primitives
GeometricPrimitive - draws basic shapes such as cubes and spheres
Model - draws simple meshes loaded from .CMO or .SDKMESH files
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
ScreenGrab - light-weight screen shot saver
SimpleMath - simplified C++ wrapper for DirectXMath

Tools

MakeSpriteFont

Building

Adding to a VS Project

In your application's solution, right-click on the Solution and use "Add \ Existing Project..." to add the appropriate .vcxproj file to your solution.

DirectXTK_Windows8 is for Windows Store apps building with VS 2012
DirectXTK_WindowsPhone8 is for Windows phone 8 apps building with VS 2012 and the Windows Phone 8.0 SDK
DirectXTK_Desktop_2012 is for Win32 desktop applications building with VS 2012 Express for Desktop, VS 2012 Professional or higher
DirectXTK_Desktop_2010 is for Win32 desktop applications building with VS 2010 using the Windows 8.0 SDK

In your application's project, right-click on the Project and use "References...", then "Add New Reference...", and then check the DirectXTK project name and click OK. For a Windows Store app, you need to set Reference Assembly Output to false since DirectXTK is a static C++ library and not a WinRT component.

In your application's project settings, on the "C++ / General" page set Configuration to "All Configurations", set Platform to "All Plaforms", and then add the relative path to DirectXTK\inc; to the Additional Include Directories properties. Click Apply.

Error Handling

Updated Wiki: Home

ShawnHargreaves — Fri, 22 Feb 2013 22:04:16 GMT

http://go.microsoft.com/fwlink/?LinkId=248929

Project Description
The DirectX Tool Kit (aka DirectXTK) is a collection of helper classes for writing Direct3D 11 code in C++.

Supported platforms:

Windows Store apps
Windows 8 Win32 desktop
Windows Phone 8
Windows 7
Windows Vista Service Pack 2 with KB 971644

Features:

SpriteBatch - simple & efficient 2D sprite rendering
SpriteFont - bitmap based text rendering
Effects - set of built-in shaders for common rendering tasks
PrimitiveBatch - simple and efficient way to draw user primitives
GeometricPrimitive - draws basic shapes such as cubes and spheres
Model - draws simple meshes loaded from .CMO or .SDKMESH files
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
ScreenGrab - light-weight screen shot saver
SimpleMath - simplified C++ wrapper for DirectXMath

Related
The DirectXTex project http://go.microsoft.com/fwlink/?LinkId=248926

Contributions
The DirectXTK contributors list will remain closed to ensure high-quality and focused feature set, but we are very interested in any bug-fixes, optimizations, additional features, or other community feedback on this library. Please use the Issue Tracker and feel free to attach code to the issue as needed. Note that any code contributed or released for the DirectXTK project is subject to the MS-PL.

directxtk Wiki Rss Feed

Updated Wiki: GeometricPrimitive

Initialization

Simple drawing

Advanced drawing

Coordinate systems

Alpha blending

Feature Level Notes

Threading model

Further Reading

Updated Wiki: GeometricPrimitive

Initialization

Simple drawing

Advanced drawing

Coordinate systems

Alpha blending

Feature Level Notes

Threading model

Further Reading

Updated Wiki: Model

Initialization

Simple drawing

Advanced drawing

Effects control

Alpha blending

Custom render states

Coordinate systems

Feature Level Notes

Content Notes

Threading model

Further reading

Updated Wiki: Model

Initialization

Simple drawing

Advanced drawing

Effects control

Alpha blending

Custom render states

Coordinate systems

Feature Level Notes

Content Notes

Threading model

Further reading

Updated Wiki: DirectXTK

Headers

Namespace

Modules

Tools

Building

Adding to a VS Project

Error Handling

Updated Wiki: DDSTextureLoader

Functions

Example

Feature Level Notes

Release Notes

Further Reading

Updated Wiki: SimpleMath

To use:

Why wrap DirectXMath?

Enter SimpleMath...

Coordinate Systems

Further Reading

Updated Wiki: SimpleMath

To use:

Why wrap DirectXMath?

Enter SimpleMath...

Coordinate Systems

Further Reading

Updated Wiki: SimpleMath

To use:

Why wrap DirectXMath?

Enter SimpleMath...

Coordinate Systems

Updated Wiki: DDSTextureLoader

Functions

Example

Feature Level Notes

Release Notes

Further Reading