GetData retrieves the data collected between calls to and . Certain queries only require a call to in which case the data returned by GetData is accurate up to the last call to (See Interface).

If DataSize is 0, GetData is only used to check status where a return value of indicates that data is available to give to an application, and a return value of S_FALSE indicates data is not yet available.

It is invalid to invoke this function on a predicate created with the flag D3D10_QUERY_MISCFLAG_PREDICATEHINT.

If the asynchronous interface that calls this function is Interface, then the following table applies.

?

If the asynchronous interface that calls this API is Interface, then the following applies.

?

The value returned by a , , , , or counter may be different depending on the number of parallel counters that exist on a video card, and those values can be interpreted with the following equation:

The number of parallel counters that a video card has is available from NumDetectableParallelUnits in , and it can be retrieved by calling .

There are several types of device child interfaces, all of which inherit this interface. They include shaders, state objects, and input layouts.

Any returned interfaces will have their reference count incremented by one, so be sure to call ::release() on the returned reference(s) before they are freed or else you will have a memory leak.

The data stored in the device is set with .

The data retrieved and the guid will typically be application-defined.

This method can be used to get the device type by specifying GUID_DeviceType as the guid. In this case pData will point to a driver-type-enumeration value (see ).

The data stored in the device child with this method can be retrieved with .

When this method is called ::addref() will be called on the -derived interface, and when the device child is detroyed ::release() will be called on the -derived interface.

Any returned interfaces will have their reference count incremented by one, so be sure to call ::release() on the returned reference(s) before they are freed or else you will have a memory leak.

Calling Begin starts the asynchronous collection of GPU data. Calling causes data collection to stop. See Interface for additional information.

Calling starts the asynchronous collection of GPU data. Calling causes data collection to stop. See Interface for additional information.

GetData retrieves the data collected between calls to and . Certain queries only require a call to in which case the data returned by GetData is accurate up to the last call to (See Interface).

If DataSize is 0, GetData is only used to check status where a return value of indicates that data is available to give to an application, and a return value of S_FALSE indicates data is not yet available.

It is invalid to invoke this function on a predicate created with the flag D3D10_QUERY_MISCFLAG_PREDICATEHINT.

If the asynchronous interface that calls this function is Interface, then the following table applies.

?

If the asynchronous interface that calls this API is Interface, then the following applies.

?

The value returned by a , , , , or counter may be different depending on the number of parallel counters that exist on a video card, and those values can be interpreted with the following equation:

The number of parallel counters that a video card has is available from NumDetectableParallelUnits in , and it can be retrieved by calling .

Blending combines two pixel values. You have control over how the pixels are blended by using a predefined set of blending operations, as well as preblending operations. The Blending Block Diagram shows conceptually how blending works.

To create a blend-state interface, call . To initialize the blend state, call .

Blending combines two pixel values. You have control over how the pixels are blended by using a predefined set of blending operations, as well as preblending operations. The Blending Block Diagram shows conceptually how blending works.

To create a blend-state interface, call . To initialize the blend state, call .

This method requires Windows Vista Service Pack 1.

Three types of buffers can be created; vertex, index, and shader-constant buffers. To create a buffer resource, call .

A buffer must be bound to the pipeline before it can be accessed. Buffers can be bound to the input-assembler stage by calls to and , and to the stream-output stage by a call to .

Buffers can be bound to multiple pipeline stages simultaneously for reading. A buffer can also be bound to a single pipeline stage for writing; however, the same buffer cannot be bound for reading and writing simultaneously. For more information, see binding resources.

A resource interface cannot be created directly; instead, buffers and textures are created that inherit from a resource interface (see Creating Buffer Resources or Creating Texture Resources).

Resource priorities determine which resource to evict from video memory when the system has run out of video memory. The resource will not be lost; it will be removed from video memory and placed into system memory, or possibly placed onto the hard drive. The resource will be loaded back into video memory when it is required.

A resource that is set to the maximum priority, , is only evicted if there is no other way of resolving the incoming memory request. The Windows Display Driver Model (WDDM) tries to split an incoming memory request to its minimum size and evict lower-priority resources before evicting a resource with maximum priority.

Changing the priorities of resources should be done carefully. The wrong eviction priorities could be a detriment to performance rather than an improvement. See QueryResourceResidency for additional information.

This method is a wrapper for SetEvictionPriority and is provided in the Interface interface for convenience.

This method is a wrapper for GetEvictionPriority and is provided in the Interface interface for convenience.

This method is a wrapper for GetEvictionPriority and is provided in the Interface interface for convenience.

For the CPU to write the contents of a resource, the resource must be created with the dynamic usage flag, . To both read and write those contents, the resource must be created with the staging usage flag, . (For more information about these flags, see .) will retrieve a reference to the resource data. For a discussion on how to access resources efficiently, see Copying and Accessing Resource Data (Direct3D 10).

Call to signify that the application has finished accessing the resource.

has a few other restrictions. For example:

• The same buffer cannot be mapped multiple times; in other words, do not call on a buffer that is already mapped.
• Any buffer that is bound to the pipeline must be unmapped before any rendering operation (that is, ) can be executed.

?

?

This structure is used by to create buffer resources.

In addition to this structure, there is also a derived structure in D3D10.h (CD3D10_BUFFER_DESC) which behaves like an inherited class to help create a buffer description.

A device is created using .

Input-layout objects describe how vertex buffer data is streamed into the IA pipeline stage. To create an input-layout object, call .

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

For information about creating vertex buffers, see Create a Vertex Buffer.

Calling this method using a buffer that is currently bound for writing (i.e. bound to the stream output pipeline stage) will effectively bind null instead because a buffer cannot be bound as both an input and an output at the same time.

The Debug Layer will generate a warning whenever a resource is prevented from being bound simultaneously as an input and an output, but this will not prevent invalid data from being used by the runtime.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

For information about creating vertex buffers, see Create a Vertex Buffer.

Calling this method using a buffer that is currently bound for writing (i.e. bound to the stream output pipeline stage) will effectively bind null instead because a buffer cannot be bound as both an input and an output at the same time.

The Debug Layer will generate a warning whenever a resource is prevented from being bound simultaneously as an input and an output, but this will not prevent invalid data from being used by the runtime.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

For information about creating index buffers, see Create an Index Buffer.

Calling this method using a buffer that is currently bound for writing (i.e. bound to the stream output pipeline stage) will effectively bind null instead because a buffer cannot be bound as both an input and an output at the same time.

The Debug Layer will generate a warning whenever a resource is prevented from being bound simultaneously as an input and an output, but this will not prevent invalid data from being used by the runtime.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

For information about creating an input-layout object, see Creating the Input-Layout Object.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

For information about creating an input-layout object, see Creating the Input-Layout Object.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

A counter can be created with .

This is a derived class of Interface.

Counter data is gathered by issuing an command, issuing some graphics commands, issuing an command, and then calling to get data about what happened in between the Begin and End calls. The data returned by GetData will be different depending on the type of counter. The call to End causes the data returned by GetData to be accurate up until the last call to End.

Counters are best suited for profiling.

For a list of the types of performance counters, see .

This interface is obtained by querying it from the Interface using IUnknown::QueryInterface.

Setting a feature-mask flag will cause a rendering-operation method (listed below) to do some extra task when called. The possible feature flags are:

?

These feature-mask flags apply to the following rendering-operation methods:

The application will only sleep if is a set in the feature mask. If that flag is not set the number of milliseconds is set but ignored and the application does not sleep. 10ms is used as a default value if this method is never called.

Value is set with .

The swap chain set by this method will only be used if is set in the feature mask.

The swap chain retrieved by this method will only be used if is set in the feature mask.

When the debug layer is turned on all draw functions will do this operation.

Value is set with .

The swap chain retrieved by this method will only be used if is set in the feature mask.

Create a depth-stencil state object by calling .

To initialize depth-stencil state, bind the depth-stencil-state object to the pipeline by calling .

To create a depth-stencil view, call .

To bind a depth-stencil view to the pipeline, call .

A view interface is the base interface for all views. There are three types of views; a depth-stencil view, a render-target view, and a shader-resource view.

• To create a render-target view, call .
• To create a depth-stencil view, call .
• To create a shader-resource view, call .

All resources must be bound to the pipeline before they can be accessed.

• To bind a render-target view or a depth-stencil view, call .
• To bind a shader-resource view, call .

A view can also be used to access a typeless resource.

This function increments the reference count of the resource by one, so it is necessary to call Release on the returned reference when the application is done with it. Destroying (or losing) the returned reference before Release is called will result in a memory leak.

This function increments the reference count of the resource by one, so it is necessary to call Release on the returned reference when the application is done with it. Destroying (or losing) the returned reference before Release is called will result in a memory leak.

A device is created using .

A draw API submits work to the rendering pipeline.

If the sum of both indices is negative, the result of the function call is undefined.

A draw API submits work to the rendering pipeline.

The vertex data for a draw call normally comes from a vertex buffer that is bound to the pipeline. However, you could also provide the vertex data from a shader that has vertex data marked with the SV_VertexId?system-value semantic.

A draw API submits work to the rendering pipeline.

Instancing may extend performance by reusing the same geometry to draw multiple objects in a scene. One example of instancing could be to draw the same object with different positions and colors. Indexing requires multiple vertex buffers: at least one for per-vertex data and a second buffer for per-instance data. For an example of instancing, see the Instancing10 Sample.

A draw API submits work to the rendering pipeline.

Instancing may extend performance by reusing the same geometry to draw multiple objects in a scene. One example of instancing could be to draw the same object with different positions and colors. For an example of instancing, see the Instancing10 Sample.

The vertex data for an instanced draw call normally comes from a vertex buffer that is bound to the pipeline. However, you could also provide the vertex data from a shader that has instanced data identified with a system-value semantic (SV_InstanceID).

The predicate must be in the "issued" or "signaled" state to be used for predication. While the predicate is set for predication, calls to and are invalid.

This method is used to denote that subsequent rendering and resource manipulation commands are not actually performed if the resulting Predicate data of the Predicate is equal to the PredicateValue. However, some Predicates are only hints, so they may not actually prevent operations from being performed.

The primary usefulness of Predication is to allow an application to issue graphics commands without taking the performance hit of spinning, waiting for to return. So, Predication can occur while returns S_FALSE. Another way to think of it: an application can also use Predication as a fallback, if it is possible that returns S_FALSE. If returns , the application can skip calling the graphics commands manually with it's own application logic.

A draw API submits work to the rendering pipeline.

After data has been streamed out to SO stage buffers, those buffers can be again bound to the Input Assembler stage at input slot 0 and DrawAuto will draw them without the application needing to know the amount of data that was written to the buffers. A measurement of the amount of data written to the SO stage buffers is maintained internally when the data is streamed out. This means that the CPU does not need to fetch the measurement before re-binding the data that was streamed as input data. Although this amount is tracked internally, it is still the responsibility of applications to use input layouts to describe the format of the data in the SO stage buffers so that the layouts are available when the buffers are again bound to the input assembler.

The following diagram shows the DrawAuto process.

Calling DrawAuto does not change the state of the streaming-output buffers that were bound again as inputs.

DrawAuto only works when drawing with one input buffer bound as an input to the IA stage at slot 0. Applications must create the SO buffer resource with both binding flags, and .

This API does not support indexing or instancing.

If an application needs to retrieve the size of the streaming-output buffer, it can query for statistics on streaming output by using .

Example of using DrawAuto can be found in the ParticlesGS Sample and PipesGS Sample.

The source box must be within the size of the source resource. The destination location is an absolute value (not a relative value). The destination location can be offset from the source location; however, the size of the region to copy (including the destination location) must fit in the destination resource.

If the resources are buffers, all coordinates are in bytes; if the resources are textures, all coordinates are in texels.

D3D10CalcSubresource is a helper function for calculating subresource indexes.

CopySubresourceRegion performs the copy on the GPU (similar to a memcpy by the CPU). As a consequence, the source and destination resources must meet the following criteria:

• Must be different subresources (although they can be from the same resource).
• Must be the same type.
• Must have compatible formats (the formats must either be identical or be from the same type group). For example, a texture can be copied to an texture because both of these formats are in the group.
• May not be currently mapped.

CopySubresourceRegion supports only copy; it does not support any stretch, color key, blend, or format conversions. An application that needs to copy an entire resource should use instead.

CopySubresourceRegion is an asynchronous call that the runtime can add to the command-buffer queue. This asynchronous behaviorattempts to remove pipeline stalls that may occur when copying data. See performance considerations for more details.

?

Note??If you use CopySubresourceRegion with a depth-stencil buffer or a multisampled resource, you must copy the whole subresource. You must also pass 0 to the DstX, DstY, and DstZ parameters and null to the pSrcBox parameter. In addition, source and destination resources, which are represented by the pSrcResource and pDstResource parameters respectively, must have identical sample count values.

The following code snippet copies a box (located at (120,100),(200,220)) from a source texture into a reqion (130,120),(210,240) in a destination texture.

  sourceRegion;	
            sourceRegion.left = 120;	
            sourceRegion.right = 200;	
            sourceRegion.top = 100;	
            sourceRegion.bottom = 220;	
            sourceRegion.front = 0;	
            sourceRegion.back = 1; pd3dDevice->CopySubresourceRegion( pDestTexture, 0, 130, 120, 0, pSourceTexture, 0, &sourceRegion );	
            

Notice that, for a 2D texture, front and back are always set to 0 and 1 respectively.

This method is unusual in that it causes the GPU to perform the copy operation (similar to a memcpy by the CPU). As a result, it has a few restrictions designed for improving performance. For instance, the source and destination resources:

• Must be different resources.
• Must be the same type.
• Must have identical dimensions (including width, height, depth, and size as appropriate).
• Will only be copied. CopyResource does not support any stretch, color key, blend, or format conversions.
• Must have compatible formats, which means the formats must be identical or at least from the same type group. For example, a texture can be copied to an texture since both of these formats are in the group.
• May not be currently mapped.

Immutable, and depth-stencil resources cannot be used as a destination. Resources created with multisampling capability cannot be used as either a source or destination.

The method is an asynchronous call which may be added to the command-buffer queue. This attempts to remove pipeline stalls that may occur when copying data. See performance considerations for more details.

An application that only needs to copy a portion of the data in a resource should use instead.

?

For a shader-constant buffer; set pDstBox to null. It is not possible to use this method to partially update a shader-constant buffer.

A resource cannot be used as a destination if:

• the resource is created with immutable or dynamic usage.
• the resource is created as a depth-stencil resource.
• the resource is created with multisampling capability (see ).

When UpdateSubresource returns, the application is free to change or even free the data pointed to by pSrcData because the method has already copied/snapped away the original contents.

The performance of UpdateSubresource depends on whether or not there is contention for the destination resource. For example, contention for a vertex buffer resource occurs when the application executes a Draw call and later calls UpdateSubresource on the same vertex buffer before the Draw call is actually executed by the GPU.

• When there is contention for the resource, UpdateSubresource will perform 2 copies of the source data. First, the data is copied by the CPU to a temporary storage space accessible by the command buffer. This copy happens before the method returns. A second copy is then performed by the GPU to copy the source data into non-mappable memory. This second copy happens asynchronously because it is executed by GPU when the command buffer is flushed.
• When there is no resource contention, the behavior of UpdateSubresource is dependent on which is faster (from the CPU's perspective): copying the data to the command buffer and then having a second copy execute when the command buffer is flushed, or having the CPU copy the data to the final resource location. This is dependent on the architecture of the underlying system.

To better understand the source row pitch and source depth pitch parameters, consider the following illustration of a 3D volume texture.

Each block in this visual represents an element of data, and the size of each element is dependent on the resource's format. For example, if the resource format is , then the size of each element would be 128 bits, or 16 bytes. This 3D volume texture has a width of two, a height of three, and a depth of four.

To calculate the source row pitch and source depth pitch for a given resource, use the following formulas:

• Source Row Pitch = [size of one element in bytes] * [number of elements in one row]
• Source Depth Pitch = [Source Row Pitch] * [number of rows (height)]

In the case of this example 3D volume texture where the size of each element is 16 bytes, the formulas are as follows:

• Source Row Pitch = 16 * 2 = 32
• Source Depth Pitch = 16 * 2 * 3 = 96

The following illustration shows the resource as it is laid out in memory.

For example, the following code snippet shows how to specify a destination region in a 2D texture. Assume the destination texture is 512x512 and the operation will copy the data pointed to by pData to [(120,100)..(200,220)] in the destination texture. Also assume that rowPitch has been initialized with the proper value (as explained above). Front and back are set to 0 and 1 respectively, because by having front equal to back, the box is technically empty.

  destRegion;	
            destRegion.left = 120;	
            destRegion.right = 200;	
            destRegion.top = 100;	
            destRegion.bottom = 220;	
            destRegion.front = 0;	
            destRegion.back = 1; pd3dDevice->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );	
            

The 1D case is similar. The following snippet shows how to specify a destination region in a 1D texture. Use the same assumptions as above, except that the texture is 512 in length.

  destRegion;	
            destRegion.left = 120	
            destRegion.right = 200;	
            destRegion.top = 0;	
            destRegion.bottom = 1;	
            destRegion.front = 0;	
            destRegion.back = 1; pd3dDevice->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );	
            

?

Applications that wish to clear a render target to a specific integer value bit pattern should render a screen-aligned quad instead of using this method. The reason for this is because this method accepts as input a floating point value, which may not have the same bit pattern as the original integer.

?

?

GenerateMips may be called on any in order to generate the lower mipmap levels. GenerateMips uses the largest mipmap level of the view to recursively generate the lower levels of the mip, stopping with the smallest level specified by the view. If the base resource was not created with and , this call has no effect.

All video adapters will automatically generate mipmaps if you are using one of the following formats:

Some video adapters will automatically generate mipmaps for this format.

For all other unsupported formats, this method will silently fail.

Both the source and destination resources must be the same resource type and have the same dimensions.

The source and destination must have compatible formats. There are three scenarios for this:

?

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

Set an exception-mode flag to elevate an error condition to a non-continuable exception.

Whenever an error occurs, a Direct3D device enters the DEVICEREMOVED state and if the appropriate exception flag has been set, an exception is raised. A raised exception is designed to terminate an application. Before termination, the last chance an application has to persist data is by using an UnhandledExceptionFilter (see Structured Exception Handling). In general, UnhandledExceptionFilters are leveraged to try to persist data when an application is crashing (to disk, for example). Any code that executes during an UnhandledExceptionFilter is not guaranteed to reliably execute (due to possible process corruption). Any data that the UnhandledExceptionFilter manages to persist, before the UnhandledExceptionFilter crashes again, should be treated as suspect, and therefore inspected by a new, non-corrupted process to see if it is usable.

An exception-mode flag is used to elevate an error condition to a non-continuable exception.

The data stored in the device with this method can be retrieved with .

The data and guid set with this method will typically be application-defined.

If an application uses this method to change the device type using GUID_DeviceType, results are undefined. However, GUID_DeviceType can be used to retrieve the device type using .

Most applications will not need to call this method. Calling this method when not necessary will incur a performance penalty. Each call to Flush incurs a significant amount of overhead.

When Direct3D state-setting, present, or draw commands are called by an application, those commands are queued into an internal command buffer. Flush sends those commands to the GPU for processing. Normally, these commands are sent to the GPU automatically whenever Direct3D determines that they need to be, such as when the command buffer is full or when mapping a resource. Flush will send the commands manually.

Flush should be used when the CPU waits for an arbitrary amount of time (such as when calling Sleep, ID3DX10ThreadPump::WaitForAllItems, or WaitForVBlank.

For more information about how flushing works, see Accurately Profiling Direct3D API Calls (Direct3D 9).

For example code, see:

• Create a Vertex Buffer
• Create an Index Buffer

CreateTexture1D creates a 1D texture resource, which contains an array of 1D textures. The number of textures is specified in the texture description. All textures in a resource must have the same format, size, and number of mipmap levels.

All resources are made up of one or more subresources. To load data into the texture, applications may supply the data initially as part of structure pointed to by pInitialData, or it may use one of the Texturing Functions supplied by the SDK.

CreateTexture2D creates a 2D texture resource, which contains an array of 1D textures. The number of textures is specified in the texture description. All textures in a resource must have the same format, size, and number of mipmap levels.

All resources are made up of one or more subresources. To load data into the texture, applications may supply the data initially as part of structure pointed to by pInitialData, or it may use one of the Texturing Functions supplied by the SDK.

CreateTexture3D creates a 3D texture resource, which contains an array of 1D textures. The number of textures is specified in the texture description. All textures in a resource must have the same format, size, and number of mipmap levels.

All resources are made up of one or more subresources. To load data into the texture, applications may supply the data initially as part of structure pointed to by pInitialData, or it may use one of the Texturing Functions supplied by the SDK.

A resource is made up of one or more subresources, a view identifies which subresources to allow the pipeline to access. In addition, each resource is bound to the pipeline using a view. A shader-resource view is designed to bind any buffer or texture resource to the shader stages using the following API methods: VSSetShaderResources, GSSetShaderResources and PSSetShaderResources.

Since a view is fully typed, this means that typeless resources become fully typed when bound to the pipeline.

A rendertarget view can be bound to the output merger stage by calling .

A depth-stencil view can be bound to the output-merger stage by calling .

For more background information, see the programming guide page about depth stencils.

After creating an input layout object, it must be bound to the input-assembler stage before calling a draw API. See Getting Started with the Input-Assembler Stage (Direct3D 10) for example code.

Once an input-layout object is created from a shader signature, the input-layout object can be reused with any other shader that has an identical input signature (semantics included). This can simplify the creation of input-layout objects when you are working with many shaders with identical inputs.

If a data type in the input-layout declaration does not match the data type in a shader-input signature, CreateInputLayout will generate a warning during compilation. The warning is simply to call attention to the fact that the data may be reinterpreted when read from a register. You may either disregard this warning (if reinterpretation is intentional) or make the data types match in both declarations to eliminate the warning. The Data Conversion Rules overview describes the rules applied for data type conversion.

?

Once created, the shader can be set to the device by calling .

For more info about using CreateGeometryShaderWithStreamOutput, see Create a Geometry-Shader Object with Stream Output.

After creating the pixel shader, you can set it to the device using .

An application can create up to 4096 unique blend-state objects. For each object created, the runtime checks to see if a previous object has the same state. If such a previous object exists, the runtime will return a reference to previous instance instead of creating a duplicate object.

4096 unique depth-stencil state objects can be created on a device at a time.

If an application attempts to create a depth-stencil state with the same description as an already existing depth-stencil state, then the same interface with an incremented reference count will be returned and the total number of unique depth-stencil state objects will stay the same.

4096 unique rasterizer state objects can be created on a device at a time.

If an application attempts to create a rasterizer state with the same description as an already existing rasterizer state, then the same interface with an incremented reference count will be returned and the total number of unique rasterizer state objects will stay the same.

4096 unique sampler state objects can be created on a device at a time.

If an application attempts to create a sampler state with the same description as an already existing sampler state, then the same interface with an incremented reference count will be returned and the total number of unique sampler state objects will stay the same.

Most format support is based on the Direct3D feature level. Only a few specific use cases require checking for support. See Hardware Support for Direct3D 10 Formats and Hardware Support for Direct3D 10.1 Formats for additional information.

When multisampling a texture, the number of quality levels available for an adapter is dependent on the texture format used and the number of samples requested. The maximum sample count defined by D3D10_MAX_MULTISAMPLE_SAMPLE_COUNT in d3d10.h is 32. If the returned value of pNumQualityLevels is 0, the format and sample count combination is not supported for the installed adapter.

Furthermore, the definition of a quality level is up to each hardware vendor to define, however no facility is provided by Direct3D to help discover this information.

Direct3D 10.1 devices are required to support 4x MSAA for all formats except R32G32B32A32 and R32G32B32 formats.

Length parameters can be null, which indicates the application is not interested in the length nor the corresponding string value. When a length parameter is non-null and the corresponding string is null, the input value of the length parameter is ignored, and the length of the corresponding string (including terminating null) will be returned through the length parameter. When length and the corresponding parameter are both non-null, the input value of length is checked to ensure there is enough room, and then the length of the string (including terminating null character) is passed out through the length parameter.

To share a resource between two Direct3D 10 devices the resource must have been created with the flag, if it was created using the interface. If it was created using the interface, then the resource is always shared.

The REFIID, or , of the interface to the resource can be obtained by using the __uuidof() macro. For example, __uuidof() will get the of the interface to a buffer resource.

When sharing a resource between two Direct3D 10 devices the unique handle of the resource can be obtained by querying the resource for the interface and then calling GetSharedHandle.

 * pOtherResource(null);	
            hr = pOtherDeviceResource->QueryInterface( __uuidof(), (void**)&pOtherResource );	
            HANDLE sharedHandle;	
            pOtherResource->GetSharedHandle(&sharedHandle); 

The only resources that can be shared are 2D non-mipmapped textures.

To share a resource between a Direct3D 9 device and a Direct3D 10 device the texture must have been created using the pSharedHandle argument of CreateTexture. The shared Direct3D 9 handle is then passed to OpenSharedResource in the hResource argument.

The following code illustrates the method calls involved.

 sharedHandle = null; // must be set to null to create, can use a valid handle here to open in D3D9 	
            pDevice9->CreateTexture(..., pTex2D_9, &sharedHandle); 	
            ... 	
            pDevice10->OpenSharedResource(sharedHandle, __uuidof(), (void**)(&tempResource10)); 	
            tempResource10->QueryInterface(__uuidof(), (void**)(&pTex2D_10)); 	
            tempResource10->Release(); 	
            // now use pTex2D_10 with pDevice10    

Textures being shared from D3D9 to D3D10 have the following restrictions.

• Textures must be 2D
• Only 1 mip level is allowed
• Texture must have default usage
• Texture must be write only
• MSAA textures are not allowed
• Bind flags must have SHADER_RESOURCE and RENDER_TARGET set
• Only R10G10B10A2_UNORM, R16G16B16A16_FLOAT and R8G8B8A8_UNORM formats are allowed

If a shared texture is updated on one device must be called on that device.

An exception-mode flag is used to elevate an error condition to a non-continuable exception.

A device is created using .

Call (before any draw calls) to stream data out; call SOSetTargets with null to stop streaming data out. For an example, see Exercise 01 from the GDC 2007 workshop, which sets the stream output rendertargets before calling draw methods in the RenderInstanceToStream function.

An offset of -1 will cause the stream output buffer to be appended, continuing after the last location written to the buffer in a previous stream output pass.

Calling this method using a buffer that is currently bound for writing will effectively bind null instead because a buffer cannot be bound as both an input and an output at the same time.

The Debug Layer will generate a warning whenever a resource is prevented from being bound simultaneously as an input and an output, but this will not prevent invalid data from being used by the runtime.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

Call (before any draw calls) to stream data out; call SOSetTargets with null to stop streaming data out. For an example, see Exercise 01 from the GDC 2007 workshop, which sets the stream output rendertargets before calling draw methods in the RenderInstanceToStream function.

An offset of -1 will cause the stream output buffer to be appended, continuing after the last location written to the buffer in a previous stream output pass.

Calling this method using a buffer that is currently bound for writing will effectively bind null instead because a buffer cannot be bound as both an input and an output at the same time.

The Debug Layer will generate a warning whenever a resource is prevented from being bound simultaneously as an input and an output, but this will not prevent invalid data from being used by the runtime.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

A device is created using .

A call to OMSetRenderTargets overrides all bounded render targets and the depth stencil target regardless of the number of render targets in ppRenderTargetViews.

The maximum number of render targets a device can have active at any given time is set by a #define in D3D10.h called D3D10_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots.

If any subresources are also currently bound for reading or writing (perhaps in a different part of the pipeline), those bind points will be null'ed out to prevent the same subresource from being read and written simultaneously in a single rendering operation.

The method will not hold references to the interfaces passed in. For that reason, applications should be careful not to release interfaces currently in use by the device.

See Binding Resources and Pipeline stages for more information on binding resources.

The pixel shader must be able to simultaneously render to at least eight separate render targets. All of these render targets must access the same type of resource: Buffer, Texture1D, Texture1DArray, Texture2D, Texture2DArray, Texture3D, or TextureCube. All render targets must have the same size in all dimensions (width and height, and depth for 3D or array size for *Array types). If render targets use multisample anti-aliasing, all bound render targets and depth buffer must be the same form of multisample resource (that is, the sample counts must be the same). Each render target can have a different data format. These render target formats are not required to have identical bit-per-element counts.

Any combination of the eight slots for render targets can have a render target set or not set.

The same resource view cannot be bound to multiple render target slots simultaneously. However, you can set multiple non-overlapping resource views of a single resource as simultaneous multiple render targets.

A call to OMSetRenderTargets overrides all bounded render targets and the depth stencil target regardless of the number of render targets in ppRenderTargetViews.

The maximum number of render targets a device can have active at any given time is set by a #define in D3D10.h called D3D10_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots.

If any subresources are also currently bound for reading or writing (perhaps in a different part of the pipeline), those bind points will be null'ed out to prevent the same subresource from being read and written simultaneously in a single rendering operation.

The method will not hold references to the interfaces passed in. For that reason, applications should be careful not to release interfaces currently in use by the device.

See Binding Resources and Pipeline stages for more information on binding resources.

The pixel shader must be able to simultaneously render to at least eight separate render targets. All of these render targets must access the same type of resource: Buffer, Texture1D, Texture1DArray, Texture2D, Texture2DArray, Texture3D, or TextureCube. All render targets must have the same size in all dimensions (width and height, and depth for 3D or array size for *Array types). If render targets use multisample anti-aliasing, all bound render targets and depth buffer must be the same form of multisample resource (that is, the sample counts must be the same). Each render target can have a different data format. These render target formats are not required to have identical bit-per-element counts.

Any combination of the eight slots for render targets can have a render target set or not set.

The same resource view cannot be bound to multiple render target slots simultaneously. However, you can set multiple non-overlapping resource views of a single resource as simultaneous multiple render targets.

Blend state is used by the output-merger stage to determine how to blend together two pixel values. The two values are commonly the current pixel value and the pixel value already in the output render target. Use the blend operation to control where the two pixel values come from and how they are mathematically combined.

To create a blend-state interface, call .

Passing in null for the blend-state interface indicates to the runtime to set a default blending state. The following table indicates the default blending parameters.

?

A sample mask determines which samples get updated in all the active render targets. The mapping of bits in a sample mask to samples in a multisample render target is the responsibility of an individual application. A sample mask is always applied; it is independent of whether multisampling is enabled, and does not depend on whether an application uses multisample render targets.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

To create a depth-stencil state interface, call .

Depth-stencil state is used by the output-merger stage to setup depth-stencil testing. The stencil reference value is the control value used in the depth-stencil test.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

The reference count of the returned interface will be incremented by one when the blend state is retrieved. Applications must release returned reference(s) when they are no longer needed, or else there will be a memory leak.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

A device is created using .

To create a rasterizer state interface, call . For more details on setting up the rasterizer state, see Set Rasterizer State.

The method will not hold a reference to the interfaces passed in. For that reason, applications should be careful not to release an interface currently in use by the device.

All viewports must be set atomically as one operation. Any viewports not defined by the call are disabled.

Which viewport to use is determined by the SV_ViewportArrayIndex semantic output by a geometry shader (see shader semantic syntax). If a geometry shader does not make use of the SV_ViewportArrayIndex semantic then Direct3D will use the first viewport in the array.

The scissor rectangles will only be used if ScissorEnable is set to true in the rasterizer state (see ).

Which scissor rectangle to use is determined by the SV_ViewportArrayIndex semantic output by a geometry shader (see shader semantic syntax). If a geometry shader does not make use of the SV_ViewportArrayIndex semantic then Direct3D will use the first scissor rectangle in the array.

Each scissor rectangle in the array corresponds to a viewport in an array of viewports (see ).

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

Any returned interfaces will have their reference count incremented by one. Applications should call IUnknown::Release on the returned interfaces when they are no longer needed to avoid memory leaks.

A device is created using .

This method requires Windows Vista Service Pack 1.

A resource is made up of one or more subresources, a view identifies which subresources to allow the pipeline to access. In addition, each resource is bound to the pipeline using a view. A shader-resource view is designed to bind any buffer or texture resource to the shader stages using the following API methods: VSSetShaderResources, GSSetShaderResources and PSSetShaderResources.

Since a view is fully typed, this means that typeless resources become fully typed when bound to the pipeline.

This method requires Windows Vista Service Pack 1.

An application can create up to 4096 unique blend-state objects. For each object created, the runtime checks to see if a previous object has the same state. If such a previous object exists, the runtime will return a reference to previous instance instead of creating a duplicate object.

This method requires Windows Vista Service Pack 1.

This method requires Windows Vista Service Pack 1.

This method requires Windows Vista Service Pack 1.

An effect is created by calling .

The effect system groups the information required for rendering into an effect which contains: state objects for assigning state changes in groups, resources for supplying input data and storing output data, and programs that control how the rendering is done called shaders. For more information, see Effects (Direct3D 10).

Note??

If you call QueryInterface on an object to retrieve the interface, QueryInterface returns E_NOINTERFACE. To work around this issue, use the following code:

 * pIUnknown = (*)pEffect; pIUnknown->AddRef();	
            

An effect is created for a specific device, by calling a function such as .

An effect description contains basic information about an effect such as the techniques it contains and the constant buffer resources it requires.

An effect that contains a variable that will be read/written by an application requires at least one constant buffer. For best performance, an effect should organize variables into one or more constant buffers based on their frequency of update.

An effect that contains a variable that will be read/written by an application requires at least one constant buffer. For best performance, an effect should organize variables into one or more constant buffers based on their frequency of update.

An effect may contain one or more variables. Variables outside of a technique are considered global to all effects, those located inside of a technique are local to that technique. You can access any local non-static effect variable using its name or with an index.

The method returns a reference to an effect-variable interface if a variable is not found; you can call to verify whether or not the index exists.

An effect may contain one or more variables. Variables outside of a technique are considered global to all effects, those located inside of a technique are local to that technique. You can access an effect variable using its name or with an index.

The method returns a reference to an effect-variable interface if a variable is not found; you can call to verify whether or not the name exists.

Each effect variable can have a semantic attached, which is a user defined metadata string. Some system-value semantics are reserved words that trigger built in functionality by pipeline stages.

The method returns a reference to an effect-variable interface if a variable is not found; you can call to verify whether or not the semantic exists.

An effect contains one or more techniques; each technique contains one or more passes. You can access a technique using its name or with an index. For more about techniques, see techniques and passes.

An effect contains one or more techniques; each technique contains one or more passes. You can access a technique using its name or with an index. For more about techniques, see techniques and passes.

An effect uses memory space two different ways: to store the information required by the runtime to execute an effect, and to store the metadata required to reflect information back to an application using the API. You can minimize the amount of memory required by an effect by calling which removes the reflection metadata from memory. API methods to read variables will no longer work once reflection data has been removed.

The following methods will fail after Optimize has been called on an effect.

Note that references retrieved with these methods before calling are still valid after is called. This allows the application to get all the variables, techniques, and passes it will use, call Optimize, and then use the effect.

An effect uses memory space two different ways: to store the information required by the runtime to execute an effect, and to store the metadata required to reflect information back to an application using the API. You can minimize the amount of memory required by an effect by calling which removes the reflection metadata from memory. Of course, API methods to read variables will no longer work once reflection data has been removed.

An effect is created for a specific device, by calling a function such as .

An effect description contains basic information about an effect such as the techniques it contains and the constant buffer resources it requires.

An effect uses memory space two different ways: to store the information required by the runtime to execute an effect, and to store the metadata required to reflect information back to an application using the API. You can minimize the amount of memory required by an effect by calling which removes the reflection metadata from memory. Of course, API methods to read variables will no longer work once reflection data has been removed.

An Interface is created when an effect is read into memory.

Effect variables are saved in memory in the backing store; when a technique is applied, the values in the backing store are copied to the device. You can use either of these methods to return state. For examples, see Two Ways to Get the State in an Effect Variable.

This method checks that the data type matches the data stored after casting one interface to another (using any of the As methods).

Annonations can be attached to a technique, a pass or a gloval variable. For the syntax, see Annotation Syntax (Direct3D 10).

Annonations can be attached to a technique, a pass or a gloval variable. For the syntax, see Annotation Syntax (Direct3D 10).

If the effect variable is an structure, use this method to look up a member by index.

If the effect variable is an structure, use this method to look up a member by name.

If the effect variable is an structure, use this method to look up a member by attached semantic.

If the effect variable is an array, use this method to return one of the elements.

Effect variables are read-from or written-to a constant buffer.

AsScalar returns a version of the effect variable that has been specialized to a scalar variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain scalar data.

Applications can test the returned object for validity by calling IsValid.

AsVector returns a version of the effect variable that has been specialized to a vector variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain vector data.

Applications can test the returned object for validity by calling IsValid.

AsMatrix returns a version of the effect variable that has been specialized to a matrix variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain matrix data.

Applications can test the returned object for validity by calling IsValid.

AsString returns a version of the effect variable that has been specialized to a string variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain string data.

Applications can test the returned object for validity by calling IsValid.

AsShaderResource returns a version of the effect variable that has been specialized to a shader-resource variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain shader-resource data.

Applications can test the returned object for validity by calling IsValid.

This method returns a version of the effect variable that has been specialized to a render-target-view variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain render-target-view data.

Applications can test the returned object for validity by calling IsValid.

This method returns a version of the effect variable that has been specialized to a depth-stencil-view variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain depth-stencil-view data.

Applications can test the returned object for validity by calling IsValid.

AsConstantBuffer returns a version of the effect variable that has been specialized to a constant buffer. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain constant buffer data.

Applications can test the returned object for validity by calling IsValid.

AsShader returns a version of the effect variable that has been specialized to a shader variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain shader data.

Applications can test the returned object for validity by calling IsValid.

AsBlend returns a version of the effect variable that has been specialized to an effect-blend variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain effect-blend data.

Applications can test the returned object for validity by calling IsValid.

AsDepthStencil returns a version of the effect variable that has been specialized to a depth-stencil variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain depth-stencil data.

Applications can test the returned object for validity by calling IsValid.

AsRasterizer returns a version of the effect variable that has been specialized to a rasterizer variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain rasterizer data.

Applications can test the returned object for validity by calling IsValid.

AsSampler returns a version of the effect variable that has been specialized to a sampler variable. Similar to a cast, this specialization will return an invalid object if the effect variable does not contain sampler data.

Applications can test the returned object for validity by calling IsValid.

This method does no conversion or type checking; it is therefore a very quick way to access array items.

This method does no conversion or type checking; it is therefore a very quick way to access array items.

This method checks that the data type matches the data stored after casting one interface to another (using any of the As methods).

Effect variables are read-from or written-to a constant buffer.

Effect variables are saved in memory in the backing store; when a technique is applied, the values in the backing store are copied to the device. Backing store data can used to recreate the variable when necessary.

An Interface is created when an effect is read into memory.

Effect variables are saved in memory in the backing store; when a technique is applied, the values in the backing store are copied to the device. You can use either of these methods to return state. For examples, see Two Ways to Get the State in an Effect Variable.

Effect variables are saved in memory in the backing store; when a technique is applied, the values in the backing store are copied to the device. Backing store data can used to recreate the variable when necessary.

Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).

Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).

Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).

Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).

A pass is a block of code that sets render-state objects and shaders. A pass is declared within a technique; the syntax for a technique is shown in Effect Technique Syntax (Direct3D 10).

To get an effect-pass interface, call a method like .

A pass is a block of code that sets render state and shaders (which in turn sets constant buffers, samplers and textures). An effect technique contains one or more passes. See techniques and passes.

An effect pass can contain render state assignments and shader object assignments.

An effect pass can contain render state assignments and shader object assignments.

An effect pass can contain render state assignments and shader object assignments.

A pass is a block of code that sets render state and shaders (which in turn sets constant buffers, samplers and textures). An effect technique contains one or more passes. See techniques and passes.

An effect pass can contain render state assignments and shader object assignments.

An effect pass can contain render state assignments and shader object assignments.

An effect pass can contain render state assignments and shader object assignments.

Get a pass description by calling ; an effect technique contains one or more passes.

To get a shader description, call a method like .

To create an effect pool, call a function like . Effect pools can improve performance by reducing the number of API calls required to make state changes (see Using Effect Pools).

An Interface is created when an effect is read into memory.

Effect variables are saved in memory in the backing store; when a technique is applied, the values in the backing store are copied to the device. You can use either of these methods to return state. For examples, see Two Ways to Get the State in an Effect Variable.

Effect variables are saved in memory in the backing store; when a technique is applied, the values in the backing store are copied to the device. Backing store data can used to recreate the variable when necessary.

An Interface is created when an effect is read into memory.

Effect variables are saved in memory in the backing store; when a technique is applied, the values in the backing store are copied to the device. You can use either of these methods to return state. For examples, see Two Ways to Get the State in an Effect Variable.

To get an effect-shader description, call .

The interface is obtained by calling or .

The LPD3DX10FONT type is defined as a reference to the interface.

 typedef interface  ;	
            typedef interface  *LPD3DX10FONT;	
            

Note??Calling this method will increase the internal reference count on the interface. Be sure to call when you are done using this interface or you will have a memory leak.

This method describes Unicode font objects if UNICODE is defined. Otherwise GetDescA is called, which returns a reference to the D3DX10FONT_DESCA structure.

This method generates textures containing glyphs that represent the input characters. The glyphs are drawn as a series of triangles.

Characters will not be rendered to the device; must still be called to render the characters. However, by pre-loading characters into video memory, will use substantially fewer CPU resources.

This method internally converts characters to glyphs using the GDI function GetCharacterPlacement.

This method generates textures that contain the input glyphs. The glyphs are drawn as a series of triangles.

Glyphs will not be rendered to the device; must still be called to render the glyphs. However, by pre-loading glyphs into video memory, will use substantially fewer CPU resources.

The compiler setting also determines the function version. If Unicode is defined, the function call resolves to PreloadTextW. Otherwise, the function call resolves to PreloadTextA because ANSI strings are being used.

This method generates textures that contain glyphs that represent the input text. The glyphs are drawn as a series of triangles.

Text will not be rendered to the device; must still be called to render the text. However, by preloading text into video memory, will use substantially fewer CPU resources.

This method internally converts characters to glyphs using the GDI function GetCharacterPlacement.

The parameters of this method are very similar to those of the GDI DrawText function.

This method supports both ANSI and Unicode strings.

Unless the DT_NOCLIP format is used, this method clips the text so that it does not appear outside the specified rectangle. All formatting is assumed to have multiple lines unless the DT_SINGLELINE format is specified.

If the selected font is too large for the rectangle, this method does not attempt to substitute a smaller font.

This method supports only fonts whose escapement and orientation are both zero.

Note??Calling this method will increase the internal reference count on the interface. Be sure to call when you are done using this interface or you will have a memory leak.

This method describes Unicode font objects if UNICODE is defined. Otherwise GetDescA is called, which returns a reference to the D3DX10FONT_DESCA structure.

In general, binding flags can be combined using a logical OR (except the constant-buffer flag); however, you should use a single flag to allow the device to optimize the resource usage.

This enumeration is used by a:

• Buffer description when creating a buffer.
• Texture description when creating a texture (see or or ).

A shader-resource buffer is NOT a constant buffer; rather, it is a texture or buffer resource that is bound to a shader, that contains texture or buffer data (it is not limited to a single element type in the buffer). A shader-resource buffer is created with the flag and is bound to the pipeline using one of these APIs: , , or . Furthermore, a shader-resource buffer cannot use the flag.

The runtime implements RGB blending and alpha blending separately. Therefore, blend state requires separate blend operations for RGB data and alpha data. These blend operations are specified in a blend description. The two sources ? Source 1, called SrcBlend and SrcBlendAlpha, and Source 2, called DestBlend and DestBlendAlpha ? are shown in the blending block diagram.

Blend operations are specified in a blend description.

These flags can be combined with a bitwise OR.

A comparison option determines whether how the runtime compares source (new) data against destination (existing) data before storing the new data. The comparison option is declared in a description before an object is created. The API allows you to set a comparison option for a depth-stencil buffer (see ), depth-stencil operations (see ), or sampler state (see ).

In addition to these performance counters, independent hardware vendors may define their own set of performance counters for their devices. The enum values for these counters would start after and would be defined by those hardware vendors.

A device can support one or more of these performance counters, but it is not required to support any of them.