From 752130767491d55dd549a8e75a512ce1af6c0b07 Mon Sep 17 00:00:00 2001 From: walbourn_cp Date: Fri, 25 Jan 2013 15:36:07 -0800 Subject: [PATCH] DirectXTK: January 25, 2013 release --- Readme.txt | 242 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 234 insertions(+), 8 deletions(-) diff --git a/Readme.txt b/Readme.txt index 86011caa9..23a927ae9 100644 --- a/Readme.txt +++ b/Readme.txt @@ -4,7 +4,7 @@ DirectXTK - the DirectX Tool Kit Copyright (c) Microsoft Corporation. All rights reserved. -December 11, 2012 +January 25, 2013 This package contains the "DirectX Tool Kit", a collection of helper classes for writing Direct3D 11 C++ code for Windows Store apps, Windows 8 Win32 desktop @@ -31,6 +31,7 @@ Inc\ Effects.h - set of built-in shaders for common rendering tasks PrimitiveBatch.h - simple and efficient way to draw user primitives GeometricPrimitive.h - draws basic shapes such as cubes and spheres + Model.h - draws simple meshes loaded from .CMO or .SDKMESH files CommonStates.h - factory providing commonly used D3D state objects VertexTypes.h - structures for commonly used vertex data formats DDSTextureLoader.h - light-weight DDS file texture loader @@ -46,6 +47,9 @@ MakeSpriteFont\ All content and source code for this package are bound to the Microsoft Public License (Ms-PL) . +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 @@ -101,13 +105,24 @@ Sorting: 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(deviceContext); + + 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 (if for instance you do not wish to use - premultiplied alpha) by passing custom state objects to SpriteBatch::Begin. - Pass null for any parameters that should use their default state. + 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 @@ -247,7 +262,7 @@ Commandline options for the MakeSpriteFont tool: /NoPremultiply By default, font textures use premultiplied alpha format. Pass this flag - if you want interpolative alpha instead. + if you want interpolative/straight alpha instead. /DebugOutputSpriteSheet: Dumps the generated texture to a bitmap file (useful when debugging the @@ -318,9 +333,14 @@ To create an input layout matching the effect vertex shader input signature: VertexPositionNormalTexture::InputElementCount, shaderByteCode, byteCodeLength, pInputLayout); +Coordinate systems: -Threading model: + 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 @@ -365,6 +385,9 @@ To initialize a PrimitiveBatch for drawing VertexPositionColor data: std::unique_ptr> primitiveBatch(new PrimitiveBatch(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(new BasicEffect(device)); @@ -427,12 +450,13 @@ GeometricPrimitive This is a helper for drawing simple geometric shapes: - Cube - - Sphere (both geodesic sphere and uv-sphere) + - Sphere + - Geodesic Sphere - Cylinder - Torus - Teapot -During initialization: +Initialization: std::unique_ptr shape(GeometricPrimitive::CreateTeapot(deviceContext)); @@ -448,6 +472,203 @@ callback function which can be used to override the default rendering state: 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 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(deviceContext); + + 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 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. + + NOTE: The EffectFactory is declared in the Effects.h header. + + 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. + + 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(effect); + if ( lights ) + { + XMVECTOR dir = XMVector3Rotate( g_XMOne, quat ); + lights->SetLightDirection( 0, dir ); + } + auto fog = dynamic_cast(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. + +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’. + ------------ @@ -676,6 +897,11 @@ Further reading: RELEASE HISTORY --------------- +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