Retrieves a specific part from a compilation result.
\t\nA reference to uncompiled shader data; either ASCII HLSL code or a compiled effect.
Length of uncompiled shader data that pSrcData points to.
A
Flags that indicate how to retrieve the blob part. Currently, no flags are defined.
The address of a reference to the ID3DBlob interface that is used to retrieve the specified part of the buffer.
Returns one of the following Direct3D 10 Return Codes.
Decompresses one or more shaders from a compressed set.
\t\nA reference to uncompiled shader data; either ASCII HLSL code or a compiled effect.
Length of uncompiled shader data that pSrcData points to.
The number of shaders to decompress.
The index of the first shader to decompress.
An array of indexes that represent the shaders to decompress.
Flags that indicate how to decompress. Currently, no flags are defined.
The address of a reference to the ID3DBlob interface that is used to retrieve the decompressed shader data.
A reference to a variable that receives the total number of shaders that
Returns one of the following Direct3D 10 Return Codes.
Disassembles compiled HLSL code.
\t\nA reference to source data as compiled HLSL code.
Length of pSrcData.
Flags affecting the behavior of
| Flag | Description |
|---|---|
| Enable the output of color codes. | |
| Enable the output of default values. | |
| Enable instruction numbering. | |
| No effect. |
?
The optional comment string at the top of the shader that identifies the shader constants and variables.
A reference to a buffer that receives the
Returns one of the following Direct3D 10 Return Codes.
Compile HLSL code or an effect file into bytecode for a given target.
\t\nA reference to uncompiled shader data; either ASCII HLSL code or a compiled effect.
Length of pSrcData.
Optional. You can use this parameter for strings that specify error messages. If not used, set to
Optional. An array of
Optional. A reference to an
#define D3D_COMPILE_STANDARD_FILE_INCLUDE ((*)()1) The name of the shader entry point function where shader execution begins. When you compile an effect,
A string that specifies the shader target or set of shader features to compile against. The shader target can be shader model 2, shader model 3, shader model 4, or shader model 5. The target can also be an effect type (for example, fx_4_1).
Shader compile options.
Effect compile options. When you compile a shader and not an effect file,
The address of a ID3DBlob that contains the compiled code.
Optional. A reference to an ID3DBlob that contains compiler error messages, or
Returns one of the Direct3D 10 Return Codes.
Removes unwanted blobs from a compilation result.
\t\nA reference to source data as compiled HLSL code.
Length of pSrcData.
Strip flag options, represented by
A reference to a variable that receives a reference to the ID3DBlob interface that you can use to access the unwanted stripped out shader code.
Returns one of the Direct3D 10 Return Codes.
Preprocesses uncompiled HLSL code.
\t\nA reference to uncompiled shader data; either ASCII HLSL code or a compiled effect.
Length of pSrcData.
Optional. The name of the file that contains the uncompiled HLSL code.
Optional. An array of
Optional. A reference to an
#define D3D_COMPILE_STANDARD_FILE_INCLUDE ((*)()1) The address of a ID3DBlob that contains the compiled code.
Optional. A reference to an ID3DBlob that contains compiler error messages, or
Returns one of the Direct3D 10 Return Codes.
Compresses a set of shaders into a more compact form.
\t\nThe number of shaders to compress.
An array of
Flags that indicate how to compress the shaders. Currently, only the D3D_COMPRESS_SHADER_KEEP_ALL_PARTS (0x00000001) flag is defined.
The address of a reference to the ID3DBlob interface that is used to retrieve the compressed shader data.
Returns one of the following Direct3D 10 Return Codes.
Gets a reference to a reflection interface.
\t\nA reference to source data as compiled HLSL code.
Length of pSrcData.
The reference
A reference to a reflection interface.
Returns one of the following Direct3D 10 Return Codes.
Shader code contains metadata that can be inspected using the reflection APIs.
The following code illustrates retrieving a
pd3dDevice->CreatePixelShader( pPixelShaderBuffer->GetBufferPointer(), pPixelShaderBuffer->GetBufferSize(), g_pPSClassLinkage, &g_pPixelShader ); * pReflector = null ; \t\n ( pPixelShaderBuffer->GetBufferPointer(), pPixelShaderBuffer->GetBufferSize(), IID_ID3D11ShaderReflection, (void**) &pReflector);\t\n Gets the input signature from a compilation result.
\t\nA reference to source data as compiled HLSL code.
Length of pSrcData.
Optional. A reference to an
Returns one of the following Direct3D 10 Return Codes.
Gets the input and output signatures from a compilation result.
\t\nA reference to source data as compiled HLSL code.
Length of pSrcData.
Optional. A reference to an
Returns one of the following Direct3D 10 Return Codes.
Gets the output signature from a compilation result.
\t\nA reference to source data as compiled HLSL code.
Length of pSrcData.
Optional. A reference to an
Returns one of the following Direct3D 10 Return Codes.
Gets shader debug information.
\t\nA reference to source data; either uncompiled or compiled HLSL code.
Length of pSrcData.
Optional. A reference to an
Returns one of the following Direct3D 10 Return Codes.
Debug information is embedded in the body of the shader after calling
Values that identify the indended use of a constant-data buffer.
\t\nBind the constant buffer to an input slot defined in HLSL code (instead of letting the compiler choose the input slot).
Values that identify the intended use of constant-buffer data.
\t\nA buffer containing scalar constants.
A buffer containing texture data.
A buffer containing interface references.
A buffer containing binding information.
Values that indicate the location of a shader #include file.
\t\nYou pass a
The local directory.
The system directory.
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
\t\nUse the
The following diagram shows the various primitive types for a geometry shader object.
\t\nValues that identify the data types that can be stored in a register.
\t\nA register component type is specified in the ComponentType member of the
The data type is unknown.
32-bit unsigned integer.
32-bit signed integer.
32-bit floating-point number.
Values that identify the return type of a resource.
\t\nA resource return type is specified in the ReturnType member of the
Return type is an unsigned integer value normalized to a value between 0 and 1.
Return type is a signed integer value normalized to a value between -1 and 1.
Return type is a signed integer.
Return type is an unsigned integer.
Return type is a floating-point number.
Return type is unknown.
Return type is a double-precision value.
Return type is a multiple-dword type, such as a double or uint64, and the component is continued from the previous component that was declared. The first component represents the lower bits.
Values that identify parts of the content of an arbitrary length data buffer.
\t\nThese values are passed to the
The blob part is an input signature.
The blob part is an output signature.
The blob part is an input and output signature.
The blob part is a patch constant signature.
The blob part is all signature.
The blob part is debug information.
The blob part is a legacy shader.
The blob part is an XNA prepass shader.
The blob part is an XNA shader.
The blob part is a test alternate shader.
Note??This value identifies a test part and is only produced by special compiler versions. Therefore, this part type is typically not present in shaders.
The blob part is test compilation details.
Note??This value identifies a test part and is only produced by special compiler versions. Therefore, this part type is typically not present in shaders.
The blob part is test compilation performance.
Note??This value identifies a test part and is only produced by special compiler versions. Therefore, this part type is typically not present in shaders.
Values that identify shader-input options.
\t\nAssign a shader input to a register based on the register assignment in the HLSL code (instead of letting the compiler choose the register).
Use a comparison sampler, which uses the SampleCmp (DirectX HLSL Texture Object) and SampleCmpLevelZero (DirectX HLSL Texture Object) sampling functions.
A 2-bit value for encoding texture components.
A 2-bit value for encoding texture components.
A 2-bit value for encoding texture components.
Values that identify resource types that can be bound to a shader and that are reflected as part of the resource description for the shader.
\t\nThe shader resource is a constant buffer.
The shader resource is a texture buffer.
The shader resource is a texture.
The shader resource is a sampler.
The shader resource is a read-and-write buffer.
The shader resource is a structured buffer.
For more information about structured buffer, see the Remarks section.
The shader resource is a read-and-write structured buffer.
The shader resource is a byte-address buffer.
The shader resource is a read-and-write byte-address buffer.
The shader resource is an append-structured buffer.
The shader resource is a consume-structured buffer.
The shader resource is a read-and-write structured buffer that uses the built-in counter to append or consume.
Values that identify the class of a shader variable.
\t\nThe class of a shader variable is not a programming class; the class identifies the variable class such as scalar, vector, object, and so on.
The shader variable is a scalar.
The shader variable is a vector.
The shader variable is a row-major matrix.
The shader variable is a column-major matrix.
The shader variable is an object.
The shader variable is a structure.
The shader variable is a class.
The shader variable is an interface.
Values that identify information about a shader variable.
\t\nA call to the
Indicates that the registers assigned to this shader variable were explicitly declared in shader code (instead of automatically assigned by the compiler).
Indicates that this variable is used by this shader. This value confirms that a particular shader variable (which can be common to many different shaders) is indeed used by a particular shader.
Indicates that this variable is an interface.
Indicates that this variable is a parameter of an interface.
Values that identify various data, texture, and buffer types that can be assigned to a shader variable.
\t\nA call to the
The types in a structured buffer describe the structure of the elements in the buffer. The layout of these types generally match their C++ struct counterparts. The following examples show structured buffers:
struct mystruct {float4 val; uint ind;}; RWStructuredBuffer<mystruct> rwbuf;\t\n RWStructuredBuffer<float3> rwbuf2;The variable is a void reference.
The variable is a boolean.
The variable is an integer.
The variable is a floating-point number.
The variable is a string.
The variable is a texture.
The variable is a 1D texture.
The variable is a 2D texture.
The variable is a 3D texture.
The variable is a texture cube.
The variable is a sampler.
The variable is a pixel shader.
The variable is a vertex shader.
The variable is an unsigned integer.
The variable is an 8-bit unsigned integer.
The variable is a geometry shader.
The variable is a rasterizer-state object.
The variable is a depth-stencil-state object.
The variable is a blend-state object.
The variable is a buffer.
The variable is a constant buffer.
The variable is a texture buffer.
The variable is a 1D-texture array.
The variable is a 2D-texture array.
The variable is a render-target view.
The variable is a depth-stencil view.
The variable is a 2D-multisampled texture.
The variable is a 2D-multisampled-texture array.
The variable is a texture-cube array.
The variable holds a compiled hull-shader binary.
The variable holds a compiled domain-shader binary.
The variable is an interface.
The variable holds a compiled compute-shader binary.
The variable is a double precision (64-bit) floating-point number.
The variable is a 1D read-and-write texture.
The variable is an array of 1D read-and-write textures.
The variable is a 2D read-and-write texture.
The variable is an array of 2D read-and-write textures.
The variable is a 3D read-and-write texture.
The variable is a read-and-write buffer.
The variable is a byte-address buffer.
The variable is a read-and-write byte-address buffer.
The variable is a structured buffer.
For more information about structured buffer, see the Remarks section.
The variable is a read-and-write structured buffer.
The variable is an append structured buffer.
The variable is a consume structured buffer.
The variable is a void reference.
The variable is a boolean.
The variable is an integer.
The variable is a floating-point number.
The variable is a string.
The variable is a texture.
Indicates shader type.
\t\nPixel shader.
Vertex shader.
Geometry shader.
Hull shader.
Domain shader.
Compute shader.
Strip flag options.
\t\nThese flags are used by
Remove reflection data.
Remove debug information.
Remove test blob data.
Values that identify shader parameters that use system-value semantics.
\t\nThe
This parameter does not use a predefined system-value semantic.
This parameter contains position data.
This parameter contains clip-distance data.
This parameter contains cull-distance data.
This parameter contains a render-target-array index.
This parameter contains a viewport-array index.
This parameter contains a vertex ID.
This parameter contains a primitive ID.
This parameter contains an instance ID.
This parameter contains data that identifies whether or not the primitive faces the camera.
This parameter contains a sampler-array index.
This parameter contains one of four tessellation factors that correspond to the amount of parts that a quad patch is broken into along the given edge. This flag is used to tessellate a quad patch.
This parameter contains one of two tessellation factors that correspond to the amount of parts that a quad patch is broken into vertically and horizontally within the patch. This flag is used to tessellate a quad patch.
This parameter contains one of three tessellation factors that correspond to the amount of parts that a tri patch is broken into along the given edge. This flag is used to tessellate a tri patch.
This parameter contains the tessellation factor that corresponds to the amount of parts that a tri patch is broken into within the patch. This flag is used to tessellate a tri patch.
This parameter contains the tessellation factor that corresponds to the number of lines broken into within the patch. This flag is used to tessellate an isolines patch.
This parameter contains the tessellation factor that corresponds to the number of lines that are created within the patch. This flag is used to tessellate an isolines patch.
This parameter contains render-target data.
This parameter contains depth data.
This parameter contains alpha-coverage data.
This parameter signifies that the value is greater than or equal to a reference value. This flag is used to specify conservative depth for a pixel shader.
This parameter signifies that the value is less than or equal to a reference value. This flag is used to specify conservative depth for a pixel shader.
Values that identify domain options for tessellator data.
\t\nThe data domain defines the type of data. This enumeration is used by
The data type is undefined.
Isoline data.
Triangle data.
Quad data.
Values that identify output primitive types.
\t\nThe output primitive type determines how the tessellator output data is organized; this enumeration is used by
The output primitive type is undefined.
The output primitive type is a point.
The output primitive type is a line.
The output primitive type is a clockwise triangle.
The output primitive type is a counter clockwise triangle.
Values that identify partitioning options.
\t\nDuring tessellation, the partition option helps to determine how the algorithm chooses the next partition value; this enumeration is used by
The partitioning type is undefined.
Partition with integers only.
Partition with a power-of-two number only.
Partition with an odd, fractional number.
Partition with an even, fractional number.
This shader-reflection interface provides access to a constant buffer.
\t\nTo create a constant-buffer interface, call
Get a constant-buffer description.
\t\nA reference to a
Returns one of the following Direct3D 11 Return Codes.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader-reflection variable by index.
\t\nZero-based index.
A reference to a shader-reflection variable interface (see
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader-reflection variable by name.
\t\nVariable name.
Returns a sentinel object (end of list marker). To determine if GetVariableByName successfully completed, call
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a constant-buffer description.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nTo use this interface, create an interface that inherits from
A shader-reflection interface accesses shader information.
\t\nAn
pd3dDevice->CreatePixelShader( pPixelShaderBuffer->GetBufferPointer(), pPixelShaderBuffer->GetBufferSize(), g_pPSClassLinkage, &g_pPixelShader ); * pReflector = null ; \t\n ( pPixelShaderBuffer->GetBufferPointer(), pPixelShaderBuffer->GetBufferSize(), IID_ID3D11ShaderReflection, (void**) &pReflector); Get a shader description.
\t\nA reference to a shader description. See
Returns one of the following Direct3D 11 Return Codes.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a constant buffer by index.
\t\nZero-based index.
A reference to a constant buffer (see
A constant buffer supplies either scalar constants or texture constants to a shader. A shader can use one or more constant buffers. For best performance, separate constants into buffers based on the frequency they are updated.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a constant buffer by name.
\t\nThe constant-buffer name.
A reference to a constant buffer (see
A constant buffer supplies either scalar constants or texture constants to a shader. A shader can use one or more constant buffers. For best performance, separate constants into buffers based on the frequency they are updated.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a description of how a resource is bound to a shader.
\t\nA zero-based resource index.
A reference to an input-binding description. See
A shader consists of executable code (the compiled HLSL functions) and a set of resources that supply the shader with input data. GetResourceBindingDesc gets information about how one resource in the set is bound as an input to the shader. The ResourceIndex parameter specifies the index for the resource.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet an input-parameter description for a shader.
\t\nA zero-based parameter index.
A reference to a shader-input-signature description. See
An input-parameter description is also called a shader signature. The shader signature contains information about the input parameters such as the order or parameters, their data type, and a parameter semantic.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet an output-parameter description for a shader.
\t\nA zero-based parameter index.
A reference to a shader-output-parameter description. See
An output-parameter description is also called a shader signature. The shader signature contains information about the output parameters such as the order or parameters, their data type, and a parameter semantic.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a patch-constant parameter description for a shader.
\t\nA zero-based parameter index.
A reference to a shader-input-signature description. See
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets a variable by name.
\t\nA reference to a string containing the variable name.
Returns a
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a description of how a resource is bound to a shader.
\t\nThe constant-buffer name of the resource.
A reference to an input-binding description. See
A shader consists of executable code (the compiled HLSL functions) and a set of resources that supply the shader with input data. GetResourceBindingDescByName gets information about how one resource in the set is bound as an input to the shader. The Name parameter specifies the name of the resource.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of Mov instructions.
\t\nReturns the number of Mov instructions.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of Movc instructions.
\t\nReturns the number of Movc instructions.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of conversion instructions.
\t\nReturns the number of conversion instructions.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of bitwise instructions.
\t\nThe number of bitwise instructions.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the geometry-shader input-primitive description.
\t\nThe input-primitive description, see D3D10_PRIMITIVE_TOPOLOGY.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nIndicates whether a shader is a sample frequency shader.
\t\nReturns true if the shader is a sample frequency shader; otherwise returns false.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of interface slots in a shader.
\t\nThe number of interface slots in the shader.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the minimum feature level.
\t\nA reference to one of the enumerated values in
Returns one of the following Direct3D 11 Return Codes.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nRetrieves the sizes, in thread groups, of the X, Y, and Z dimensions of the shader's thread-group grid.
\t\nA reference to the size, in thread groups, of the x-dimension of the thread-group grid. The maximum size is 65535.
A reference to the size, in thread groups, of the y-dimension of the thread-group grid. The maximum size is 65535.
A reference to the size, in thread groups, of the z-dimension of the thread-group grid. The maximum size is 65535.
Returns one of the following Direct3D 11 Return Codes.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader description.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of Mov instructions.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of Movc instructions.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of conversion instructions.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of bitwise instructions.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the geometry-shader input-primitive description.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nIndicates whether a shader is a sample frequency shader.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of interface slots in a shader.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the minimum feature level.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nThis shader-reflection interface provides access to variable type.
\t\nThe get a shader-reflection-type interface, call
Get the description of a shader-reflection-variable type.
\t\nA reference to a shader-type description (see
Returns one of the following Direct3D 11 Return Codes.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader-reflection-variable type by index.
\t\nZero-based index.
A reference to a
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader-reflection-variable type by name.
\t\nMember name.
A reference to a
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader-reflection-variable type.
\t\nZero-based index.
The variable type.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nIndicates whether two
Returns
IsEqual indicates whether the sources of the
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the base class of a class.
\t\nReturns a reference to a
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets an
Returns A reference to a
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of interfaces.
\t\nReturns the number of interfaces.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet an interface by index.
\t\nZero-based index.
A reference to a
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nIndicates whether a variable is of the specified type.
\t\nA reference to a
Returns
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nIndicates whether a class type implements an interface.
\t\nA reference to a
Returns
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet the description of a shader-reflection-variable type.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the base class of a class.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets an
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the number of interfaces.
\t\nThis method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nThis shader-reflection interface provides access to a variable.
\t\nTo get a shader-reflection-variable interface, call a method like
Get a shader-variable description.
\t\nA reference to a shader-variable description (see
Returns one of the following Direct3D 11 Return Codes.
This method can be used to determine if the
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader-variable type.
\t\nA reference to a
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGets the corresponding interface slot for a variable that represents an interface reference.
\t\nIndex of the array element to get the slot number for. For a non-array variable this value will be zero.
Returns the index of the interface in the interface array.
GetInterfaceSlot gets the corresponding slot in an dynamic linkage array for an interface instance. The returned slot number is used to set an interface instance to a particular class instance. See the HLSL Interfaces and Classes overview for additional information.
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nGet a shader-variable description.
\t\nThis method can be used to determine if the
This method's interface is hosted in the out-of-box DLL D3DCompiler_xx.dll.
\t\nDescribes a shader constant-buffer.
\t\nConstants are supplied to shaders in a shader-constant buffer. Get the description of a shader-constant-buffer by calling
The name of the buffer.
The intended use of the constant data.
The number of unique variables.
Buffer size (in bytes).
Shader buffer properties.
Describes how a shader resource is bound to a shader input.
\t\nGet a shader-input-signature description by calling
Name of the shader resource.
Identifies the type of data in the resource. See D3D10_SHADER_INPUT_TYPE.
Starting bind point.
Number of contiguous bind points for arrays.
Shader input-parameter options. See D3D10_SHADER_INPUT_FLAGS.
If the input is a texture, the return type. See D3D11_RESOURCE_RETURN_TYPE.
Identifies the dimensions of the bound resource. For a list of values that
The number of samples for a multisampled texture; otherwise 0.
Describes shader data.
\t\nAn array of
A reference to shader data.
Length of shader data that pBytecode points to.
Describes a shader.
\t\nA shader is written in HLSL and compiled into an intermediate language by the HLSL compiler. The shader description returns information about the compiled shader. Get a shader description by calling
Shader version.
The name of the originator of the shader.
Shader compilation/parse flags.
The number of shader-constant buffers.
The number of resource (textures and buffers) bound to a shader.
The number of parameters in the input signature.
The number of parameters in the output signature.
The number of intermediate-language instructions in the compiled shader.
The number of temporary registers in the compiled shader.
Number of temporary arrays used.
Number of constant defines.
Number of declarations (input + output).
Number of non-categorized texture instructions.
Number of texture load instructions
Number of texture comparison instructions
Number of texture bias instructions
Number of texture gradient instructions.
Number of floating point arithmetic instructions used.
Number of signed integer arithmetic instructions used.
Number of unsigned integer arithmetic instructions used.
Number of static flow control instructions used.
Number of dynamic flow control instructions used.
Number of macro instructions used.
Number of array instructions used.
Number of cut instructions used.
Number of emit instructions used.
The D3D10_PRIMITIVE_TOPOLOGY, which represents the shader output topology.
Geometry shader maximum output vertex count.
The D3D11_PRIMITIVE-typed value that represents the input primitive for a geometry shader or hull shader.
Number of parameters in the patch-constant signature.
Number of geometry shader instances.
Number of control points in the hull shader and domain shader.
The D3D11_TESSELLATOR_OUTPUT_PRIMITIVE, which represents the tessellator output-primitive type.
The D3D11_TESSELLATOR_PARTITIONING, which represents the tessellator partitioning mode.
The D3D11_TESSELLATOR_DOMAIN, which represents the tessellator domain.
Number of barrier instructions in a compute shader.
Number of interlocked instructions in a compute shader.
Number of texture writes in a compute shader.
Describes a shader signature.
\t\nA shader can take n inputs and can produce m outputs. The order of the input (or output) parameters, their associated types, and any attached semantics make up the shader signature. Each shader has an input and an output signature.
When compiling a shader or an effect, some API calls validate shader signatures That is, they compare the output signature of one shader (like a vertex shader) with the input signature of another shader (like a pixel shader). This ensures that a shader outputs data that is compatible with a downstream shader that is consuming that data. Compatible means that a shader signature is a exact-match subset of the preceding shader stage. Exact match means parameter types and semantics must exactly match. Subset means that a parameter that is not required by a downstream stage, does not need to include that parameter in its shader signature.
Get a shader-signature from a shader or an effect by calling APIs such as
A per-parameter string that identifies how the data will be used.
Semantic index that modifies the semantic. Used to differentiate different parameters that use the same semantic.
The register that will contain this variable's data.
A predefined string that determines the functionality of certain pipeline stages. See D3D10_NAME.
The per-component-data type that is stored in a register. See D3D10_REGISTER_COMPONENT_TYPE. Each register can store up to four-components of data.
Mask which indicates which components of a register are used.
Mask which indicates whether a given component is never written (if the signature is an output signature) or always read (if the signature is an input signature).
Indicates which stream the geometry shader is using for the signature parameter.
Describes a shader-variable type.
\t\nGet a shader-variable-type description by calling
Identifies the variable class as one of scalar, vector, matrix or object. See D3D10_SHADER_VARIABLE_CLASS.
The variable type. See D3D10_SHADER_VARIABLE_TYPE.
Number of rows in a matrix. Otherwise a numeric type returns 1, any other type returns 0.
Number of columns in a matrix. Otherwise a numeric type returns 1, any other type returns 0.
Number of elements in an array; otherwise 0.
Number of members in the structure; otherwise 0.
Offset, in bytes, between the start of the parent structure and this variable.
Describes a shader variable.
\t\nGet a shader-variable description using reflection by calling
As of the June 2010 update, DefaultValue emits default values for reflection.
\t\nThe variable name.
Offset from the start of the parent structure to the beginning of the variable.
Size of the variable (in bytes).
A combination of
The default value for initializing the variable.
The
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
An
Sets application-defined data to the object and associates that data with a
A
The size of the object's data.
A reference to the object's data.
Returns one of the DXGI_ERROR values.
SetPrivateData makes a copy of the specified data and stores it with the object.
Private data that SetPrivateData stores in the object occupies the same storage space as private data that is stored by associated Direct3D objects (for example, by a Microsoft Direct3D?11 device through
The debug layer reports memory leaks by outputting a list of object interface references along with their friendly names. The default friendly name is \"<unnamed>\". You can set the friendly name so that you can determine if the corresponding object interface reference caused the leak. To set the friendly name, use the SetPrivateData method and the well-known private data
static const char c_szName[] = \"My name\";\t\n hr = pContext->SetPrivateData( , sizeof( c_szName ) - 1, c_szName );\t\n You can use
Set an interface in the object's private data.
\t\nA
The interface to set.
Returns one of the following DXGI_ERROR.
This API associates an interface reference with the object.
When the interface is set its reference count is incremented. When the data are overwritten (by calling SPD or SPDI with the same
Get a reference to the object's data.
\t\nA
The size of the data.
Pointer to the data.
Returns one of the following DXGI_ERROR.
If the data returned is a reference to an
Gets the parent of the object.
\t\nThe ID of the requested interface.
The address of a reference to the parent object.
Returns one of the DXGI_ERROR values.
Enumerate adapter (video card) outputs.
\t\nThe index of the output.
The address of a reference to an
A code that indicates success or failure (see DXGI_ERROR). Will return
When the EnumOutputs method succeeds and fills the ppOutput parameter with the address of the reference to the output interface, EnumOutputs increments the output interface's reference count. To avoid a memory leak, when you finish using the output interface, call the Release method to decrement the reference count.
EnumOutputs first returns the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumOutputs then returns other outputs.
\t\nGets a DXGI 1.0 description of an adapter (or video card).
\t\nA reference to a
Returns
Graphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()\t\n { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L\"d3d9.dll\" ); if ( null == hD3D9 ) { return false; } // /* Try to create interface (also known as a DX9L interface). This interface can only be created if the driver is a WDDM driver. */ // pD3D9Create9Ex = (LPDIRECT3DCREATE9EX) GetProcAddress( hD3D9, \"Direct3DCreate9Ex\" ); return pD3D9Create9Ex != null ;\t\n } * pDXGIDevice;\t\n hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice);\t\n * pDXGIAdapter;\t\n pDXGIDevice->GetAdapter(&pDXGIAdapter);\t\n adapterDesc;\t\n pDXGIAdapter->GetDesc(&adapterDesc); Checks whether the system supports a device interface for a graphics component.
\t\nThe
The user mode driver version of InterfaceName. This is returned only if the interface is supported. This parameter can be
Note??You can use CheckInterfaceSupport only to check whether a Direct3D 10.x interface is supported, and only on Windows Vista SP1 and later versions of the operating system. If you try to use CheckInterfaceSupport to check whether a Direct3D 11.x and later version interface is supported, CheckInterfaceSupport returns
Gets a DXGI 1.0 description of an adapter (or video card).
\t\nGraphics applications can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have WDDM drivers. The following are the critical steps involved.
HasWDDMDriver()\t\n { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null ; HMODULE hD3D9 = null ; hD3D9 = LoadLibrary( L\"d3d9.dll\" ); if ( null == hD3D9 ) { return false; } // /* Try to create interface (also known as a DX9L interface). This interface can only be created if the driver is a WDDM driver. */ // pD3D9Create9Ex = (LPDIRECT3DCREATE9EX) GetProcAddress( hD3D9, \"Direct3DCreate9Ex\" ); return pD3D9Create9Ex != null ;\t\n } * pDXGIDevice;\t\n hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice);\t\n * pDXGIAdapter;\t\n pDXGIDevice->GetAdapter(&pDXGIAdapter);\t\n adapterDesc;\t\n pDXGIAdapter->GetDesc(&adapterDesc); An
The
The object returned by the Direct3D create device functions implements the
* pDXGIDevice;\t\n hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice);\t\n Returns the adapter for the specified device.
\t\nThe address of an
Returns
If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
\t\nReturns a surface. This method is used internally and you should not call it directly in your application.
\t\nA reference to a
The number of surfaces to create.
A DXGI_USAGE flag that specifies how the surface is expected to be used.
An optional reference to a
The address of an
Returns
The CreateSurface method creates a buffer to exchange data between one or more devices. It is used internally, and you should not directly call it.
The runtime automatically creates an
Gets the residency status of an array of resources.
\t\nAn array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
\t\nGets the residency status of an array of resources.
\t\nAn array of
An array of
The number of resources in the ppResources argument array and pResidencyStatus argument array.
Returns
The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called. Note that the residency status will constantly change.
If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the
Note??This method should not be called every frame as it incurs a non-trivial amount of overhead.
\t\nSets the GPU thread priority.
\t\nA value that specifies the required GPU thread priority. This value must be between -7 and 7, inclusive, where 0 represents normal priority.
Return
The values for the Priority parameter function as follows:
To use the SetGPUThreadPriority method, you should have a comprehensive understanding of GPU scheduling. You should profile your application to ensure that it behaves as intended. If used inappropriately, the SetGPUThreadPriority method can impede rendering speed and result in a poor user experience.
\t\nGets the GPU thread priority.
\t\nA reference to a variable that receives a value that indicates the current GPU thread priority. The value will be between -7 and 7, inclusive, where 0 represents normal priority.
Return
Returns the adapter for the specified device.
\t\nIf the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.
\t\nGets or sets the GPU thread priority.
\t\nInherited from objects that are tied to the device so that they can retrieve a reference to it.
\t\nRetrieves the device.
\t\nThe reference id for the device.
The address of a reference to the device.
A code that indicates success or failure (see DXGI_ERROR).
The type of interface that is returned can be any interface published by the device. For example, it could be an
An
Create a factory by calling CreateDXGIFactory.
Because a Direct3D device can be created without creating a swap chain, you might need to retrieve the factory that is used to create the device in order to create a swap chain.\t\n This can be accomplished by requesting the
* pDXGIDevice;\t\n hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice); * pDXGIAdapter;\t\n hr = pDXGIDevice->GetParent(__uuidof(), (void **)&pDXGIAdapter); * pIDXGIFactory;\t\n pDXGIAdapter->GetParent(__uuidof(), (void **)&pIDXGIFactory);\t\n See
Enumerates the adapters (video cards).
\t\nThe index of the adapter to enumerate.
The address of a reference to an
Returns
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters then returns other adapters with outputs.
\t\nAllows DXGI to monitor an application's message queue for the alt-enter key sequence (which causes the application to switch from windowed to full screen or vice versa).
\t\nThe handle of the window that is to be monitored. This parameter can be
One or more of the following values:
The combination of WindowHandle and Flags informs DXGI to stop monitoring window messages for the previously-associated window.
If the application switches to full-screen mode, DXGI will choose a full-screen resolution to be the smallest supported resolution that is larger or the same size as the current back buffer size.
Applications can make some changes to make the transition from windowed to full screen more efficient. For example, on a WM_SIZE message, the application should release any outstanding swap-chain back buffers, call
While windowed, the application can, if it chooses, restrict the size of its window's client area to sizes to which it is comfortable rendering. A fully flexible application would make no such restriction, but UI elements or other design considerations can, of course, make this flexibility untenable. If the application further chooses to restrict its window's client area to just those that match supported full-screen resolutions, the application can field WM_SIZING, then check against
Applications that want to handle mode changes or Alt+Enter themselves should call MakeWindowAssociation with the
If a Metro style app calls MakeWindowAssociation, it fails with
A Microsoft Win32 application can use MakeWindowAssociation to control full-screen transitions through the Alt+Enter key combination and print screen behavior for full screen. For Metro style apps, because DXGI cannot perform full-screen transitions, Metro style app have no way to control full-screen transitions.
\t\nGet the window through which the user controls the transition to and from full screen.
\t\nA reference to a window handle.
If a Metro style app calls GetWindowAssociation, it fails with
[Starting with Direct3D 11.1, we recommend not to use CreateSwapChain anymore to create a swap chain. Instead, use CreateSwapChainForHwnd, CreateSwapChainForImmersiveWindow, or CreateSwapChainForCompositionSurface depending on how you want to create the swap chain.]
Creates a swap chain.
\t\n
If you attempt to create a swap chain in full-screen mode, and full-screen mode is unavailable, the swap chain will be created in windowed mode and
If the buffer width or the buffer height is zero, the sizes will be inferred from the output window size in the swap-chain description.
Because the target output cannot be chosen explicitly when the swap-chain is created, you should not create a full-screen swap chain. This can reduce presentation performance if the swap chain size and the output window size do not match. Here are two ways to ensure that the sizes match:
If the swap chain is in full-screen mode, before you release it you must use SetFullscreenState to switch it to windowed mode. For more information about releasing a swap chain, see the \"Destroying a Swap Chain\" section of DXGI Overview.
You can specify
However, to use stereo presentation and to change resize behavior for the flip model, applications must use the IDXGIFactory2::CreateSwapChainForHwnd method. Otherwise, the back-buffer contents implicitly scale to fit the presentation target size; that is, you can't turn off scaling.
Notes for Metro style appsIf a Metro style app calls CreateSwapChain with full screen specified, CreateSwapChain fails.
Metro style apps call the IDXGIFactory2::CreateSwapChainForImmersiveWindow method to create a swap chain.
\t\nCreate an adapter interface that represents a software adapter.
\t\nHandle to the software adapter's dll. HMODULE can be obtained with GetModuleHandle or LoadLibrary.
Address of a reference to an adapter (see
A software adapter is a DLL that implements the entirety of a device driver interface, plus emulation, if necessary, of kernel-mode graphics components for Windows. Details on implementing a software adapter can be found in the Windows Vista Driver Development Kit. This is a very complex development task, and is not recommended for general readers.
Calling this method will increment the module's reference count by one. The reference count can be decremented by calling FreeLibrary.
The typical calling scenario is to call LoadLibrary, pass the handle to CreateSoftwareAdapter, then immediately call FreeLibrary on the DLL and forget the DLL's HMODULE. Since the software adapter calls FreeLibrary when it is destroyed, the lifetime of the DLL will now be owned by the adapter, and the application is free of any further consideration of its lifetime.
\t\nThe
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
To create a factory, call the CreateDXGIFactory1 function.
\t\nEnumerates both adapters (video cards) with or without outputs.
\t\nThe index of the adapter to enumerate.
The address of a reference to an
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the
When the EnumAdapters1 method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters1 increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.
EnumAdapters1 first returns the local adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters1 next returns other adapters with outputs. EnumAdapters1 finally returns adapters without outputs.
\t\nInforms an application of the possible need to re-enumerate adapters.
\t\nIsCurrent returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
\t\nInforms an application of the possible need to re-enumerate adapters.
\t\nThis method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
\t\nIdentifies the type of DXGI adapter.
\t\nThe
Specifies no flags.
Value always set to 0. This flag is reserved.
Flags that indicate how the back buffers should be rotated to fit the physical rotation of a monitor.
\t\nUnspecified rotation.
Specifies no rotation.
Specifies 90 degrees of rotation.
Specifies 180 degrees of rotation.
Specifies 270 degrees of rotation.
Flags indicating how an image is stretched to fit a given monitor's resolution.
\t\nUnspecified scaling.
Specifies no scaling. The image is centered on the display. This flag is typically used for a fixed-dot-pitch display (such as an LED display).
Specifies stretched scaling.
Flags indicating the method the raster uses to create an image on a surface.
\t\nScanline order is unspecified.
The image is created from the first scanline to the last without skipping any.
The image is created beginning with the upper field.
The image is created beginning with the lower field.
Status codes that can be returned by DXGI functions.
\t\nResource data formats which includes fully-typed and typeless formats. There is a list of format modifiers at the bottom of the page, that more fully describes each format type.
\t\nA few formats have additional restrictions.
The following topics provide lists of the formats that particular hardware feature levels support:
For a list of the DirectXMath types that map to
Each enumeration value contains a format modifier which describes the data type.
| Format Modifiers | Description |
|---|---|
| _FLOAT | A floating-point value; 32-bit floating-point formats use IEEE 754 single-precision (s23e8 format): sign bit, 8-bit biased (127) exponent, and 23-bit mantissa. 16-bit floating-point formats use half-precision (s10e5 format): sign bit, 5-bit biased (15) exponent, and 10-bit mantissa. |
| _SINT | Two's complement signed integer. For example, a 3-bit SINT represents the values -4, -3, -2, -1, 0, 1, 2, 3. |
| _SNORM | Signed normalized integer; which is interpreted in a resource as a signed integer, and is interpreted in a shader as a signed normalized floating-point value in the range [-1, 1]. For an 2's complement number, the maximum value is 1.0f (a 5-bit value 01111 maps to 1.0f), and the minimum value is -1.0f (a 5-bit value 10000 maps to -1.0f). In addition, the second-minimum number maps to -1.0f (a 5-bit value 10001 maps to -1.0f). The resulting integer representations are evenly spaced floating-point values in the range (-1.0f...0.0f), and also a complementary set of representations for numbers in the range (0.0f...1.0f). |
| _SRGB | Standard RGB data, which roughly displays colors in a linear ramp of luminosity levels such that an average observer, under average viewing conditions, can view them on an average display. All 0's maps to 0.0f, and all 1's maps to 1.0f. The sequence of unsigned integer encodings between all 0's and all 1's represent a nonlinear progression in the floating-point interpretation of the numbers between 0.0f to 1.0f. For more detail, see the SRGB color standard, IEC 61996-2-1, at IEC (International Electrotechnical Commission). Conversion to or from sRGB space is automatically done by D3DX10 or D3DX9 texture-load functions. If the format has an alpha channel, the alpha data is also stored in sRGB color space. |
| _TYPELESS | Typeless data, with a defined number of bits. Typeless formats are designed for creating typeless resources; that is, a resource whose size is known, but whose data type is not yet fully defined. When a typeless resource is bound to a shader, the application or shader must resolve the format type (which must match the number of bits per component in the typeless format). A typeless format contains one or more subformats; each subformat resolves the data type. For example, in the R32G32B32 group, which defines types for three-component 96-bit data, there is one typeless format and three fully typed subformats. |
| _UINT | Unsigned integer. For instance, a 3-bit UINT represents the values 0, 1, 2, 3, 4, 5, 6, 7. |
| _UNORM | Unsigned normalized integer; which is interpreted in a resource as an unsigned integer, and is interpreted in a shader as an unsigned normalized floating-point value in the range [0, 1]. All 0's maps to 0.0f, and all 1's maps to 1.0f. A sequence of evenly spaced floating-point values from 0.0f to 1.0f are represented. For instance, a 2-bit UNORM represents 0.0f, 1/3, 2/3, and 1.0f. |
?
New Resource FormatsDirect3D 10 offers new data compression formats for compressing high-dynamic range (HDR) lighting data, normal maps and heightfields to a fraction of their original size. These compression types include:
The block compression formats can be used for any of the 2D or 3D texture types ( Texture2D, Texture2DArray, Texture3D, or TextureCube) including mipmap surfaces. The block compression techniques require texture dimensions to be a multiple of 4 (since the implementation compresses on blocks of 4x4 texels). In the texture sampler, compressed formats are always decompressed before texture filtering.
\t\nThe format is not known.
A four-component, 128-bit typeless format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit floating-point format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit unsigned-integer format that supports 32 bits per channel including alpha. 1
A four-component, 128-bit signed-integer format that supports 32 bits per channel including alpha. 1
A three-component, 96-bit typeless format that supports 32 bits per color channel.
A three-component, 96-bit floating-point format that supports 32 bits per color channel.
A three-component, 96-bit unsigned-integer format that supports 32 bits per color channel.
A three-component, 96-bit signed-integer format that supports 32 bits per color channel.
A four-component, 64-bit typeless format that supports 16 bits per channel including alpha.
A four-component, 64-bit floating-point format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit unsigned-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-normalized-integer format that supports 16 bits per channel including alpha.
A four-component, 64-bit signed-integer format that supports 16 bits per channel including alpha.
A two-component, 64-bit typeless format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit floating-point format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit unsigned-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit signed-integer format that supports 32 bits for the red channel and 32 bits for the green channel.
A two-component, 64-bit typeless format that supports 32 bits for the red channel, 8 bits for the green channel, and 24 bits are unused.
A 32-bit floating-point component, and two unsigned-integer components (with an additional 32 bits). This format supports 32-bit depth, 8-bit stencil, and 24 bits are unused.
A 32-bit floating-point component, and two typeless components (with an additional 32 bits). This format supports 32-bit red channel, 8 bits are unused, and 24 bits are unused.
A 32-bit typeless component, and two unsigned-integer components (with an additional 32 bits). This format has 32 bits unused, 8 bits for green channel, and 24 bits are unused.
A four-component, 32-bit typeless format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 10 bits for each color and 2 bits for alpha.
A four-component, 32-bit unsigned-integer format that supports 10 bits for each color and 2 bits for alpha.
Three partial-precision floating-point numbers encoded into a single 32-bit value (a variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There are no sign bits, and there is a 5-bit biased (15) exponent for each channel, 6-bit mantissa for R and G, and a 5-bit mantissa for B, as shown in the following illustration.
A four-component, 32-bit typeless format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-normalized integer sRGB format that supports 8 bits per channel including alpha.
A four-component, 32-bit unsigned-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-normalized-integer format that supports 8 bits per channel including alpha.
A four-component, 32-bit signed-integer format that supports 8 bits per channel including alpha.
A two-component, 32-bit typeless format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit floating-point format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit unsigned-normalized-integer format that supports 16 bits each for the green and red channels.
A two-component, 32-bit unsigned-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-normalized-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A two-component, 32-bit signed-integer format that supports 16 bits for the red channel and 16 bits for the green channel.
A single-component, 32-bit typeless format that supports 32 bits for the red channel.
A single-component, 32-bit floating-point format that supports 32 bits for depth.
A single-component, 32-bit floating-point format that supports 32 bits for the red channel.
A single-component, 32-bit unsigned-integer format that supports 32 bits for the red channel.
A single-component, 32-bit signed-integer format that supports 32 bits for the red channel.
A two-component, 32-bit typeless format that supports 24 bits for the red channel and 8 bits for the green channel.
A 32-bit z-buffer format that supports 24 bits for depth and 8 bits for stencil.
A 32-bit format, that contains a 24 bit, single-component, unsigned-normalized integer, with an additional typeless 8 bits. This format has 24 bits red channel and 8 bits unused.
A 32-bit format, that contains a 24 bit, single-component, typeless format, with an additional 8 bit unsigned integer component. This format has 24 bits unused and 8 bits green channel.
A two-component, 16-bit typeless format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit unsigned-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-normalized-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A two-component, 16-bit signed-integer format that supports 8 bits for the red channel and 8 bits for the green channel.
A single-component, 16-bit typeless format that supports 16 bits for the red channel.
A single-component, 16-bit floating-point format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for depth.
A single-component, 16-bit unsigned-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit unsigned-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-normalized-integer format that supports 16 bits for the red channel.
A single-component, 16-bit signed-integer format that supports 16 bits for the red channel.
A single-component, 8-bit typeless format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-normalized-integer format that supports 8 bits for the red channel.
A single-component, 8-bit signed-integer format that supports 8 bits for the red channel.
A single-component, 8-bit unsigned-normalized-integer format for alpha only.
A single-component, 1-bit unsigned-normalized integer format that supports 1 bit for the red channel. 2.
Three partial-precision floating-point numbers encoded into a single 32-bit value all sharing the same 5-bit exponent (variant of s10e5, which is sign bit, 10-bit mantissa, and 5-bit biased (15) exponent). There is no sign bit, and there is a shared 5-bit biased (15) exponent and a 9-bit mantissa for each channel, as shown in the following illustration. 2.
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the UYVY format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
A four-component, 32-bit unsigned-normalized-integer format. This packed RGB format is analogous to the YUY2 format. Each 32-bit block describes a pair of pixels: (R8, G8, B8) and (R8, G8, B8) where the R8/B8 values are repeated, and the G8 values are unique to each pixel. 3
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Four-component block-compression format for sRGB data. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
One-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component typeless block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Two-component block-compression format. For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A three-component, 16-bit unsigned-normalized-integer format that supports 5 bits for blue, 6 bits for green, and 5 bits for red.
A four-component, 16-bit unsigned-normalized-integer format that supports 5 bits for each color channel and 1-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8-bit alpha.
A four-component, 32-bit unsigned-normalized-integer format that supports 8 bits for each color channel and 8 bits unused.
A four-component, 32-bit 2.8-biased fixed-point format that supports 10 bits for each color channel and 2-bit alpha.
A four-component, 32-bit typeless format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each channel including alpha. 4
A four-component, 32-bit typeless format that supports 8 bits for each color channel, and 8 bits are unused. 4
A four-component, 32-bit unsigned-normalized standard RGB format that supports 8 bits for each color channel, and 8 bits are unused. 4
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A typeless block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
A block-compression format. 4 For information about block-compression formats, see Texture Block Compression in Direct3D 11.
Flags indicating the memory location of a resource.
\t\nThe resource is located in video memory.
At least some of the resource is located in CPU memory.
At least some of the resource has been paged out to the hard drive.
Options for handling pixels in a display surface after calling
This enumeration is used by the
This enumeration is also used by the DXGI_SWAP_CHAIN_DESC1 structure.
The primary difference between presentation models is how back-buffer contents get to the Desktop Window Manager (DWM) for composition. In the bitblt model, which is used with the
Regardless of whether the flip model is more efficient, an application still might choose the bitblt model for the following reasons:
The bitblt model is the only way to mix GDI and DirectX presentation.
In the flip model, the application must create the swap chain with
Options for swap-chain behavior.
\t\nThis enumeration is used by the
This enumeration is also used by the DXGI_SWAP_CHAIN_DESC1 structure.
Swap chains that you create in full-screen mode with the
Swap chains that you create with the IDXGIFactory2::CreateSwapChainForHwnd, IDXGIFactory2::CreateSwapChainForImmersiveWindow, and IDXGIFactory2::CreateSwapChainForCompositionSurface methods are not protected if DXGI_SWAP_CHAIN_FLAG_DISPLAY_ONLY is not set and are protected if DXGI_SWAP_CHAIN_FLAG_DISPLAY_ONLY is set. When swap chains are protected, screen scraping is prevented and, in full-screen mode, presented content is not accessible through the desktop duplication APIs.
\t\nSet this flag to turn off automatic image rotation; that is, do not perform a rotation when transferring the contents of the front buffer to the monitor. Use this flag to avoid a bandwidth penalty when an application expects to handle rotation. This option is valid only during full-screen mode.
Set this flag to enable an application to switch modes by calling
Set this flag to enable an application to render using GDI on a swap chain or a surface. This will allow the application to call
Creates a DXGI 1.1 factory that generates objects used to enumerate and specify video graphics settings.
\t\nThe globally unique identifier (
Address of a reference to an
Returns
Use a DXGI 1.1 factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the full-screen display mode.
If the CreateDXGIFactory1 function succeeds, the reference count on the
This entry point is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Note??Do not mix the use of DXGI 1.0 (
Creates a DXGI 1.0 factory that generates objects used to enumerate and specify video graphics settings.
\t\nThe globally unique identifier (
Address of a reference to an
Returns
Use a DXGI factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the fullscreen display mode.
If the CreateDXGIFactory function succeeds, the reference count on the
Note??Do not mix the use of DXGI 1.0 (
The CreateDXGIFactory function does not exist for Metro style apps. Instead, Metro style apps use the CreateDXGIFactory1 function.
\t\nThe
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
A display sub-system is often referred to as a video card, however, on some machines the display sub-system is part of the mother board.
To enumerate the display sub-systems, use
Gets a DXGI 1.1 description of an adapter (or video card).
\t\nA reference to a
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
Gets a DXGI 1.1 description of an adapter (or video card).
\t\nThis method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the
An
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
The
Sets the number of frames that the system is allowed to queue for rendering.
\t\nThe maximum number of back buffer frames that a driver can queue. The value defaults to 3, but can range from 1 to 16. A value of 0 will reset latency to the default. For multi-head devices, this value is specified per-head.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
\t\nGets the number of frames that the system is allowed to queue for rendering.
\t\nThis value is set to the number of frames that can be queued for render. This value defaults to 3, but can range from 1 to 16.
Returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
\t\nGets or sets the number of frames that the system is allowed to queue for rendering.
\t\nThis method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Frame latency is the number of frames that are allowed to be stored in a queue before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue. It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
\t\nUsing a key, acquires exclusive rendering access to a shared resource.
\t\nThe AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, acquires exclusive rendering access to a shared resource.
\t\nA value that indicates which device to give access to. This method will succeed when the device that currently owns the surface calls the
The time-out interval, in milliseconds. This method will return if the interval elapses, and the keyed mutex has not been released using the specified Key. If this value is set to zero, the AcquireSync method will test to see if the keyed mutex has been released and returns immediately. If this value is set to INFINITE, the time-out interval will never elapse.
Return
If the owning device attempted to create another keyed mutex on the same shared resource, AcquireSync returns E_FAIL.
AcquireSync can also return the following DWORD constants. Therefore, you should explicitly check for these constants. If you only use the SUCCEEDED macro on the return value to determine if AcquireSync succeeded, you will not catch these constants.
The AcquireSync method creates a lock to a surface that is shared between multiple devices, allowing only one device to render to a surface at a time. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
The AcquireSync method uses the key as follows, depending on the state of the surface:
Using a key, releases exclusive rendering access to a shared resource.
\t\nA value that indicates which device to give access to. This method succeeds when the device that currently owns the surface calls the ReleaseSync method using the same value. This value can be any UINT64 value.
Returns
If the device attempted to release a keyed mutex that is not valid or owned by the device, ReleaseSync returns E_FAIL.
The ReleaseSync method releases a lock to a surface that is shared between multiple devices. This method uses a key to determine which device currently has exclusive access to the surface.
When a surface is created using the
After you call the ReleaseSync method, the shared resource is unset from the rendering pipeline.
To acquire a reference to the keyed mutex object of a shared resource, call the QueryInterface method of the resource and pass in the UUID of the
An
To see the outputs available, use
Get a description of the output.
\t\nA reference to the output description (see
Returns a code that indicates success or failure.
[Starting with Direct3D 11.1, we recommend not to use GetDisplayModeList anymore to retrieve the matching display mode. Instead, use IDXGIOutput1::GetDisplayModeList1, which supports stereo display mode.]
Gets the display modes that match the requested format and other input options.
\t\nReturns one of the following DXGI_ERROR. It is rare, but possible, that the display modes available can change immediately after calling this method, in which case
In general, when switching from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth and refresh rate of the swap chain. To exercise more control over the display mode, use this API to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).
As shown, this API is designed to be called twice. First to get the number of modes available, and second to return a description of the modes.
UINT num = 0;\t\n format = ;\t\n UINT flags = ; pOutput->GetDisplayModeList( format, flags, &num, 0); ... * pDescs = new [num];\t\n pOutput->GetDisplayModeList( format, flags, &num, pDescs); [Starting with Direct3D 11.1, we recommend not to use FindClosestMatchingMode anymore to find the display mode that most closely matches the requested display mode. Instead, use IDXGIOutput1::FindClosestMatchingMode1, which supports stereo display mode.]
Finds the display mode that most closely matches the requested display mode.
\t\nReturns one of the following DXGI_ERROR.
FindClosestMatchingMode behaves similarly to the IDXGIOutput1::FindClosestMatchingMode1 except FindClosestMatchingMode considers only the mono display modes. IDXGIOutput1::FindClosestMatchingMode1 considers only stereo modes if you set the Stereo member in the DXGI_MODE_DESC1 structure that pModeToMatch points to, and considers only mono modes if Stereo is not set.
IDXGIOutput1::FindClosestMatchingMode1 returns a matched display-mode set with only stereo modes or only mono modes.\t\n FindClosestMatchingMode behaves as though you specified the input mode as mono.
\t\nHalt a thread until the next vertical blank occurs.
\t\nReturns one of the following DXGI_ERROR.
A vertical blank occurs when the raster moves from the lower right corner to the upper left corner to begin drawing the next frame.
\t\nTakes ownership of an output.
\t\nA reference to the
Set to TRUE to enable other threads or applications to take ownership of the device; otherwise, set to
Returns one of the DXGI_ERROR values.
When you are finished with the output, call
TakeOwnership should not be called directly by applications, since results will be unpredictable. It is called implicitly by the DXGI swap chain object during full-screen transitions, and should not be used as a substitute for swap-chain methods.
Notes for Metro style appsIf a Metro style app uses TakeOwnership, it fails with
Releases ownership of the output.
\t\nIf you are not using a swap chain, get access to an output by calling
Gets a description of the gamma-control capabilities.
\t\nA reference to a description of the gamma-control capabilities (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
\t\nSets the gamma controls.
\t\nA reference to an array of gamma controls (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
\t\nGets the gamma control settings.
\t\nAn array of gamma control settings (see
Returns one of the DXGI_ERROR values.
Note??Calling this method is only supported while in full-screen mode.
\t\nChanges the display mode.
\t\nA reference to a surface (see
Returns one of the DXGI_ERROR values.
This method should only be called between
If a Metro style app uses SetDisplaySurface, it fails with
[Starting with Direct3D 11.1, we recommend not to use GetDisplaySurfaceData anymore to retrieve the current display surface. Instead, use IDXGIOutput1::GetDisplaySurfaceData1, which supports stereo display mode.]
Gets a copy of the current display surface.
\t\nReturns one of the DXGI_ERROR values.
Use
Gets statistics about recently rendered frames.
\t\nA reference to frame statistics (see
If this function succeeds, it returns
This API is similar to
Note??Calling this method is only supported while in full-screen mode.
\t\n UINT num = 0;\t\n DXGI_FORMAT format = DXGI_FORMAT_R32G32B32A32_FLOAT;\t\n UINT flags = DXGI_ENUM_MODES_INTERLACED; pOutput->GetDisplayModeList( format, flags, &num, 0); ... DXGI_MODE_DESC * pDescs = new DXGI_MODE_DESC[num];\t\n pOutput->GetDisplayModeList( format, flags, &num, pDescs); \t\n \t\n \t\n Get a description of the output.
\t\nGets a description of the gamma-control capabilities.
\t\n
Note??Calling this method is only supported while in full-screen mode.
\t\nGets or sets the gamma control settings.
\t\n
Note??Calling this method is only supported while in full-screen mode.
\t\nGets statistics about recently rendered frames.
\t\nThis API is similar to
Note??Calling this method is only supported while in full-screen mode.
\t\nAn
To find out what type of memory a resource is currently located in, use
You can retrieve the
* pDXGIResource;\t\n hr = g_pd3dTexture2D->QueryInterface(__uuidof(), (void **)&pDXGIResource);\t\n [Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use IDXGIResource1::CreateSharedHandle to get a handle for sharing. To use IDXGIResource1::CreateSharedHandle, you must create the resource as shared and specify that it uses NT handles (that is, you set the D3D11_RESOURCE_MISC_SHARED_NTHANDLE flag). We also recommend that you create shared resources that use NT handles so you can use CloseHandle, DuplicateHandle, and so on on those shared resources.]
Gets the handle to a shared resource.
\t\nReturns one of the DXGI_ERROR values.
You can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
\t\nGet the expected resource usage.
\t\nA reference to a usage flag (see DXGI_USAGE). For Direct3D 10, a surface can be used as a shader input or a render-target output.
Returns one of the following DXGI_ERROR.
Set the priority for evicting the resource from memory.
\t\nThe priority is one of the following values:
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI for determining how to populate overcommitted memory.
You can set priority levels other than the defined values when appropriate. For example, you can set a resource with a priority level of 0x78000001 to indicate that the resource is slightly above normal.
\t\nGet the eviction priority.
\t\nA reference to the eviction priority, which determines when a resource can be evicted from memory.
The following defined values are possible.
| Value | Meaning |
|---|---|
| The resource is unused and can be evicted as soon as another resource requires the memory that the resource occupies. |
| The eviction priority of the resource is low. The placement of the resource is not critical, and minimal work is performed to find a location for the resource. For example, if a GPU can render with a vertex buffer from either local or non-local memory with little difference in performance, that vertex buffer is low priority. Other more critical resources (for example, a render target or texture) can then occupy the faster memory. |
| The eviction priority of the resource is normal. The placement of the resource is important, but not critical, for performance. The resource is placed in its preferred location instead of a low-priority resource. |
| The eviction priority of the resource is high. The resource is placed in its preferred location instead of a low-priority or normal-priority resource. |
| The resource is evicted from memory only if there is no other way of resolving the memory requirement. |
?
Returns one of the following DXGI_ERROR.
The eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
\t\n[Starting with Direct3D 11.1, we recommend not to use GetSharedHandle anymore to retrieve the handle to a shared resource. Instead, use IDXGIResource1::CreateSharedHandle to get a handle for sharing. To use IDXGIResource1::CreateSharedHandle, you must create the resource as shared and specify that it uses NT handles (that is, you set the D3D11_RESOURCE_MISC_SHARED_NTHANDLE flag). We also recommend that you create shared resources that use NT handles so you can use CloseHandle, DuplicateHandle, and so on on those shared resources.]
Gets the handle to a shared resource.
\t\nYou can pass the handle that GetSharedHandle returns in a call to the
GetSharedHandle doesn't always return a handle. GetSharedHandle only returns the handle when you created the resource as shared (that is, you set the
The handle that GetSharedHandle returns is not an NT handle. Therefore, don't use the handle with CloseHandle, DuplicateHandle, and so on. The creator of a shared resource must not destroy the resource until all entities that opened the resource have destroyed the resource. The validity of the handle is tied to the lifetime of the underlying video memory. If no resource objects exist on any devices that refer to this resource, the handle is no longer valid. To extend the lifetime of the handle and video memory, you must open the shared resource on a device.
\t\nGet the expected resource usage.
\t\nGet or sets the eviction priority.
\t\nThe eviction priority is a memory-management variable that is used by DXGI to determine how to manage overcommitted memory.
Priority levels other than the defined values are used when appropriate. For example, a resource with a priority level of 0x78000001 indicates that the resource is slightly above normal.
\t\nThe
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
The runtime automatically creates an
Get a description of the surface.
\t\nA reference to the surface description (see
Returns
Get a reference to the data contained in the surface, and deny GPU access to the surface.
\t\nA reference to the surface data (see
CPU read-write flags. These flags can be combined with a logical OR.
Returns
Use
Invalidate the reference to the surface retrieved by
Returns
Get a description of the surface.
\t\nThe
This interface is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
An image-data object is a 2D section of memory, commonly called a surface. To get the surface from an output, call
Any object that supports
The runtime automatically creates an
Returns a device context (DC) that allows you to render to a Microsoft DirectX Graphics Infrastructure (DXGI) surface using Windows Graphics Device Interface (GDI).
\t\nA Boolean value that specifies whether to preserve Direct3D contents in the GDI DC. TRUE directs the runtime not to preserve Direct3D contents in the GDI DC; that is, the runtime discards the Direct3D contents.
A reference to an
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
After you use the GetDC method to retrieve a DC, you can render to the DXGI surface by using GDI. The GetDC method readies the surface for GDI rendering and allows inter-operation between DXGI and GDI technologies.
Keep the following in mind when using this method:
You can also call GetDC on the back buffer at index 0 of a swap chain by obtaining an
* g_pSwapChain = null ;\t\n * g_pSurface1 = null ;\t\n ...\t\n //Setup the device and and swapchain\t\n g_pSwapChain->GetBuffer(0, __uuidof(), (void**) &g_pSurface1);\t\n g_pSurface1->GetDC( , &g_hDC );\t\n ... \t\n //Draw on the DC using GDI\t\n ...\t\n //When finish drawing release the DC\t\n g_pSurface1->ReleaseDC( null ); Releases the GDI device context (DC) that is associated with the current surface and allows you to use Direct3D to render.
\t\nA reference to a
You can pass a reference to an empty
If this method succeeds, it returns
This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).
Use the ReleaseDC method to release the DC and indicate that your application finished all GDI rendering to this surface. You must call the ReleaseDC method before you can use Direct3D to perform additional rendering.
Prior to resizing buffers you must release all outstanding DCs.
\t\nAn
You can create a swap chain in several ways. If your application uses Direct3D, create a swap chain when you create a device by \t\n calling
[Starting with Direct3D 11.1, we recommend not to use Present anymore to present a rendered image. Instead, use IDXGISwapChain1::Present1.]
Presents a rendered image to the user.
\t\nPossible return values include:
Note??The Present method can return either
For the best performance when flipping swap-chain buffers in a full-screen application, see Full-Screen Application Performance Hints.
Because calling Present might cause the render thread to wait on the message-pump thread, be careful when calling this method in an application that uses multiple threads. For more details, see Multithreading Considerations.
| Differences between Direct3D 9 and Direct3D 10: Specifying |
?
For flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set, a successful presentation unbinds back buffer 0 from the graphics pipeline, except for when you pass the
Suppose the following frames with sync-interval values are queued from oldest (A) to newest (E) before you call Present.
A: 3, B: 0, C: 0, D: 1, E: 0
When you call Present, the runtime shows frame A for 3 vertical blank intervals, then frame D for 1 vertical blank interval, and then frame E until you submit a new presentation. The runtime discards frames C and D.
\t\nAccesses one of the swap-chain's back buffers.
\t\nA zero-based buffer index.
If the swap chain's swap effect is
If the swap chain's swap effect is either
The type of interface used to manipulate the buffer. See remarks.
A reference to a back-buffer interface.
Returns one of the following DXGI_ERROR.
Sets the display state to windowed or full screen.
\t\nA Boolean value that specifies whether to set the display state to windowed or full screen. TRUE for full screen, and
If you pass TRUE to the Fullscreen parameter to set the display state to full screen, you can optionally set this parameter to a reference to an
This methods returns:
When this error is returned, an application can continue to run in windowed mode and try to switch to full-screen mode later.
DXGI may change the display state of a swap chain in response to end user or system requests.
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through SetFullscreenState; that is, do not set the Windowed member of
If a Metro style app calls SetFullscreenState to set the display state to full screen, SetFullscreenState fails with
You cannot call SetFullscreenState on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
For the flip presentation model, after you transition the display state to full screen, you must call ResizeBuffers to ensure that your call to IDXGISwapChain1::Present1 succeeds.
\t\nGet the state associated with full-screen mode.
\t\nA reference to a boolean whose value is either:
A reference to the output target (see
Returns one of the following DXGI_ERROR.
When the swap chain is in full-screen mode, a reference to the target output will be returned and its reference count will be incremented.
\t\n[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use IDXGISwapChain1::GetDesc1.]
Get a description of the swap chain.
\t\nReturns one of the following DXGI_ERROR.
Changes the swap chain's back buffer size, format, and number of buffers. This should be called when the application window is resized.
\t\nThe number of buffers in the swap chain (including all back and front buffers). This number can be different from the number of buffers with which you created the swap chain. This number can't be greater than DXGI_MAX_SWAP_CHAIN_BUFFERS. Set this number to zero to preserve the existing number of buffers in the swap chain. You can't specify greater than two buffers for the flip presentation model.
New width of the back buffer. If you specify zero, DXGI will use the width of the client area of the target window. You can't specify the width as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
New height of the back buffer. If you specify zero, DXGI will use the height of the client area of the target window. You can't specify the height as zero if you called the IDXGIFactory2::CreateSwapChainForCompositionSurface method to create the swap chain for a composition surface.
A
A combination of
Returns
You can't resize a swap chain unless you release all outstanding references to its back buffers. You must release all of its direct and indirect references on the back buffers in order for ResizeBuffers to succeed.
Direct references are held by the application after it calls AddRef on a resource.
Indirect references are held by views to a resource, binding a view of the resource to a device context, a command list that used the resource, a command list that used a view to that resource, a command list that executed another command list that used the resource, and so on.
Before you call ResizeBuffers, ensure that the application releases all references (by calling the appropriate number of Release invocations) on the resources, any views to the resource, and any command lists that use either the resources or views, and ensure that neither the resource nor a view is still bound to a device context. You can use
For swap chains that you created with
We recommend that you call ResizeBuffers when a client window is resized (that is, when an application receives a WM_SIZE message).
The only difference between ResizeBuffers in Windows Developer Preview and ResizeBuffers in Windows?7 is with flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set. In Windows Developer Preview, you must call ResizeBuffers to realize a transition between full-screen mode and windowed mode; otherwise, your next call to the Present method fails.
\t\nResizes the output target.
\t\nA reference to a
Returns a code that indicates success or failure.
ResizeTarget resizes the target window when the swap chain is in windowed mode, and changes the display mode on the target output when the swap chain is in full-screen mode. Therefore, applications can call ResizeTarget to resize the target window (rather than a Microsoft Win32API such as SetWindowPos) without knowledge of the swap chain display mode.
If a Metro style app calls ResizeTarget, it fails with
You cannot call ResizeTarget on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
\t\nGet the output (the display monitor) that contains the majority of the client area of the target window.
\t\nA reference to the output interface (see
Returns one of the following DXGI_ERROR.
If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
\t\nGets performance statistics about the last render frame.
\t\nA reference to a
Returns one of the DXGI_ERROR values.
You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of the DXGI_SWAP_CHAIN_DESC1 structure to specify that the swap chain uses the flip presentation model.
\t\nGets the number of times that
Returns one of the DXGI_ERROR values.
For info about presentation statistics for a frame, see
[Starting with Direct3D 11.1, we recommend not to use GetDesc anymore to get a description of the swap chain. Instead, use IDXGISwapChain1::GetDesc1.]
Get a description of the swap chain.
\t\nGet the output (the display monitor) that contains the majority of the client area of the target window.
\t\nIf the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.
The output is also owned by the adapter on which the swap chain's device was created.
You cannot call GetContainingOutput on a windowless swap chain that you created with IDXGIFactory2::CreateSwapChainForCompositionSurface.
\t\nGets performance statistics about the last render frame.
\t\nYou cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.
You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of the DXGI_SWAP_CHAIN_DESC1 structure to specify that the swap chain uses the flip presentation model.
\t\nGets the number of times that
For info about presentation statistics for a frame, see
Describes an adapter (or video card) by using DXGI 1.0.
\t\nThe
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
Describes an adapter (or video card) using DXGI 1.1.
\t\nThe
A string that contains the adapter description.
The PCI ID of the hardware vendor.
The PCI ID of the hardware device.
The PCI ID of the sub system.
The PCI ID of the revision number of the adapter.
The number of bytes of dedicated video memory that are not shared with the CPU.
The number of bytes of dedicated system memory that are not shared with the CPU. This memory is allocated from available system memory at boot time.
The number of bytes of shared system memory. This is the maximum value of system memory that may be consumed by the adapter during operation. Any incidental memory consumed by the driver as it manages and uses video memory is additional.
A unique value that identifies the adapter. See
A value of the
Describes timing and presentation statistics for a frame.
\t\nYou initialize the
You can only use
The values in the PresentCount and PresentRefreshCount members indicate information about when a frame was presented on the display screen. You can use these values to determine whether a glitch occurred. The values in the SyncRefreshCount and SyncQPCTime members indicate timing information that you can use for audio and video synchronization or very precise animation. If the swap chain draws in full-screen mode, these values are based on when the computer booted. \t\n If the swap chain draws in windowed mode, these values are based on when the swap chain is created.
\t\nA value that represents the running total count of times that an image was presented to the monitor since the computer booted.
Note??The number of times that an image was presented to the monitor is not necessarily the same as the number of times that you called
A value that represents the running total count of v-blanks at which the last image was presented to the monitor and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the running total count of v-blanks when the scheduler last sampled the machine time by calling QueryPerformanceCounter and that have happened since the computer booted (for windowed mode, since the swap chain was created).
A value that represents the high-resolution performance counter timer. This value is the same as the value returned by the QueryPerformanceCounter function.
Reserved. Always returns 0.
Controls the settings of a gamma curve.
\t\nThe
A
A
An array of
Controls the gamma capabilities of an adapter.
\t\nTo get a list of the capabilities for controlling gamma correction, call
True if scaling and offset operations are supported during gamma correction; otherwise, false.
A value describing the maximum range of the control-point positions.
A value describing the minimum range of the control-point positions.
A value describing the number of control points in the array.
An array of values describing control points; the maximum length of control points is 1025.
Describes a mapped rectangle that is used to access a surface.
\t\nThe
A value that describes the width, in bytes, of the surface.
A reference to the image buffer of the surface.
Describes a display mode.
\t\nThe following format values are valid for display modes and when you create a bit-block transfer (bitblt) model swap chain. The valid values depend on the feature level that you are working with.
Feature level >= 9.1
Feature level >= 10.0
Feature level >= 11.0
You can pass one of these format values to
Starting with Windows Developer Preview for a flip model swap chain (that is, a swap chain that has the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set in the SwapEffect member of
Because of the relaxed render target creation rules that Direct3D 11 has for back buffers, applications can create a
A value that describes the resolution width. If you specify the width as zero when you call the
A value describing the resolution height. If you specify the height as zero when you call the
A
A
A member of the
A member of the
Describes an output or physical connection between the adapter (video card) and a device.
\t\nThe
A string that contains the name of the output device.
A
True if the output is attached to the desktop; otherwise, false.
A member of the
An
Represents a rational number.
\t\nThe
An unsigned integer value representing the top of the rational number.
An unsigned integer value representing the bottom of the rational number.
Describes multi-sampling parameters for a resource.
\t\nThe default sampler mode, with no anti-aliasing, has a count of 1 and a quality level of 0.
If multi-sample antialiasing is being used, all bound render targets and depth buffers must have the same sample counts and quality levels.
| Differences between Direct3D 10.0 and Direct3D 10.1 and between Direct3D 10.0 and Direct3D 11: Direct3D 10.1 has defined two standard quality levels: Direct3D 11 has defined two standard quality levels: |
?
\t\nThe number of multisamples per pixel.
The image quality level. The higher the quality, the lower the performance. The valid range is between zero and one less than the level returned by
For Direct3D 10.1 and Direct3D 11, you can use two special quality level values. For more information about these quality level values, see Remarks.
Represents a handle to a shared resource.
\t\nTo create a shared surface, pass a shared-resource handle into the
A handle to a shared resource.
Describes a surface.
\t\nA value describing the surface width.
A value describing the surface height.
A member of the
A member of the
Describes a swap chain.
\t\nIn full-screen mode, there is a dedicated front buffer; in windowed mode, the desktop is the front buffer.
If you create a swap chain with one buffer, specifying
For performance information about flipping swap-chain buffers in full-screen application, see Full-Screen Application Performance Hints.
\t\nA
A
A member of the DXGI_USAGE enumerated type that describes the surface usage and CPU access options for the back buffer. The back buffer can be used for shader input or render-target output.
A value that describes the number of buffers in the swap chain. When you call
An
A Boolean value that specifies whether the output is in windowed mode. TRUE if the output is in windowed mode; otherwise,
We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through
For more information about choosing windowed verses full screen, see
A member of the
A member of the
Contains the content bounds, mask information, opacity settings, and other options for a layer resource.
\t\nThe content bounds of the layer. Content outside these bounds is not guaranteed to render.
The geometric mask specifies the area of the layer that is composited into the render target.
A value that specifies the antialiasing mode for the geometricMask.
A value that specifies the transform that is applied to the geometric mask when composing the layer.
An opacity value that is applied uniformly to all resources in the layer when compositing to the target.
A brush that is used to modify the opacity of the layer. The brush \t\n is mapped to the layer, and the alpha channel of each mapped brush pixel is multiplied against the corresponding layer pixel.
A value that specifies whether the layer intends to render text with ClearType antialiasing.
Specifies the identifiers of the metadata items in an 8BIM IPTC digest metadata block.
\t\n[VT_LPSTR] A name that identifies the 8BIM block.
[VT_BLOB] The embedded IPTC digest value.
Specifies the identifiers of the metadata items in an 8BIM IPTC block.
\t\n[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UNKNOWN] The IPTC block embedded in this 8BIM IPTC block.
Specifies the identifiers of the metadata items in an 8BIMResolutionInfo block.
\t\n[VT_LPSTR] A name that identifies the 8BIM block.
[VT_UI4] The horizontal resolution of the image.
[VT_UI2] The units that the horizontal resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image width is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
[VT_UI4] The vertical resolution of the image.
[VT_UI2] The units that the vertical resolution is specified in; a 1 indicates pixels per inch and a 2 indicates pixels per centimeter.
[VT_UI2] The units that the image height is specified in; a 1 indicates inches, a 2 indicates centimeters, a 3 indicates points, a 4 specifies picas, and a 5 specifies columns.
Specifies the desired alpha channel usage.
\t\nUse alpha channel.
Use a pre-multiplied alpha channel.
Ignore alpha channel.
Specifies the desired cache usage.
\t\nThe CreateBitmap of the
Do not cache the bitmap.
Cache the bitmap when needed.
Cache the bitmap at initialization.
Specifies the capabilities of the decoder.
\t\nDecoder recognizes the image was encoded with an encoder produced by the same vendor.
Decoder can decode all the images within an image container.
Decoder can decode some of the images within an image container.
Decoder can enumerate the metadata blocks within a container format.
Decoder can find and decode a thumbnail.
Specifies the type of dither algorithm to apply when converting between image formats.
\t\nA solid color algorithm without dither.
A solid color algorithm without dither.
A 4x4 ordered dither algorithm.
An 8x8 ordered dither algorithm.
A 16x16 ordered dither algorithm.
A 4x4 spiral dither algorithm.
An 8x8 spiral dither algorithm.
A 4x4 dual spiral dither algorithm.
An 8x8 dual spiral dither algorithm.
An error diffusion algorithm.
Specifies the cache options available for an encoder.
\t\nThe encoder is cached in memory. This option is not supported.
The encoder is cached to a temporary file. This option is not supported.
The encoder is not cached.
Specifies the sampling or filtering mode to use when scaling an image.
\t\nA nearest neighbor interpolation algorithm. Also known as nearest pixel or point interpolation.
The output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered.
A bilinear interpolation algorithm.
The output pixel values are computed as a weighted average of the nearest four pixels in a 2x2 grid.
A bicubic interpolation algorithm.
Destination pixel values are computed as a weighted average of the nearest sixteen pixels in a 4x4 grid.
A Fant resampling algorithm.
Destination pixel values are computed as a weighted average of the all the pixels that map to the new pixel.
Specifies access to an
Specifies the type of palette used for an indexed image format.
\t\nAn arbitrary custom palette provided by caller.
An optimal palette generated using a median-cut algorithm. Derived from the colors in an image.
A black and white palette.
A palette that has its 8-color on-off primaries and the 16 system colors added. With duplicates removed, 16 colors are available.
A palette that has 3 intensity levels of each primary: 27-color on-off primaries and the 16 system colors added. With duplicates removed, 35 colors are available.
A palette that has 4 intensity levels of each primary: 64-color on-off primaries and the 16 system colors added. With duplicates removed, 72 colors are available.
A palette that has 5 intensity levels of each primary: 125-color on-off primaries and the 16 system colors added. With duplicates removed, 133 colors are available.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as WICBitmapPaletteFixedHalftoneWeb.
A palette that has 6 intensity levels of each primary: 216-color on-off primaries and the 16 system colors added. With duplicates removed, 224 colors are available. This is the same as
A palette that has its 252-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has its 256-color on-off primaries and the 16 system colors added. With duplicates removed, 256 colors are available.
A palette that has 4 shades of gray.
A palette that has 16 shades of gray.
A palette that has 256 shades of gray.
Specifies the flip and rotation transforms.
\t\nA rotation of 0 degrees.
A clockwise rotation of 90 degrees.
A clockwise rotation of 180 degrees.
A clockwise rotation of 270 degrees.
A horizontal flip. Pixels are flipped around the vertical y-axis.
A vertical flip. Pixels are flipped around the horizontal x-axis.
Specifies the color context types.
\t\nAn uninitialized color context.
A color context profile.
An EXIF color space color context.
Specifies component enumeration options.
\t\nEnumerate signed components.
Force a read of the registry when enumerating components.
Enumerate disabled components.
Enumerate unsigned components.
Enumerate only built in components.
Specifies the component signing status.
\t\nA signed component.
An unsigned component
A component is safe.
Components that do not have a binary component to sign, such as a pixel format, should return this value.
A component has been disabled.
Specifies the type of Windows Imaging Component (WIC) component.
\t\nA WIC decoder.
A WIC encoder.
A WIC pixel converter.
A WIC metadata reader.
A WIC metadata writer.
A WIC pixel format.
All WIC components.
Specifies decode options.
\t\nCache metadata when needed.
Cache metadata when decoder is loaded.
Specifies the application extension metadata properties for a Graphics Interchange Format (GIF) image.
\t\n[VT_UI1 | VT_VECTOR] Indicates a string that identifies the application.
[VT_UI1 | VT_VECTOR] Indicates data that is exposed by the application.
Specifies the comment extension metadata properties for a Graphics Interchange Format (GIF) image.
\t\n[VT_LPSTR] Indicates the comment text.
Specifies the graphic control extension metadata properties that define the transitions between each frame animation for Graphics Interchange Format (GIF) images.
\t\n[VT_UI1] Indicates the disposal requirements. 0 - no disposal, 1 - do not dispose, 2 - restore to background color, 3 - restore to previous.
[VT_BOOL] Indicates the user input flag. TRUE if user input should advance to the next frame; otherwise,
[VT_BOOL] Indicates the transparency flag. TRUE if a transparent color in is in the color table for this frame; otherwise,
[VT_UI2] Indicates how long to display the next frame before advancing to the next frame, in units of 1/100th of a second.
[VT_UI1] Indicates which color in the palette should be treated as transparent.
Specifies the image descriptor metadata properties for Graphics Interchange Format (GIF) frames.
\t\n[VT_UI2] Indicates the X offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates the Y offset at which to locate this frame within the logical screen.
[VT_UI2] Indicates width of this frame, in pixels.
[VT_UI2] Indicates height of this frame, in pixels.
[VT_BOOL] Indicates the local color table flag. TRUE if global color table is present; otherwise,
[VT_BOOL] Indicates the interlace flag. TRUE if image is interlaced; otherwise,
[VT_BOOL] Indicates the sorted color table flag. TRUE if the color table is sorted from most frequently to least frequently used color; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
Specifies the logical screen descriptor properties for Graphics Interchange Format (GIF) metadata.
\t\n[VT_UI1 | VT_VECTOR] Indicates the signature property.
[VT_UI2] Indicates the width in pixels.
[VT_UI2] Indicates the height in pixels.
[VT_BOOL] Indicates the global color table flag. TRUE if a global color table is present; otherwise,
[VT_UI1] Indicates the color resolution in bits per pixel.
[VT_BOOL] Indicates the sorted color table flag. TRUE if the table is sorted; otherwise,
[VT_UI1] Indicates the value used to calculate the number of bytes contained in the global color table.
To calculate the actual size of the color table, raise 2 to the value of the field + 1.
[VT_UI1] Indicates the index within the color table to use for the background (pixels not defined in the image).
[VT_UI1] Indicates the factor used to compute an approximation of the aspect ratio.
Specifies the JPEG comment properties.
\t\nIndicates the metadata property is comment text.
Specifies the JPEG chrominance table property.
\t\n[VT_UI2|VT_VECTOR] Indicates the metadata property is a chrominance table.
Specifies the JPEG luminance table property.
\t\n[VT_UI2|VT_VECTOR] Indicates the metadata property is a luminance table.
Specifies the JPEG YCrCB subsampling options.
\t\nThe native JPEG encoder uses
The default subsampling option.
Subsampling option that uses both horizontal and vertical decimation.
Subsampling option that uses horizontal decimation .
Subsampling option that uses no decimation.
Specifies named white balances for raw images.
\t\nThe default white balance.
A daylight white balance.
A cloudy white balance.
A shade white balance.
A tungsten white balance.
A fluorescent white balance.
Daylight white balance.
A flash white balance.
A custom white balance. This is typically used when using a picture (grey-card) as white balance.
An automatic balance.
An \"as shot\" white balance.
Specifies the Portable Network Graphics (PNG) background (bKGD) chunk metadata properties.
\t\nIndicates the background color. There are three possible types, depending on the image's pixel format.
Specifies the index of the background color in an image with an indexed pixel format.
Specifies the background color in a grayscale image.
Specifies the background color in an RGB image as three USHORT values: {0xRRRR, 0xGGGG, 0xBBBB}.
Specifies the Portable Network Graphics (PNG) filters available for compression optimization.
\t\nIndicates an unspecified PNG filter. This enables WIC to algorithmically choose the best filtering option for the image.
Indicates no PNG filter.
Indicates a PNG sub filter.
Indicates a PNG up filter.
Indicates a PNG average filter.
Indicates a PNG paeth filter.
Indicates a PNG adaptive filter. This enables WIC to choose the best filtering mode on a per-scanline basis.
Specifies the Portable Network Graphics (PNG) gAMA chunk metadata properties.
\t\n[VT_UI4] Indicates the gamma value.
Specifies the Portable Network Graphics (PNG) hIST chunk metadata properties.
\t\n[VT_VECTOR | VT_UI2] Indicates the approximate usage frequency of each color in the color palette.
Specifies the Portable Network Graphics (PNG) cHRM chunk metadata properties for CIE XYZ chromaticity.
\t\n[VT_UI4] Indicates the whitepoint x value ratio.
[VT_UI4] Indicates the whitepoint y value ratio.
[VT_UI4] Indicates the red x value ratio.
[VT_UI4] Indicates the red y value ratio.
[VT_UI4] Indicates the green x value ratio.
[VT_UI4] Indicates the green y value ratio.
[VT_UI4] Indicates the blue x value ratio.
[VT_UI4] Indicates the blue y value ratio.
Specifies the Portable Network Graphics (PNG) iCCP chunk metadata properties.
\t\n[VT_LPSTR] Indicates the International Color Consortium (ICC) profile name.
[VT_VECTOR | VT_UI1] Indicates the embedded ICC profile.
Specifies the Portable Network Graphics (PNG) iTXT chunk metadata properties.
\t\n[VT_LPSTR] Indicates the keywords in the iTXT metadata chunk.
[VT_UI1] Indicates whether the text in the iTXT chunk is compressed. 1 if the text is compressed; otherwise, 0.
[VT_LPSTR] Indicates the human language used by the translated keyword and the text.
[VT_LPWSTR] Indicates a translation of the keyword into the language indicated by the language tag.
[VT_LPWSTR] Indicates additional text in the iTXT metadata chunk.
Specifies the Portable Network Graphics (PNG) sRGB chunk metadata properties.
\t\n[VT_UI1] Indicates the rendering intent for an sRGB color space image. The rendering intents have the following meaning.
| Value | Meaning |
|---|---|
| 0 | Perceptual |
| 1 | Relative colorimetric |
| 2 | Saturation |
| 3 | Absolute colorimetric |
?
Specifies the Portable Network Graphics (PNG) tIME chunk metadata properties.
\t\n[VT_UI2] Indicates the year of the last modification.
[VT_UI1] Indicates the month of the last modification.
[VT_UI1] Indicates day of the last modification.
[VT_UI1] Indicates the hour of the last modification.
[VT_UI1] Indicates the minute of the last modification.
[VT_UI1] Indicates the second of the last modification.
Specifies when the progress notification callback should be called.
\t\nThe callback should be called when codec operations begin.
The callback should be called when codec operations end.
The callback should be called frequently to report status.
The callback should be called on all available progress notifications.
Specifies the progress operations to receive notifications for.
\t\nReceive copy pixel operation.
Receive write pixel operation.
Receive all progress operations available.
Specifies the capability support of a raw image.
\t\nThe capability is not supported.
The capability supports only get operations.
The capability supports get and set operations.
Specifies the parameter set used by a raw codec.
\t\nAn as shot parameter set.
A user adjusted parameter set.
A codec adjusted parameter set.
Specifies the render intent of the next CopyPixels call.
\t\nSpecifies the rotation capabilities of the codec.
\t\nRotation is not supported.
Set operations for rotation is not supported.
90 degree rotations are supported.
All rotation angles are supported.
Specifies the access level of a Windows Graphics Device Interface (GDI) section.
\t\nIndicates a read only access level.
Indicates a read/write access level.
Specifies the Tagged Image File Format (TIFF) compression options.
\t\nIndicates a suitable compression algorithm based on the image and pixel format.
Indicates no compression.
Indicates a CCITT3 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a CCITT4 compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a LZW compression algorithm.
Indicates a RLE compression algorithm. This algorithm is only valid for 1bpp pixel formats.
Indicates a ZIP compression algorithm.
Indicates an LZWH differencing algorithm.
Defines methods that add the concept of writeability and static in-memory representations of bitmaps to
Because of to the internal memory representation implied by the
Exposes methods that refers to a source from which pixels are retrieved, but cannot be written back to.
\t\nThis interface provides a common way of accessing and linking together bitmaps, decoders, format converters, and scalers. Components that implement this interface can be connected together in a graph to pull imaging data through.
This interface defines only the notion of readability or being able to produce pixels. Modifying or writing to a bitmap is considered to be a specialization specific to bitmaps which have storage and is defined in the descendant interface
Retrieves the pixel width and height of the bitmap.
\t\nA reference that receives the pixel width of the bitmap.
A reference that receives the pixel height of the bitmap
If this method succeeds, it returns
Retrieves the pixel format of the bitmap source..
\t\nReceives the pixel format
If this method succeeds, it returns
The pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
\t\nRetrieves the sampling rate between pixels and physical world measurements.
\t\nA reference that receives the x-axis dpi resolution.
A reference that receives the y-axis dpi resolution.
If this method succeeds, it returns
Some formats, such as GIF and ICO, do not have full DPI support. For GIF, this method calculates the DPI values from the aspect ratio, using a base DPI of (96.0, 96.0). The ICO format does not support DPI at all, and the method always returns (96.0,96.0) for ICO images.
Additionally, WIC itself does not transform images based on the DPI values in an image. It is up to the caller to transform an image based on the resolution returned.
\t\nRetrieves the color table for indexed pixel formats.
\t\nAn
Returns one of the following values.
| Return code | Description |
|---|---|
| | The palette was unavailable. |
| | The palette was successfully copied. |
?
If the
Instructs the object to produce pixels.
\t\nThe rectangle to copy. A
The stride of the bitmap
The size of the buffer.
A reference to the buffer.
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
\t\nInstructs the object to produce pixels.
\t\nThe rectangle to copy. A
The stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
\t\nInstructs the object to produce pixels.
\t\nThe stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
\t\nInstructs the object to produce pixels.
\t\nThe stride of the bitmap
A reference to the buffer.
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
\t\nInstructs the object to produce pixels.
\t\nThe rectangle to copy. A
If this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
\t\nInstructs the object to produce pixels.
\t\nIf this method succeeds, it returns
CopyPixels is one of the two main image processing routines (the other being Lock) triggering the actual processing. It instructs the object to produce pixels according to its algorithm - this may involve decoding a portion of a JPEG stored on disk, copying a block of memory, or even analytically computing a complex gradient. The algorithm is completely dependent on the object implementing the interface.
The caller can restrict the operation to a rectangle of interest (ROI) using the prc parameter. The ROI sub-rectangle must be fully contained in the bounds of the bitmap. Specifying a
The caller controls the memory management and must provide an output buffer (pbBuffer) for the results of the copy along with the buffer's bounds (cbBufferSize). The cbStride parameter defines the count of bytes between two vertically adjacent pixels in the output buffer. The caller must ensure that there is sufficient buffer to complete the call based on the width, height and pixel format of the bitmap and the sub-rectangle provided to the copy method.
If the caller needs to perform numerous copies of an expensive
The callee must only write to the first (prc->Width*bitsperpixel+7)/8 bytes of each line of the output buffer (in this case, a line is a consecutive string of cbStride bytes).
\t\nRetrieves the pixel format of the bitmap source..
\t\nThe pixel format returned by this method is not necessarily the pixel format the image is stored as. The codec may perform a format conversion from the storage pixel format to an output pixel format.
\t\nRetrieves the pixel width and height of the bitmap.
\t\nProvides access to a rectangular area of the bitmap.
\t\nThe rectangle to be accessed.
The access mode you wish to obtain for the lock. This is a bitwise combination of
| Value | Meaning |
|---|---|
| The read access lock. | |
| The write access lock. |
?
A reference that receives the locked memory location.
Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the
Provides access for palette modifications.
\t\nThe palette to use for conversion.
If this method succeeds, it returns
Changes the physical resolution of the image.
\t\nThe horizontal resolution.
The vertical resolution.
If this method succeeds, it returns
This method has no effect on the actual pixels or samples stored in the bitmap. Instead the interpretation of the sampling rate is modified. This means that a 96 DPI image which is 96 pixels wide is one inch. If the physical resolution is modified to 48 DPI, then the bitmap is considered to be 2 inches wide but has the same number of pixels. If the resolution is less than REAL_EPSILON (1.192092896e-07F) the error code
Provides access for palette modifications.
\t\nExposes methods that produce a clipped version of the input bitmap for a specified rectangular region of interest.
\t\nInitializes the bitmap clipper with the provided parameters.
\t\nhe input bitmap source.
The rectangle of the bitmap source to clip.
If this method succeeds, it returns
Exposes methods that provide information about a particular codec.
\t\nExposes methods that provide component information.
\t\nRetrieves the component's
If this method succeeds, it returns
Retrieves the component's class identifier (CLSID)
\t\nA reference that receives the component's CLSID.
If this method succeeds, it returns
Retrieves the signing status of the component.
\t\nA reference that receives the
If this method succeeds, it returns
Signing is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
\t\nRetrieves the name of component's author.
\t\nThe size of the wzAuthor buffer.
A reference that receives the name of the component's author. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's authors name. The author name is optional; if an author name is not specified by the component, the length returned is 0.
If this method succeeds, it returns
If cchAuthor is 0 and wzAuthor is
Retrieves the vendor
A reference that receives the component's vendor
If this method succeeds, it returns
Retrieves the component's version.
\t\nThe size of the wzVersion buffer.
A reference that receives a culture invariant string of the component's version.
A reference that receives the actual length of the component's version. The version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return \"1.0.0.0\", except for pixel formats, which do not have a version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's specification version.
\t\nThe size of the wzSpecVersion buffer.
When this method returns, contain a culture invarient string of the component's specification version. The version form is NN.NN.NN.NN.
A reference that receives the actual length of the component's specification version. The specification version is optional; if a value is not specified by the component, the length returned is 0.
If this method succeeds, it returns
All built-in components return \"1.0.0.0\", except for pixel formats, which do not have a spec version.
If cchAuthor is 0 and wzAuthor is
Retrieves the component's friendly name, which is a human-readable display name for the component.
\t\nThe size of the wzFriendlyName buffer.
A reference that receives the friendly name of the component. The locale of the string depends on the value that the codec wrote to the registry at install time. For built-in components, these strings are always in English.
A reference that receives the actual length of the component's friendly name.
If this method succeeds, it returns
If cchFriendlyName is 0 and wzFriendlyName is
Retrieves the component's
Retrieves the component's class identifier (CLSID)
\t\nRetrieves the signing status of the component.
\t\nSigning is unused by WIC. Therefore, all components
This function can be used to determine whether a component has no binary component or has been added to the disabled components list in the registry.
\t\nRetrieves the vendor
Retrieves the container
Receives the container
If this method succeeds, it returns
Retrieves the pixel formats the codec supports.
\t\nThe size of the pguidPixelFormats array. Use 0 on first call to determine the needed array size.
Receives the supported pixel formats. Use
The array size needed to retrieve all supported pixel formats.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the array size needed to retrieve all the supported pixel formats by calling it with cFormats set to 0 and pguidPixelFormats set to
Retrieves the color manangement version number the codec supports.
\t\nThe size of the version buffer. Use 0 on first call to determine needed buffer size.
Receives the color management version number. Use
The actual buffer size needed to retrieve the full color management version number.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchColorManagementVersion set to 0 and wzColorManagementVersion set to
Retrieves the name of the device manufacture associated with the codec.
\t\nThe size of the device manufacture's name. Use 0 on first call to determine needed buffer size.
Receives the device manufacture's name. Use
The actual buffer size needed to retrieve the device manufacture's name.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceManufacturer set to 0 and wzDeviceManufacturer set to
Retrieves a comma delimited list of device models associated with the codec.
\t\nThe size of the device models buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of device model names associated with the codec. Use
The actual buffer size needed to retrieve all of the device model names.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchDeviceModels set to 0 and wzDeviceModels set to
Retrieves a comma delimited sequence of mime types associated with the codec.
\t\nThe size of the mime types buffer. Use 0 on first call to determine needed buffer size.
Receives the mime types associated with the codec. Use
The actual buffer size needed to retrieve all mime types associated with the codec.
If this method succeeds, it returns
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchMimeTypes set to 0 and wzMimeTypes set to
Retrieves a comma delimited list of the file name extensions associated with the codec.
\t\nThe size of the file name extension buffer. Use 0 on first call to determine needed buffer size.
Receives a comma delimited list of file name extensions associated with the codec. Use
The actual buffer size needed to retrieve all file name extensions associated with the codec.
If this method succeeds, it returns
The default extension for an image encoder is the first item in the list of returned extensions.
The usage pattern for this method is a two call process. The first call retrieves the buffer size needed to retrieve the full color management version number by calling it with cchFileExtensions set to 0 and wzFileExtensions set to
Retrieves a value indicating whether the codec supports animation.
\t\nReceives TRUE if the codec supports images with timing information; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports chromakeys.
\t\nReceives TRUE if the codec supports chromakeys; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports lossless formats.
\t\nReceives TRUE if the codec supports lossless formats; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the codec supports multi frame images.
\t\nReceives TRUE if the codec supports multi frame images; otherwise,
If this method succeeds, it returns
Retrieves a value indicating whether the given mime type matches the mime type of the codec.
\t\nThe mime type to compare.
Receives TRUE if the mime types match; otherwise,
Retrieves the container
Retrieves a value indicating whether the codec supports animation.
\t\nRetrieves a value indicating whether the codec supports chromakeys.
\t\nRetrieves a value indicating whether the codec supports lossless formats.
\t\nRetrieves a value indicating whether the codec supports multi frame images.
\t\nRegisters a progress notification callback function.
\t\nA function reference to the application defined progress notification callback function. See ProgressNotificationCallback for the callback signature.
A reference to component data for the callback method.
The
If this method succeeds, it returns
Applications can only register a single callback. Subsequent registration calls will replace the previously registered callback. To unregister a callback, pass in
Progress is reported in an increasing order between 0.0 and 1.0. If dwProgressFlags includes
Exposes methods that represent a decoder.
The interface provides access to the decoder's properties such as global thumbnails (if supported), frames, and palette.
\t\nThere are a number of concrete implemenations of this interface representing each of the standard decoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), icon (ICO), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native decoder.
| CLSID Name | CLSID |
|---|---|
| 0x6b462062, 0x7cbf, 0x400d, 0x9f, 0xdb, 0x81, 0x3d, 0xd1, 0xf, 0x27, 0x78 | |
| 0x389ea17b, 0x5078, 0x4cde, 0xb6, 0xef, 0x25, 0xc1, 0x51, 0x75, 0xc7, 0x51 | |
| 0xc61bfcdf, 0x2e0f, 0x4aad, 0xa8, 0xd7, 0xe0, 0x6b, 0xaf, 0xeb, 0xcd, 0xfe | |
| 0x9456a480, 0xe88b, 0x43ea, 0x9e, 0x73, 0xb, 0x2d, 0x9b, 0x71, 0xb1, 0xca | |
| 0x381dda3c, 0x9ce9, 0x4834, 0xa2, 0x3e, 0x1f, 0x98, 0xf8, 0xfc, 0x52, 0xbe | |
| 0xb54e85d9, 0xfe23, 0x499f, 0x8b, 0x88, 0x6a, 0xce, 0xa7, 0x13, 0x75, 0x2b | |
| 0xa26cec36, 0x234c, 0x4950, 0xae, 0x16, 0xe3, 0x4a, 0xac, 0xe7, 0x1d, 0x0d |
?
This interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
Codecs written as TIFF container formats that are not register will decode as a TIFF image. Client applications should check for a zero frame count to determine if the codec is valid.
\t\nRetrieves the capabilities of the decoder based on the specified stream.
\t\nThe stream to retrieve the decoder capabilities from.
The
Custom decoder implementations should save the current position of the specified
Initializes the decoder with the provided stream.
\t\nThe stream to use for initialization.
The stream contains the encoded pixels which are decoded each time the CopyPixels method on the
The
If this method succeeds, it returns
Retrieves the image's container format.
\t\nA reference that receives the image's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Copies the decoder's
If this method succeeds, it returns
CopyPalette returns a global palette (a palette that applies to all the frames in the image) if there is one; otherwise, it returns
Retrieves the metadata query reader from the decoder.
\t\nReceives a reference to the decoder's
If this method succeeds, it returns
Retrieves a preview image, if supported.
\t\nReceives a reference to the preview bitmap if supported.
If this method succeeds, it returns
Not all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
\t\nRetrieves the
If this method succeeds, it returns
Retrieves a bitmap thumbnail of the image, if one exists
\t\nReceives a reference to the
If this method succeeds, it returns
None of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
\t\nRetrieves the total number of frames in the image.
\t\nA reference that receives the total number of frames in the image.
If this method succeeds, it returns
Retrieves the specified frame of the image.
\t\nThe particular frame to retrieve.
A reference that receives a reference to the
Retrieves the image's container format.
\t\nRetrieves an
Retrieves the metadata query reader from the decoder.
\t\nRetrieves a preview image, if supported.
\t\nNot all formats support previews. Only the native Microsoft?Windows Digital Photo (WDP) codec support previews.
\t\nRetrieves a bitmap thumbnail of the image, if one exists
\t\nNone of the native formats support global thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support frame level thumbnails that can be accessed through a frame's GetThumbnail method.
\t\nRetrieves the total number of frames in the image.
\t\nExposes methods that provide information about a decoder.
\t\nRetrieves the file pattern signatures supported by the decoder.
\t\nThe array size of the pPatterns array.
Receives a list of
Receives the number of patterns the decoder supports.
Receives the actual buffer size needed to retrieve all pattern signatures supported by the decoder.
If this method succeeds, it returns
To retrieve all pattern signatures, this method should first be called with pPatterns set to
Retrieves a value that indicates whether the codec recognizes the pattern within a specified stream.
\t\nThe stream to pattern match within.
A reference that receives TRUE if the patterns match; otherwise,
Creates a new
If this method succeeds, it returns
Defines methods for setting an encoder's properties such as thumbnails, frames, and palettes.
\t\nThere are a number of concrete implemenations of this interface representing each of the standard encoders provided by the platform including bitmap (BMP), Portable Network Graphics (PNG), Joint Photographic Experts Group (JPEG), Graphics Interchange Format (GIF), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP). The following table includes the class identifier (CLSID) for each native encoder.
| CLSID Name | CLSID |
|---|---|
| 0x69be8bb4, 0xd66d, 0x47c8, 0x86, 0x5a, 0xed, 0x15, 0x89, 0x43, 0x37, 0x82 | |
| 0x27949969, 0x876a, 0x41d7, 0x94, 0x47, 0x56, 0x8f, 0x6a, 0x35, 0xa4, 0xdc | |
| 0x1a34f5c1, 0x4a5a, 0x46dc, 0xb6, 0x44, 0x1f, 0x45, 0x67, 0xe7, 0xa6, 0x76 | |
| 0x114f5598, 0xb22, 0x40a0, 0x86, 0xa1, 0xc8, 0x3e, 0xa4, 0x95, 0xad, 0xbd | |
| 0x0131be10, 0x2001, 0x4c5f, 0xa9, 0xb0, 0xcc, 0x88, 0xfa, 0xb6, 0x4c, 0xe8 | |
| 0xac4ce3cb, 0xe1c1, 0x44cd, 0x82, 0x15, 0x5a, 0x16, 0x65, 0x50, 0x9e, 0xc2 |
?
Additionally this interface may be sub-classed to provide support for third party codecs as part of the extensibility model. See the AITCodec Sample CODEC.
\t\nInitializes the encoder with an
If this method succeeds, it returns
Retrieves the encoder's container format.
\t\nA reference that receives the encoder's container format
If this method succeeds, it returns
Retrieves an
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
Sets the global palette for the image.
\t\nThe
Returns
Returns
Sets the global thumbnail for the image.
\t\nThe
Returns
Returns
Sets the global preview for the image.
\t\nThe
Returns
Returns
Creates a new
If this method succeeds, it returns
The parameter ppIEncoderOptions can be used to receive an
Note??Do not pass in a reference to an initialized
Otherwise, you can pass
See Encoding Overview for an example of how to set encoder options.
\t\nCommits all changes for the image and closes the stream.
\t\nIf this method succeeds, it returns
To finalize an image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
\t\nRetrieves a metadata query writer for the encoder.
\t\nWhen this method returns, contains a reference to the encoder's metadata query writer.
If this method succeeds, it returns
Retrieves the encoder's container format.
\t\nRetrieves an
Sets the global palette for the image.
\t\nSets the global thumbnail for the image.
\t\nSets the global preview for the image.
\t\nRetrieves a metadata query writer for the encoder.
\t\nExposes methods that provide information about an encoder.
\t\nCreates a new
If this method succeeds, it returns
Exposes methods that produce a flipped (horizontal or vertical) and/or rotated (by 90 degree increments) bitmap source. Rotations are done before the flip.
\t\nIWICBitmapFipRotator requests data on a per-pixel basis, while WIC codecs provide data on a per-scanline basis. This causes the fliprotator object to exhibit n2 behavior if there is no buffering. This occures because each pixel in the transformed image requires an entire scanline to be decoded in the file. It is recommended that you buffer the image using
Initializes the bitmap flip rotator with the provided parameters.
\t\nThe input bitmap source.
The
If this method succeeds, it returns
Defines methods for decoding individual image frames of an encoded file.
\t\nRetrieves a metadata query reader for the frame.
\t\nWhen this method returns, contains a reference to the frame's metadata query reader.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
Retrieves a small preview of the frame, if supported by the codec.
\t\nA reference that receives a reference to the
If this method succeeds, it returns
Not all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
\t\nRetrieves a metadata query reader for the frame.
\t\nRetrieves a small preview of the frame, if supported by the codec.
\t\nNot all formats support thumbnails. Joint Photographic Experts Group (JPEG), Tagged Image File Format (TIFF), and Microsoft?Windows Digital Photo (WDP) support thumbnails.
Note to ImplementersIf the codec does not support thumbnails, return WINCODEC_ERROR_CODECNOTHUMBNAIL rather than E_NOTIMPL.
\t\nRepresents an encoder's individual image frames.
\t\nInitializes the frame encoder using the given properties.
\t\nThe set of properties to use for
If this method succeeds, it returns
Sets the output image dimensions for the frame.
\t\nThe width of the output image.
The height of the output image.
If this method succeeds, it returns
Sets the physical resolution of the output image.
\t\nThe horizontal resolution value.
The vertical resolution value.
If this method succeeds, it returns
Requests that the encoder use the specified pixel format.
\t\nIf the method succeeds, contains the specified pixel format
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The |
?
Sets a given number
If this method succeeds, it returns
Sets a given number
If this method succeeds, it returns
Sets the
If this method succeeds, it returns
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
\t\nSets the frame thumbnail if supported by the codec.
\t\nThe bitmap source to use as the thumbnail.
Returns
Returns
SetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
\t\nEncodes the frame scanlines.
\t\nThe number of lines to encode.
The stride of the image pixels.
The size of the pixel buffer.
A reference to the pixel buffer.
Possible return values include the following.
| Return code | Description |
|---|---|
| | Success. |
| | The value of lineCount is larger than the number of scan lines in the image. |
?
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
\t\nEncodes a bitmap source.
\t\nThe bitmap source to encode.
The size rectangle of the bitmap source.
If this method succeeds, it returns
If SetSize is not called prior to calling WriteSource, the size given in prc is used if not
If SetPixelFormat is not called prior to calling WriteSource, the pixel format of the
If SetResolution is not called prior to calling WriteSource, the pixel format of pIBitmapSource is used.
If SetPalette is not called prior to calling WriteSource, the target pixel format is indexed, and the pixel format of pIBitmapSource matches the encoder frame's pixel format, then the pIBitmapSource pixel format is used.
When encoding a GIF image, if the global palette is set and the frame level palette is not set directly by the user or by a custom independent software vendor (ISV) GIF codec, WriteSource will use the global palette to encode the frame even when pIBitmapSource has a frame level palette.
Windows Vista:The source rect width must match the width set through SetSize. Repeated WriteSource calls can be made as long as the total accumulated source rect height is the same as set through SetSize.
\t\nCommits the frame to the image.
\t\nIf this method succeeds, it returns
To finalize the image, both the frame Commit and the encoder Commit must be called. However, only call the encoder Commit method after all frames have been committed.
\t\nGets the metadata query writer for the encoder frame.
\t\nWhen this method returns, contains a reference to metadata query writer for the encoder frame.
If this method succeeds, it returns
Encodes the frame scanlines.
\t\nThe number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
\t\nEncodes the frame scanlines.
\t\nThe number of lines to encode.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
\t\nEncodes the frame scanlines.
\t\nThe number of lines to encode.
The stride of the image pixels.
A reference to the pixel buffer.
Successive WritePixels calls are assumed to be sequential scanline access in the output image.
\t\nSets the
This method does not fail if called on a frame whose pixel format is set to a non-indexed pixel format. The target pixel format is a non-indexed format, the palette will be ignored.
\t\nSets the frame thumbnail if supported by the codec.
\t\nSetThumbnail should be called before calling WritePixels or WriteSource. The thumbnail will not be added to the encoded file if SetThumbnail after a call to WritePixels or WriteSource.
\t\nGets the metadata query writer for the encoder frame.
\t\nExposes methods that support the Lock method.
\t\nThe bitmap lock is simply an abstraction for a rectangular memory window into the bitmap. For the simplest case, a system memory bitmap, this is simply a reference to the top left corner of the rectangle and a stride value.
To release the exclusive lock set by Lock method and the associated
Retrieves the width and height, in pixels, of the locked rectangle.
\t\nA reference that receives the width of the locked rectangle.
A reference that receives the height of the locked rectangle.
If this method succeeds, it returns
Provides access to the stride value for the memory.
\t\nIf this method succeeds, it returns
Note the stride value is specific to the
Gets the reference to the top left pixel in the locked rectangle.
\t\nA reference that receives the size of the buffer.
A reference that receives a reference to the top left pixel in the locked rectangle.
The reference provided by this method should not be used outside of the lifetime of the lock itself.
GetDataPointer is not available in multi-threaded apartment applications.
\t\nGets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
\t\nA reference that receives the pixel format
If this method succeeds, it returns
Provides access to the stride value for the memory.
\t\n Note the stride value is specific to the
Gets the pixel format of for the locked area of pixels. This can be used to compute the number of bytes-per-pixel in the locked area.
\t\nRepresents a resized version of the input bitmap using a resampling or filtering algorithm.
\t\nImages can be scaled to larger sizes; however, even with sophisticated scaling algorithms, there is only so much information in the image and artifacts tend to worsen the more you scale up.
The scaler will reapply the resampling algorithm every time CopyPixels is called. If the scaled image is to be animated, the scaled image should be created once and cached in a new bitmap, after which the
The scaler is optimized to use the minimum amount of memory required to scale the image correctly. The scaler may be used to produce parts of the image incrementally (banding) by calling CopyPixels with different rectangles representing the output bands of the image. Resampling typically requires overlapping rectangles from the source image and thus may need to request the same pixels from the source bitmap multiple times. Requesting scanlines out-of-order from some image decoders can have a significant performance penalty. Because of this reason, the scaler is optimized to handle consecutive horizontal bands of scanlines (rectangle width equal to the bitmap width). In this case the accumulator from the previous vertically adjacent rectangle is re-used to avoid duplicate scanline requests from the source. This implies that banded output from the scaler may have better performance if the bands are requested sequentially. Of course if the scaler is simply used to produce a single rectangle output, this concern is eliminated because the scaler will internally request scanlines in the correct order.
\t\nInitializes the bitmap scaler with the provided parameters.
\t\nThe input bitmap source.
The destination width.
The desination height.
The
If this method succeeds, it returns
Copies pixel data using the supplied input parameters.
\t\nThe rectangle of pixels to copy.
The width to scale the source bitmap. This parameter must equal the value obtainable through
The height to scale the source bitmap. This parameter must equal the value obtainable through
The
This
The desired rotation or flip to perform prior to the pixel copy.
The transform must be an operation supported by an DoesSupportTransform call.
If a dstTransform is specified, nStride is the transformed stride and is based on the pguidDstFormat pixel format, not the original source's pixel format.
The stride of the destination buffer.
The size of the destination buffer.
The output buffer.
If this method succeeds, it returns
For codec developer implementation details for this method, see Implementing
When multiple transform operations are requested, the result is dependent on the order in which the operations are performed. To ensure predictability and consistency across CODECs, it's important that all CODECs perform these operations in the same order. The recommended order of these operations is:
Pixel format conversion can be performed at any time, since it has no effect on the other transforms.
The first parameter, prc is used to specify the region of interest for clipping the image. By convention, scaling is performed before clipping so, if the image is to be scaled as well as clipped, the region of interest should be determined after the image has been scaled.
If a dstTransform is specified, the stride is the transformed stride, and is based on the pixelFormat specified in the CopyPixels call, not the original frame's pixel format.
\t\nReturns the closest dimensions the implementation can natively scale to given the desired dimensions.
\t\nThe desired width. A reference that receives the closest supported width.
The desired height.A reference that receives the closest supported height.
If this method succeeds, it returns
Retrieves the closest pixel format to which the implementation of
If this method succeeds, it returns
Determines whether a specific transform option is supported natively by the implementation of the
If this method succeeds, it returns
Exposes methods for color management.
\t\nA Color Context is an abstraction for a color profile. The profile can be loaded from a file (ie. \"sRGB Color Space Profile.icm\") or from a memory buffer obtained by reading. The color profile directory can be obtained by calling the GetColorDirectory API (See http://msdn.microsoft.com/library/en-us/icm/icm_58xl.asp).
\t\nInitializes the color context from the given file.
\t\nIf this method succeeds, it returns
Initializes the color context from a memory block.
\t\nThe buffer used to initialize the
The size of the pbBuffer buffer.
If this method succeeds, it returns
Initializes the color context using an Exchangeable Image File (EXIF) color space.
\t\nThe value of the EXIF color space.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
?
If this method succeeds, it returns
Retrieves the color context type.
\t\nA reference that receives the
If this method succeeds, it returns
Retrieves the color context profile.
\t\nThe size of the pbBuffer buffer.
A reference that receives the color context profile.
A reference that receives the actual buffer size needed to retrieve the entire color context profile.
If this method succeeds, it returns
Retrieves the Exchangeable Image File (EXIF) color space color context.
\t\nA reference that receives the EXIF color space color context.
| Value | Meaning |
|---|---|
| A sRGB color space. |
| An Adobe RGB color space. |
| Unused. |
?
If this method succeeds, it returns
Retrieves the color context type.
\t\nRetrieves the Exchangeable Image File (EXIF) color space color context.
\t\nExposes methods that transforms an
A
Initializes an
If this method succeeds, it returns
Exposes methods that provide access to the capabilites of a raw codec format.
\t\nRetrieves information about which capabilities are supported for a raw image.
\t\nA reference that receives
If this method succeeds, it returns
It is recommended that a codec report that a capability is supported even if the results at the outer range limits are not of perfect quality.
\t\nSets the desired
If this method succeeds, it returns
Gets the current set of parameters.
\t\nA reference that receives a reference to the current set of parameters.
If this method succeeds, it returns
Sets the exposure compensation stop value.
\t\nThe exposure compensation value. The value range for exposure compensation is -5.0 through +5.0, which equates to 10 full stops.
If this method succeeds, it returns
It is recommended that a codec report that this method is supported even if the results at the outer range limits are not of perfect quality.
\t\nGets the exposure compensation stop value of the raw image.
\t\nA reference that receives the exposure compensation stop value. The default is the \"as-shot\" setting.
If this method succeeds, it returns
Sets the white point RGB values.
\t\nThe red white point value.
The green white point value.
The blue white point value.
If this method succeeds, it returns
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the white point RGB values.
\t\nA reference that receives the red white point value.
A reference that receives the green white point value.
A reference that receives the blue white point value.
If this method succeeds, it returns
Sets the named white point of the raw file.
\t\nA bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in the API.
Due to other white point setting methods (e.g. SetWhitePointKelvin), care must be taken by codec implementers to ensure proper interoperability. For instance, if the caller sets via a named white point then the codec implementer may whis to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wishes to deny a given action because of previous calls,
Gets the named white point of the raw image.
\t\nA reference that receives the bitwise combination of the enumeration values.
If this method succeeds, it returns
If the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Sets the white point Kelvin value.
\t\nThe white point Kelvin value. Acceptable Kelvin values are 1,500 through 30,000.
If this method succeeds, it returns
Codec implementers should faithfully adjust the color temperature within the range supported natively by the raw image. For values outside the native support range, the codec implementer should provide a best effort representation of the image at that color temperature.
Codec implementers should return
Codec implementers must ensure proper interoperability with other white point setting methods such as SetWhitePointRGB. For example, if the caller sets the white point via SetNamedWhitePoint then the codec implementer may want to disable reading back the correspoinding Kelvin temperature. In specific cases where the codec implementer wants to deny a given action because of previous calls,
Gets the white point Kelvin temperature of the raw image.
\t\nA reference that receives the white point Kelvin temperature of the raw image. The default is the \"as-shot\" setting value.
If this method succeeds, it returns
Gets the information about the current Kelvin range of the raw image.
\t\nA reference that receives the minimum Kelvin temperature.
A reference that receives the maximum Kelvin temperature.
A reference that receives the Kelvin step value.
If this method succeeds, it returns
Sets the contrast value of the raw image.
\t\nThe contrast value of the raw image. The default value is the \"as-shot\" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
\t\nGets the contrast value of the raw image.
\t\nA reference that receives the contrast value of the raw image. The default value is the \"as-shot\" setting. The value range for contrast is 0.0 through 1.0. The 0.0 lower limit represents no contrast applied to the image, while the 1.0 upper limit represents the highest amount of contrast that can be applied.
If this method succeeds, it returns
Sets the desired gamma value.
\t\nThe desired gamma value.
If this method succeeds, it returns
Gets the current gamma setting of the raw image.
\t\nA reference that receives the current gamma setting.
If this method succeeds, it returns
Sets the sharpness value of the raw image.
\t\nThe sharpness value of the raw image. The default value is the \"as-shot\" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
\t\nGets the sharpness value of the raw image.
\t\nA reference that receives the sharpness value of the raw image. The default value is the \"as-shot\" setting. The value range for sharpness is 0.0 through 1.0. The 0.0 lower limit represents no sharpening applied to the image, while the 1.0 upper limit represents the highest amount of sharpness that can be applied.
If this method succeeds, it returns
Sets the saturation value of the raw image.
\t\nThe saturation value of the raw image. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
\t\nGets the saturation value of the raw image.
\t\nA reference that receives the saturation value of the raw image. The default value is the \"as-shot\" setting. The value range for saturation is 0.0 through 1.0. A value of 0.0 represents an image with a fully de-saturated image, while a value of 1.0 represents the highest amount of saturation that can be applied.
If this method succeeds, it returns
Sets the tint value of the raw image.
\t\nThe tint value of the raw image. The default value is the \"as-shot\" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
The codec implementer must determine what the outer range values represent and must determine how to map the values to their image processing routines.
\t\nGets the tint value of the raw image.
\t\nA reference that receives the tint value of the raw image. The default value is the \"as-shot\" setting if it exists or 0.0. The value range for sharpness is -1.0 through +1.0. The -1.0 lower limit represents a full green bias to the image, while the 1.0 upper limit represents a full magenta bias.
If this method succeeds, it returns
Sets the noise reduction value of the raw image.
\t\nThe noise reduction value of the raw image. The default value is the \"as-shot\" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents highest noise reduction amount that can be applied.
If this method succeeds, it returns
The codec implementer must determine what the upper range value represents and must determine how to map the value to their image processing routines.
\t\nGets the noise reduction value of the raw image.
\t\nA reference that receives the noise reduction value of the raw image. The default value is the \"as-shot\" setting if it exists or 0.0. The value range for noise reduction is 0.0 through 1.0. The 0.0 lower limit represents no noise reduction applied to the image, while the 1.0 upper limit represents full highest noise reduction amount that can be applied.
If this method succeeds, it returns
Sets the destination color context.
\t\nThe destination color context.
If this method succeeds, it returns
Sets the tone curve for the raw image.
\t\nThe size of the pToneCurve structure.
The desired tone curve.
If this method succeeds, it returns
Gets the tone curve of the raw image.
\t\nThe size of the pToneCurve buffer.
A reference that receives the
A reference that receives the size needed to obtain the tone curve structure.
If this method succeeds, it returns
Sets the desired rotation angle.
\t\nThe desired rotation angle.
If this method succeeds, it returns
Gets the current rotation angle.
\t\nA reference that receives the current rotation angle.
If this method succeeds, it returns
Sets the current
If this method succeeds, it returns
Gets the current
If this method succeeds, it returns
Sets the notification callback method.
\t\nPointer to the notification callback method.
If this method succeeds, it returns
Gets the current set of parameters.
\t\nGets or sets the exposure compensation stop value of the raw image.
\t\nGets or sets the named white point of the raw image.
\t\nIf the named white points are not supported by the raw image or the raw file contains named white points that are not supported by this API, the codec implementer should still mark this capability as supported.
If the named white points are not supported by the raw image, a best effort should be made to adjust the image to the named white point even when it isn't a pre-defined white point of the raw file.
If the raw file containes named white points not supported by this API, the codec implementer should support the named white points in
Gets or sets the white point Kelvin temperature of the raw image.
\t\nGets or sets the contrast value of the raw image.
\t\nGets or sets the current gamma setting of the raw image.
\t\nGets or sets the sharpness value of the raw image.
\t\nGets or sets the saturation value of the raw image.
\t\nGets or sets the tint value of the raw image.
\t\nGets or sets the noise reduction value of the raw image.
\t\nSets the destination color context.
\t\nGets or sets the current rotation angle.
\t\nGets or sets the current
Sets the notification callback method.
\t\nFlags used to by
An application-defined callback method used for raw image parameter change notifications.
\t\nA set of
If this method succeeds, it returns
Exposes methods that provide enumeration services for individual metadata items.
\t\nSkips to given number of objects.
\t\nThe number of objects to skip.
If this method succeeds, it returns
Resets the current position to the beginning of the enumeration.
\t\nIf this method succeeds, it returns
Creates a copy of the current
If this method succeeds, it returns
Exposes methods used for in-place metadata editing. A fast metadata encoder enables you to add and remove metadata to an image without having to fully re-encode the image.
\t\n A decoder must be created using the
Not all metadata formats support fast metadata encoding. The native metadata handlers that support metadata are IFD, Exif, XMP, and GPS.
If a fast metadata encoder fails, the image will need to be fully re-encoded to add the metadata.
\t\nFinalizes metadata changes to the image stream.
\t\nIf this method succeeds, it returns
If the commit fails and returns
If the commit fails for any reason, you will need to re-encode the image to ensure the new metadata is added to the image.
\t\nRetrieves a metadata query writer for fast metadata encoding.
\t\nWhen this method returns, contains a reference to the fast metadata encoder's metadata query writer.
If this method succeeds, it returns
Retrieves a metadata query writer for fast metadata encoding.
\t\n Represents an
Initializes the format converter.
\t\nThe input bitmap to convert
The destination pixel format
The
The palette to use for conversion.
The alpha threshold to use for conversion.
The palette translation type to use for conversion.
If this method succeeds, it returns
If you do not have a predefined palette, you must first create one. Use InitializeFromBitmap to create the palette object, then pass it in along with your other parameters.
dither, pIPalette, alphaThresholdPercent, and paletteTranslate are used to mitigate color loss when converting to a reduced bit-depth format. For conversions that do not need these settings, the following parameters values should be used: dither set to
The basic algorithm involved when using an ordered dither requires a fixed palette, found in the
If colors in pIPalette do not closely match those in paletteTranslate, the mapping may produce undesireable results.
When converting a bitmap which has an alpha channel, such as a Portable Network Graphics (PNG), to 8bpp, the alpha channel is normally ignored. Any pixels which were transparent in the original bitmap show up as black in the final output because both transparent and black have pixel values of zero in the respective formats.
Some 8bpp content can contains an alpha color; for instance, the Graphics Interchange Format (GIF) format allows for a single palette entry to be used as a transparent color. For this type of content, alphaThresholdPercent specifies what percentage of transparency should map to the transparent color. Because the alpha value is directly proportional to the opacity (not transparency) of a pixel, the alphaThresholdPercent indicates what level of opacity is mapped to the fully transparent color. For instance, 9.8% implies that any pixel with an alpha value of less than 25 will be mapped to the transparent color. A value of 100% maps all pixels which are not fully opaque to the transparent color. Note that the palette should provide a transparent color. If it does not, the 'transparent' color will be the one closest to zero - often black.
\t\nDetermines if the source pixel format can be converted to the destination pixel format.
\t\nThe source pixel format.
The destionation pixel format.
A reference that receives a value indicating whether the source pixel format can be converted to the destination pixel format.
Exposes methods that provide information about a pixel format converter.
\t\nRetrieves a list of GUIDs that signify which pixel formats the converter supports.
\t\nThe size of the pPixelFormatGUIDs array.
Pointer to a
The actual array size needed to retrieve all pixel formats supported by the converter.
If this method succeeds, it returns
The format converter does not necessarily guarantee symmetricality with respect to conversion; that is, a converter may be able to convert FROM a particular format without actually being able to convert TO a particular format. In order to test symmetricality, use CanConvert.
To determine the number of pixel formats a coverter can handle, set cFormats to 0 and pPixelFormatGUIDs to
Creates a new
If this method succeeds, it returns
Exposes methods used to create components for the Windows Imaging Component (WIC) such as decoders, encoders and pixel format converters.
\t\nCreates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
When a decoder is created using this method, the file handle must remain alive during the lifetime of the decoder.
\t\nCreates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Other values may be available for both guidContainerFormat and pguidVendor depending on the installed WIC-enabled encoders. The values listed are those that are natively supported by the operating system.
\t\nCreates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of an
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates a new instance of the
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Component types must be enumerated seperately. Combinations of component types and
Creates a new instance of the fast metadata encoder based on the given
If this method succeeds, it returns
The native image formats provided by Windows Imaging Component (WIC) do not support metadata at the decoder level. WIC codecs only support metadata on image frames. To create a fast metadata encoder from an image frame, see the image factory's CreateFastMetadataEncoderFromFrameDecode method.
\t\nCreates a new instance of the fast metadata encoder based on the given image frame.
\t\nThe
When this method returns, contains a reference to a new fast metadata encoder.
If this method succeeds, it returns
Creates a new instance of a query writer.
\t\nThe
The
When this method returns, contains a reference to a new
If this method succeeds, it returns
Creates a new instance of a query writer based on the given query reader. The query writer will be pre-populated with metadata from the query reader.
\t\nThe
The
When this method returns, contains a reference to a new metadata writer.
If this method succeeds, it returns
Exposes methods for retrieving metadata blocks and items from a decoder or its image frames using a metadata query expression.
\t\nA metadata query reader uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
\t\nGets the metadata query readers container format.
\t\nPointer that receives the cointainer format
If this method succeeds, it returns
Retrieves the current path relative to the root metadata block.
\t\nThe length of the wzNamespace buffer.
Pointer that receives the current namespace location.
The actual buffer length that was needed to retrieve the current namespace location.
If this method succeeds, it returns
If the query reader is relative to the top of the metadata hierarchy it will return an empty string.
If the query reader is relative to a nested metadata block this method will return the path to the current query reader.
\t\nRetrieves the metadata block or item identified by a metadata query expression.
\t\nThe query expression to the requested metadata block or item.
When this method returns, contains the metadata block or item requested.
If this method succeeds, it returns
GetMetadataByName uses metadata query expressions to access embedded metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If multiple blocks or items exist that are expressed by the same query expression, the first metadata block or item found will be returned.
\t\nGets an enumerator of all metadata items at the current relative location within the metadata hierachy.
\t\nWhen this method returns, contais a reference to an enumerator that contains the metadata items.
If a metadata item is a nested metadata block it will be passed back as a VT_UNKNOWN; otherwise, the \"name\" of the property will be passed back as a VT_LPWSTR. The enumerator does not enumerate content within nested metadata blocks.
Gets the metadata query readers container format.
\t\nExposes methods for setting or removing metadata blocks and items to an encoder or its image frames using a metadata query expression.
\t\nA metadata query writer uses metadata query expressions to set or remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
\t\nSets a metadata item to a specific location.
\t\nThe name of the metadata item.
The metadata to set.
If this method succeeds, it returns
SetMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the value set is a nested metadata block then use variant type VT_UNKNOWN and pvarValue pointing to the
Removes a metadata item from a specific location using a metadata query expression.
\t\nThe name of the metadata item to remove.
If this method succeeds, it returns
RemoveMetadataByName uses metadata query expressions to remove metadata. For more information on the metadata query language, see the Metadata Query Language Overview.
If the metadata item is a metadata block, it is removed from the metadata hierarchy.
\t\nExposes methods for accessing and building a color table, primarily for indexed pixel formats.
\t\nIf the
InitializeFromBitmap's fAddTransparentColor parameter will add a transparent color to the end of the color collection if its size if less than 256, otherwise index 255 will be replaced with the transparent color. If a pre-defined palette type is used, it will change to BitmapPaletteTypeCustom since it no longer matches the predefined palette.
The palette interface is an auxiliary imaging interface in that it does not directly concern bitmaps and pixels; rather it provides indexed color translation for indexed bitmaps. For an indexed pixel format with M bits per pixels: (The number of colors in the palette) greater than 2^M.
Traditionally the basic operation of the palette is to provide a translation from a byte (or smaller) index into a 32bpp color value. This is often accomplished by a 256 entry table of color values.
\t\nInitializes the palette to one of the pre-defined palettes specified by
If this method succeeds, it returns
Initializes a palette to the custom color entries provided.
\t\nPointer to the color array.
The number of colors in pColors.
If this method succeeds, it returns
If a transparent color is required, it should be provided as part of the custom entries.
The entry count is limited to 256.
\t\nInitializes a palette using a computed optimized values based on the reference bitmap.
\t\nPointer to the source bitmap.
The number of colors to initialize the palette with.
A value to indicate whether to add a transparent color.
If this method succeeds, it returns
The resulting palette contains the specified number of colors which best represent the colors present in the bitmap. The algorithm operates on the opaque RGB color value of each pixel in the reference bitmap and hence ignores any alpha values. If a transparent color is required, set the fAddTransparentColor parameter to TRUE and one fewer optimized color will be computed, reducing the colorCount, and a fully transparent color entry will be added.
\t\nInitialize the palette based on a given palette.
\t\nPointer to the source palette.
If this method succeeds, it returns
Retrieves the
If this method succeeds, it returns
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
\t\nRetrieves the number of colors in the color table.
\t\nPointer that receives the number of colors in the color table.
If this method succeeds, it returns
Fills out the supplied color array with the colors from the internal color table. The color array should be sized according to the return results from GetColorCount.
\t\nIf this method succeeds, it returns
Retrieves a value that describes whether the palette is black and white.
\t\nPointer that receives TRUE if the palette is black and white; otherwise,
If this method succeeds, it returns
Retrieves a value that describes whether a palette is grayscale.
\t\nPointer that receives TRUE if the palette is grayscale; otherwise
If this method succeeds, it returns
Retrieves a value that describes whether the palette contains an alpha transparent color.
\t\nPointer that receives TRUE if the palette contains a transparent color; otherwise,
If this method succeeds, it returns
Retrieves the
WICBitmapPaletteCustom is used for palettes initialized from both InitializeCustom and InitializeFromBitmap. There is no distinction is made between optimized and custom palettes.
\t\nRetrieves the number of colors in the color table.
\t\nRetrieves a value that describes whether the palette is black and white.
\t\nRetrieves a value that describes whether a palette is grayscale.
\t\nExposes methods that provide information about a pixel format.
\t\nGets the pixel format
Pointer that receives the pixel format
If this method succeeds, it returns
Gets the pixel format's
If this method succeeds, it returns
Gets the bits per pixel (BPP) of the pixel format.
\t\nPointer that receives the BPP of the pixel format.
If this method succeeds, it returns
Gets the number of channels the pixel format contains.
\t\nPointer that receives the channel count.
If this method succeeds, it returns
Gets the pixel format's channel mask.
\t\nThe index to the channel mask to retrieve.
The size of the pbMaskBuffer buffer.
Pointer to the mask buffer.
The actual buffer size needed to obtain the channel mask.
If this method succeeds, it returns
Gets the pixel format
Gets the pixel format's
Gets the bits per pixel (BPP) of the pixel format.
\t\nGets the number of channels the pixel format contains.
\t\nExtends
Returns whether the format supports transparent pixels.
\t\nReturns TRUE if the pixel format supports transparency; otherwise, false.
If this method succeeds, it returns
Returns the
If this method succeeds, it returns
Returns whether the format supports transparent pixels.
\t\nNotify method is documented only for compliance; its use is not recommended and may be altered or unavailable in the future. Instead, and use RegisterProgressNotification. \t\n
\t\nIf this method succeeds, it returns
Exposes methods for obtaining information about and controlling progressive decoding.
\t\nImages can only be progressively decoded if they were progressively encoded. The native encoders supplied by Windows Imaging Component (WIC) do not
E_NOTIMPL is returned if the codec does not support progressive level decoding.
\t\nGets the number of levels of progressive decoding supported by the CODEC.
\t\nIndicates the number of levels supported by the CODEC.
If this method succeeds, it returns
Users should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
\t\nGets the last level set by the SetCurrentLevel call.
\t\nIf this method succeeds, it returns
Specifies the level to retrieve on the next call to CopyPixels.
\t\nIf this method succeeds, it returns
A call does not have to request every level supported. If a caller requests level 1, without having previously requested level 0, the bits returned by the next call to CopyPixels will include both levels.
\t\nGets the number of levels of progressive decoding supported by the CODEC.
\t\nUsers should not use this function to iterate through the progressive levels of a progressive JPEG image. JPEG progressive levels are determined by the image and do not have a fixed level count. Using this method will force the application to wait for all progressive levels to be downloaded before it can return. Instead, applications should use the following code to iterate through the progressive levels of a progressive JPEG image.
\t\nGets or sets the last level set by the SetCurrentLevel call.
\t\nRepresents a Windows Imaging Component (WIC) stream for referencing imaging and metadata content.
\t\nDecoders and metadata handlers are expected to create sub streams of whatever stream they hold when handing off control for embedded metadata to another metadata handler. If the stream is not restricted then use MAXLONGLONG as the max size and offset 0.
The
Initializes a stream from another stream. Access rights are inherited from the underlying stream.
\t\nThe initialize stream.
If this method succeeds, it returns
Initializes a stream from a particular file.
\t\nThe file used to initialize the stream.
The desired file access mode.
| Value | Meaning |
|---|---|
| Read access. |
| Write access. |
?
If this method succeeds, it returns
The
Initializes a stream to treat a block of memory as a stream. The stream cannot grow beyond the buffer size.
\t\nPointer to the buffer used to initialize the stream.
The size of buffer.
If this method succeeds, it returns
This method should be avoided whenever possible. The caller is responsible for ensuring the memory block is valid for the lifetime of the stream when using InitializeFromMemory. A workaround for this behavior is to create an
If you require a growable memory stream, use CreateStreamOnHGlobal.
\t\nInitializes the stream as a substream of another stream.
\t\nPointer to the input stream.
The stream offset used to create the new stream.
The maximum size of the stream.
If this method succeeds, it returns
The stream functions with its own stream position, independent of the underlying stream but restricted to a region. All seek positions are relative to the sub region. It is allowed, though not recommended, to have multiple writable sub streams overlapping the same range.
\t\nContains members that identify a pattern within an image file which can be used to identify a particular format.
\t\nThe offset the pattern is located in the file.
The pattern length.
The actual pattern.
The pattern mask.
The end of the stream.
Defines raw codec capabilites.
\t\nSize of the
The codec's major version.
The codec's minor version.
The
The
The
The
The
The
The
The
The
The
The
The
The
The
The
Represents a raw image tone curve.
\t\nThe number of tone curve points.
The array of tone curve points.
Represents a raw image tone curve point.
\t\nThe tone curve input.
The tone curve output.
Represents an object that can receive drawing commands. Interfaces that inherit from
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Represents a Direct2D drawing resource.
\t\nRetrieves the factory associated with this resource.
\t\nWhen this method returns, contains a reference to a reference to the factory that created this resource. This parameter is passed uninitialized.
Retrieves the factory associated with this resource.
\t\nCreates a Direct2D bitmap from a reference to in-memory source data.
\t\nThe dimension of the bitmap to create in pixels.
A reference to the memory location of the image data, or
The byte count of each scanline, which is equal to (the image width in pixels ? the number of bytes per pixel) + memory padding. If srcData is
The pixel format and dots per inch (DPI) of the bitmap to create.
When this method returns, contains a reference to a reference to the new bitmap. This parameter is passed uninitialized.
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Before Direct2D can load a WIC bitmap, that bitmap must be converted to a supported pixel format and alpha mode. For a list of supported pixel formats and alpha modes, see Supported Pixel Formats and Alpha Modes.
\t\nCreates an
If this method succeeds, it returns
The CreateSharedBitmap method is useful for efficiently reusing bitmap data and can also be used to provide interoperability with Direct3D.
Sharing anBy passing an
You may also use this method to reinterpret the data of an existing bitmap and specify a new DPI or alpha mode. For example, in the case of a bitmap atlas, an
When using a DXGI surface render target (an
Note also that the
For more information about interoperability with Direct3D, see the Direct2D and Direct3D Interoperability Overview.
Sharing anAn
To use an
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a layer resource that can be used with this render target and its compatible render targets.
\t\nWhen the method returns, contains a reference to a reference to the new layer. This parameter is passed uninitialized.
If this method succeeds, it returns
The layer automatically resizes itself, as needed.
\t\nCreate a mesh that uses triangles to describe a shape.
\t\nWhen this method returns, contains a reference to a reference to the new mesh.
If this method succeeds, it returns
To populate a mesh, use its Open method to obtain an
Draws a line between the specified points using the specified stroke style.
\t\nThe start point of the line, in device-independent pixels.
The end point of the line, in device-independent pixels.
The brush used to paint the line's stroke.
A value greater than or equal to 0.0f that specifies the width of the stroke. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.
The style of stroke to paint, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the
Draws the outline of a rectangle that has the specified dimensions and stroke style.
\t\nThe dimensions of the rectangle to draw, in device-independent pixels.
The brush used to paint the rectangle's stroke.
A value greater than or equal to 0.0f that specifies the width of the rectangle's stroke. The stroke is centered on the rectangle's outline.
The style of stroke to paint, or
When this method fails, it does not return an error code. To determine whether a drawing method (such as DrawRectangle) failed, check the result returned by the
Paints the interior of the specified rectangle.
\t\nThe dimension of the rectangle to paint, in device-independent pixels.
The brush used to paint the rectangle's interior.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRectangle) failed, check the result returned by the
Draws the outline of the specified rounded rectangle using the specified stroke style.
\t\nThe dimensions of the rounded rectangle to draw, in device-independent pixels.
The brush used to paint the rounded rectangle's outline.
The width of the rounded rectangle's stroke. The stroke is centered on the rounded rectangle's outline. The default value is 1.0f.
The style of the rounded rectangle's stroke, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawRoundedRectangle) failed, check the result returned by the
Paints the interior of the specified rounded rectangle.
\t\nThe dimensions of the rounded rectangle to paint, in device independent pixels.
The brush used to paint the interior of the rounded rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRoundedRectangle) failed, check the result returned by the
Draws the outline of the specified ellipse using the specified stroke style.
\t\nThe position and radius of the ellipse to draw, in device-independent pixels.
The brush used to paint the ellipse's outline.
The thickness of the ellipse's stroke. The stroke is centered on the ellipse's outline.
The style of stroke to apply to the ellipse's outline, or
The DrawEllipse method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the
Paints the interior of the specified ellipse.
\t\nThe position and radius, in device-independent pixels, of the ellipse to paint.
The brush used to paint the interior of the ellipse.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillEllipse) failed, check the result returned by the
Draws the outline of the specified geometry using the specified stroke style.
\t\nThe geometry to draw.
The brush used to paint the geometry's stroke.
The thickness of the geometry's stroke. The stroke is centered on the geometry's outline.
The style of stroke to apply to the geometry's outline, or
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the
Paints the interior of the specified geometry.
\t\nThe geometry to paint.
The brush used to paint the geometry's interior.
The opacity mask to apply to the geometry, or
If the opacityBrush parameter is not
When this method fails, it does not return an error code. To determine whether a drawing operation (such as FillGeometry) failed, check the result returned by the
Paints the interior of the specified mesh.
\t\nThe mesh to paint.
The brush used to paint the mesh.
The current antialias mode of the render target must be
FillMesh does not expect a particular winding order for the triangles in the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillMesh) failed, check the result returned by the
For this method to work properly, the render target must be using the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillOpacityMask) failed, check the result returned by the
Draws the specified bitmap after scaling it to the size of the specified rectangle.
\t\nThe bitmap to render.
The size and position, in device-independent pixels in the render target's coordinate space, of the area to which the bitmap is drawn. If the rectangle is not well-ordered, nothing is drawn, but the render target does not enter an error state.
A value between 0.0f and 1.0f, inclusive, that specifies the opacity value to be applied to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. Default is 1.0f.
The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is
The size and position, in device-independent pixels in the bitmap's coordinate space, of the area within the bitmap to draw;
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawBitmap) failed, check the result returned by the
To draw text with Direct2D, use the
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawText) failed, check the result returned by the
Draws the formatted text described by the specified
When drawing the same text repeatedly, using the DrawTextLayout method is more efficient than using the DrawText method because the text doesn't need to be formatted and the layout processed with each call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawTextLayout) failed, check the result returned by the
Draws the specified glyphs.
\t\nThe origin, in device-independent pixels, of the glyphs' baseline.
The glyphs to render.
The brush used to paint the specified glyphs.
A value that indicates how glyph metrics are used to measure text when it is formatted. The default value is
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGlyphRun) failed, check the result returned by the
Gets the current transform of the render target.
\t\nWhen this returns, contains the current transform of the render target. This parameter is passed uninitialized.
Sets the antialiasing mode of the render target. The antialiasing mode applies to all subsequent drawing operations, excluding text and glyph drawing operations.
\t\nThe antialiasing mode for future drawing operations.
To specify the antialiasing mode for text and glyph operations, use the SetTextAntialiasMode method.
\t\nRetrieves the current antialiasing mode for nontext drawing operations.
\t\nThe current antialiasing mode for nontext drawing operations.
Specifies the antialiasing mode to use for subsequent text and glyph drawing operations.
\t\nThe antialiasing mode to use for subsequent text and glyph drawing operations.
Gets the current antialiasing mode for text and glyph drawing operations.
\t\nThe current antialiasing mode for text and glyph drawing operations.
Specifies text rendering options to be applied to all subsequent text and glyph drawing operations.
\t\nThe text rendering options to be applied to all subsequent text and glyph drawing operations;
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
\t\nRetrieves the render target's current text rendering options.
\t\nWhen this method returns, textRenderingParamscontains the address of a reference to the render target's current text rendering options.
If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
\t\nSpecifies a label for subsequent drawing operations.
\t\nA label to apply to subsequent drawing operations.
A label to apply to subsequent drawing operations.
The labels specified by this method are printed by debug error messages. If no tag is set, the default value for each tag is 0.
\t\nGets the label for subsequent drawing operations.
\t\nWhen this method returns, contains the first label for subsequent drawing operations. This parameter is passed uninitialized. If
When this method returns, contains the second label for subsequent drawing operations. This parameter is passed uninitialized. If
If the same address is passed for both parameters, both parameters receive the value of the second tag.
\t\nAdds the specified layer to the render target so that it receives all subsequent drawing operations until PopLayer is called.
\t\nThe PushLayer method allows a caller to begin redirecting rendering to a layer. All rendering operations are valid in a layer. The location of the layer is affected by the world transform set on the render target.
Each PushLayer must have a matching PopLayer call. If there are more PopLayer calls than PushLayer calls, the render target is placed into an error state. If Flush is called before all outstanding layers are popped, the render target is placed into an error state, and an error is returned. The error state can be cleared by a call to EndDraw.
A particular
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushLayer) failed, check the result returned by the
Stops redirecting drawing operations to the layer that is specified by the last PushLayer call.
\t\nA PopLayer must match a previous PushLayer call.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopLayer) failed, check the result returned by the
Executes all pending drawing commands.
\t\nWhen this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
This command does not flush the device that is associated with the render target.
Calling this method resets the error state of the render target.
\t\nSaves the current drawing state to the specified
Sets the render target's drawing state to that of the specified
Specifies a rectangle to which all subsequent drawing operations are clipped.
\t\nThe size and position of the clipping area, in device-independent pixels.
The antialiasing mode that is used to draw the edges of clip rects that have subpixel boundaries, and to blend the clip with the scene contents. The blending is performed once when the PopAxisAlignedClip method is called, and does not apply to each primitive within the layer.
The clipRect is transformed by the current world transform set on the render target. After the transform is applied to the clipRect that is passed in, the axis-aligned bounding box for the clipRect is computed. For efficiency, the contents are clipped to this axis-aligned bounding box and not to the original clipRect that is passed in.
The following diagrams show how a rotation transform is applied to the render target, the resulting clipRect, and a calculated axis-aligned bounding box.
Assume the rectangle in the following illustration is a render target that is aligned to the screen pixels.
Apply a rotation transform to the render target. In the following illustration, the black rectangle represents the original render target and the red dashed rectangle represents the transformed render target.
After calling PushAxisAlignedClip, the rotation transform is applied to the clipRect. In the following illustration, the blue rectangle represents the transformed clipRect.
The axis-aligned bounding box is calculated. The green dashed rectangle represents the bounding box in the following illustration. All contents are clipped to this axis-aligned bounding box.
Note??If rendering operations fail or if PopAxisAlignedClip is not called, clip rects may cause some artifacts on the render target. PopAxisAlignedClip can be considered a drawing operation that is designed to fix the borders of a clipping region. Without this call, the borders of a clipped area may be not antialiased or otherwise corrected.
The PushAxisAlignedClip and PopAxisAlignedClip must match. Otherwise, the error state is set. For the render target to continue receiving new commands, you can call Flush to clear the error.
A PushAxisAlignedClip and PopAxisAlignedClip pair can occur around or within a PushLayer and PopLayer, but cannot overlap. For example, the sequence of PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip is valid, but the sequence of PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer is invalid.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushAxisAlignedClip) failed, check the result returned by the
Removes the last axis-aligned clip from the render target. After this method is called, the clip is no longer applied to subsequent drawing operations.
\t\nA PushAxisAlignedClip/PopAxisAlignedClip pair can occur around or within a PushLayer/PopLayer pair, but may not overlap. For example, a PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip sequence is valid, but a PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer sequence is not.
PopAxisAlignedClip must be called once for every call to PushAxisAlignedClip.
For an example, see How to Clip with an Axis-Aligned Clip Rectangle.
This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopAxisAlignedClip) failed, check the result returned by the
Clears the drawing area to the specified color.
\t\nThe color to which the drawing area is cleared.
Direct2D interprets the clearColor as straight alpha (not premultiplied). If the render target's alpha mode is
If the render target has an active clip (specified by PushAxisAlignedClip), the clear command is applied only to the area within the clip region.
\t\nInitiates drawing on this render target.
\t\nDrawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are used to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Ends drawing operations on the render target and indicates the current error state and associated tags.
\t\nWhen this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.
If the method succeeds, it returns
Drawing operations can only be issued between a BeginDraw and EndDraw call.
BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of
The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.
After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an
If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate
Retrieves the pixel format and alpha mode of the render target.
\t\nThe pixel format and alpha mode of the render target.
Sets the dots per inch (DPI) of the render target.
\t\nA value greater than or equal to zero that specifies the horizontal DPI of the render target.
A value greater than or equal to zero that specifies the vertical DPI of the render target.
This method specifies the mapping from pixel space to device-independent space for the render target. If both dpiX and dpiY are 0, the factory-read system DPI is chosen. If one parameter is zero and the other unspecified, the DPI is not changed.
For
Return the render target's dots per inch (DPI).
\t\nWhen this method returns, contains the horizontal DPI of the render target. This parameter is passed uninitialized.
When this method returns, contains the vertical DPI of the render target. This parameter is passed uninitialized.
This method indicates the mapping from pixel space to device-independent space for the render target.
For
Returns the size of the render target in device-independent pixels.
\t\nThe current size of the render target in device-independent pixels.
Returns the size of the render target in device pixels.
\t\nThe size of the render target in device pixels.
Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
\t\nThe maximum size, in pixels, of any one bitmap dimension supported by the render target.
Indicates whether the render target supports the specified properties.
\t\nThe render target properties to test.
TRUE if the specified render target properties are supported by this render target; otherwise,
This method does not evaluate the DPI settings specified by the renderTargetProperties parameter.
\t\nGets or sets the current transform of the render target.
\t\nRetrieves or sets the current antialiasing mode for nontext drawing operations.
\t\nGets or sets the current antialiasing mode for text and glyph drawing operations.
\t\nRetrieves or sets the render target's current text rendering options.
\t\nIf the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.
\t\nRetrieves the pixel format and alpha mode of the render target.
\t\nReturns the size of the render target in device-independent pixels.
\t\nReturns the size of the render target in device pixels.
\t\nGets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.
\t\nEncapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs.
\t\nYou create an
if (SUCCEEDED(hr))\t\n { hr = g_pGdiInterop->CreateBitmapRenderTarget(hdc, r.right, r.bottom, &g_pBitmapRenderTarget);\t\n }\t\n
One way to use a
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, measuringMode, __in const* glyphRun, __in const* glyphRunDescription, * clientDrawingEffect )\t\n { hr = ; // Pass on the drawing call to the render target to do the real work. dirtyRect = {0}; hr = pRenderTarget_->DrawGlyphRun( baselineOriginX, baselineOriginY, measuringMode, glyphRun, pRenderingParams_, RGB(0,200,255), &dirtyRect ); return hr;\t\n }\t\n The
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, DWRITE_MEASURING_MODE measuringMode, __in DWRITE_GLYPH_RUN const* glyphRun, __in DWRITE_GLYPH_RUN_DESCRIPTION const* glyphRunDescription, IUnknown* clientDrawingEffect )\t\n { HRESULT hr = S_OK; // Pass on the drawing call to the render target to do the real work. RECT dirtyRect = {0}; hr = pRenderTarget_->DrawGlyphRun( baselineOriginX, baselineOriginY, measuringMode, glyphRun, pRenderingParams_, RGB(0,200,255), &dirtyRect ); return hr;\t\n } \t\n \n The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not. Default rendering params can be retrieved by using the Draws a run of glyphs to a bitmap target at the specified position.
\t\nThe horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.
The measuring method for glyphs in the run, used with the other properties to determine the rendering mode.
The structure containing the properties of the glyph run.
The object that controls rendering behavior.
The foreground color of the text.
The optional rectangle that receives the bounding box (in pixels not DIPs) of all the pixels affected by drawing the glyph run. The black box rectangle may extend beyond the dimensions of the bitmap.
If this method succeeds, it returns
You can use the
STDMETHODIMP GdiTextRenderer::DrawGlyphRun( __maybenull void* clientDrawingContext, FLOAT baselineOriginX, FLOAT baselineOriginY, measuringMode, __in const* glyphRun, __in const* glyphRunDescription, * clientDrawingEffect )\t\n { hr = ; // Pass on the drawing call to the render target to do the real work. dirtyRect = {0}; hr = pRenderTarget_->DrawGlyphRun( baselineOriginX, baselineOriginY, measuringMode, glyphRun, pRenderingParams_, RGB(0,200,255), &dirtyRect ); return hr;\t\n }\t\n The baselineOriginX, baslineOriginY, measuringMethod, and glyphRun parameters are provided (as arguments) when the callback method is invoked. The renderingParams, textColor and blackBoxRect are not.
Default rendering params can be retrieved by using the
Gets a handle to the memory device context.
\t\nReturns a device context handle to the memory device context.
An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();\t\n The
Gets the number of bitmap pixels per DIP.
\t\nThe number of bitmap pixels per DIP.
A DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
\t\nSets the number of bitmap pixels per DIP (device-independent pixel). A DIP is 1/96 inch, so this value is the number if pixels per inch divided by 96.
\t\nA value that specifies the number of pixels per DIP.
If this method succeeds, it returns
Gets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
\t\nWhen this method returns, contains a transform matrix.
If this method succeeds, it returns
Sets the transform that maps abstract coordinate to DIPs (device-independent pixel). This does not affect the world transform of the underlying device context.
\t\n Specifies the new transform. This parameter can be
If this method succeeds, it returns
Gets the dimensions of the target bitmap.
\t\nReturns the width and height of the bitmap in pixels.
If this method succeeds, it returns
Resizes the bitmap.
\t\nThe new bitmap width, in pixels.
The new bitmap height, in pixels.
If this method succeeds, it returns
Gets a handle to the memory device context.
\t\n An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle (
Note that this method takes no parameters and returns an
memoryHdc = g_pBitmapRenderTarget->GetMemoryDC();\t\n The
Gets or sets the number of bitmap pixels per DIP.
\t\nA DIP (device-independent pixel) is 1/96 inch. Therefore, this value is the number if pixels per inch divided by 96.
\t\nGets or sets the transform that maps abstract coordinates to DIPs. By default this is the identity transform. Note that this is unrelated to the world transform of the underlying device context.
\t\nGets the dimensions of the target bitmap.
\t\nWraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
\t\nWraps an application-defined inline graphic, allowing DWrite to query metrics as if the graphic were a glyph inline with the text.
\t\n The application implemented rendering callback (
If this method succeeds, it returns
If this method succeeds, it returns
TextLayout calls this callback function to get the visible extents (in DIPs) of the inline object. In the case of a simple bitmap, with no padding and no overhang, all the overhangs will simply be zeroes.
The overhangs should be returned relative to the reported size of the object (see
If this method succeeds, it returns
Layout uses this to determine the line-breaking behavior of the inline object among the text.
\t\nWhen this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately preceding it.
When this method returns, contains a value which indicates the line-breaking condition between the object and the content immediately following it.
If this method succeeds, it returns
Used to create all subsequent DirectWrite objects. This interface is the root factory interface for all DirectWrite objects.
\t\n Create an
if (SUCCEEDED(hr))\t\n { hr = ( , __uuidof(), reinterpret_cast<**>(&pDWriteFactory_) );\t\n } An
Gets an object which represents the set of installed fonts.
\t\nIf this parameter is nonzero, the function performs an immediate check for changes to the set of installed fonts. If this parameter is
When this method returns, contains the address of a reference to the system font collection object, or
Creates a font collection using a custom font collection loader.
\t\nAn application-defined font collection loader, which must have been previously registered using RegisterFontCollectionLoader.
The key used by the loader to identify a collection of font files. The buffer allocated for this key should at least be the size of collectionKeySize.
The size, in bytes, of the collection key.
Contains an address of a reference to the system font collection object if the method succeeds, or
If this method succeeds, it returns
Registers a custom font collection loader with the factory object.
\t\nPointer to a
If this method succeeds, it returns
This function registers a font collection loader with DirectWrite. The font collection loader interface, which should be implemented by a singleton object, handles enumerating font files in a font collection given a particular type of key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
\t\nUnregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader.
\t\nIf this method succeeds, it returns
Creates a font file reference object from a local font file.
\t\nAn array of characters that contains the absolute file path for the font file. Subsequent operations on the constructed object may fail if the user provided filePath doesn't correspond to a valid file on the disk.
The last modified time of the input file path. If the parameter is omitted, the function will access the font file to obtain its last write time. You should specify this value to avoid extra disk access. Subsequent operations on the constructed object may fail if the user provided lastWriteTime doesn't match the file on the disk.
When this method returns, contains an address of a reference to the newly created font file reference object, or
If this method succeeds, it returns
Creates a reference to an application-specific font file resource.
\t\nA font file reference key that uniquely identifies the font file resource during the lifetime of fontFileLoader.
The size of the font file reference key in bytes.
The font file loader that will be used by the font system to load data from the file identified by fontFileReferenceKey.
Contains an address of a reference to the newly created font file object when this method succeeds, or
If this method succeeds, it returns
This function is provided for cases when an application or a document needs to use a private font without having to install it on the system. fontFileReferenceKey has to be unique only in the scope of the fontFileLoader used in this call.
\t\nCreates an object that represents a font face.
\t\nA value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates an object that represents a font face.
\t\nA value that indicates the type of file format of the font face.
The number of font files, in element count, required to represent the font face.
A font file object representing the font face. Because
The zero-based index of a font face, in cases when the font files contain a collection of font faces. If the font files contain a single face, this value should be zero.
A value that indicates which, if any, font face simulation flags for algorithmic means of making text bold or italic are applied to the current font face.
When this method returns, contains an address of a reference to the newly created font face object, or
If this method succeeds, it returns
Creates a rendering parameters object with default settings for the primary monitor. Different monitors may have different rendering parameters, for more information see the How to Add Support for Multiple Monitors topic.
\t\nStandard
Creates a rendering parameters object with default settings for the specified monitor. In most cases, this is the preferred way to create a rendering parameters object.
\t\nA handle for the specified monitor.
When this method returns, contains an address of a reference to the rendering parameters object created by this method.
If this method succeeds, it returns
Creates a rendering parameters object with the specified properties.
\t\nThe gamma level to be set for the new rendering parameters object.
The enhanced contrast level to be set for the new rendering parameters object.
The ClearType level to be set for the new rendering parameters object.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text.
A value that represents the method (for example, ClearType natural quality) for rendering glyphs.
When this method returns, contains an address of a reference to the newly created rendering parameters object.
If this method succeeds, it returns
Registers a font file loader with DirectWrite.
\t\nPointer to a
If this method succeeds, it returns
This function registers a font file loader with DirectWrite. The font file loader interface, which should be implemented by a singleton object, handles loading font file resources of a particular type from a key. A given instance can only be registered once. Succeeding attempts will return an error, indicating that it has already been registered. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors, and must not unregister themselves inside their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration with DirectWrite of font file loaders should be performed outside of the font file loader implementation.
\t\nUnregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
\t\nIf this method succeeds, it returns
This function unregisters font file loader callbacks with the DirectWrite font system. You should implement the font file loader interface by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite should be performed outside of the font file loader implementation.
\t\nCreates a text format object used for text layout.
\t\nAn array of characters that contains the name of the font family
A reference to a font collection object. When this is
A value that indicates the font weight for the text object created by this method.
A value that indicates the font style for the text object created by this method.
A value that indicates the font stretch for the text object created by this method.
The logical size of the font in DIP (\"device-independent pixel\") units. A DIP equals 1/96 inch.
An array of characters that contains the locale name.
When this method returns, contains an address of a reference to a newly created text format object, or
If this method succeeds, it returns
Creates a typography object for use in a text layout.
\t\nWhen this method returns, contains the address of a reference to a newly created typography object, or
If this method succeeds, it returns
Creates an object that is used for interoperability with GDI.
\t\nWhen this method returns, contains an address of a reference to a GDI interop object if successful, or
If this method succeeds, it returns
Takes a string, text format, and associated constraints, and produces an object that represents the fully analyzed and formatted result.
\t\nAn array of characters that contains the string to create a new
The number of characters in the string.
A reference to an object that indicates the format to apply to the string.
The width of the layout box.
The height of the layout box.
When this method returns, contains an address of a reference to the resultant text layout object.
If this method succeeds, it returns
Takes a string, format, and associated constraints, and produces an object representing the result, formatted for a particular display resolution and measuring mode.
\t\nAn array of characters that contains the string to create a new
The length of the string, in character count.
The text formatting object to apply to the string.
The width of the layout box.
The height of the layout box.
The number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI device pixelsPerDip is 1. If rendering onto a 120 DPI device pixelsPerDip is 1.25 (120/96).
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specifies the font size and pixels per DIP.
Instructs the text layout to use the same metrics as GDI bi-level text when set to
When this method returns, contains an address to the reference of the resultant text layout object.
If this method succeeds, it returns
The resulting text layout should only be used for the intended resolution, and for cases where text scalability is desired CreateTextLayout should be used instead.
\t\nCreates an inline object for trimming, using an ellipsis as the omission sign.
\t\nA text format object, created with CreateTextFormat, used for text layout.
When this method returns, contains an address of a reference to the omission (that is, ellipsis trimming) sign created by this method.
If this method succeeds, it returns
The ellipsis will be created using the current settings of the format, including base font, style, and any effects. Alternate omission signs can be created by the application by implementing
Returns an interface for performing text analysis.
\t\nWhen this method returns, contains an address of a reference to the newly created text analyzer object.
If this method succeeds, it returns
Creates a number substitution object using a locale name, substitution method, and an indicator whether to ignore user overrides (use NLS defaults for the given culture instead).
\t\nA value that specifies how to apply number substitution on digits and related punctuation.
The name of the locale to be used in the numberSubstitution object.
A Boolean flag that indicates whether to ignore user overrides.
When this method returns, contains an address to a reference to the number substitution object created by this method.
If this method succeeds, it returns
Creates a glyph run analysis object, which encapsulates information used to render a glyph run.
\t\nA structure that contains the properties of the glyph run (font face, advances, and so on).
Number of physical pixels per DIP (device independent pixel). For example, if rendering onto a 96 DPI bitmap then pixelsPerDip is 1. If rendering onto a 120 DPI bitmap then pixelsPerDip is 1.25.
Optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified the emSize and pixelsPerDip.
A value that specifies the rendering mode, which must be one of the raster rendering modes (that is, not default and not outline).
Specifies the measuring mode to use with glyphs.
The horizontal position (X-coordinate) of the baseline origin, in DIPs.
Vertical position (Y-coordinate) of the baseline origin, in DIPs.
When this method returns, contains an address of a reference to the newly created glyph run analysis object.
If this method succeeds, it returns
The glyph run analysis object contains the results of analyzing the glyph run, including the positions of all the glyphs and references to all of the rasterized glyphs in the font cache.
\t\nCreates an object that is used for interoperability with GDI.
\t\nAn object that encapsulates a set of fonts, such as the set of fonts installed on the system, or the set of fonts in a particular directory. The font collection API can be used to discover what font families and fonts are available, and to obtain some metadata about the fonts.
\t\nThe
* pFontCollection = null ; // Get the system font collection.\t\n if (SUCCEEDED(hr))\t\n { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection);\t\n }\t\n
To determine what fonts are available on the system, get a reference to the system font collection. You can then use the
#include <dwrite.h>\t\n #include <string.h>\t\n #include <stdio.h>\t\n #include <new> // SafeRelease inline function.\t\n template <class T> inline void SafeRelease(T **ppT)\t\n { if (*ppT) { (*ppT)->Release(); *ppT = null ; }\t\n } void wmain()\t\n { * pDWriteFactory = null ; hr = ( , __uuidof(), reinterpret_cast<**>(&pDWriteFactory) ); * pFontCollection = null ; // Get the system font collection. if (SUCCEEDED(hr)) { hr = pDWriteFactory->GetSystemFontCollection(&pFontCollection); } UINT32 familyCount = 0; // Get the number of font families in the collection. if (SUCCEEDED(hr)) { familyCount = pFontCollection->GetFontFamilyCount(); } for (UINT32 i = 0; i < familyCount; ++i) { * pFontFamily = null ; // Get the font family. if (SUCCEEDED(hr)) { hr = pFontCollection->GetFontFamily(i, &pFontFamily); } * pFamilyNames = null ; // Get a list of localized strings for the family name. if (SUCCEEDED(hr)) { hr = pFontFamily->GetFamilyNames(&pFamilyNames); } UINT32 index = 0; exists = false; wchar_t localeName[LOCALE_NAME_MAX_LENGTH]; if (SUCCEEDED(hr)) { // Get the default locale for this user. int defaultLocaleSuccess = GetUserDefaultLocaleName(localeName, LOCALE_NAME_MAX_LENGTH); // If the default locale is returned, find that locale name, otherwise use \"en-us\". if (defaultLocaleSuccess) { hr = pFamilyNames->FindLocaleName(localeName, &index, &exists); } if (SUCCEEDED(hr) && !exists) // if the above find did not find a match, retry with US English { hr = pFamilyNames->FindLocaleName(L\"en-us\", &index, &exists); } } // If the specified locale doesn't exist, select the first on the list. if (!exists) index = 0; UINT32 length = 0; // Get the string length. if (SUCCEEDED(hr)) { hr = pFamilyNames->GetStringLength(index, &length); } // Allocate a string big enough to hold the name. wchar_t* name = new (std::nothrow) wchar_t[length+1]; if (name == null ) { hr = E_OUTOFMEMORY; } // Get the family name. if (SUCCEEDED(hr)) { hr = pFamilyNames->GetString(index, name, length+1); } if (SUCCEEDED(hr)) { // Print out the family name. wprintf(L\"%s\\n\", name); } SafeRelease(&pFontFamily); SafeRelease(&pFamilyNames); delete [] name; } SafeRelease(&pFontCollection); SafeRelease(&pDWriteFactory);\t\n } Gets the number of font families in the collection.
\t\nThe number of font families in the collection.
Creates a font family object given a zero-based font family index.
\t\nZero-based index of the font family.
When this method returns, contains the address of a reference to the newly created font family object.
Finds the font family with the specified family name.
\t\nAn array of characters, which is null-terminated, containing the name of the font family. The name is not case-sensitive but must otherwise exactly match a family name in the collection.
When this method returns, contains the zero-based index of the matching font family if the family name was found; otherwise, UINT_MAX.
When this method returns, TRUE if the family name exists; otherwise,
Gets the font object that corresponds to the same physical font as the specified font face object. The specified physical font must belong to the font collection.
\t\nA font face object that specifies the physical font.
When this method returns, contains the address of a reference to the newly created font object if successful; otherwise,
Gets the number of font families in the collection.
\t\nUsed to construct a collection of fonts given a particular type of key.
\t\nThe font collection loader interface is recommended to be implemented by a singleton object. Note that font collection loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
\t\nRepresents an absolute reference to a font face which contains font face type, appropriate file references, face identification data and various font data such as metrics, names and glyph outlines.
\t\nObtains the file format type of a font face.
\t\nA value that indicates the type of format for the font face (such as Type 1, TrueType, vector, or bitmap).
Obtains the font files representing a font face.
\t\nIf fontFiles is
When this method returns, contains a reference to a user-provided array that stores references to font files representing the font face. This parameter can be
If this method succeeds, it returns
The
Then, call the method a second time, passing the numberOfFiles value that was output the first call, and a non-null buffer of the correct size to store the
Obtains the index of a font face in the context of its font files.
\t\nThe zero-based index of a font face in cases when the font files contain a collection of font faces. If the font files contain a single face, this value is zero.
Obtains the algorithmic style simulation flags of a font face.
\t\nFont face simulation flags for algorithmic means of making text bold or italic.
Determines whether the font is a symbol font.
\t\nReturns TRUE if the font is a symbol font, otherwise
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
\t\nWhen this method returns, a?
Obtains the number of glyphs in the font face.
\t\nThe number of glyphs in the font face.
Obtains ideal (resolution-independent) glyph metrics in font design units.
\t\nAn array of glyph indices for which to compute metrics. The array must contain at least as many elements as specified by glyphCount.
The number of elements in the glyphIndices array.
When this method returns, contains an array of
Indicates whether the font is being used in a sideways run. This can affect the glyph metrics if the font has oblique simulation because sideways oblique simulation differs from non-sideways oblique simulation
If this method succeeds, it returns
Design glyph metrics are used for glyph positioning.
\t\nReturns the nominal mapping of UCS4 Unicode code points to glyph indices as defined by the font 'CMAP' table.
\t\nAn array of USC4 code points from which to obtain nominal glyph indices. The array must be allocated and be able to contain the number of elements specified by codePointCount.
The number of elements in the codePoints array.
When this method returns, contains a reference to an array of nominal glyph indices filled by this function.
If this method succeeds, it returns
Note that this mapping is primarily provided for line layout engines built on top of the physical font API. Because of OpenType glyph substitution and line layout character substitution, the nominal conversion does not always correspond to how a Unicode string will map to glyph indices when rendering using a particular font face. Also, note that Unicode variant selectors provide for alternate mappings for character to glyph. This call will always return the default variant.
\t\n Finds the specified OpenType font table if it exists and returns a reference to it. The function accesses the underlying font data through the
If this method succeeds, it returns
The context for the same tag may be different for each call, so each one must be held and released separately.
\t\nReleases the table obtained earlier from TryGetFontTable.
\t\nComputes the outline of a run of glyphs by calling back to the outline sink interface.
\t\nThe logical size of the font in DIP units. A DIP (\"device-independent pixel\") equals 1/96 inch.
An array of glyph indices. The glyphs are in logical order and the advance direction depends on the isRightToLeft parameter. The array must be allocated and be able to contain the number of elements specified by glyphCount.
An optional array of glyph advances in DIPs. The advance of a glyph is the amount to advance the position (in the direction of the baseline) after drawing the glyph. glyphAdvances contains the number of elements specified by glyphCount.
An optional array of glyph offsets, each of which specifies the offset along the baseline and offset perpendicular to the baseline of a glyph relative to the current pen position. glyphOffsets contains the number of elements specified by glyphCount.
The number of glyphs in the run.
If TRUE, the ascender of the glyph runs alongside the baseline. If
A client can render a vertical run by setting isSideways to TRUE and rotating the resulting geometry 90 degrees to the right using a transform. The isSideways and isRightToLeft parameters cannot both be true.
The visual order of the glyphs. If this parameter is
A reference to the interface that is called back to perform outline drawing operations.
If this method succeeds, it returns
Determines the recommended rendering mode for the font, using the specified size and rendering parameters.
\t\nThe logical size of the font in DIP units. A DIP (\"device-independent pixel\") equals 1/96 inch.
The number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96, this value is 1.0f. If the DPI is 120, this value is 120.0f/96.
The measuring method that will be used for glyphs in the font. Renderer implementations may choose different rendering modes for different measuring methods, for example:
A reference to an object that contains rendering settings such as gamma level, enhanced contrast, and ClearType level. This parameter is necessary in case the rendering parameters object overrides the rendering mode.
When this method returns, contains a value that indicates the recommended rendering mode to use.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a fontface and are used by applications for layout calculations.
\t\nThe logical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
A reference to a DWRITE_FONT_METRICS structure to fill in. The metrics returned by this function are in font design units.
Obtains glyph metrics in font design units with the return values compatible with what GDI would produce.
\t\nThe ogical size of the font in DIP units.
The number of physical pixels per DIP.
An optional transform applied to the glyphs and their positions. This transform is applied after the scaling specified by the font size and pixelsPerDip.
When set to
An array of glyph indices for which to compute the metrics.
The number of elements in the glyphIndices array.
An array of
A
Standard
Obtains the file format type of a font face.
\t\nObtains the index of a font face in the context of its font files.
\t\nObtains the algorithmic style simulation flags of a font face.
\t\nDetermines whether the font is a symbol font.
\t\nObtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
\t\nObtains the number of glyphs in the font face.
\t\nSpecifies properties used to identify and execute typographic features in the current font face.
\t\nA non-zero value generally enables the feature execution, while the zero value disables it. A feature requiring a selector uses this value to indicate the selector index.
The OpenType standard provides access to typographic features available in the font by means of a feature tag with the associated parameters. The OpenType feature tag is a 4-byte identifier of the registered name of a feature. For example, the 'kern' feature name tag is used to identify the 'Kerning' feature in OpenType font. Similarly, the OpenType feature tag for 'Standard Ligatures' and 'Fractions' is 'liga' and 'frac' respectively. Since a single run can be associated with more than one typographic features, the Text String API accepts typographic settings for a run as a list of features and are executed in the order they are specified.
The value of the tag member represents the OpenType name tag of the feature, while the param value represents additional parameter for the execution of the feature referred by the tag member. Both nameTag and parameter are stored as little endian, the same convention followed by GDI. Most features treat the Param value as a binary value that indicates whether to turn the execution of the feature on or off, with it being off by default in the majority of cases. Some features, however, treat this value as an integral value representing the integer index to the list of alternate results it may produce during the execution; for instance, the feature 'Stylistic Alternates' or 'salt' uses the parameter value as an index to the list of alternate substituting glyphs it could produce for a specified glyph.
\t\nThe feature OpenType name identifier.
The execution parameter of the feature.
Represents a font file. Applications such as font managers or font viewers can call
Obtains the reference to the reference key of a font file. The returned reference is valid until the font file object is released.
\t\nWhen this method returns, contains an address of a reference to the font file reference key. Note that the reference value is only valid until the font file object it is obtained from is released. This parameter is passed uninitialized.
When this method returns, contains the size of the font file reference key in bytes. This parameter is passed uninitialized.
If this method succeeds, it returns
Obtains the file loader associated with a font file object.
\t\nWhen this method returns, contains the address of a reference to the font file loader associated with the font file object.
If this method succeeds, it returns
Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system.
\t\nTRUE if the font type is supported by the font system; otherwise,
When this method returns, contains a value that indicates the type of the font file. Note that even if isSupportedFontType is
When this method returns, contains a value that indicates the type of the font face. If fontFileType is not equal to
When this method returns, contains the number of font faces contained in the font file.
If this method succeeds, it returns
Important??Certain font file types are recognized, but not supported by the font system. For example, the font system will recognize a file as a Type 1 font file but will not be able to construct a font face object from it. In such situations, Analyze will set isSupportedFontType output parameter to
Encapsulates a collection of font files. The font system uses this interface to enumerate font files when building a font collection.
\t\nHandles loading font file resources of a particular type from a font file reference key into a font file stream object.
\t\nThe font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
\t\nHandles loading font file resources of a particular type from a font file reference key into a font file stream object.
\t\nThe font file loader interface is recommended to be implemented by a singleton object. Note that font file loader implementations must not register themselves with DirectWrite factory inside their constructors and must not unregister themselves in their destructors, because registration and unregistraton operations increment and decrement the object reference count respectively. Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed outside of the font file loader implementation as a separate step.
\t\nCreates a font file stream object that encapsulates an open file resource.
\t\nA reference to a font file reference key that uniquely identifies the font file resource within the scope of the font loader being used. The buffer allocated for this key must at least be the size, in bytes, specified by fontFileReferenceKeySize.
The size of font file reference key, in bytes.
When this method returns, contains the address of a reference to the newly created
If this method succeeds, it returns
The resource is closed when the last reference to fontFileStream is released.
\t\nLoads font file data from a custom font file loader.
\t\nLoads font file data from a custom font file loader.
\t\nReads a fragment from a font file.
\t\nWhen this method returns, contains an address of a reference to the start of the font file fragment. This parameter is passed uninitialized.
The offset of the fragment, in bytes, from the beginning of the font file.
The size of the file fragment, in bytes.
When this method returns, contains the address of a reference to a reference to the client-defined context to be passed to ReleaseFileFragment.
If this method succeeds, it returns
Note that ReadFileFragment implementations must check whether the requested font file fragment is within the file bounds. Otherwise, an error should be returned from ReadFileFragment.
DirectWrite may invoke
Releases a fragment from a file.
\t\nA reference to the client-defined context of a font fragment returned from ReadFileFragment.
Obtains the total size of a file.
\t\nWhen this method returns, contains the total size of the file.
If this method succeeds, it returns
Implementing GetFileSize() for asynchronously loaded font files may require downloading the complete file contents. Therefore, this method should be used only for operations that either require a complete font file to be loaded (for example, copying a font file) or that need to make decisions based on the value of the file size (for example, validation against a persisted file size).
\t\nObtains the last modified time of the file.
\t\nWhen this method returns, contains the last modified time of the file in the format that represents the number of 100-nanosecond intervals since January 1, 1601 (UTC).
If this method succeeds, it returns
The \"last modified time\" is used by DirectWrite font selection algorithms to determine whether one font resource is more up to date than another one.
\t\nProvides interoperability with GDI, such as methods to convert a font face to a
Creates a font object that matches the properties specified by the
A structure containing a GDI-compatible font description.
When this method returns, contains an address of a reference to a newly created
If this method succeeds, it returns
Initializes a
An
When this method returns, contains a structure that receives a GDI-compatible font description.
When this method returns, contains TRUE if the specified font object is part of the system font collection; otherwise,
If this method succeeds, it returns
The conversion to a
Initializes a
An
When this method returns, contains a reference to a structure that receives a GDI-compatible font description.
If this method succeeds, it returns
The conversion to a
Creates an
A handle to a device context into which a font has been selected. It is assumed that the client has already performed font mapping and that the font selected into the device context is the actual font to be used for rendering glyphs.
Contains an address of a reference to the newly created font face object, or
This function is intended for scenarios in which an application wants to use GDI and Uniscribe 1.x for text layout and shaping, but DirectWrite for final rendering. This function assumes the client is performing text output using glyph indexes.
\t\nCreates an object that encapsulates a bitmap and memory DC (device context) which can be used for rendering glyphs.
\t\nA handle to the optional device context used to create a compatible memory DC (device context).
The width of the bitmap render target.
The height of the bitmap render target.
When this method returns, contains an address of a reference to the newly created
Contains the information needed by renderers to draw glyph runs. All coordinates are in device independent pixels (DIPs).
\t\nThe physical font face object to draw with.
The logical size of the font in DIPs (equals 1/96 inch), not points.
The number of glyphs in the glyph run.
A reference to an array of indices to render for the glyph run.
A reference to an array containing glyph advance widths for the glyph run.
A reference to an array containing glyph offsets for the glyph run.
If true, specifies that glyphs are rotated 90 degrees to the left and vertical metrics are used. Vertical writing is achieved by specifying isSideways = true and rotating the entire run 90 degrees to the right via a rotate transform.
The implicit resolved bidi level of the run. Odd levels indicate right-to-left languages like Hebrew and Arabic, while even levels indicate left-to-right languages like English and Japanese (when written horizontally). For right-to-left languages, the text origin is on the right, and text should be drawn to the left.
Contains low-level information used to render a glyph run.
\t\nThe alpha texture can be a bi-level alpha texture or a ClearType alpha texture.
A bi-level alpha texture contains one byte per pixel, therefore the size of the buffer for a bi-level texture will be the area of the texture bounds, in bytes. Each byte in a bi-level alpha texture created by CreateAlphaTexture is either set to DWRITE_ALPHA_MAX (that is, 255) or zero.
A ClearType alpha texture contains three bytes per pixel, therefore the size of the buffer for a ClearType alpha texture is three times the area of the texture bounds, in bytes.
\t\nGets the bounding rectangle of the physical pixels affected by the glyph run.
\t\nSpecifies the type of texture requested. If a bi-level texture is requested, the bounding rectangle includes only bi-level glyphs. Otherwise, the bounding rectangle includes only antialiased glyphs.
When this method returns, contains the bounding rectangle of the physical pixels affected by the glyph run, or an empty rectangle if there are no glyphs of the specified texture type.
Creates an alpha texture of the specified type for glyphs within a specified bounding rectangle.
\t\nA value that specifies the type of texture requested. This can be DWRITE_TEXTURE_BILEVEL_1x1 or
The bounding rectangle of the texture, which can be different than the bounding rectangle returned by GetAlphaTextureBounds.
When this method returns, contains the array of alpha values from the texture. The buffer allocated for this array must be at least the size of bufferSize.
The size of the alphaValues array, in bytes. The minimum size depends on the dimensions of the rectangle and the type of texture requested.
If this method succeeds, it returns
Gets alpha blending properties required for ClearType blending.
\t\nAn object that specifies the ClearType level and enhanced contrast, gamma, pixel geometry, and rendering mode. In most cases, the values returned by the output parameters of this method are based on the properties of this object, unless a GDI-compatible rendering mode was specified.
When this method returns, contains the gamma value to use for gamma correction.
When this method returns, contains the enhanced contrast value to be used for blending.
When this method returns, contains the ClearType level used in the alpha blending.
If this method succeeds, it returns
Contains additional properties related to those in
An array of characters containing the locale name associated with this run.
An array of characters containing the text associated with the glyphs.
The number of characters in UTF16 code-units. Note that this may be different than the number of glyphs.
An array of indices to the glyph indices array, of the first glyphs of all the glyph clusters of the glyphs to render.
Corresponding text position in the string this glyph run came from. This is relative to the beginning of the string represented by the
Line breakpoint characteristics of a character.
\t\nIndicates a breaking condition before the character.
Indicates a breaking condition after the character.
Indicates that the character is some form of whitespace, which may be meaningful for justification.
Indicates that the character is a soft hyphen, often used to indicate hyphenation points inside words.
Reserved for future use.
Represents a collection of strings indexed by locale name.
\t\nThe set of strings represented by an
A common use for the
* pFamilyNames = null ; // Get a list of localized strings for the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFontFamily->GetFamilyNames(&pFamilyNames);\t\n } UINT32 index = 0;\t\n exists = false; wchar_t localeName[LOCALE_NAME_MAX_LENGTH]; if (SUCCEEDED(hr))\t\n { // Get the default locale for this user. int defaultLocaleSuccess = GetUserDefaultLocaleName(localeName, LOCALE_NAME_MAX_LENGTH); // If the default locale is returned, find that locale name, otherwise use \"en-us\". if (defaultLocaleSuccess) { hr = pFamilyNames->FindLocaleName(localeName, &index, &exists); } if (SUCCEEDED(hr) && !exists) // if the above find did not find a match, retry with US English { hr = pFamilyNames->FindLocaleName(L\"en-us\", &index, &exists); }\t\n } // If the specified locale doesn't exist, select the first on the list.\t\n if (!exists) index = 0; UINT32 length = 0; // Get the string length.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetStringLength(index, &length);\t\n } // Allocate a string big enough to hold the name.\t\n wchar_t* name = new (std::nothrow) wchar_t[length+1];\t\n if (name == null )\t\n { hr = E_OUTOFMEMORY;\t\n } // Get the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetString(index, name, length+1);\t\n }\t\n Gets the number of language/string pairs.
\t\nThe number of language/string pairs.
Gets the zero-based index of the locale name/string pair with the specified locale name.
\t\nA null-terminated array of characters containing the locale name to look for.
The zero-based index of the locale name/string pair. This method initializes index to UINT_MAX.
When this method returns, contains TRUE if the locale name exists; otherwise,
Note that if the locale name does not exist, the return value is a success and the exists parameter is
UINT32 index = 0;\t\n exists = false; wchar_t localeName[LOCALE_NAME_MAX_LENGTH]; if (SUCCEEDED(hr))\t\n { // Get the default locale for this user. int defaultLocaleSuccess = GetUserDefaultLocaleName(localeName, LOCALE_NAME_MAX_LENGTH); // If the default locale is returned, find that locale name, otherwise use \"en-us\". if (defaultLocaleSuccess) { hr = pFamilyNames->FindLocaleName(localeName, &index, &exists); } if (SUCCEEDED(hr) && !exists) // if the above find did not find a match, retry with US English { hr = pFamilyNames->FindLocaleName(L\"en-us\", &index, &exists); }\t\n } // If the specified locale doesn't exist, select the first on the list.\t\n if (!exists) index = 0;\t\n Gets the length in characters (not including the null terminator) of the locale name with the specified index.
\t\nZero-based index of the locale name to be retrieved.
When this method returns, contains the length in characters of the locale name, not including the null terminator.
If this method succeeds, it returns
Copies the locale name with the specified index to the specified array.
\t\nZero-based index of the locale name to be retrieved.
When this method returns, contains a character array, which is null-terminated, that receives the locale name from the language/string pair. The buffer allocated for this array must be at least the size of size, in element count.
The size of the array in characters. The size must include space for the terminating null character.
If this method succeeds, it returns
Gets the length in characters (not including the null terminator) of the string with the specified index.
\t\nA zero-based index of the language/string pair.
The length in characters of the string, not including the null terminator, from the language/string pair.
If this method succeeds, it returns
Use GetStringLength to get the string length before calling the
UINT32 length = 0; // Get the string length.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetStringLength(index, &length);\t\n } // Allocate a string big enough to hold the name.\t\n wchar_t* name = new (std::nothrow) wchar_t[length+1];\t\n if (name == null )\t\n { hr = E_OUTOFMEMORY;\t\n } // Get the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetString(index, name, length+1);\t\n }\t\n Copies the string with the specified index to the specified array.
\t\nThe zero-based index of the language/string pair to be examined.
The null terminated array of characters that receives the string from the language/string pair. The buffer allocated for this array should be at least the size of size. GetStringLength can be used to get the size of the array before using this method.
The size of the array in characters. The size must include space for the terminating null character. GetStringLength can be used to get the size of the array before using this method.
If this method succeeds, it returns
The string returned must be allocated by the caller. You can get the size of the string by using the GetStringLength method prior to calling GetString, as shown in the following example.
UINT32 length = 0; // Get the string length.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetStringLength(index, &length);\t\n } // Allocate a string big enough to hold the name.\t\n wchar_t* name = new (std::nothrow) wchar_t[length+1];\t\n if (name == null )\t\n { hr = E_OUTOFMEMORY;\t\n } // Get the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetString(index, name, length+1);\t\n }\t\n Gets the number of language/string pairs.
\t\nHolds the appropriate digits and numeric punctuation for a specified locale.
\t\nDefines the pixel snapping properties such as pixels per DIP(device-independent pixel) and the current transform matrix of a text renderer.
\t\nRepresents text rendering settings such as ClearType level, enhanced contrast, and gamma correction for glyph rasterization and filtering.
An application typically obtains a rendering parameters object by calling the
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
\t\nReturns the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
The gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
\t\nGets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
\t\nReturns the amount of contrast enhancement. Valid values are greater than or equal to zero.
Enhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
\t\nGets the ClearType level of the rendering parameters object.
\t\nThe ClearType level of the rendering parameters object.
The ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
\t\nGets the pixel geometry of the rendering parameters object.
\t\nA value that indicates the type of pixel geometry used in the rendering parameters object.
Gets the rendering mode of the rendering parameters object.
\t\nA value that indicates the rendering mode of the rendering parameters object.
By default, the rendering mode is initialized to
Gets the gamma value used for gamma correction. Valid values must be greater than zero and cannot exceed 256.
\t\nThe gamma value is used for gamma correction, which compensates for the non-linear luminosity response of most monitors.
\t\nGets the enhanced contrast property of the rendering parameters object. Valid values are greater than or equal to zero.
\t\nEnhanced contrast is the amount to increase the darkness of text, and typically ranges from 0 to 1. Zero means no contrast enhancement.
\t\nGets the ClearType level of the rendering parameters object.
\t\nThe ClearType level represents the amount of ClearType ? that is, the degree to which the red, green, and blue subpixels of each pixel are treated differently. Valid values range from zero (meaning no ClearType, which is equivalent to grayscale anti-aliasing) to one (meaning full ClearType)
\t\nGets the pixel geometry of the rendering parameters object.
\t\nGets the rendering mode of the rendering parameters object.
\t\nBy default, the rendering mode is initialized to
Contains shaping output properties for an output glyph.
\t\nIndicates that the glyph has justification applied.
Indicates that the glyph is the start of a cluster.
Indicates that the glyph is a diacritic mark.
Indicates that the glyph is a word boundary with no visible space.
Reserved for future use.
This interface is implemented by the text analyzer's client to receive the output of a given text analysis.
\t\nThe text analyzer disregards any current state of the analysis sink, therefore, a Set method call on a range overwrites the previously set analysis result of the same range.
\t\nImplemented by the text analyzer's client to provide text to the analyzer. It allows the separation between the logical view of text as a continuous stream of characters identifiable by unique text positions, and the actual memory layout of potentially discrete blocks of text in the client's backing store.
\t\nIf any of these callbacks returns an error, then the analysis functions will stop prematurely and return a callback error. Note that rather than return E_NOTIMPL, an application should stub the method and return a constant/null and
Analyzes various text properties for complex script processing such as bidirectional (bidi) support for languages like Arabic, determination of line break opportunities, glyph placement, and number substitution.
\t\nAnalyzes a text range for script boundaries, reading text attributes from the source and reporting the Unicode script ID to the sink callback SetScript.
\t\nIf this method succeeds, it returns
Analyzes a text range for script directionality, reading attributes from the source and reporting levels to the sink callback SetBidiLevel.
\t\nIf this method succeeds, it returns
While the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs. Otherwise, the returned levels may be wrong, because the Bidi algorithm is meant to apply to the paragraph as a whole.
\t\nAnalyzes a text range for spans where number substitution is applicable, reading attributes from the source and reporting substitutable ranges to the sink callback SetNumberSubstitution.
\t\nIf this method succeeds, it returns
Although the function can handle multiple ranges of differing number substitutions, the text ranges should not arbitrarily split the middle of numbers. Otherwise, it will treat the numbers separately and will not translate any intervening punctuation.
\t\nAnalyzes a text range for potential breakpoint opportunities, reading attributes from the source and reporting breakpoint opportunities to the sink callback SetLineBreakpoints.
\t\nIf this method succeeds, it returns
Although the function can handle multiple paragraphs, the text range should not arbitrarily split the middle of paragraphs, unless the specified text span is considered a whole unit. Otherwise, the returned properties for the first and last characters will inappropriately allow breaks.
\t\nParses the input text string and maps it to the set of glyphs and associated glyph data according to the font and the writing system's rendering rules.
\t\nAn array of characters to convert to glyphs.
The length of textString.
The font face that is the source of the output glyphs.
A Boolean flag set to TRUE if the text is intended to be drawn vertically.
A Boolean flag set to TRUE for right-to-left text.
A reference to a Script analysis result from an AnalyzeScript call.
The locale to use when selecting glyphs. For example the same character may map to different glyphs for ja-jp versus zh-chs. If this is
A reference to an optional number substitution which selects the appropriate glyphs for digits and related numeric characters, depending on the results obtained from AnalyzeNumberSubstitution. Passing
An array of references to the sets of typographic features to use in each feature range.
The length of each feature range, in characters. The sum of all lengths should be equal to textLength.
The number of feature ranges.
The maximum number of glyphs that can be returned.
When this method returns, contains the mapping from character ranges to glyph ranges.
When this method returns, contains a reference to an array of structures that contains shaping properties for each character.
The output glyph indices.
When this method returns, contains a reference to an array of structures that contain shaping properties for each output glyph.
When this method returns, contains the actual number of glyphs returned if the call succeeds.
If this method succeeds, it returns
Note that the mapping from characters to glyphs is, in general, many-to-many. The recommended estimate for the per-glyph output buffers is (3 * textLength / 2 + 16). This is not guaranteed to be sufficient. The value of the actualGlyphCount parameter is only valid if the call succeeds. In the event that maxGlyphCount is not big enough, HRESULT_FROM_WIN32(
Places glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
\t\nIf this method succeeds, it returns
Place glyphs output from the GetGlyphs method according to the font and the writing system's rendering rules.
\t\nIf this method succeeds, it returns
The
To get a reference to the
if (SUCCEEDED(hr))\t\n { hr = pDWriteFactory_->CreateTextFormat( L\"Gabriola\", null , , , , 72.0f, L\"en-us\", &pTextFormat_ );\t\n } When creating an
These properties cannot be changed after the
The
To draw text with multiple formats, or to use a custom text renderer, use the
This object may not be thread-safe, and it may carry the state of text format change.
DirectWrite and Direct2D To draw simple text with a single format, Direct2D provides the
Sets trimming options for text overflowing the layout width.
\t\nText trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the alignment of text in a paragraph, relative to the leading and trailing edge of a layout box for a
This method can return one of the following values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| The textAlignment argument is invalid. |
?
The text can be aligned to the leading or trailing edge of the layout box, or it can be centered. The following illustration shows text with the alignment set to
Note??The alignment is dependent on reading direction, the above is for left-to-right reading direction. For right-to-left reading direction it would be the opposite.
See
Sets the alignment option of a paragraph relative to the layout box's top and bottom edge.
\t\nThe paragraph alignment option being set for a paragraph; see
If this method succeeds, it returns
Sets the word wrapping option.
\t\nThe word wrapping option being set for a paragraph; see
If this method succeeds, it returns
Sets the paragraph reading direction.
\t\nThe text reading direction (for example,
If this method succeeds, it returns
Sets the paragraph flow direction.
\t\nThe paragraph flow direction; see
If this method succeeds, it returns
Sets a fixed distance between two adjacent tab stops.
\t\nThe fixed distance between two adjacent tab stops.
If this method succeeds, it returns
Sets trimming options for text overflowing the layout width.
\t\nText trimming options.
Application-defined omission sign. This parameter may be
If this method succeeds, it returns
Sets the line spacing.
\t\nSpecifies how line height is being determined; see
The line height, or distance between one baseline to another.
The distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
For the default method, spacing depends solely on the content. For uniform spacing, the specified line height overrides the content.
\t\nGets the alignment option of text relative to the layout box's leading and trailing edge.
\t\nReturns the text alignment option of the current paragraph.
Gets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
\t\nA value that indicates the current paragraph alignment option.
Gets the word wrapping option.
\t\nReturns the word wrapping option; see
Gets the current reading direction for text in a paragraph.
\t\nA value that indicates the current reading direction for text in a paragraph.
Gets the direction that text lines flow.
\t\nThe direction that text lines flow within their parent container. For example,
Gets the incremental tab stop position.
\t\nThe incremental tab stop value.
Gets the trimming options for text that overflows the layout box.
\t\nWhen this method returns, it contains a reference to a
When this method returns, contains an address of a reference to a trimming omission sign. This parameter may be
If this method succeeds, it returns
Gets the line spacing adjustment set for a multiline text paragraph.
\t\nA value that indicates how line height is determined.
When this method returns, contains the line height, or distance between one baseline to another.
When this method returns, contains the distance from top of line to baseline. A reasonable ratio to lineSpacing is 80 percent.
If this method succeeds, it returns
Gets the current font collection.
\t\nWhen this method returns, contains an address of a reference to the font collection being used for the current text.
If this method succeeds, it returns
Gets the length of the font family name.
\t\nThe size of the character array, in character count, not including the terminated
Gets a copy of the font family name.
\t\nWhen this method returns, contains a reference to a character array, which is null-terminated, that receives the current font family name. The buffer allocated for this array should be at least the size, in elements, of nameSize.
The size of the fontFamilyName character array, in character count, including the terminated
If this method succeeds, it returns
Gets the font weight of the text.
\t\nA value that indicates the type of weight (such as normal, bold, or black).
Gets the font style of the text.
\t\nA value which indicates the type of font style (such as slope or incline).
Gets the font stretch of the text.
\t\nA value which indicates the type of font stretch (such as normal or condensed).
Gets the font size in DIP unites.
\t\nThe current font size in DIP units.
Gets the length of the locale name.
\t\nThe size of the character array in character count, not including the terminated
Gets a copy of the locale name.
\t\nContains a character array that receives the current locale name.
The size of the character array, in character count, including the terminated
If this method succeeds, it returns
Gets or sets the alignment option of text relative to the layout box's leading and trailing edge.
\t\nGets or sets the alignment option of a paragraph which is relative to the top and bottom edges of a layout box.
\t\nGets or sets the word wrapping option.
\t\nGets or sets the current reading direction for text in a paragraph.
\t\nGets or sets the direction that text lines flow.
\t\nGets or sets the incremental tab stop position.
\t\nGets the current font collection.
\t\nGets the font weight of the text.
\t\nGets the font style of the text.
\t\nGets the font stretch of the text.
\t\nGets the font size in DIP unites.
\t\nThe
To get a reference to the
// Create a text layout using the text format.\t\n if (SUCCEEDED(hr))\t\n { rect; GetClientRect(hwnd_, &rect); float width = rect.right / dpiScaleX_; float height = rect.bottom / dpiScaleY_; hr = pDWriteFactory_->CreateTextLayout( wszText_, // The string to be laid out and formatted. cTextLength_, // The length of the string. pTextFormat_, // The text format to apply to the string (contains font information, etc). width, // The width of the layout box. height, // The height of the layout box. &pTextLayout_ // The interface reference. );\t\n } The
// Set the font weight to bold for the first 5 letters.\t\n textRange = {0, 4}; if (SUCCEEDED(hr))\t\n { hr = pTextLayout_->SetFontWeight(, textRange);\t\n } To draw the block of text represented by an
To draw a formatted string represented by an
To render using a custom renderer, use the
// Draw the text layout using DirectWrite and the CustomTextRenderer class.\t\n hr = pTextLayout_->Draw( null , pTextRenderer_, // Custom text renderer. origin.x, origin.y );
Using a custom text renderer also enables you to render using another technology, such as GDI.
\t\nSets the layout maximum width.
\t\nA value that indicates the maximum width of the layout box.
If this method succeeds, it returns
Sets the layout maximum height.
\t\nA value that indicates the maximum height of the layout box.
If this method succeeds, it returns
Sets the font collection.
\t\nThe font collection to set.
Text range to which this change applies.
If this method succeeds, it returns
Sets null-terminated font family name for text within a specified text range.
\t\nThe font family name that applies to the entire text string within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font weight for text within a text range specified by a
If this method succeeds, it returns
The font weight can be set to one of the predefined font weight values provided in the
The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
\t\n Sets the font style for text within a text range specified by a
If this method succeeds, it returns
The font style can be set to Normal, Italic or Oblique. The following illustration shows three styles for the Palatino font. For more information, see
Sets the font stretch for text within a specified text range.
\t\nA value which indicates the type of font stretch for text within the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the font size in DIP units for text within a specified text range.
\t\nThe font size in DIP units to be set for text in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets underlining for text within a specified text range.
\t\nA Boolean flag that indicates whether underline takes place within a specified text range.
Text range to which this change applies.
If this method succeeds, it returns
Sets strikethrough for text within a specified text range.
\t\nA Boolean flag that indicates whether strikethrough takes place in the range specified by textRange.
Text range to which this change applies.
If this method succeeds, it returns
Sets the application-defined drawing effect.
\t\nApplication-defined drawing effects that apply to the range. This data object will be passed back to the application's drawing callbacks for final rendering.
The text range to which this change applies.
If this method succeeds, it returns
An
This drawing effect is associated with the specified range and will be passed back to the application by way of the callback when the range is drawn at drawing time.
\t\nSets the inline object.
\t\nAn application-defined inline object.
Text range to which this change applies.
If this method succeeds, it returns
The application may call this function to specify the set of properties describing an application-defined inline object for specific range.
This inline object applies to the specified range and will be passed back to the application by way of the DrawInlineObject callback when the range is drawn. Any text in that range will be suppressed.
\t\nSets font typography features for text within a specified text range.
\t\nPointer to font typography settings.
Text range to which this change applies.
If this method succeeds, it returns
Sets the locale name for text within a specified text range.
\t\nA null-terminated locale name string.
Text range to which this change applies.
If this method succeeds, it returns
Gets the layout maximum width.
\t\nReturns the layout maximum width.
Gets the layout maximum height.
\t\nThe layout maximum height.
Gets the font collection associated with the text at the specified position.
\t\nThe position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
Contains an address of a reference to the current font collection.
Get the length of the font family name at the current position.
\t\nThe current text position.
When this method returns, contains the size of the character array containing the font family name, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family.
If this method succeeds, it returns
Copies the font family name of the text at the specified position.
\t\nThe position of the text to examine.
When this method returns, contains an array of characters that receives the current font family name. You must allocate storage for this parameter.
The size of the character array in character count including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font family name.
If this method succeeds, it returns
Gets the font weight of the text at the specified position.
\t\nThe position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font weight.
When this method returns, contains a value which indicates the type of font weight being applied at the specified position.
Gets the font style (also known as slope) of the text at the specified position.
\t\nThe position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font style.
When this method returns, contains a value which indicates the type of font style (also known as slope or incline) being applied at the specified position.
Gets the font stretch of the text at the specified position.
\t\nThe position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font stretch.
When this method returns, contains a value which indicates the type of font stretch (also known as width) being applied at the specified position.
Gets the font em height of the text at the specified position.
\t\nThe position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the font size.
When this method returns, contains the size of the font in ems of the text at the specified position.
Gets the underline presence of the text at the specified position.
\t\nThe current text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the underline.
A Boolean flag that indicates whether underline is present at the position indicated by currentPosition.
Get the strikethrough presence of the text at the specified position.
\t\nThe position of the text to inspect.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to strikethrough.
A Boolean flag that indicates whether strikethrough is present at the position indicated by currentPosition.
Gets the application-defined drawing effect at the specified text position.
\t\nThe position of the text whose drawing effect is to be retrieved.
Contains the range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the drawing effect.
When this method returns, contains an address of a reference to the current application-defined drawing effect. Usually this effect is a foreground brush that is used in glyph drawing.
Gets the inline object at the specified position.
\t\nThe specified text position.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the inline object.
Contains the application-defined inline object.
Gets the typography setting of the text at the specified position.
\t\nThe position of the text to inspect.
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the typography.
When this method returns, contains an address of a reference to the current typography setting.
Gets the length of the locale name of the text at the specified position.
\t\nThe position of the text to inspect.
Size of the character array, in character count, not including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Gets the locale name of the text at the specified position.
\t\nThe position of the text to inspect.
When this method returns, contains the character array receiving the current locale name.
Size of the character array, in character count, including the terminated
The range of text that has the same formatting as the text at the position specified by currentPosition. This means the run has the exact formatting as the position specified, including but not limited to the locale name.
If this method succeeds, it returns
Draws text using the specified client drawing context.
\t\nAn application-defined drawing context.
Pointer to the set of callback functions used to draw parts of a text string.
The x-coordinate of the layout's left side.
The y-coordinate of the layout's top side.
If this method succeeds, it returns
To draw text with this method, a textLayout object needs to be created by the application using
After the textLayout object is obtained, the application calls the
Retrieves the information about each individual text line of the text string.
\t\nWhen this method returns, contains a reference to an array of structures containing various calculated length values of individual text lines.
The maximum size of the lineMetrics array.
When this method returns, contains the actual size of the lineMetrics array that is needed.
If this method succeeds, it returns
If maxLineCount is not large enough E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Retrieves overall metrics for the formatted string.
\t\nWhen this method returns, contains the measured distances of text and associated content after being formatted.
If this method succeeds, it returns
Returns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
\t\nOvershoots of visible extents (in DIPs) outside the layout.
If this method succeeds, it returns
Underlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
\t\nRetrieves logical properties and measurements of each glyph cluster.
\t\nWhen this method returns, contains metrics, such as line-break or total advance width, for a glyph cluster.
The maximum size of the clusterMetrics array.
When this method returns, contains the actual size of the clusterMetrics array that is needed.
If this method succeeds, it returns
If maxClusterCount is not large enough, then E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
Determines the minimum possible width the layout can be set to without emergency breaking between the characters of whole words occurring.
\t\nMinimum width.
The application calls this function passing in a specific pixel location relative to the top-left location of the layout box and obtains the information about the correspondent hit-test metrics of the text string where the hit-test has occurred. When the specified pixel location is outside the text string, the function sets the output value *isInside to
The pixel location X to hit-test, relative to the top-left location of the layout box.
The pixel location Y to hit-test, relative to the top-left location of the layout box.
An output flag that indicates whether the hit-test location is at the leading or the trailing side of the character. When the output *isInside value is set to
An output flag that indicates whether the hit-test location is inside the text string. When
The output geometry fully enclosing the hit-test location. When the output *isInside value is set to
The application calls this function to get the pixel location relative to the top-left of the layout box given the text position and the logical side of the position. This function is normally used as part of caret positioning of text where the caret is drawn at the location corresponding to the current text editing position. It may also be used as a way to programmatically obtain the geometry of a particular text position in UI automation.
\t\nThe text position used to get the pixel location.
A Boolean flag that indicates whether the pixel location is of the leading or the trailing side of the specified text position.
When this method returns, contains the output pixel location X, relative to the top-left location of the layout box.
When this method returns, contains the output pixel location Y, relative to the top-left location of the layout box.
When this method returns, contains the output geometry fully enclosing the specified text position.
The application calls this function to get a set of hit-test metrics corresponding to a range of text positions. One of the main usages is to implement highlight selection of the text string. The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(
The first text position of the specified range.
The number of positions of the specified range.
The origin pixel location X at the left of the layout box. This offset is added to the hit-test metrics returned.
The origin pixel location Y at the top of the layout box. This offset is added to the hit-test metrics returned.
When this method returns, contains a reference to a buffer of the output geometry fully enclosing the specified position range. The buffer must be at least as large as maxHitTestMetricsCount.
Maximum number of boxes hitTestMetrics could hold in its buffer memory.
Actual number of geometries hitTestMetrics holds in its buffer memory.
If this method succeeds, it returns
Gets or sets the layout maximum width.
\t\nGets or sets the layout maximum height.
\t\nRetrieves overall metrics for the formatted string.
\t\nReturns the overhangs (in DIPs) of the layout and all objects contained in it, including text glyphs and inline objects.
\t\nUnderlines and strikethroughs do not contribute to the black box determination, since these are actually drawn by the renderer, which is allowed to draw them in any variety of styles.
\t\nSpecifies a range of text positions where format is applied in the text represented by an
Represents a set of application-defined callbacks that perform rendering of text, inline objects, and decorations such as underlines.
\t\nRepresents a bitmap that has been bound to an
To create a bitmap, use one of the following methods of the render target on which the bitmap will be drawn:
For information about the pixel formats supported by Direct2D bitmaps, see Supported Pixel Formats and Alpha Modes.
An
Returns the size, in device-independent pixels (DIPs), of the bitmap.
\t\nThe size, in DIPs, of the bitmap.
A DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
\t\nThe size, in pixels, of the bitmap.
Retrieves the pixel format and alpha mode of the bitmap.
\t\nThe pixel format and alpha mode of the bitmap.
Return the dots per inch (DPI) of the bitmap.
\t\nThe horizontal DPI of the image. You must allocate storage for this parameter.
The vertical DPI of the image. You must allocate storage for this parameter.
Copies the specified region from the specified bitmap into the current bitmap.
\t\nIn the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The bitmap to copy from.
The area of bitmap to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Copies the specified region from the specified render target into the current bitmap.
\t\nIn the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The render target that contains the region to copy.
The area of renderTarget to copy.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion, and will fail if the bitmap formats do not match.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
All clips and layers must be popped off of the render target before calling this method. The method returns
Copies the specified region from memory into the current bitmap.
\t\nIn the current bitmap, the upper-left corner of the area to which the region specified by srcRect is copied.
The data to copy.
The stride, or pitch, of the source bitmap stored in srcData. The stride is the byte count of a scanline (one row of pixels in memory). The stride can be computed from the following formula: pixel width * bytes per pixel + memory padding.
If this method succeeds, it returns
This method does not update the size of the current bitmap. If the contents of the source bitmap do not fit in the current bitmap, this method fails. Also, note that this method does not perform format conversion; the two bitmap formats should match.
If this method is passed invalid input (such as an invalid destination rectangle), can produce unpredictable results, such as a distorted image or device failure.
Calling this method may cause the current batch to flush if the bitmap is active in the batch. If the batch that was flushed does not complete successfully, this method fails. However, this method does not clear the error state of the render target on which the batch was flushed. The failing
Returns the size, in device-independent pixels (DIPs), of the bitmap.
\t\nA DIP is 1/96?of an inch. To retrieve the size in device pixels, use the
Returns the size, in device-dependent units (pixels), of the bitmap.
\t\nRetrieves the pixel format and alpha mode of the bitmap.
\t\nPaints an area with a bitmap.
\t\nA bitmap brush is used to fill a geometry with a bitmap. Like all brushes, it defines an infinite plane of content. Because bitmaps are finite, the brush relies on an \"extend mode\" to determine how the plane is filled horizontally and vertically.
CreatingTo create a bitmap brush, use the
An
Defines an object that paints an area. Interfaces that derive from
An
Brush space in Direct2D is specified differently than in XPS and Windows Presentation Foundation (WPF). In Direct2D, brush space is not relative to the object being drawn, but rather is the current coordinate system of the render target, transformed by the brush transform, if present. To paint an object as it would be painted by a WPF brush, you must translate the brush space origin to the upper-left corner of the object's bounding box, and then scale the brush space so that the base tile fills the bounding box of the object.
For more information about brushes, see the Brushes Overview.
\t\nSets the degree of opacity of this brush.
\t\nA value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Sets the transformation applied to the brush.
\t\nThe transformation to apply to this brush.
When you paint with a brush, it paints in the coordinate space of the render target. Brushes do not automatically position themselves to align with the object being painted; by default, they begin painting at the origin (0, 0) of the render target.
You can \"move\" the gradient defined by an
To align the content of an
The following illustrations show the effect of using an
The illustration on the right shows the result of transforming the
Gets the degree of opacity of this brush.
\t\nA value between zero and 1 that indicates the opacity of the brush. This value is a constant multiplier that linearly scales the alpha value of all pixels filled by the brush. The opacity values are clamped in the range 0?1 before they are multipled together.
Gets the transform applied to this brush.
\t\nThe transform applied to this brush.
When the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
\t\nGets or sets the degree of opacity of this brush.
\t\nGets or sets the transform applied to this brush.
\t\nWhen the brush transform is the identity matrix, the brush appears in the same coordinate space as the render target in which it is drawn.
\t\nSpecifies how the brush horizontally tiles those areas that extend past its bitmap.
\t\nA value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies how the brush vertically tiles those areas that extend past its bitmap.
\t\nA value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Sometimes, the bitmap for a bitmap brush doesn't completely fill the area being painted. When this happens, Direct2D uses the brush's horizontal (SetExtendModeX) and vertical (SetExtendModeY) extend mode settings to determine how to fill the remaining area.
The following illustration shows the results from every possible combination of the extend modes for an
Specifies the interpolation mode used when the brush bitmap is scaled or rotated.
\t\nThe interpolation mode used when the brush bitmap is scaled or rotated.
This method sets the interpolation mode for a bitmap, which is an enum value that is specified in the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, bilinear interpolation positions the bitmap more precisely to the application requests, but blurs the bitmap in the process.
\t\nSpecifies the bitmap source that this brush uses to paint.
\t\nThe bitmap source used by the brush.
This method specifies the bitmap source that this brush uses to paint. The bitmap is not resized or rescaled automatically to fit the geometry that it fills. The bitmap stays at its native size. To resize or translate the bitmap, use the SetTransform method to apply a transform to the brush.
The native size of a bitmap is the width and height in bitmap pixels, divided by the bitmap DPI. This native size forms the base tile of the brush. To tile a subregion of the bitmap, you must generate a new bitmap containing this subregion and use SetBitmap to apply it to the brush. \t\n
\t\nGets the method by which the brush horizontally tiles those areas that extend past its bitmap.
\t\nA value that specifies how the brush horizontally tiles those areas that extend past its bitmap.
Like all brushes,
Gets the method by which the brush vertically tiles those areas that extend past its bitmap.
\t\nA value that specifies how the brush vertically tiles those areas that extend past its bitmap.
Like all brushes,
Gets the interpolation method used when the brush bitmap is scaled or rotated.
\t\nThe interpolation method used when the brush bitmap is scaled or rotated.
This method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
\t\nGets the bitmap source that this brush uses to paint.
\t\nWhen this method returns, contains the address to a reference to the bitmap with which this brush paints.
Gets or sets the method by which the brush horizontally tiles those areas that extend past its bitmap.
\t\nLike all brushes,
Gets or sets the method by which the brush vertically tiles those areas that extend past its bitmap.
\t\nLike all brushes,
Gets or sets the interpolation method used when the brush bitmap is scaled or rotated.
\t\nThis method gets the interpolation mode of a bitmap, which is specified by the
The interpolation mode of a bitmap also affects subpixel translations. In a subpixel translation, linear interpolation positions the bitmap more precisely to the application request, but blurs the bitmap in the process.
\t\nGets or sets the bitmap source that this brush uses to paint.
\t\nDescribes the pixel format and dpi of a bitmap.
\t\nThe bitmap's pixel format and alpha mode.
The horizontal dpi of the bitmap.
The vertical dpi of the bitmap.
Renders to an intermediate texture created by the CreateCompatibleRenderTarget method.
\t\nAn
To write directly to a WIC bitmap instead, use the
To create a bitmap render target, call the
Like other render targets, an
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
\t\nWhen this method returns, contains the address of a reference to the bitmap for this render target. This bitmap can be used for drawing operations.
If this method succeeds, it returns
The DPI for the
Retrieves the bitmap for this render target. The returned bitmap can be used for drawing operations.
\t\nThe DPI for the
Gets the number of OpenType font features for the current font.
\t\nA single run of text can be associated with more than one typographic feature. The
Adds an OpenType font feature.
\t\nA structure that contains the OpenType name identifier and the execution parameter for the font feature being added.
If this method succeeds, it returns
Gets the number of OpenType font features for the current font.
\t\nThe number of font features for the current text format.
A single run of text can be associated with more than one typographic feature. The
Gets the font feature at the specified index.
\t\nThe zero-based index of the font feature to retrieve.
When this method returns, contains the font feature which is at the specified index.
A single run of text can be associated with more than one typographic feature. The
Gets the number of OpenType font features for the current font.
\t\nA single run of text can be associated with more than one typographic feature. The
Contains the center point, x-radius, and y-radius of an ellipse.
\t\nThe center point of the ellipse.
The X-radius of the ellipse.
The Y-radius of the ellipse.
Provides access to an device context that can accept GDI drawing commands.
\t\nYou don't create an
Not all render targets support the
Note that the QueryInterface method always succeeds; if the render target doesn't support the
To test whether a given render target supports the
Retrieves the device context associated with this render target.
\t\nA value that specifies whether the device context should be cleared.
When this method returns, contains the device context associated with this render target. You must allocate storage for this parameter.
Calling this method flushes the render target.
This command can be called only after BeginDraw and before EndDraw. It should not be called between PushAxisAlignedClip/PopAxisAlignedClip commands or between PushLayer/PopLayer.
ReleaseDC must be called once for each call to GetDC.
\t\nIndicates that drawing with the device context retrieved using the GetDC method is finished.
\t\nIf this method succeeds, it returns
ReleaseDC must be called once for each call to GetDC.
\t\nIndicates the condition at the edges of inline object or text used to determine line-breaking behavior.
\t\nIndicates whether a break is allowed by determining the condition of the neighboring text span or inline object.
Indicates that a line break is allowed, unless overruled by the condition of the neighboring text span or inline object, either prohibited by a \"may not break\" condition or forced by a \"must break\" condition.\t\t\t\t
Indicates that there should be no line break, unless overruled by a \"must break\" condition from the neighboring text span or inline object.\t\t
Indicates that the line break must happen, regardless of the condition of the adjacent text span or inline object.\t\t\t
Specifies the type of DirectWrite factory object.
\t\nA DirectWrite factory object contains information about its internal state, such as font loader registration and cached font data. In most cases you should use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state information, thereby reducing memory usage. However, there are cases when it is desirable to reduce the impact of a component on the rest of the process, such as a plug-in from an untrusted source, by sandboxing and isolating it from the rest of the process components. In such cases, you should use an isolated factory for the sandboxed component.
\t\nIndicates that the DirectWrite factory is a shared factory and that it allows for the reuse of cached font data across multiple in-process components. Such factories also take advantage of cross process font caching components for better performance.
Indicates that the DirectWrite factory object is isolated. Objects created from the isolated factory do not interact with internal DirectWrite state from other components.
Indicates the direction of flow for placing lines of text in a paragraph.
\t\nSpecifies that text lines are placed from top to bottom.
Indicates the file format of a complete font face.
\t\nFont formats that consist of multiple files, such as Type 1 .PFM and .PFB, have a single enum entry.
\t\nOpenType font face with CFF outlines.
OpenType font face with TrueType outlines.
OpenType font face that is a part of a TrueType collection.
A Type 1 font face.
A vector .FON format font face.
A bitmap .FON format font face.
Font face type is not recognized by the DirectWrite font system.
A value that indicates the typographic feature of text supplied by the font.
\t\nReplaces figures separated by a slash with an alternative form.
Equivalent OpenType tag: 'afrc'
Turns capital characters into petite capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in petite-cap form to avoid disrupting the flow of text. See the pcap feature description for notes on the relationship of caps, smallcaps and petite caps.
Equivalent OpenType tag: 'c2pc'
Turns capital characters into small capitals. It is generally used for words which would otherwise be set in all caps, such as acronyms, but which are desired in small-cap form to avoid disrupting the flow of text.
Equivalent OpenType tag: 'c2sc'
In specified situations, replaces default glyphs with alternate forms which provide better joining behavior. Used in script typefaces which are designed to have some or all of their glyphs join.
Equivalent OpenType tag: 'calt'
Shifts various punctuation marks up to a position that works better with all-capital sequences or sets of lining figures; also changes oldstyle figures to lining figures. By default, glyphs in a text face are designed to work with lowercase characters. Some characters should be shifted vertically to fit the higher visual center of all-capital or lining text. Also, lining figures are the same height (or close to it) as capitals, and fit much better with all-capital text.
Equivalent OpenType tag: 'case'
To minimize the number of glyph alternates, it is sometimes desired to decompose a character into two glyphs. Additionally, it may be preferable to compose two characters into a single glyph for better glyph processing. This feature permits such composition/decomposition. The feature should be processed as the first feature processed, and should be processed only when it is called.
Equivalent OpenType tag: 'ccmp'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. Unlike other ligature features, clig specifies the context in which the ligature is recommended. This capability is important in some script designs and for swash ligatures.
Equivalent OpenType tag: 'clig'
Globally adjusts inter-glyph spacing for all-capital text. Most typefaces contain capitals and lowercase characters, and the capitals are positioned to work with the lowercase. When capitals are used for words, they need more space between them for legibility and esthetics. This feature would not apply to monospaced designs. Of course the user may want to override this behavior in order to do more pronounced letterspacing for esthetic reasons.
Equivalent OpenType tag: 'cpsp'
Replaces default character glyphs with corresponding swash glyphs in a specified context. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'cswh'
In cursive scripts like Arabic, this feature cursively positions adjacent glyphs.
Equivalent OpenType tag: 'curs'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures which may be used for special effect, at the user's preference.
Equivalent OpenType tag: 'dlig'
Replaces standard forms in Japanese fonts with corresponding forms preferred by typographers. For example, a user would invoke this feature to replace kanji character U+5516 with U+555E.\t\n
Equivalent OpenType tag: 'expt'
Replaces figures separated by a slash with 'common' (diagonal) fractions.
Equivalent OpenType tag: 'frac'
Replaces glyphs set on other widths with glyphs set on full (usually em) widths. In a CJKV font, this may include \"lower ASCII\" Latin characters and various symbols. In a European font, this feature replaces proportionally-spaced glyphs with monospaced glyphs, which are generally set on widths of 0.6 em. For example, a user may invoke this feature in a Japanese font to get full monospaced Latin glyphs instead of the corresponding proportionally-spaced versions.
Equivalent OpenType tag: 'fwid'
Produces the half forms of consonants in Indic scripts. For example, in Hindi (Devanagari script), the conjunct KKa, obtained by doubling the Ka, is denoted with a half form of Ka followed by the full form.
Equivalent OpenType tag: 'half'
Produces the halant forms of consonants in Indic scripts. For example, in Sanskrit (Devanagari script), syllable final consonants are frequently required in their halant form.
Equivalent OpenType tag: 'haln'
Respaces glyphs designed to be set on full-em widths, fitting them onto half-em widths. This differs from hwid in that it does not substitute new glyphs.
Equivalent OpenType tag: 'halt'
Replaces the default (current) forms with the historical alternates. While some ligatures are also used for historical effect, this feature deals only with single characters. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hist'
Replaces standard kana with forms that have been specially designed for only horizontal writing. This is a typographic optimization for improved fit and more even color.
Equivalent OpenType tag: 'hkna'
Replaces the default (current) forms with the historical alternates. Some ligatures were in common use in the past, but appear anachronistic today. Some fonts include the historical forms as alternates, so they can be used for a 'period' effect.
Equivalent OpenType tag: 'hlig'
Replaces glyphs on proportional widths, or fixed widths other than half an em, with glyphs on half-em (en) widths. Many CJKV fonts have glyphs which are set on multiple widths; this feature selects the half-em version. There are various contexts in which this is the preferred behavior, including compatibility with older desktop documents.
Equivalent OpenType tag: 'hwid'
Used to access the JIS X 0212-1990 glyphs for the cases when the JIS X 0213:2004 form is encoded. The JIS X 0212-1990 (aka, \"Hojo Kanji\") and JIS X 0213:2004 character sets overlap significantly. In some cases their prototypical glyphs differ. When building fonts that support both JIS X 0212-1990 and JIS X 0213:2004 (such as those supporting the Adobe-Japan 1-6 character collection), it is recommended that JIS X 0213:2004 forms be the preferred encoded form.
Equivalent OpenType tag: 'hojo'
The National Language Council (NLC) of Japan has defined new glyph shapes for a number of JIS characters, which were incorporated into JIS X 0213:2004 as new prototypical forms. The 'jp04' feature is A subset of the 'nlck' feature, and is used to access these prototypical glyphs in a manner that maintains the integrity of JIS X 0213:2004.
Equivalent OpenType tag: 'jp04'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS C 6226-1978 (JIS78) specification.
Equivalent OpenType tag: 'jp78'
Replaces default (JIS90) Japanese glyphs with the corresponding forms from the JIS X 0208-1983 (JIS83) specification.
Equivalent OpenType tag: 'jp83'
Replaces Japanese glyphs from the JIS78 or JIS83 specifications with the corresponding forms from the JIS X 0208-1990 (JIS90) specification.
Equivalent OpenType tag: 'jp90'
Adjusts amount of space between glyphs, generally to provide optically consistent spacing between glyphs. Although a well-designed typeface has consistent inter-glyph spacing overall, some glyph combinations require adjustment for improved legibility. Besides standard adjustment in the horizontal direction, this feature can supply size-dependent kerning data via device tables, \"cross-stream\" kerning in the Y text direction, and adjustment of glyph placement independent of the advance adjustment. Note that this feature may apply to runs of more than two glyphs, and would not be used in monospaced fonts. Also note that this feature does not apply to text set vertically.
Equivalent OpenType tag: 'kern'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers the ligatures which the designer/manufacturer judges should be used in normal conditions.
Equivalent OpenType tag: 'liga'
Changes selected figures from oldstyle to the default lining form. For example, a user may invoke this feature in order to get lining figures, which fit better with all-capital text. This feature overrides results of the Oldstyle Figures feature (onum).
Equivalent OpenType tag: 'lnum'
Enables localized forms of glyphs to be substituted for default forms. Many scripts used to write multiple languages over wide geographical areas have developed localized variant forms of specific letters, which are used by individual literary communities. For example, a number of letters in the Bulgarian and Serbian alphabets have forms distinct from their Russian counterparts and from each other. In some cases the localized form differs only subtly from the script 'norm', in others the forms are radically distinct.
Equivalent OpenType tag: 'locl'
Positions mark glyphs with respect to base glyphs. For example, in Arabic script positioning the Hamza above the Yeh.
Equivalent OpenType tag: 'mark'
Replaces standard typographic forms of Greek glyphs with corresponding forms commonly used in mathematical notation (which are a subset of the Greek alphabet).
Equivalent OpenType tag: 'mgrk'
Positions marks with respect to other marks. Required in various non-Latin scripts like Arabic. For example, in Arabic, the ligaturised mark Ha with Hamza above it can also be obtained by positioning these marks relative to one another.
Equivalent OpenType tag: 'mkmk'
Replaces default glyphs with various notational forms (such as glyphs placed in open or solid circles, squares, parentheses, diamonds or rounded boxes). In some cases an annotation form may already be present, but the user may want a different one.
Equivalent OpenType tag: 'nalt'
Used to access glyphs made from glyph shapes defined by the National Language Council (NLC) of Japan for a number of JIS characters in 2000.
Equivalent OpenType tag: 'nlck'
Changes selected figures from the default lining style to oldstyle form. For example, a user may invoke this feature to get oldstyle figures, which fit better into the flow of normal upper- and lowercase text. This feature overrides results of the Lining Figures feature (lnum).
Equivalent OpenType tag: 'onum'
Replaces default alphabetic glyphs with the corresponding ordinal forms for use after figures. One exception to the follows-a-figure rule is the numero character (U+2116), which is actually a ligature substitution, but is best accessed through this feature.
Equivalent OpenType tag: 'ordn'
Respaces glyphs designed to be set on full-em widths, fitting them onto individual (more or less proportional) horizontal widths. This differs from pwid in that it does not substitute new glyphs (GPOS, not GSUB feature). The user may prefer the monospaced form, or may simply want to ensure that the glyph is well-fit and not rotated in vertical setting (Latin forms designed for proportional spacing would be rotated).
Equivalent OpenType tag: 'palt'
Turns lowercase characters into petite capitals. Forms related to petite capitals, such as specially designed figures, may be included. Some fonts contain an additional size of capital letters, shorter than the regular smallcaps and it is referred to as petite caps. Such forms are most likely to be found in designs with a small lowercase x-height, where they better harmonise with lowercase text than the taller smallcaps (for examples of petite caps, see the Emigre type families Mrs Eaves and Filosofia).
Equivalent OpenType tag: 'pcap'
Replaces figure glyphs set on uniform (tabular) widths with corresponding glyphs set on glyph-specific (proportional) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'pnum'
Replaces glyphs set on uniform widths (typically full or half-em) with proportionally spaced glyphs. The proportional variants are often used for the Latin characters in CJKV fonts, but may also be used for Kana in Japanese fonts.
Equivalent OpenType tag: 'pwid'
Replaces glyphs on other widths with glyphs set on widths of one quarter of an em (half an en). The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'qwid'
Replaces a sequence of glyphs with a single glyph which is preferred for typographic purposes. This feature covers those ligatures, which the script determines as required to be used in normal conditions. This feature is important for some scripts to ensure correct glyph formation.
Equivalent OpenType tag: 'rlig'
Identifies glyphs in the font which have been designed for \"ruby\", from the old typesetting term for four-point-sized type. Japanese typesetting often uses smaller kana glyphs, generally in superscripted form, to clarify the meaning of kanji which may be unfamiliar to the reader.
Equivalent OpenType tag: 'ruby'
Replaces the default forms with the stylistic alternates. Many fonts contain alternate glyph designs for a purely esthetic effect; these don't always fit into a clear category like swash or historical. As in the case of swash glyphs, there may be more than one alternate form.
Equivalent OpenType tag: 'salt'
Replaces lining or oldstyle figures with inferior figures (smaller glyphs which sit lower than the standard baseline, primarily for chemical or mathematical notation). May also replace lowercase characters with alphabetic inferiors.
Equivalent OpenType tag: 'sinf'
Turns lowercase characters into small capitals. This corresponds to the common SC font layout. It is generally used for display lines set in Large & small caps, such as titles. Forms related to small capitals, such as oldstyle figures, may be included.
Equivalent OpenType tag: 'smcp'
Replaces 'traditional' Chinese or Japanese forms with the corresponding 'simplified' forms.
Equivalent OpenType tag: 'smpl'
In addition to, or instead of, stylistic alternatives of individual glyphs (see 'salt' feature), some fonts may contain sets of stylistic variant glyphs corresponding to portions of the character set, such as multiple variants for lowercase letters in a Latin font. Glyphs in stylistic sets may be designed to harmonise visually, interract in particular ways, or otherwise work together. Examples of fonts including stylistic sets are Zapfino Linotype and Adobe's Poetica. Individual features numbered sequentially with the tag name convention 'ss01' 'ss02' 'ss03' . 'ss20' provide a mechanism for glyphs in these sets to be associated via GSUB lookup indexes to default forms and to each other, and for users to select from available stylistic sets
Equivalent OpenType tag: 'ss01'
See the description for
Equivalent OpenType tag: 'ss02'
See the description for
Equivalent OpenType tag: 'ss03'
See the description for
Equivalent OpenType tag: 'ss04'
See the description for
Equivalent OpenType tag: 'ss05'
See the description for
Equivalent OpenType tag: 'ss06'
See the description for
Equivalent OpenType tag: 'ss07'
See the description for
Equivalent OpenType tag: 'ss08'
See the description for
Equivalent OpenType tag: 'ss09'
See the description for
Equivalent OpenType tag: 'ss10'
See the description for
Equivalent OpenType tag: 'ss11'
See the description for
Equivalent OpenType tag: 'ss12'
See the description for
Equivalent OpenType tag: 'ss13'
See the description for
Equivalent OpenType tag: 'ss14'
See the description for
Equivalent OpenType tag: 'ss15'
See the description for
Equivalent OpenType tag: 'ss16'
See the description for
Equivalent OpenType tag: 'ss17'
See the description for
Equivalent OpenType tag: 'ss18'
See the description for
Equivalent OpenType tag: 'ss19'
See the description for
Equivalent OpenType tag: 'ss20'
May replace a default glyph with a subscript glyph, or it may combine a glyph substitution with positioning adjustments for proper placement.
Equivalent OpenType tag: 'subs'
Replaces lining or oldstyle figures with superior figures (primarily for footnote indication), and replaces lowercase letters with superior letters (primarily for abbreviated French titles).
Equivalent OpenType tag: 'sups'
Replaces default character glyphs with corresponding swash glyphs. Note that there may be more than one swash alternate for a given character.
Equivalent OpenType tag: 'swsh'
Replaces the default glyphs with corresponding forms designed specifically for titling. These may be all-capital and/or larger on the body, and adjusted for viewing at larger sizes.
Equivalent OpenType tag: 'titl'
Replaces 'simplified' Japanese kanji forms with the corresponding 'traditional' forms. This is equivalent to the Traditional Forms feature, but explicitly limited to the traditional forms considered proper for use in personal names (as many as 205 glyphs in some fonts).
Equivalent OpenType tag: 'tnam'
Replaces figure glyphs set on proportional widths with corresponding glyphs set on uniform (tabular) widths. Tabular widths will generally be the default, but this cannot be safely assumed. Of course this feature would not be present in monospaced designs.
Equivalent OpenType tag: 'tnum'
Replaces 'simplified' Chinese hanzi or Japanese kanji forms with the corresponding 'traditional' forms.
Equivalent OpenType tag: 'trad'
Replaces glyphs on other widths with glyphs set on widths of one third of an em. The characters involved are normally figures and some forms of punctuation.
Equivalent OpenType tag: 'twid'
Maps upper- and lowercase letters to a mixed set of lowercase and small capital forms, resulting in a single case alphabet (for an example of unicase, see the Emigre type family Filosofia). The letters substituted may vary from font to font, as appropriate to the design. If aligning to the x-height, smallcap glyphs may be substituted, or specially designed unicase forms might be used. Substitutions might also include specially designed figures.\t\n
Equivalent OpenType tag: 'unic'
Allows the user to change from the default 0 to a slashed form. Some fonts contain both a default form of zero, and an alternative form which uses a diagonal slash through the counter. Especially in condensed designs, it can be difficult to distinguish between 0 and O (zero and capital O) in any situation where capitals and lining figures may be arbitrarily mixed.
Equivalent OpenType tag: 'zero'
The type of a font represented by a single font file. Font formats that consist of multiple files, for example Type 1 .PFM and .PFB, have separate enum values for each of the file types.
\t\nFont type is not recognized by the DirectWrite font system.
OpenType font with CFF outlines.
OpenType font with TrueType outlines.
OpenType font that contains a TrueType collection.
Type 1 PFM font.
Type 1 PFB font.
Vector .FON font.
Bitmap .FON font.
Specifies algorithmic style simulations to be applied to the font face. Bold and oblique simulations can be combined via bitwise OR operation.
\t\nStyle simulations are not recommended for good typographic quality.
\t\nIndicates that no simulations are applied to the font face.
Indicates that algorithmic emboldening is applied to the font face.
Indicates that algorithmic italicization is applied to the font face.
Represents the degree to which a font has been stretched compared to a font's normal aspect ratio. The enumerated values correspond to the usWidthClass definition in the OpenType specification. The usWidthClass represents an integer value between 1 and 9?lower values indicate narrower widths; higher values indicate wider widths.
\t\nA font stretch describes the degree to which a font form is stretched from its normal aspect ratio, which is the original width to height ratio specified for the glyphs in the font. \t\n The following illustration shows an example of Normal and Condensed stretches for the Rockwell Bold typeface.
Note??Values other than the ones defined in the enumeration are considered to be invalid, and are rejected by font API functions.
\t\nPredefined font stretch : Not known (0).
Predefined font stretch : Ultra-condensed (1).
Predefined font stretch : Extra-condensed (2).
Predefined font stretch : Condensed (3).
Predefined font stretch : Semi-condensed (4).
Predefined font stretch : Normal (5).
Predefined font stretch : Medium (5).
Predefined font stretch : Semi-expanded (6).
Predefined font stretch : Expanded (7).
Predefined font stretch : Extra-expanded (8).
Predefined font stretch : Ultra-expanded (9).
Represents the style of a font face as normal, italic, or oblique.
\t\nThree terms categorize the slant of a font: normal, italic, and oblique.
| Font style | Description |
|---|---|
| Normal | The characters in a normal, or roman, font are upright. \t\n |
| Italic \t\n | The characters in an italic font are truly slanted and appear as they were designed. \t\n |
| Oblique | The characters in an oblique font are artificially slanted. |
?
For Oblique, the slant is achieved by performing a shear transformation on the characters from a normal font. When a true italic font is not available on a computer or printer, an oblique style can be generated from the normal font and used to simulate an italic font. The following illustration shows the normal, italic, and oblique font styles for the Palatino Linotype font. Notice how the italic font style has a more flowing and visually appealing appearance than the oblique font style, which is simply created by skewing the normal font style version of the text.
Note?? Values other than the ones defined in the enumeration are considered to be invalid, and they are rejected by font API functions.
\t\nFont style : Normal.
Font style : Oblique.
Font style : Italic.
Represents the density of a typeface, in terms of the lightness or heaviness of the strokes. The enumerated values correspond to the usWeightClass definition in the OpenType specification. The usWeightClass represents an integer value between 1 and 999. Lower values indicate lighter weights; higher values indicate heavier weights.
\t\nWeight differences are generally differentiated by an increased stroke or thickness that is associated with a given character in a typeface, as compared to a \"normal\" character from that same typeface. \t\n The following illustration shows an example of Normal and UltraBold weights for the Palatino Linotype typeface.
Note??Not all weights are available for all typefaces. When a weight is not available for a typeface, the closest matching weight is returned.
Font weight values less than 1 or greater than 999 are considered invalid, and they are rejected by font API functions.
\t\nPredefined font weight : Thin (100).
Predefined font weight : Extra-light (200).
Predefined font weight : Ultra-light (200).
Predefined font weight : Light (300).
Predefined font weight : Normal (400).
Predefined font weight : Regular (400).
Predefined font weight : Medium (500).
Predefined font weight : Demi-bold (600).
Predefined font weight : Semi-bold (600).
Predefined font weight : Bold (700).
Predefined font weight : Extra-bold (800).
Predefined font weight : Ultra-bold (800).
Predefined font weight : Black (900).
Predefined font weight : Heavy (900).
Predefined font weight : Extra-black (950).
Predefined font weight : Ultra-black (950).
The informational string enumeration which identifies a string embedded in a font file.
\t\nIndicates the string containing the unspecified name ID.
Indicates the string containing the copyright notice provided by the font.
Indicates the string containing a version number.
Indicates the string containing the trademark information provided by the font.
Indicates the string containing the name of the font manufacturer.
Indicates the string containing the name of the font designer.
Indicates the string containing the URL of the font designer (with protocol, e.g., http://, ftp://).
Indicates the string containing the description of the font. This may also contain revision information, usage recommendations, history, features, etc.
Indicates the string containing the URL of the font vendor (with protocol, e.g., http://, ftp://). If a unique serial number is embedded in the URL, it can be used to register the font.
Indicates the string containing the description of how the font may be legally used, or different example scenarios for licensed use.
Indicates the string containing the URL where additional licensing information can be found.
Indicates the string containing the GDI-compatible family name. Since GDI allows a maximum of four fonts per family, fonts in the same family may have different GDI-compatible family names (e.g., \"Arial\", \"Arial Narrow\", \"Arial Black\").
Indicates the string containing a GDI-compatible subfamily name.
Indicates the string containing the family name preferred by the designer. This enables font designers to group more than four fonts in a single family without losing compatibility with GDI. This name is typically only present if it differs from the GDI-compatible family name.
Indicates the string containing the subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name.
Contains sample text for display in font lists. This can be the font name or any other text that the designer thinks is the best example to display the font in.
The method used for line spacing in a text layout.
\t\nThe line spacing method is set by using the SetLineSpacing method of the
Line spacing depends solely on the content, adjusting to accommodate the size of fonts and inline objects.
Lines are explicitly set to uniform spacing, regardless of the size of fonts and inline objects. This can be useful to avoid the uneven appearance that can occur from font fallback.
Specifies how to apply number substitution on digits and related punctuation.
\t\nSpecifies that the substitution method should be determined based on the LOCALE_IDIGITSUBSTITUTION value of the specified text culture.
If the culture is Arabic or Persian, specifies that the number shapes depend on the context. Either traditional or nominal number shapes are used, depending on the nearest preceding strong character or (if there is none) the reading direction of the paragraph.
Specifies that code points 0x30-0x39 are always rendered as nominal numeral shapes (ones of the European number), that is, no substitution is performed.
Specifies that numbers are rendered using the national number shapes as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture.
Specifies that numbers are rendered using the traditional shapes for the specified culture. For most cultures, this is the same as NativeNational. However, NativeNational results in Latin numbers for some Arabic cultures, whereasDWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL results in arabic numbers for all Arabic cultures.
Specifies the alignment of paragraph text along the flow direction axis, relative to the top and bottom of the flow's layout box.
\t\nThe top of the text flow is aligned to the top edge of the layout box.
The bottom of the text flow is aligned to the bottom edge of the layout box.
The center of the flow is aligned to the center of the layout box.
Represents the internal structure of a device pixel (that is, the physical arrangement of red, green, and blue color components) that is assumed for purposes of rendering text.\t\n
\t\nThe red, green, and blue color components of each pixel are assumed to occupy the same point.
Each pixel is composed of three vertical stripes, with red on the left, green in the center, and blue on the right. This is the most common pixel geometry for LCD monitors.\t
Each pixel is composed of three vertical stripes, with blue on the left, green in the center, and red on the right.
Specifies the direction in which reading progresses.
\t\nIndicates that reading progresses from left to right.
Indicates that reading progresses from right to left.
Represents a method of rendering glyphs.
\t\nSpecifies that the rendering mode is determined automatically, based on the font and size.
Specifies that no anti-aliasing is performed. Each pixel is either set to the foreground color of the text or retains the color of the background.
Specifies ClearType rendering with the same metrics as bi-level text. Glyphs can only be positioned on whole-pixel boundaries.
Specifies ClearType rendering with the same metrics as text rendering using GDI using a font created with CLEARTYPE_NATURAL_QUALITY. Glyph metrics are closer to their ideal values than with bi-level text, but glyphs are still positioned on whole-pixel boundaries.
Specifies ClearType rendering with anti-aliasing in the horizontal dimension only. This is typically used with small to medium font sizes (up to 16 ppem).
Specifies ClearType rendering with anti-aliasing in both horizontal and vertical dimensions. This is typically used at larger sizes to makes curves and diagonal lines look smoother, at the expense of some softness.
Specifies that rendering should bypass the rasterizer and use the outlines directly. This is typically used at very large sizes.
Indicates additional shaping requirements for text.
\t\nIndicates that there is no additional shaping requirements for text. Text is shaped with the writing system default behavior.
Indicates that text should leave no visible control or format control characters.
Specifies the alignment of paragraph text along the reading direction axis, relative to the leading and trailing edge of the layout box.
\t\nThe leading edge of the paragraph text is aligned to the leading edge of the layout box.
The trailing edge of the paragraph text is aligned to the trailing edge of the layout box.
The center of the paragraph text is aligned to the center of the layout box.
Identifies a type of alpha texture.
\t\nAn alpha texture is a bitmap of alpha values, each representing opacity of a pixel or subpixel.
\t\nSpecifies an alpha texture for aliased text rendering (that is, each pixel is either fully opaque or fully transparent), with one byte per pixel.
Specifies an alpha texture for ClearType text rendering, with three bytes per pixel in the horizontal dimension and one byte per pixel in the vertical dimension.
Specifies the text granularity used to trim text overflowing the layout box.
\t\nNo trimming occurs. Text flows beyond the layout width.
Trimming occurs at a character cluster boundary.
Trimming occurs at a word boundary.
Specifies the word wrapping to be used in a particular multiline paragraph.
\t\nIndicates that words are broken across lines to avoid text overflowing the layout box.
Indicates that words are kept within the same line even when it overflows the layout box. This option is often used with scrolling to reveal overflow text.
Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects.
\t\nA value that specifies whether the factory object will be shared or isolated.
A
An address of a reference to the newly created DirectWrite factory object.
If this function succeeds, it returns
This function creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects. DirectWrite factory contains internal state data such as font loader registration and cached font data. In most cases it is recommended you use the shared factory object, because it allows multiple components that use DirectWrite to share internal DirectWrite state data, and thereby reduce memory usage. However, there are cases when it is desirable to reduce the impact of a component, such as a plug-in from an untrusted source, on the rest of the process, by sandboxing and isolating it from the rest of the process components. In such cases, it is recommended you use an isolated factory for the sandboxed component.
The following example shows how to create a shared DirectWrite factory.
if (SUCCEEDED(hr))\t\n { hr = ( , __uuidof(), reinterpret_cast<**>(&pDWriteFactory_) );\t\n } Represents a physical font in a font collection. This interface is used to create font faces from physical fonts, or to retrieve information such as font face metrics or face names from existing font faces.
\t\nGets the font family to which the specified font belongs.
\t\nWhen this method returns, contains an address of a reference to the font family object to which the specified font belongs.
If this method succeeds, it returns
Gets the weight, or stroke thickness, of the specified font.
\t\nA value that indicates the weight for the specified font.
Gets the stretch, or width, of the specified font.
\t\nA value that indicates the type of stretch, or width, applied to the specified font.
Gets the style, or slope, of the specified font.
\t\nA value that indicates the type of style, or slope, of the specified font.
Determines whether the font is a symbol font.
\t\nTRUE if the font is a symbol font; otherwise,
Gets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
\t\nWhen this method returns, contains an address to a reference to the newly created localized strings object.
If this method succeeds, it returns
Gets a localized strings collection containing the specified informational strings, indexed by locale name.
\t\nA value that identifies the informational string to get. For example,
When this method returns, contains an address of a reference to the newly created localized strings object.
When this method returns, TRUE if the font contains the specified string ID; otherwise,
If the font does not contain the string specified by informationalStringID, the return value is
Gets a value that indicates what simulations are applied to the specified font.
\t\nA value that indicates one or more of the types of simulations (none, bold, or oblique) applied to the specified font.
Obtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
\t\nWhen this method returns, contains a structure that has font metrics for the current font face. The metrics returned by this function are in font design units.
Determines whether the font supports a specified character.
\t\nA Unicode (UCS-4) character value for the method to inspect.
When this method returns, TRUE if the font supports the specified character; otherwise,
Creates a font face object for the font.
\t\nWhen this method returns, contains an address of a reference to the newly created font face object.
If this method succeeds, it returns
Gets the font family to which the specified font belongs.
\t\nGets the weight, or stroke thickness, of the specified font.
\t\nGets the stretch, or width, of the specified font.
\t\nGets the style, or slope, of the specified font.
\t\nDetermines whether the font is a symbol font.
\t\nGets a localized strings collection containing the face names for the font (such as Regular or Bold), indexed by locale name.
\t\nGets a value that indicates what simulations are applied to the specified font.
\t\nObtains design units and common metrics for the font face. These metrics are applicable to all the glyphs within a font face and are used by applications for layout calculations.
\t\nRepresents a family of related fonts.
\t\nA font family is a set of fonts that share the same family name, such as \"Times New Roman\", but that differ in features. These feature differences include style, such as italic, and weight, such as bold. The following illustration shows examples of fonts that are members of the \"Times New Roman\" font family.
An
* pFontFamily = null ; // Get the font family.\t\n if (SUCCEEDED(hr))\t\n { hr = pFontCollection->GetFontFamily(i, &pFontFamily);\t\n }\t\n The font family name is used to specify the font family for text layout and text format objects. You can get a list of localized font family names from an
* pFamilyNames = null ; // Get a list of localized strings for the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFontFamily->GetFamilyNames(&pFamilyNames);\t\n }\t\n Represents a list of fonts.
\t\nGets the font collection that contains the fonts in the font list.
\t\nWhen this method returns, contains the address of a reference to the current
If this method succeeds, it returns
Gets the number of fonts in the font list.
\t\nThe number of fonts in the font list.
Gets a font given its zero-based index.
\t\nZero-based index of the font in the font list.
When this method returns, contains the address of a reference to the newly created
Gets the font collection that contains the fonts in the font list.
\t\nGets the number of fonts in the font list.
\t\nCreates a localized strings object that contains the family names for the font family, indexed by locale name.
\t\nThe address of a reference to the newly created
If this method succeeds, it returns
The following code example shows how to get the font family name from a
* pFamilyNames = null ; // Get a list of localized strings for the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFontFamily->GetFamilyNames(&pFamilyNames);\t\n } UINT32 index = 0;\t\n exists = false; wchar_t localeName[LOCALE_NAME_MAX_LENGTH]; if (SUCCEEDED(hr))\t\n { // Get the default locale for this user. int defaultLocaleSuccess = GetUserDefaultLocaleName(localeName, LOCALE_NAME_MAX_LENGTH); // If the default locale is returned, find that locale name, otherwise use \"en-us\". if (defaultLocaleSuccess) { hr = pFamilyNames->FindLocaleName(localeName, &index, &exists); } if (SUCCEEDED(hr) && !exists) // if the above find did not find a match, retry with US English { hr = pFamilyNames->FindLocaleName(L\"en-us\", &index, &exists); }\t\n } // If the specified locale doesn't exist, select the first on the list.\t\n if (!exists) index = 0; UINT32 length = 0; // Get the string length.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetStringLength(index, &length);\t\n } // Allocate a string big enough to hold the name.\t\n wchar_t* name = new (std::nothrow) wchar_t[length+1];\t\n if (name == null )\t\n { hr = E_OUTOFMEMORY;\t\n } // Get the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetString(index, name, length+1);\t\n }\t\n Gets the font that best matches the specified properties.
\t\nA value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
When this method returns, contains the address of a reference to the newly created
Gets a list of fonts in the font family ranked in order of how well they match the specified properties.
\t\nA value that is used to match a requested font weight.
A value that is used to match a requested font stretch.
A value that is used to match a requested font style.
An address of a reference to the newly created
Creates a localized strings object that contains the family names for the font family, indexed by locale name.
\t\n The following code example shows how to get the font family name from a
* pFamilyNames = null ; // Get a list of localized strings for the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFontFamily->GetFamilyNames(&pFamilyNames);\t\n } UINT32 index = 0;\t\n exists = false; wchar_t localeName[LOCALE_NAME_MAX_LENGTH]; if (SUCCEEDED(hr))\t\n { // Get the default locale for this user. int defaultLocaleSuccess = GetUserDefaultLocaleName(localeName, LOCALE_NAME_MAX_LENGTH); // If the default locale is returned, find that locale name, otherwise use \"en-us\". if (defaultLocaleSuccess) { hr = pFamilyNames->FindLocaleName(localeName, &index, &exists); } if (SUCCEEDED(hr) && !exists) // if the above find did not find a match, retry with US English { hr = pFamilyNames->FindLocaleName(L\"en-us\", &index, &exists); }\t\n } // If the specified locale doesn't exist, select the first on the list.\t\n if (!exists) index = 0; UINT32 length = 0; // Get the string length.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetStringLength(index, &length);\t\n } // Allocate a string big enough to hold the name.\t\n wchar_t* name = new (std::nothrow) wchar_t[length+1];\t\n if (name == null )\t\n { hr = E_OUTOFMEMORY;\t\n } // Get the family name.\t\n if (SUCCEEDED(hr))\t\n { hr = pFamilyNames->GetString(index, name, length+1);\t\n }\t\n A built-in implementation of the
Obtains the length of the absolute file path from the font file reference key.
\t\nFont file reference key that uniquely identifies the local font file within the scope of the font loader being used.
Size of font file reference key in bytes.
Length of the file path string, not including the terminated
Obtains the absolute font file path from the font file reference key.
\t\nThe font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The character array that receives the local file path.
The length of the file path character array.
If this method succeeds, it returns
Obtains the last write time of the file from the font file reference key.
\t\nThe font file reference key that uniquely identifies the local font file within the scope of the font loader being used.
The size of font file reference key in bytes.
The time of the last font file modification.
Contains information about a glyph cluster.
\t\nThe total advance width of all glyphs in the cluster.
The number of text positions in the cluster.
Indicates whether a line can be broken right after the cluster.
Indicates whether the cluster corresponds to a whitespace character.
Indicates whether the cluster corresponds to a newline character.
Indicates whether the cluster corresponds to a soft hyphen character.
Indicates whether the cluster is read from right to left.
Reserved for future use.
The
The number of font design units per em unit. Font files use their own coordinate system of font design units. A font design unit is the smallest measurable unit in the em square, an imaginary square that is used to size and align glyphs. The concept of em square is used as a reference scale factor when defining font size and device transformation semantics. The size of one em square is also commonly used to compute the paragraph identation value.
The ascent value of the font face in font design units. Ascent is the distance from the top of font character alignment box to the English baseline.
The descent value of the font face in font design units. Descent is the distance from the bottom of font character alignment box to the English baseline.
The line gap in font design units. Recommended additional white space to add between lines to improve legibility. The recommended line spacing (baseline-to-baseline distance) is the sum of ascent, descent, and lineGap. The line gap is usually positive or zero but can be negative, in which case the recommended line spacing is less than the height of the character alignment box.
The cap height value of the font face in font design units. Cap height is the distance from the English baseline to the top of a typical English capital. Capital \"H\" is often used as a reference character for the purpose of calculating the cap height value.
The x-height value of the font face in font design units. x-height is the distance from the English baseline to the top of lowercase letter \"x\", or a similar lowercase character.
The underline position value of the font face in font design units. Underline position is the position of underline relative to the English baseline. The value is usually made negative in order to place the underline below the baseline.
The suggested underline thickness value of the font face in font design units.
The strikethrough position value of the font face in font design units. Strikethrough position is the position of strikethrough relative to the English baseline. The value is usually made positive in order to place the strikethrough above the baseline.
The suggested strikethrough thickness value of the font face in font design units.
Specifies the metrics of an individual glyph. The units depend on how the metrics are obtained.
\t\nSpecifies the X offset from the glyph origin to the left edge of the black box. The glyph origin is the current horizontal writing position. A negative value means the black box extends to the left of the origin (often true for lowercase italic 'f').
Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally.
Specifies the X offset from the right edge of the black box to the origin of the next glyph when writing horizontally. The value is negative when the right edge of the black box overhangs the layout box.
Specifies the vertical offset from the vertical origin to the top of the black box. Thus, a positive value adds whitespace whereas a negative value means the glyph overhangs the top of the layout box.
Specifies the Y offset from the vertical origin of the current glyph to the vertical origin of the next glyph when writing vertically. Note that the term \"origin\" by itself denotes the horizontal origin. The vertical origin is different. Its Y coordinate is specified by verticalOriginY value, and its X coordinate is half the advanceWidth to the right of the horizontal origin.
Specifies the vertical distance from the bottom edge of the black box to the advance height. This is positive when the bottom edge of the black box is within the layout box, or negative when the bottom edge of black box overhangs the layout box.
Specifies the Y coordinate of a glyph's vertical origin, in the font's design coordinate system. The y coordinate of a glyph's vertical origin is the sum of the glyph's top side bearing and the top (that is, yMax) of the glyph's bounding box.
The optional adjustment to a glyph's position.
\t\nAn glyph offset changes the position of a glyph without affecting the pen position. Offsets are in logical, pre-transform units.
\t\nThe offset in the advance direction of the run. A positive advance offset moves the glyph to the right (in pre-transform coordinates) if the run is left-to-right or to the left if the run is right-to-left.
The offset in the ascent direction, that is, the direction ascenders point. A positive ascender offset moves the glyph up (in pre-transform coordinates). A negative ascender offset moves the glyph down.
Describes the region obtained by a hit test.
\t\nThe first text position within the hit region.
The number of text positions within the hit region.
The x-coordinate of the upper-left corner of the hit region.
The y-coordinate of the upper-left corner of the hit region.
The width of the hit region.
The height of the hit region.
The BIDI level of the text positions within the hit region.
true if the hit region contains text; otherwise, false.
Contains properties describing the geometric measurement of an\t\n application-defined inline object.
\t\nThe width of the inline object.
The height of the inline object.
The distance from the top of the object to the point where it is lined up with the adjacent text. If the baseline is at the bottom, then baseline simply equals height.
A Boolean flag that indicates whether the object is to be placed upright or alongside the text baseline for vertical text.
Contains information about a formatted line of text.
\t\nThe number of text positions in the text line. This includes any trailing whitespace and newline characters.
The number of whitespace positions at the end of the text line. Newline sequences are considered whitespace.
The number of characters in the newline sequence at the end of the text line. If the count is zero, then the text line was either wrapped or it is the end of the text.
The height of the text line.
The distance from the top of the text line to its baseline.
The line is trimmed.
The
A value indicating the horizontal scaling / cosine of rotation.
A value indicating the vertical shear / sine of rotation.
A value indicating the horizontal shear / negative sine of rotation.
A value indicating the vertical scaling / cosine of rotation.
A value indicating the horizontal shift (always orthogonal regardless of rotation).
A value indicating the vertical shift (always orthogonal regardless of rotation.)
Indicates how much any visible DIPs (device independent pixels) overshoot each side of the layout or inline objects.
Positive overhangs indicate that the visible area extends outside the layout box or inline object, while negative values mean there is whitespace inside. The returned values are unaffected by rendering transforms or pixel snapping. Additionally, they may not exactly match the final target's pixel bounds after applying grid fitting and hinting.
\t\nThe distance from the left-most visible DIP to its left-alignment edge.
The distance from the top-most visible DIP to its top alignment edge.
The distance from the right-most visible DIP to its right-alignment edge.
The distance from the bottom-most visible DIP to its lower-alignment edge.
Stores the association of text and its writing system script, as well as some display attributes.
\t\nThe zero-based index representation of writing system script.
A value that indicates additional shaping requirement of text.
Shaping output properties for an output glyph.
\t\nIndicates that the glyph is shaped alone.
Reserved for future use.
Contains information regarding the size and placement of strikethroughs. All coordinates are in device independent pixels (DIPs).
\t\nA value that indicates the width of the strikethrough, measured parallel to the baseline.
A value that indicates the thickness of the strikethrough, measured perpendicular to the baseline.
A value that indicates the offset of the strikethrough from the baseline. A positive offset represents a position below the baseline and a negative offset is above. Typically, the offset will be negative.
Reading direction of the text associated with the strikethrough. This value is used to interpret whether the width value runs horizontally or vertically.
Flow direction of the text associated with the strikethrough. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters containing the locale of the text that is the strikethrough is being drawn over.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Contains the metrics associated with text after layout. All coordinates are in device independent pixels (DIPs).
\t\nA value that indicates the left-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the top-most point of formatted text relative to the layout box, while excluding any glyph overhang.
A value that indicates the width of the formatted text, while ignoring trailing whitespace at the end of each line.
The width of the formatted text, taking into account the trailing whitespace at the end of each line.
The height of the formatted text. The height of an empty string is set to the same value as that of the default font.
The initial width given to the layout. It can be either larger or smaller than the text content width, depending on whether the text was wrapped.
Initial height given to the layout. Depending on the length of the text, it may be larger or smaller than the text content height.
The maximum reordering count of any line of text, used to calculate the most number of hit-testing boxes needed. If the layout has no bidirectional text, or no text at all, the minimum level is 1.
Specifies the trimming option for text overflowing the layout box.
\t\nA value that specifies the text granularity used to trim text overflowing the layout box.
A character code used as the delimiter that signals the beginning of the portion of text to be preserved. Most useful for path ellipsis, where the delimiter would be a slash.
A value that indicates how many occurrences of the delimiter to step back.
Contains a set of typographic features to be applied during text shaping.
\t\nA reference to a structure that specifies properties used to identify and execute typographic features in the font.
A value that indicates the number of features being applied to a font face.
Contains information about the width, thickness, offset, run height, reading direction, and flow direction of an underline.
\t\nAll coordinates are in device independent pixels (DIPs).
\t\nA value that indicates the width of the underline, measured parallel to the baseline.
A value that indicates the thickness of the underline, measured perpendicular to the baseline.
A value that indicates the offset of the underline from the baseline. A positive offset represents a position below the baseline (away from the text) and a negative offset is above (toward the text).
A value that indicates the height of the tallest run where the underline is applied.
A value that indicates the reading direction of the text associated with the underline. This value is used to interpret whether the width value runs horizontally or vertically.
A value that indicates the flow direction of the text associated with the underline. This value is used to interpret whether the thickness value advances top to bottom, left to right, or right to left.
An array of characters which contains the locale of the text that the underline is being drawn under. For example, in vertical text, the underline belongs on the left for Chinese but on the right for Japanese.
The measuring mode can be useful to the renderer to determine how underlines are rendered, such as rounding the thickness to a whole pixel in GDI-compatible modes.
Specifies how the alpha value of a bitmap or render target should be treated.
\t\nThe
When describing an RGBA color using straight alpha, the alpha value of the color is stored in the alpha channel. For example, to describe a red color that is 60% opaque, you'd use the following values: (255, 0, 0, 255 * 0.6) = (255, 0, 0, 153). The 255 value indicates full red, and 153 (which is 60 percent of 255) indicates that the color should have an opacity of 60 percent.
When describing an RGBA color using premultiplied alpha, each color is multiplied by the alpha value: (255 * 0.6, 0 * 0.6, 0 * 0.6, 255 * 0.6) = (153, 0, 0, 153).
Regardless of the alpha mode of the render target, D2D1_COLOR_F values are always interpreted as straight alpha. For example, when specifying the color of an
Regardless of the alpha mode setting, a render target's contents support transparency. For example, if you draw a partially transparent red rectangle with a render target with an alpha mode of
If you draw a partially transparent red rectangle when the alpha mode is
If you specify an alpha mode other than
You can use the SetTextAntialiasMode method to change the text antialias mode back to
The alpha value might not be meaningful.
The alpha value has been premultiplied. Each color is first scaled by the alpha value. The alpha value itself is the same in both straight and premultiplied alpha. Typically, no color channel value is greater than the alpha channel value. If a color channel value in a premultiplied format is greater than the alpha channel, the standard source-over blending math results in an additive blend.
The alpha value has not been premultiplied. The alpha channel indicates the transparency of the color.
The alpha value is ignored.
Specifies how the edges of nontext primitives are rendered.
\t\nEdges are antialiased using the Direct2D per-primitive method of high-quality antialiasing.
Objects are aliased in most cases. Objects are antialiased only when they are drawn to a render target created by the CreateDxgiSurfaceRenderTarget method and Direct3D multisampling has been enabled on the backing DirectX Graphics Infrastructure (DXGI) surface.
Specifies whether an arc should be greater than 180 degrees.
\t\nAn arc's sweep should be 180 degrees or less.
An arc's sweep should be 180 degrees or greater.
Specifies the algorithm that is used when images are scaled or rotated.
\t\n To stretch an image, each pixel in the original image must be mapped to a group of pixels in the larger image. To shrink an image, groups of pixels in the original image must be mapped to single pixels in the smaller image. The effectiveness of the algorithms that perform these mappings determines the quality of a scaled image. Algorithms that produce higher-quality scaled images tend to require more processing time.
Use the exact color of the nearest bitmap pixel to the current rendering pixel.
Interpolate a color from the four bitmap pixels that are the nearest to the rendering pixel.
Describes the shape at the end of a line or segment.
\t\nThe following illustration shows the available cap styles for lines or segments. The red portion of the line shows the extra area added by the line cap setting.
\t\nA cap that does not extend past the last point of the line. Comparable to cap used for objects other than lines.
Half of a square that has a length equal to the line thickness.
A semicircle that has a diameter equal to the line thickness.
An isosceles right triangle whose hypotenuse is equal in length to the thickness of the line.
Specifies the different methods by which two geometries can be combined.
\t\nThe following illustration shows the different geometry combine modes.\t\n
\t\nThe two regions are combined by taking the union of both. Given two geometries, A and B, the resulting geometry is geometry A + geometry B.
The two regions are combined by taking their intersection. The new area consists of the overlapping region between the two geometries.
The two regions are combined by taking the area that exists in the first region but not the second and the area that exists in the second region but not the first. Given two geometries, A and B, the new region consists of (A-B) + (B-A).
The second region is excluded from the first. Given two geometries, A and B, the area of geometry B is removed from the area of geometry A, producing a region that is A-B.
Specifies additional features supportable by a compatible render target when it is created. This enumeration allows a bitwise combination of its member values.
\t\nUse this enumeration when creating a compatible render target with the CreateCompatibleRenderTarget method. For more information about compatible render targets, see the Render Targets Overview.
The
The render target supports no additional features.
The render target supports interoperability with the Windows Graphics Device Interface (GDI).
Describes the sequence of dashes and gaps in a stroke.
\t\nThe following illustration shows several available dash styles. For more information, see the Stroke Style Example.
\t\nA solid line with no breaks.
A dash followed by a gap of equal length. The dash and the gap are each twice as long as the stroke thickness.
The equivalent dash array for
A dot followed by a longer gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap.
The equivalent dash array for
A dash, followed by a gap, followed by a dot, followed by another gap, followed by another dot, followed by another gap.
The equivalent dash array for
The dash pattern is specified by an array of floating-point values.
Indicates the type of information provided by the Direct2D Debug Layer.
\t\nTo receive debugging messages, you must install the Direct2D Debug Layer.
\t\nSpecifies how a device context is initialized for GDI rendering when it is retrieved from the render target.
\t\nUse this enumeration with the
The current contents of the render target are copied to the device context when it is initialized.
The device context is cleared to transparent black when it is initialized.
Specifies whether text snapping is suppressed or clipping to the layout rectangle is enabled. This enumeration allows a bitwise combination of its member values.
\t\nText is not vertically snapped to pixel boundaries. This setting is recommended for text that is being animated.
Text is clipped to the layout rectangle.
Text is vertically snapped to pixel boundaries and is not clipped to the layout rectangle.
Specifies how a brush paints areas outside of its normal content area.
\t\nFor an
For an example, see the Draw Extend Mode Example.
\t\nRepeat the edge pixels of the brush's content for all regions outside the normal content area.
Repeat the brush's content.
The same as
Specifies whether Direct2D provides synchronization for an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread, and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note the qualifier \"On the CPU\": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU; however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
\t\nDescribes the minimum DirectX support required for hardware rendering by a render target.
\t\nDirect2D determines whether the video card provides adequate hardware rendering support.
The video card must support DirectX 9.
The video card must support DirectX 10.
Indicates whether a specific
Indicates whether a specific
Specifies how the intersecting areas of geometries or figures are combined to form the area of the composite geometry.
\t\nUse the
Direct2D fills the interior of a path by using one of the two fill modes specified by this enumeration:
To see the difference between the winding and alternate fill modes, assume that you have four circles with the same center and a different radius, as shown in the following illustration. The first one has the radius of 25, the second 50, the third 75, and the fourth 100.
The following illustration shows the shape filled by using the alternate fill mode. Notice that the center and third ring are not filled. This is because a ray drawn from any point in either of those two rings passes through an even number of segments.
The following illustration explains this process.
The following illustration shows how the same shape is filled when the winding fill mode is specified.
Notice that all the rings are filled. This is because all the segments run in the same direction, so a ray drawn from any point will cross one or more segments, and the sum of the crossings will not equal zero.
The following illustration explains this process. The red arrows represent the direction in which the segments are drawn and the black arrow represents an arbitrary ray that runs from a point in the innermost ring. Starting with a value of zero, for each segment that the ray crosses, a value of one is added for every clockwise intersection. All points lie in the fill region in this illustration, because the count does not equal zero.
\t\nDetermines whether a point is in the fill region by drawing a ray from that point to infinity in any direction, and then counting the number of path segments within the given shape that the ray crosses. If this number is odd, the point is in the fill region; if even, the point is outside the fill region.
Determines whether a point is in the fill region of the path by drawing a ray from that point to infinity in any direction, and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left, as long as left and right are seen from the perspective of the ray. After counting the crossings, if the result is zero, then the point is outside the path. Otherwise, it is inside the path.
Specifies which gamma is used for interpolation.
\t\nInterpolating in a linear gamma space (
The first gradient is interpolated linearly in the space of the render target (sRGB in this case), and one can see the dark bands between each color. The second gradient uses a gamma-correct linear interpolation, and thus does not exhibit the same variations in brightness.
\t\nInterpolation is performed in the standard RGB (sRGB) gamma.
Interpolation is performed in the linear-gamma color space.
Describes how one geometry object is spatially related to another geometry object.
\t\nThe relationship between the two geometries cannot be determined. This value is never returned by any D2D method.
The two geometries do not intersect at all.
The instance geometry is entirely contained by the passed-in geometry.
The instance geometry entirely contains the passed-in geometry.
The two geometries overlap but neither completely contains the other.
Specifies how a geometry is simplified to an
Specifies options that can be applied when a layer resource is applied to create a layer.
\t\nClearType antialiasing must use the current contents of the render target to blend properly. When a pushed layer requests initializing for ClearType, Direct 2D copies the current contents of the render target into the layer so that ClearType antialiasing can be performed. Rendering ClearType text into a transparent layer does not produce the desired results.
A small performance hit from re-copying content occurs when
The text in this layer does not use ClearType antialiasing.
The layer renders correctly for ClearType text. If the render target is set to ClearType, the layer continues to render ClearType. If the render target is set to ClearType and this option is not specified, the render target will be set to render gray-scale until the layer is popped. The caller can override this default by calling SetTextAntialiasMode while within the layer. This flag is slightly slower than the default.
Describes the shape that joins two lines or segments.
\t\n A miter limit affects how sharp miter joins are allowed to be. If the line join style is
The following illustration shows different line join settings for the same stroked path geometry. For more information, see Stroke Style Example.
\t\nRegular angular vertices.
Beveled vertices.
Rounded vertices.
Regular angular vertices unless the join would extend beyond the miter limit; otherwise, beveled vertices.
Indicates the measuring method used for text layout.
\t\nSpecifies that text is measured using glyph ideal metrics whose values are independent to the current display resolution.
Specifies that text is measured using glyph display-compatible metrics whose values tuned for the current display resolution.
Specifies that text is measured using the same glyph display metrics as text measured by GDI using a font created with CLEARTYPE_NATURAL_QUALITY.
Describes whether an opacity mask contains graphics or text. Direct2D uses this information to determine which gamma space to use when blending the opacity mask.
\t\nThe opacity mask contains graphics. The opacity mask is blended in the gamma 2.2 color space.
The opacity mask contains non-GDI text. The gamma space used for blending is obtained from the render target's text rendering parameters. (
The opacity mask contains text rendered using the GDI-compatible rendering mode. The opacity mask is blended using the gamma for GDI rendering.
Indicates whether a segment should be stroked and whether the join between this segment and the previous one should be smooth. This enumeration allows a bitwise combination of its member values.
\t\nThe segment is joined as specified by the
The segment is not stroked.
The segment is always joined with the one preceding it using a round line join, regardless of which
Describes how a render target behaves when it presents its content. This enumeration allows a bitwise combination of its member values.
\t\nThe render target waits until the display refreshes to present and discards the frame upon presenting.
The render target does not discard the frame upon presenting.
The render target does not wait until the display refreshes to present.
Describes whether a render target uses hardware or software rendering, or if Direct2D should select the rendering mode.
\t\nNot every render target supports hardware rendering. For more information, see the Render Targets Overview.
\t\nThe render target uses hardware rendering, if available; otherwise, it uses software rendering.
The render target uses software rendering only.
The render target uses hardware rendering only.
Describes how a render target is remoted and whether it should be GDI-compatible. This enumeration allows a bitwise combination of its member values.
\t\nThe render target attempts to use Direct3D command-stream remoting and uses bitmap remoting if stream remoting fails. The render target is not GDI-compatible.
The render target renders content locally and sends it to the terminal services client as a bitmap.
The render target can be used efficiently with GDI.
Defines the direction that an elliptical arc is drawn.
\t\nArcs are drawn in a counterclockwise (negative-angle) direction.
Arcs are drawn in a clockwise (positive-angle) direction.
Describes the antialiasing mode used for drawing text.
\t\nThis enumeration is used with the SetTextAntialiasMode of an
By default, Direct2D renders text in ClearType mode. Factors that can downgrade the default quality to grayscale or aliased:
Use the system default. See Remarks.
Use ClearType antialiasing.
Use grayscale antialiasing.
Do not use antialiasing.
Describes whether a window is occluded.
\t\nIf the window was occluded the last time EndDraw was called, the next time the render target calls CheckWindowState, it returns
The window is not occluded.
The window is occluded.
Indicates whether the specified matrix is invertible.
\t\nThe matrix to test.
true if the matrix was inverted; otherwise, false.
Tries to invert the specified matrix.
\t\nThe matrix to invert.
true if the matrix was inverted; otherwise, false.
Creates a skew transformation that has the specified x-axis angle, y-axis angle, and center point.
\t\nThe x-axis skew angle, which is measured in degrees counterclockwise from the y-axis.
The y-axis skew angle, which is measured in degrees counterclockwise from the x-axis.
The center point of the skew operation.
When this method returns, contains the rotation transformation. You must allocate storate for this parameter.
Creates a factory object that can be used to create Direct2D resources.
\t\nThe threading model of the factory and the resources it creates.
A reference to the IID of
The level of detail provided to the debugging layer.
When this method returns, contains the address to a reference to the new factory.
If this function succeeds, it returns
The
Creates a rotation transformation that rotates by the specified angle about the specified point.
\t\nThe clockwise rotation angle, in degrees.
The point about which to rotate.
When this method returns, contains the new rotation transformation. You must allocate storage for this parameter.
Rotation occurs in the plane of the 2-D surface.
\t\nIssues drawing commands to a GDI device context.
\t\nTo create an
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
To enable the DC render target to work with GDI, set its pixel format to
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
When you use an
It's possible for GDI to apply a GDI transform (through the SetWorldTransform method) or other effect to the same DC used by the render target, in which case GDI transforms the bitmap produced by Direct2D. Using a GDI transform to transform the Direct2D content has the potential to degrade the visual quality of the output, because you're transforming a bitmap for which antialiasing and subpixel positioning have already been calculated.
For example, suppose you use the render target to draw a scene that contains antialiased geometries and text. If you use a GDI transform to apply a scale transform to the DC and scale the scene so that it's 10 times larger, you'll see pixelization and jagged edges. (If, however, you applied a similar transform using Direct2D, the visual quality of the scene would not be degraded.)
In some cases, it might not be obvious that GDI is performing additional processing that might degrade the quality of the Direct2D content. For example, on a right-to-left (RTL) build of Windows, content rendered by an
Depending on the type of content being rendered, you might want to prevent the inversion. If the Direct2D content includes ClearType text, this inversion will degrade the quality of the text.
You can control RTL rendering behavior by using the SetLayout GDI function. To prevent the mirroring, call the SetLayout GDI function and specify LAYOUT_BITMAPORIENTATIONPRESERVED as the only value for the second parameter (do not combine it with LAYOUT_RTL), as shown in the following example:
SetLayout(m_hwnd, LAYOUT_BITMAPORIENTATIONPRESERVED);Binds the render target to the device context to which it issues drawing commands.
\t\nThe device context to which the render target issues drawing commands.
The dimensions of the handle to a device context (
If this method succeeds, it returns
Before you can render with the DC render target, you must use its BindDC method to associate it with a GDI DC. You do this each time you use a different DC, or the size of the area you want to draw to changes.
\t\nRepresents the drawing state of a render target: the antialiasing mode, transform, tags, and text-rendering options.
\t\nTo create an
A drawing state block is a device-independent resource; you can create it once and retain it for the life of your application. For more information about resources, see the Resources Overview.
\t\nRetrieves the antialiasing mode, transform, and tags portion of the drawing state.
\t\nWhen this method returns, contains the antialiasing mode, transform, and tags portion of the drawing state. You must allocate storage for this parameter.
Specifies the antialiasing mode, transform, and tags portion of the drawing state.
\t\nThe antialiasing mode, transform, and tags portion of the drawing state.
Specifies the text-rendering configuration of the drawing state.
\t\nThe text-rendering configuration of the drawing state, or
Retrieves the text-rendering configuration of the drawing state.
\t\nWhen this method returns, contains the address of a reference to an
Retrieves or sets the antialiasing mode, transform, and tags portion of the drawing state.
\t\nRetrieves or sets the text-rendering configuration of the drawing state.
\t\nRepresents an ellipse.
\t\nTo create an elipse geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Represents a geometry resource and defines a set of helper methods for manipulating and measuring geometric shapes. Interfaces that inherit from
There are several types of Direct2D geometry objects: a simple geometry (
Direct2D geometries enable you to describe two-dimensional figures and also offer many uses, such as defining hit-test regions, clip regions, and even animation paths.
Direct2D geometries are immutable and device-independent resources created by
Gets the bounds of the geometry after it has been widened by the specified stroke width and style and transformed by the specified matrix.
\t\nThe amount by which to widen the geometry by stroking its outline.
The style of the stroke that widens the geometry.
A transform to apply to the geometry after the geometry is transformed and after the geometry has been stroked.
When this method returns, contains the bounds of the widened geometry. You must allocate storage for this parameter.
Determines whether the geometry's stroke contains the specified point given the specified stroke thickness, style, and transform.
\t\nThe point to test for containment.
The thickness of the stroke to apply.
The style of stroke to apply.
The transform to apply to the stroked geometry.
When this method returns, contains a boolean value set to true if the geometry's stroke contains the specified point; otherwise, false. You must allocate storage for this parameter.
Indicates whether the area filled by the geometry would contain the specified point given the specified flattening tolerance.
\t\nThe point to test.
The transform to apply to the geometry prior to testing for containment, or
The numeric accuracy with which the precise geometric path and path intersection is calculated. Points missing the fill by less than the tolerance are still considered inside. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a
Describes the intersection between this geometry and the specified geometry. The comparison is performed by using the specified flattening tolerance.
\t\nThe geometry to test.
The transform to apply to inputGeometry, or
The maximum bounds on the distance between points in the polygonal approximation of the geometries. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to a value that describes how this geometry is related to inputGeometry. You must allocate storage for this parameter.
When interpreting the returned relation value, it is important to remember that the member
For more information about how to interpret other possible return values, see
Computes the outline of the geometry and writes the result to an
If this method succeeds, it returns
The Outline method allows the caller to produce a geometry with an equivalent fill to the input geometry, with the following additional properties:
Additionally, the Outline method can be useful in removing redundant portions of said geometries to simplify complex geometries. It can also be useful in combination with
Computes the area of the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
\t\nThe transform to apply to this geometry before computing its area, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this this method returns, contains a reference to the area of the transformed, flattened version of this geometry. You must allocate storage for this parameter.
Calculates the point and tangent vector at the specified distance along the geometry after it has been transformed by the specified matrix and flattened using the specified tolerance.
\t\nThe distance along the geometry of the point and tangent to find. If this distance is less then 0, this method calculates the first point in the geometry. If this distance is greater than the length of the geometry, this method calculates the last point in the geometry.
The transform to apply to the geometry before calculating the specified point and tangent, or
The maximum bounds on the distance between points in the polygonal approximation of the geometry. Smaller values produce more accurate results but cause slower execution.
When this method returns, contains a reference to the tangent vector at the specified distance along the geometry. If the geometry is empty, this vector contains NaN as its x and y values. You must allocate storage for this parameter.
The location at the specified distance along the geometry. If the geometry is empty, this point contains NaN as its x and y values.
Widens the geometry by the specified stroke and writes the result to an
If this method succeeds, it returns
Gets the
Gets the
Creates Direct2D resources.
\t\nThe
A factory defines a set of CreateResource methods that can produce the following drawing resources:
To create an
When you create a factory, you can specify whether it is multithreaded or singlethreaded. A singlethreaded factory provides no serialization against any other single threaded instance within Direct2D, so, this mechanism provides a very large degree of scaling on the CPU.
You can also create a multithreaded factory instance. In this case, the factory and all derived objects can be used from any thread and each render target can be rendered to independently. Direct2D serializes calls to these objects, so a single multithreaded Direct2D instance won't scale as well on the CPU as many single threaded instances. However, the resources can be shared within the multithreaded instance.
Note that the qualifier \"On the CPU\": GPUs generally take advantage of fine-grained parallelism more so than CPUs. For example, multithreaded calls from the CPU might still end up being serialized when being sent to the GPU, however, a whole bank of pixel and vertex shaders will run in parallel to perform the rendering.
\t\nForces the factory to refresh any system defaults that it might have changed since factory creation.
\t\nIf this method succeeds, it returns
You should call this method before calling the GetDesktopDpi method, to ensure that the system DPI is current.
\t\nRetrieves the current desktop dots per inch (DPI). To refresh this value, call ReloadSystemMetrics.
\t\nUse this method to obtain the system DPI when setting physical pixel values, such as when you specify the size of a window.
\t\n Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Creates an
If this method succeeds, it returns
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one. To create a
Transforms the specified geometry and stores the result as an
If this method succeeds, it returns
Like other resources, a transformed geometry the inherits the resource space and threading policy of the factory that created it. This object is immutable.
When stroking a transformed geometry with the DrawGeometry method, the stroke width is not affected by the transform applied to the geometry. The stroke width is only affected by the world transform.
\t\nCreates an empty
If this method succeeds, it returns
Creates an
If this method succeeds, it returns
Creates a render target that renders to a Microsoft Windows Imaging Component (WIC) bitmap.
\t\nThe bitmap that receives the rendering output of the render target.
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
Your application should create render targets once and hold onto them for the life of the application or until the
Creates an
If this method succeeds, it returns
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the
Creates a render target that draws to a DirectX Graphics Infrastructure (DXGI) surface.
\t\nThe
The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.
When this method returns, contains the address of the reference to the
If this method succeeds, it returns
To write to a Direct3D surface, you obtain an
A DXGI surface render target is a type of
The DXGI surface render target and the DXGI surface must use the same DXGI format. If you specify the DXGI_FORMAT_UNKOWN format when you create the render target, it will automatically use the surface's format.
The DXGI surface render target does not perform DXGI surface synchronization.
For more information about creating and using DXGI surface render targets, see the Direct2D and Direct3D Interoperability Overview.
To work with Direct2D, the Direct3D device that provides the
When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Creates a render target that draws to a Windows Graphics Device Interface (GDI) device context.
\t\nThe rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. To enable the device context (DC) render target to work with GDI, set the DXGI format to
When this method returns, dcRenderTarget contains the address of the reference to the
If this method succeeds, it returns
Before you can render with a DC render target, you must use the render target's BindDC method to associate it with a GDI DC. Do this for each different DC and whenever there is a change in the size of the area you want to draw to.
To enable the DC render target to work with GDI, set the render target's DXGI format to
Your application should create render targets once and hold on to them for the life of the application or until the render target's EndDraw method returns the
Represents a composite geometry, composed of other
Geometry groups are a convenient way to group several geometries simultaneously so all figures of several distinct geometries are concatenated into one.
CreatingTo create a
Direct2D geometries are immutable and device-independent resources created by
Indicates how the intersecting areas of the geometries contained in this geometry group are combined.
\t\nA value that indicates how the intersecting areas of the geometries contained in this geometry group are combined.
Indicates the number of geometry objects in the geometry group.
\t\nThe number of geometries in the
Retrieves the geometries in the geometry group.
\t\nWhen this method returns, contains the address of a reference to an array of geometries to be filled by this method. The length of the array is specified by the geometryCount parameter. If the array is
A value indicating the number of geometries to return in the geometries array. If this value is less than the number of geometries in the geometry group, the remaining geometries are omitted. If this value is larger than the number of geometries in the geometry group, the extra geometries are set to
The returned geometries are referenced and counted, and the caller must release them.
\t\nIndicates how the intersecting areas of the geometries contained in this geometry group are combined.
\t\nIndicates the number of geometry objects in the geometry group.
\t\nDescribes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
\t\nThe
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
\t\nDescribes a geometric path that does not contain quadratic bezier curves or arcs.
\t\nA geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Describes a geometric path that can contain lines, arcs, cubic Bezier curves, and quadratic Bezier curves.
\t\nThe
A geometry sink consists of one or more figures. Each figure is made up of one or more line, curve, or arc segments. To create a figure, call the BeginFigure method, specify the figure's start point, and then use its Add methods (such as AddLine and AddBezier) to add segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
\t\nDescribes a geometric path that does not contain quadratic bezier curves or arcs.
\t\nA geometry sink consists of one or more figures. Each figure is made up of one or more line or Bezier curve segments. To create a figure, call the BeginFigure method and specify the figure's start point, then use AddLines and AddBeziers to add line and Bezier segments. When you are finished adding segments, call the EndFigure method. You can repeat this sequence to create additional figures. When you are finished creating figures, call the Close method.
To create geometry paths that can contain arcs and quadratic Bezier curves, use an
Specifies the method used to determine which points are inside the geometry described by this geometry sink and which points are outside.
\t\nThe method used to determine whether a given point is part of the geometry.
The fill mode defaults to
Specifies stroke and join options to be applied to new segments added to the geometry sink.
\t\nStroke and join options to be applied to new segments added to the geometry sink.
After this method is called, the specified segment flags are applied to each segment subsequently added to the sink. The segment flags are applied to every additional segment until this method is called again and a different set of segment flags is specified.
\t\nStarts a new figure at the specified point.
\t\nThe point at which to begin the new figure.
Whether the new figure should be hollow or filled.
If this method is called while a figure is currently in progress, the interface is invalidated and all future methods will fail.
\t\nCreates a sequence of lines using the specified points and adds them to the geometry sink.
\t\nA reference to an array of one or more points that describe the lines to draw. A line is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the first point in the array. if the array contains additional points, a line is drawn from the first point to the second point in the array, from the second point to the third point, and so on.
The number of points in the points array.
Creates a sequence of cubic Bezier curves and adds them to the geometry sink.
\t\nA reference to an array of Bezier segments that describes the Bezier curves to create. A curve is drawn from the geometry sink's current point (the end point of the last segment drawn or the location specified by BeginFigure) to the end point of the first Bezier segment in the array. if the array contains additional Bezier segments, each subsequent Bezier segment uses the end point of the preceding Bezier segment as its start point.
The number of Bezier segments in the beziers array.
Ends the current figure; optionally, closes it.
\t\nA value that indicates whether the current figure is closed. If the figure is closed, a line is drawn between the current point and the start point specified by BeginFigure.
Calling this method without a matching call to BeginFigure places the geometry sink in an error state; subsequent calls are ignored, and the overall failure will be returned when the Close method is called.
\t\nCloses the geometry sink, indicates whether it is in an error state, and resets the sink's error state.
\t\nIf this method succeeds, it returns
Do not close the geometry sink while a figure is still in progress; doing so puts the geometry sink in an error state. For the close operation to be successful, there must be one EndFigure call for each call to BeginFigure.
After calling this method, the geometry sink might not be usable. Direct2D implementations of this interface do not allow the geometry sink to be modified after it is closed, but other implementations might not impose this restriction.
\t\nCreates a line segment between the current point and the specified end point and adds it to the geometry sink.
\t\nThe end point of the line to draw.
Creates a cubic Bezier curve between the current point and the specified end point.
\t\nA structure that describes the control points and end point of the Bezier curve to add.
Creates a quadratic Bezier curve between the current point and the specified endpoint.
\t\nA structure that describes the control point and the endpoint of the quadratic Bezier curve to add.
Adds a sequence of quadratic Bezier segments as an array in a single call.
\t\nAn array of a sequence of quadratic Bezier segments.
A value indicating the number of quadratic Bezier segments in beziers.
Adds a single arc to the path geometry.
\t\nThe arc segment to add to the figure.
Represents an collection of
To create an
A gradient stop collection is a device-dependent resource: your application should create gradient stop collections after it initializes the render target with which the gradient stop collection will be used, and recreate the gradient stop collection whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
\t\nRetrieves the number of gradient stops in the collection.
\t\nThe number of gradient stops in the collection.
Copies the gradient stops from the collection into an array of
Gradient stops are copied in order of position, starting with the gradient stop with the smallest position value and progressing to the gradient stop with the largest position value.
\t\nIndicates the gamma space in which the gradient stops are interpolated.
\t\nThe gamma space in which the gradient stops are interpolated.
Indicates the behavior of the gradient outside the normalized gradient range.
\t\nThe behavior of the gradient outside the [0,1] normalized gradient range.
Retrieves the number of gradient stops in the collection.
\t\nIndicates the gamma space in which the gradient stops are interpolated.
\t\nIndicates the behavior of the gradient outside the normalized gradient range.
\t\nRepresents the backing store required to render a layer.
\t\nTo create a layer, call the CreateLayer method of the render target where the layer will be used. To draw to a layer, push the layer to the render target stack by calling the PushLayer method. After you have finished drawing to the layer, call the PopLayer method.
Between PushLayer and PopLayer calls, the layer is in use and cannot be used by another render target.
If the size of the layer is not specified, the corresponding PushLayer call determines the minimum layer size, based on the layer content bounds and the geometric mask. The layer resource can be larger than the size required by PushLayer without any rendering artifacts.
If the size of a layer is specified, or if the layer has been used and the required backing store size as calculated during PushLayer is larger than the layer, then the layer resource is expanded on each axis monotonically to ensure that it is large enough. The layer resource never shrinks in size.
CreatingTo create a layer, call the CreateLayer method of the render target where the layer will be used.
A layer is a device-dependent resource: your application should create layers after it initializes the render target with which the layers will be used, and recreate the layers whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
\t\nGets the size of the layer in device-independent pixels.
\t\nThe size of the layer in device-independent pixels.
Gets the size of the layer in device-independent pixels.
\t\nPaints an area with a linear gradient.
\t\nAn
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush start point and end point are also transformed.
It is possible to specify a gradient axis that does not completely fill the area that is being painted. When this occurs, the
To create a linear gradient brush, use the
A linear gradient brush is a device-dependent resource: your application should create linear gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
\t\nSets the starting coordinates of the linear gradient in the brush's coordinate space.
\t\nThe starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
\t\nSets the ending coordinates of the linear gradient in the brush's coordinate space.
\t\nThe ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
\t\nRetrieves the starting coordinates of the linear gradient.
\t\nThe starting two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
\t\nRetrieves the ending coordinates of the linear gradient.
\t\nThe ending two-dimensional coordinates of the linear gradient, in the brush's coordinate space.
The start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
\t\n Retrieves the
Retrieves or sets the starting coordinates of the linear gradient.
\t\nThe start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
\t\nRetrieves or sets the ending coordinates of the linear gradient.
\t\nThe start point and end point are described in the brush's space and are mapped to the render target when the brush is used. If there is a non-identity brush transform or render target transform, the brush's start point and end point are also transformed.
\t\n Retrieves the
Represents a set of vertices that form a list of triangles.
\t\nTo create a mesh, call the
A mesh is a device-dependent resource: your application should create meshes after it initializes the render target with which the meshes will be used, and recreate the meshes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
\t\nOpens the mesh for population.
\t\nWhen this method returns, contains a reference to a reference to an
If this method succeeds, it returns
Represents a complex shape that may be composed of arcs, curves, and lines.
\t\nAn
To create a path geometry, use the
Retrieves the geometry sink that is used to populate the path geometry with figures and segments.
\t\nWhen this method returns, geometrySink contains the address of a reference to the geometry sink that is used to populate the path geometry with figures and segments. This parameter is passed uninitialized.
Because path geometries are immutable and can only be populated once, it is an error to call Open on a path geometry more than once.
Note that the fill mode defaults to
Copies the contents of the path geometry to the specified
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
\t\nA reference that receives the number of segments in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of figures in the path geometry.
\t\nA reference that receives the number of figures in the path geometry when this method returns. You must allocate storage for this parameter.
If this method succeeds, it returns
Retrieves the number of segments in the path geometry.
\t\nRetrieves the number of figures in the path geometry.
\t\nPaints an area with a radial gradient.
\t\nThe
The brush maps the gradient stop position 0.0f of the gradient origin, and the position 1.0f is mapped to the ellipse boundary. When the gradient origin is within the ellipse, the contents of the ellipse enclose the entire [0, 1] range of the brush gradient stops. If the gradient origin is outside the bounds of the ellipse, the brush still works, but its gradient is not well-defined.
The start point and end point are described in the brush space and are mappped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps just one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush ellipse and gradient origin are also transformed.
It is possible to specify an ellipse that does not completely fill area being painted. When this occurs, the
To create a radial gradient brush, use the
A radial gradient brush is a device-dependent resource: your application should create radial gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)
\t\nSpecifies the center of the gradient ellipse in the brush's coordinate space.
\t\nThe center of the gradient ellipse, in the brush's coordinate space.
Specifies the offset of the gradient origin relative to the gradient ellipse's center.
\t\nThe offset of the gradient origin from the center of the gradient ellipse.
Specifies the x-radius of the gradient ellipse, in the brush's coordinate space.
\t\nThe x-radius of the gradient ellipse. This value is in the brush's coordinate space.
Specifies the y-radius of the gradient ellipse, in the brush's coordinate space.
\t\nThe y-radius of the gradient ellipse. This value is in the brush's coordinate space.
Retrieves the center of the gradient ellipse.
\t\nThe center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the offset of the gradient origin relative to the gradient ellipse's center.
\t\nThe offset of the gradient origin from the center of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the x-radius of the gradient ellipse.
\t\nThe x-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the y-radius of the gradient ellipse.
\t\nThe y-radius of the gradient ellipse. This value is expressed in the brush's coordinate space.
Retrieves the
Retrieves or sets the center of the gradient ellipse.
\t\nRetrieves or sets the offset of the gradient origin relative to the gradient ellipse's center.
\t\nRetrieves or sets the x-radius of the gradient ellipse.
\t\nRetrieves or sets the y-radius of the gradient ellipse.
\t\nRetrieves the
Describes a two-dimensional rectangle.
\t\nTo create a rectangle geometry, use the
Direct2D geometries are immutable and device-independent resources created by
Retrieves the rectangle that describes the rectangle geometry's dimensions.
\t\nContains a reference to a rectangle that describes the rectangle geometry's dimensions when this method returns. You must allocate storage for this parameter.
Retrieves the rectangle that describes the rectangle geometry's dimensions.
\t\nRetrieves a rounded rectangle that describes this rounded rectangle geometry.
\t\nRetrieves a rounded rectangle that describes this rounded rectangle geometry.
\t\nA reference that receives a rounded rectangle that describes this rounded rectangle geometry. You must allocate storage for this parameter.
Retrieves a rounded rectangle that describes this rounded rectangle geometry.
\t\nPaints an area with a solid color.
\t\nTo create a solid color brush, use the
A solid color brush is a device-dependent resource. (For more information about resources, see Resources Overview.)
\t\nSpecifies the color of this solid-color brush.
\t\nThe color of this solid-color brush.
To help create colors, Direct2D provides the ColorF class. It offers several helper methods for creating colors and provides a set or predefined colors.
\t\nRetrieves the color of the solid color brush.
\t\nThe color of this solid color brush.
Retrieves or sets the color of the solid color brush.
\t\nDescribes the caps, miter limit, line join, and dash information for a stroke.
\t\nTo create a stroke style, use the
A stroke style is a device-indenpendent resource; you can create it once then retain it for the life of your application. For more information about resources, see the Resources Overview.
\t\nRetrieves the type of shape used at the beginning of a stroke.
\t\nThe type of shape used at the beginning of a stroke.
Retrieves the type of shape used at the end of a stroke.
\t\nThe type of shape used at the end of a stroke.
Gets a value that specifies how the ends of each dash are drawn.
\t\nA value that specifies how the ends of each dash are drawn.
Retrieves the limit on the ratio of the miter length to half the stroke's thickness.
\t\nA positive number greater than or equal to 1.0f that describes the limit on the ratio of the miter length to half the stroke's thickness.
Retrieves the type of joint used at the vertices of a shape's outline.
\t\nA value that specifies the type of joint used at the vertices of a shape's outline.
Retrieves a value that specifies how far in the dash sequence the stroke will start.
\t\nA value that specifies how far in the dash sequence the stroke will start.
Gets a value that describes the stroke's dash pattern.
\t\nA value that describes the predefined dash pattern used, or
If a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
\t\nRetrieves the number of entries in the dashes array.
\t\nThe number of entries in the dashes array if the stroke is dashed; otherwise, 0.
Copies the dash pattern to the specified array.
\t\nA reference to an array that will receive the dash pattern. The array must be able to contain at least as many elements as specified by dashesCount. You must allocate storage for this array.
The number of dashes to copy. If this value is less than the number of dashes in the stroke style's dashes array, the returned dashes are truncated to dashesCount. If this value is greater than the number of dashes in the stroke style's dashes array, the extra dashes are set to 0.0f. To obtain the actual number of dashes in the stroke style's dashes array, use the GetDashesCount method.
The dashes are specified in units that are a multiple of the stroke width, with subsequent members of the array indicating the dashes and gaps between dashes: the first entry indicates a filled dash, the second a gap, and so on.
\t\nRetrieves the type of shape used at the beginning of a stroke.
\t\nRetrieves the type of shape used at the end of a stroke.
\t\nGets a value that specifies how the ends of each dash are drawn.
\t\nRetrieves the limit on the ratio of the miter length to half the stroke's thickness.
\t\nRetrieves the type of joint used at the vertices of a shape's outline.
\t\nRetrieves a value that specifies how far in the dash sequence the stroke will start.
\t\nGets a value that describes the stroke's dash pattern.
\t\nIf a custom dash style is specified, the dash pattern is described by the dashes array, which can be retrieved by calling the GetDashes method.
\t\nRetrieves the number of entries in the dashes array.
\t\nPopulates an
Populates an
Copies the specified triangles to the sink.
\t\nAn array of
The number of triangles to copy from the triangles array.
Closes the sink and returns its error status.
\t\nIf this method succeeds, it returns
Represents a geometry that has been transformed.
\t\nUsing an
To create an
Direct2D geometries are immutable and device-independent resources created by
Retrieves the source geometry of this transformed geometry object.
\t\nWhen this method returns, contains a reference to a reference to the source geometry for this transformed geometry object. This parameter is passed uninitialized.
Retrieves the matrix used to transform the
Retrieves the source geometry of this transformed geometry object.
\t\nRetrieves the matrix used to transform the
Renders drawing instructions to a window.
\t\nAs is the case with other render targets, you must call BeginDraw before issuing drawing commands. After you've finished drawing, call EndDraw to indicate that drawing is finished and to release access to the buffer backing the render target. For
A hardware render target's back-buffer is the size specified by GetPixelSize. If EndDraw presents the buffer, this bitmap is stretched to cover the surface where it is presented: the entire client area of the window. This stretch is performed using bilinear filtering if the render target is rendering in hardware and using nearest-neighbor filtering if the rendering target is using software. (Typically, an application will call Resize to ensure the pixel size of the render target and the pixel size of the destination match, and no scaling is necessary, though this is not a requirement.)
In the case where a window straddles adapters, Direct2D ensures that the portion of the off-screen render target is copied from the adapter where rendering is occurring to the adapter that needs to display the contents. If the adapter a render target is on has been removed or the driver upgraded while the application is running, this is returned as an error in the EndDraw call. In this case, the application should create a new render target and resources as necessary.\t\n
CreatingTo create an
Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the
Indicates whether the
A value that indicates whether the
Note??If the window was occluded the last time that EndDraw was called, the next time that the render target calls CheckWindowState, it will return
After this method is called, the contents of the render target's back-buffer are not defined, even if the
Returns the
The
Returns the
Describes an elliptical arc between two points.
\t\nThe end point of the arc.
The x-radius and y-radius of the arc.
A value that specifies how many degrees in the clockwise direction the ellipse is rotated relative to the current coordinate system.
A value that specifies whether the arc sweep is clockwise or counterclockwise.
A value that specifies whether the given arc is larger than 180 degrees.
Represents a cubic bezier segment drawn between two points.
\t\nA cubic Bezier curve is defined by four points: a start point, an end point (point3), and two control points (point1 and point2). A Bezier segment does not contain a property for the starting point of the curve; it defines only the end point. The beginning point of the curve is the current point of the path to which the Bezier curve is added.
The two control points of a cubic Bezier curve behave like magnets, attracting portions of what would otherwise be a straight line toward themselves and producing a curve. The first control point, point1, affects the beginning portion of the curve; the second control point, point2, affects the ending portion of the curve.
Note??The curve doesn't necessarily pass through either of the control points; each control point moves its portion of the line toward itself, but not through itself.
\t\nThe first control point for the Bezier segment.
The second control point for the Bezier segment.
The end point for the Bezier segment.
Describes the extend modes and the interpolation mode of an
Describes the opacity and transformation of a brush.
\t\nThis structure is used when creating a brush. For convenience, Direct2D provides the D2D1::BrushProperties function for creating
After creating a brush, you can change its opacity or transform by calling the SetOpacity or SetTransform methods.
\t\nA value between 0.0f and 1.0f, inclusive, that specifies the degree of opacity of the brush.
The transformation that is applied to the brush.
Describes the drawing state of a render target.
\t\nThe antialiasing mode for subsequent nontext drawing operations.
The antialiasing mode for subsequent text and glyph drawing operations.
A label for subsequent drawing operations.
A label for subsequent drawing operations.
The transformation to apply to subsequent drawing operations.
Contains the debugging level of an
To enable debugging, you must install the Direct2D Debug Layer.
\t\nContains the position and color of a gradient stop.
\t\nGradient stops can be specified in any order if they are at different positions. Two stops may share a position. In this case, the first stop specified is treated as the \"low\" stop (nearer 0.0f) and subsequent stops are treated as \"higher\" (nearer 1.0f). This behavior is useful if a caller wants an instant transition in the middle of a stop.
Typically, there are at least two points in a collection, although creation with only one stop is permitted. For example, one point is at position 0.0f, another point is at position 1.0f, and additional points are distributed in the [0, 1] range. Where the gradient progression is beyond the range of [0, 1], the stops are stored, but may affect the gradient.
When drawn, the [0, 1] range of positions is mapped to the brush, in a brush-dependent way. For details, see
Gradient stops with a position outside the [0, 1] range cannot be seen explicitly, but they can still affect the colors produced in the [0, 1] range. For example, a two-stop gradient 0.0f, Black}, {2.0f, White is indistinguishable visually from 0.0f, Black}, {1.0f, Mid-level gray. Also, the colors are clamped before interpolation.
\t\nA value that indicates the relative position of the gradient stop in the brush. This value must be in the [0.0f, 1.0f] range if the gradient stop is to be seen explicitly.
The color of the gradient stop.
Contains the
Use this structure when you call the CreateHwndRenderTarget method to create a new
For convenience, Direct2D provides the D2D1::HwndRenderTargetProperties function for creating new
Contains the starting point and endpoint of the gradient axis for an
Use this method when creating new
The following illustration shows how a linear gradient changes as you change its start and end points. For the first gradient, the start point is set to (0,0) and the end point to (150, 50); this creates a diagonal gradient that starts at the upper-left corner and extends to the lower-right corner of the area being painted. When you set the start point to (0, 25) and the end point to (150, 25), a horizontal gradient is created. Similarly, setting the start point to (75, 0) and the end point to (75, 50) creates a vertical gradient. Setting the start point to (0, 50) and the end point to (150, 0) creates a diagonal gradient that starts at the lower-left corner and extends to the upper-right corner of the area being painted.
\t\nContains the data format and alpha mode for a bitmap or render target.
\t\nFor more information about the pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
\t\nA value that specifies the size and arrangement of channels in each pixel.
A value that specifies whether the alpha channel is using pre-multiplied alpha, straight alpha, whether it should be ignored and considered opaque, or whether it is unkown.
Contains the control point and end point for a quadratic Bezier segment.
\t\nThe control point of the quadratic Bezier segment.
The end point of the quadratic Bezier segment.
Contains the gradient origin offset and the size and position of the gradient ellipse for an
Different values for center, gradientOriginOffset, radiusX and/or radiusY produce different gradients. The following illustration shows several radial gradients that have different gradient origin offsets, creating the appearance of the light illuminating the circles from different angles.
For convenience, Direct2D provides the D2D1::RadialGradientBrushProperties function for creating new D2D1_RADIAL_GRADIENT_BRUSH structures.
\t\nContains rendering options (hardware or software), pixel format, DPI information, remoting options, and Direct3D support requirements for a render target.
\t\nUse this structure when creating a render target, or use it with the
As a convenience, Direct2D provides the D2D1::RenderTargetProperties helper function for creating
Not all render targets support hardware rendering. For a list, see the Render Targets Overview.
Using Default DPI SettingsTo use the default DPI, set dpiX and dpiY to 0. The default DPI varies depending on the render target:
To use the default DPI setting, both dpiX and dpiY must be set to 0. Setting only one value to 0 causes an E_INVALIDARG error when attempting to create a render target.
\t\nA value that specifies whether the render target should force hardware or software rendering. A value of
The pixel format and alpha mode of the render target. You can use the D2D1::PixelFormat function to create a pixel format that specifies that Direct2D should select the pixel format and alpha mode for you. For a list of pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.
The horizontal DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
The vertical DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.
A value that specifies how the render target is remoted and whether it should be GDI-compatible. Set to
A value that specifies the minimum Direct3D feature level required for hardware rendering. If the specified minimum level is not available, the render target uses software rendering if the type member is set to
Contains the dimensions and corner radii of a rounded rectangle.
\t\nEach corner of the rectangle specified by the rect is replaced with a quarter ellipse, with a radius in each direction specified by radiusX and radiusY.
If the radiusX is greater than or equal to half the width of the rectangle, and the radiusY is greater than or equal to one-half the height, the rounded rectangle is an ellipse with the same width and height of the rect.
Even when both radiuX and radiusY are zero, the rounded rectangle is different from a rectangle., When stroked, the corners of the rounded rectangle are roundly joined, not mitered (square).
\t\nThe coordinates of the rectangle.
The x-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
The y-radius for the quarter ellipse that is drawn to replace every corner of the rectangle.
Describes the stroke that outlines a shape.
\t\nThe following illustration shows different dashOffset values for the same custom dash style.
\t\nThe cap applied to the start of all the open figures in a stroked geometry.
The cap applied to the end of all the open figures in a stroked geometry.
The shape at either end of each dash segment.
A value that describes how segments are joined. This value is ignored for a vertex if the segment flags specify that the segment should have a smooth join.
The limit of the thickness of the join on a mitered corner. This value is always treated as though it is greater than or equal to 1.0f.
A value that specifies whether the stroke has a dash pattern and, if so, the dash style.
A value that specifies an offset in the dash sequence. A positive dash offset value shifts the dash pattern, in units of stroke width, toward the start of the stroked geometry. A negative dash offset value shifts the dash pattern, in units of stroke width, toward the end of the stroked geometry.
Contains the three vertices that describe a triangle.
\t\nThe first vertex of a triangle.
The second vertex of a triangle.
The third vertex of a triangle.
Get data from the GPU asynchronously.
\t\nGetData retrieves the data collected between calls to
If DataSize is 0, GetData is only used to check status where a return value of
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
| Query Type | Output Data Type | Supports Begin Method |
|---|---|---|
| NO | ||
| UINT64 | YES | |
| UINT64 | NO | |
| YES | ||
| YES | ||
| YES | ||
| YES | ||
| YES |
?
If the asynchronous interface that calls this API is
| Counter Type | Output Data Type | Units |
|---|---|---|
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction | |
| FLOAT32 | fraction |
?
The value returned by a
The number of parallel counters that a video card has is available from NumDetectableParallelUnits in
A device-child interface accesses data used by a device.
\t\nThere are several types of device child interfaces, all of which inherit this interface. They include shaders, state objects, and input layouts.
\t\nGet a reference to the device that created this interface.
\t\nAddress of a reference to a device (see
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.
\t\nGet data from a device that is associated with a guid.
\t\nGuid associated with the data.
Size of the data.
Pointer to the data stored with the device. If pData is
This method returns one of the following Direct3D 10 Return Codes.
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
Set application-defined data to a device child and associate that data with an application-defined guid.
\t\nGuid associated with the data.
Size of the data.
Pointer to the data to be stored with this device child. If pData is
This method returns one of the following Direct3D 10 Return Codes.
The data stored in the device child with this method can be retrieved with
Associate an
This method returns one of the following Direct3D 10 Return Codes.
When this method is called ::addref() will be called on the
Get a reference to the device that created this interface.
\t\nAny 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.
\t\nStarts the collection of GPU data.
\t\nCalling Begin starts the asynchronous collection of GPU data. Calling
Ends the collection of GPU data.
\t\nCalling
Get data from the GPU asynchronously.
\t\nAddress of memory that will receive the data. If
Size of the data to retrieve or 0. This value can be obtained with
Optional flags. Can be 0 or any combination of the flags enumerated by
If this function succeeds, it returns
GetData retrieves the data collected between calls to
If DataSize is 0, GetData is only used to check status where a return value of
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
| Query Type | Output Data Type | Supports Begin Method |
|---|---|---|
| NO | ||
| UINT64 | YES | |
| UINT64 | NO | |
| YES | ||
| YES | ||
| YES | ||
| YES | ||
| YES |
?
If the asynchronous interface that calls this API is
| Counter Type | Output Data Type | Units |
|---|---|---|
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of theoretical maximum | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction of time | |
| FLOAT32 | fraction | |
| FLOAT32 | fraction |
?
The value returned by a
The number of parallel counters that a video card has is available from NumDetectableParallelUnits in
Get the size of the data (in bytes) that is output when calling
Size of the data (in bytes) that is output when calling GetData.
This blend-state interface accesses blending state for a Direct3D 10.0 device for the output-merger stage.
\t\nBlending 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
Get the blend state.
\t\nA reference to the blend state (see
Get the blend state.
\t\nThis blend-state interface accesses blending state for a Direct3D 10.1 device for the output-merger stage.
\t\nBlending 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
This method requires Windows Vista Service Pack 1.
\t\nA buffer interface accesses a buffer resource, which is unstructured memory. Buffers typically store vertex or index data.
\t\nThree 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
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.
\t\nA resource interface provides common actions on all resources.
\t\nA 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).
\t\nGet the type of the resource.
\t\nPointer to the resource type (see
Set the eviction priority of a resource.
\t\nEviction priority for the resource, which is one of the following values:
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,
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
Get the eviction priority of a resource.
\t\nOne of the following values, which specifies the eviction priority for the resource:
This method is a wrapper for GetEvictionPriority and is provided in the
Get the type of the resource.
\t\nGet or sets the eviction priority of a resource.
\t\nThis method is a wrapper for GetEvictionPriority and is provided in the
Get a reference to the data contained in the resource and deny GPU access to the resource.
\t\nFlag that specifies the CPU's permissions for the reading and writing of a resource. For possible values, see
Flag that specifies what the CPU should do when the GPU is busy (see
Pointer to the buffer resource data.
If this function succeeds, it returns
For more information about the preceding return values, see DXGI_ERROR.
For the CPU to write the contents of a resource, the resource must be created with the dynamic usage flag,
Call
| Differences between Direct3D 9 and Direct3D 10: |
?
\t\nInvalidate the reference to the resource retrieved by
| Differences between Direct3D 9 and Direct3D 10: Unmap() in Direct3D 10 is analogous to resource Unlock() in Direct3D 9. |
?
\t\nGet the properties of a buffer resource.
\t\nPointer to a resource description (see
Get the properties of a buffer resource.
\t\nDescribes a buffer resource.
\t\nThis structure is used by
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.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
Bind an input-layout object to the input-assembler stage.
\t\nInput-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.
\t\nBind an array of vertex buffers to the input-assembler stage.
\t\nFor 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
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.
\t\nBind an array of vertex buffers to the input-assembler stage.
\t\nFor 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
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.
\t\nBind an index buffer to the input-assembler stage.
\t\nFor 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
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.
\t\nBind information about the primitive type, and data order that describes input data for the input assembler stage.
\t\nGet a reference to the input-layout object that is bound to the input-assembler stage.
\t\nFor 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.
\t\nGet the vertex buffers bound to the input-assembler stage.
\t\nAny 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.
\t\nGet a reference to the index buffer that is bound to the input-assembler stage.
\t\nAny 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.
\t\nGet information about the primitive type, and data order that describes input data for the input assembler stage.
\t\nGet or sets a reference to the input-layout object that is bound to the input-assembler stage.
\t\nFor 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.
\t\nGet or sets information about the primitive type, and data order that describes input data for the input assembler stage.
\t\nThis interface encapsulates methods for measuring GPU performance.
\t\nA counter can be created with
This is a derived class of
Counter data is gathered by issuing an
Counters are best suited for profiling.
For a list of the types of performance counters, see
Get a counter description.
\t\nPointer to a counter description (see
Get a counter description.
\t\nA debug interface controls debug settings, validates pipeline state and can only be used if the debug layer is turned on.
\t\nThis interface is obtained by querying it from the
Set a bitfield of flags that will turn debug features on and off.
\t\nFeature-mask flags bitwise ORed together. If a flag is present, then that feature will be set to on, otherwise the feature will be set to off. See remarks for a list of flags.
This method returns one of the following Direct3D 10 Return Codes.
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:
| Application will wait for the GPU to finish processing the rendering operation before continuing. | |
| Runtime will additionally call | |
| Runtime will call Present. Presentation of render buffers will occur according to the settings established by prior calls to |
?
These feature-mask flags apply to the following rendering-operation methods:
Get a bitfield of flags that indicates which debug features are on or off.
\t\nMask of feature-mask flags bitwise ORed together. If a flag is present, then that feature will be set to on, otherwise the feature will be set to off. See
Set the number of milliseconds to sleep after Present is called.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
The application will only sleep if
Get the number of milliseconds to sleep after Present is called.
\t\nNumber of milliseconds to sleep after Present is called.
Value is set with
Set a swap chain that the runtime will use for automatically calling Present.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
The swap chain set by this method will only be used if
Get the swap chain that the runtime will use for automatically calling Present.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
The swap chain retrieved by this method will only be used if
Check the validity of pipeline state.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
When the debug layer is turned on all draw functions will do this operation.
\t\nGet or sets the number of milliseconds to sleep after Present is called.
\t\nValue is set with
Get or sets the swap chain that the runtime will use for automatically calling Present.
\t\nThe swap chain retrieved by this method will only be used if
A depth-stencil-state interface accesses depth-stencil state which sets up the depth-stencil test for the output-merger stage.
\t\nCreate a depth-stencil state object by calling
To initialize depth-stencil state, bind the depth-stencil-state object to the pipeline by calling
Get the depth-stencil state.
\t\nA reference to the depth-stencil state (see
Get the depth-stencil state.
\t\nA depth-stencil-view interface accesses a texture resource during depth-stencil testing.
\t\nTo create a depth-stencil view, call
To bind a depth-stencil view to the pipeline, call
A view interface specifies the parts of a resource the pipeline can access during rendering (see view).
\t\nA 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.
All resources must be bound to the pipeline before they can be accessed.
A view can also be used to access a typeless resource.
\t\nGet the resource that is accessed through this view.
\t\nAddress of a reference to the resource that is accessed through this view. (See
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.
\t\nGet the resource that is accessed through this view.
\t\nThis 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.
\t\nGet the depth-stencil view.
\t\nGet the depth-stencil view.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
IDXGIResource* pOtherResource(NULL);\n hr = pOtherDeviceResource->QueryInterface( __uuidof(IDXGIResource), (void**)&pOtherResource );\n HANDLE sharedHandle;\n pOtherResource->GetSharedHandle(&sharedHandle); \n 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.\n sharedHandle = NULL; // must be set to NULL to create, can use a valid handle here to open in D3D9\n pDevice9->CreateTexture(..., pTex2D_9, &sharedHandle);\n ...\n pDevice10->OpenSharedResource(sharedHandle, __uuidof(ID3D10Resource), (void**)(&tempResource10));\n tempResource10->QueryInterface(__uuidof(ID3D10Texture2D), (void**)(&pTex2D_10));\n tempResource10->Release();\n // now use pTex2D_10 with pDevice10 \n 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 D3D10_BOX sourceRegion;\t\n sourceRegion.left = 120;\t\n sourceRegion.right = 200;\t\n sourceRegion.top = 100;\t\n sourceRegion.bottom = 220;\t\n sourceRegion.front = 0;\t\n sourceRegion.back = 1; pd3dDevice->CopySubresourceRegion( pDestTexture, 0, 130, 120, 0, pSourceTexture, 0, &sourceRegion ); \t\n \t\n Notice that, for a 2D texture, front and back are always set to 0 and 1 respectively. \t\n Draw indexed, non-instanced primitives.
\t\nNumber of indices to draw.
Index of the first index to use when accesssing the vertex buffer; begin at StartIndexLocation to index vertices from the vertex buffer.
Offset from the start of the vertex buffer to the first vertex.
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.
\t\nDraw non-indexed, non-instanced primitives.
\t\nNumber of vertices to draw.
Index of the first vertex, which is usually an offset in a vertex buffer; it could also be used as the first vertex id generated for a shader parameter marked with the SV_TargetId?system-value semantic.
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.
\t\nDraw indexed, instanced primitives.
\t\nSize of the index buffer used in each instance.
Number of instances to draw.
Index of the first index.
Index of the first vertex. The index is signed, which allows a negative index. If the negative index plus the index value from the index buffer are less than 0, the result is undefined.
Index of the first instance.
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.
\t\nDraw non-indexed, instanced primitives.
\t\nNumber of vertices to draw.
Number of instances to draw.
Index of the first vertex.
Index of the first instance.
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).
\t\nSet a rendering predicate.
\t\nPointer to a predicate (see
If TRUE, rendering will be affected by when the predicate's conditions are met. If
The predicate must be in the \"issued\" or \"signaled\" state to be used for predication. While the predicate is set for predication, calls to
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
Draw geometry of an unknown size that was created by the geometry shader stage. See remarks.
\t\nA 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,
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.
\t\nCopy a region from a source resource to a destination resource.
\t\nA reference to the destination resource (see
Subresource index of the destination.
The x coordinate of the upper left corner of the destination region.
The y coordinate of the upper left corner of the destination region.
The z coordinate of the upper left corner of the destination region. For a 1D or 2D subresource, this must be zero.
A reference to the source resource (see
Subresource index of the source.
A 3D box (see
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:
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
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.
| Differences between Direct3D 10 and Direct3D 10.1: Direct3D 10 has the following limitations:
Direct3D 10.1 has added support for the following features:
|
?
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
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;\t\n sourceRegion.left = 120;\t\n sourceRegion.right = 200;\t\n sourceRegion.top = 100;\t\n sourceRegion.bottom = 220;\t\n sourceRegion.front = 0;\t\n sourceRegion.back = 1; pd3dDevice->CopySubresourceRegion( pDestTexture, 0, 130, 120, 0, pSourceTexture, 0, &sourceRegion );\t\n Notice that, for a 2D texture, front and back are always set to 0 and 1 respectively.
\t\nCopy the entire contents of the source resource to the destination resource using the GPU.
\t\nA reference to the destination resource (see
A reference to the source resource (see
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:
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
| Differences between Direct3D 10 and Direct3D 10.1: Direct3D 10.1 enables depth-stencil resources to be used as either a source or destination. Direct3D 10.1 enables multisampled resources to be used as source and destination only if both source and destination have identical multisampled count and quality. If source and destination differ in multisampled count and quality or one of them is multisampled and the other is not multisampled, the call to It is possible to copy between prestructured+typed resources and block-compressed textures. See Format Conversion using Direct3D 10.1. |
?
\t\nThe CPU copies data from memory to a subresource created in non-mappable memory. See remarks.
\t\nFor a shader-constant buffer; set pDstBox to
A resource cannot be used as a destination if:
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.
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
To calculate the source row pitch and source depth pitch for a given resource, use the following formulas:
In the case of this example 3D volume texture where the size of each element is 16 bytes, the formulas are as follows:
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;\t\n destRegion.left = 120;\t\n destRegion.right = 200;\t\n destRegion.top = 100;\t\n destRegion.bottom = 220;\t\n destRegion.front = 0;\t\n destRegion.back = 1; pd3dDevice->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );\t\n 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;\t\n destRegion.left = 120\t\n destRegion.right = 200;\t\n destRegion.top = 0;\t\n destRegion.bottom = 1;\t\n destRegion.front = 0;\t\n destRegion.back = 1; pd3dDevice->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );\t\n | Differences between Direct3D 10 and Direct3D 10.1: Direct3D 10.1 enables depth-stencil resources to be used as either a source or destination. |
?
\t\nSet all the elements in a render target to one value.
\t\nPointer to the rendertarget.
A 4-component array that represents the color to fill the render target with.
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.
| Differences between Direct3D 9 and Direct3D 10: Unlike Direct3D 9, the full extent of the resource view is always cleared. Viewport and scissor settings are not applied. |
?
\t\nClears the depth-stencil resource.
\t\nPointer to the depth stencil to be cleared.
Which parts of the buffer to clear. See
Clear the depth buffer with this value. This value will be clamped between 0 and 1.
Clear the stencil buffer with this value.
| Differences between Direct3D 9 and Direct3D 10: Unlike Direct3D 9, the full extent of the resource view is always cleared. Viewport and scissor settings are not applied. |
?
\t\nGenerate mipmaps for the given shader resource.
\t\nPointer to an
GenerateMips may be called on any
All video adapters will automatically generate mipmaps if you are using one of the following formats:
\t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n Some video adapters will automatically generate mipmaps for this format.
\t\n For all other unsupported formats, this method will silently fail.
\t\nCopy a multisampled resource into a non-multisampled resource. This API is most useful when re-using the resulting rendertarget of one render pass as an input to a second render pass.
\t\nDestination resource. Must be a created with the
A zero-based index, that identifies the destination subresource. See D3D10CalcSubresource for more details.
Source resource. Must be multisampled.
The source subresource of the source resource.
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:
| Scenario | Requirements |
|---|---|
| Source and destination are prestructured and typed | Both the source and destination must have identical formats and that format must be specified in the Format parameter. |
| One resource is prestructured and typed and the other is prestructured and typeless | The typed resource must have a format that is compatible with the typeless resource (i.e. the typed resource is |
| Source and destination are prestructured and typeless | Both the source and desintation must have the same typeless format (i.e. both must have |
?
\t\nGet the rendering predicate state.
\t\nAddress of a reference to a predicate (see
Address of a boolean to fill with the predicate comparison value.
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.
\t\nGet the reason why the device was removed.
\t\nPossible return values include:
For more detail on these return codes, see DXGI_ERROR.
Get the exception-mode flags.
\t\nA value that contains one or more exception flags; each flag specifies a condition which will cause an exception to be raised. The flags are listed in D3D10_RAISE_FLAG. A default value of 0 means there are no flags.
This method returns one of the following Direct3D 10 Return Codes.
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.
\t\nGet the exception-mode flags.
\t\nA value that contains one or more exception flags; each flag specifies a condition which will cause an exception to be raised. The flags are listed in D3D10_RAISE_FLAG. A default value of 0 means there are no flags.
An exception-mode flag is used to elevate an error condition to a non-continuable exception.
\t\nSet data to a device and associate that data with a guid.
\t\nGuid associated with the data.
Size of the data.
Pointer to the data to be stored with this device. If pData is
This method returns one of the following Direct3D 10 Return Codes.
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
Restore all default device settings; return the device to the state it was in when it was created. This will set all set all input/output resource slots, shaders, input layouts, predications, scissor rectangles, depth-stencil state, rasterizer state, blend state, sampler state, and viewports to
Send queued-up commands in the command buffer to the GPU.
\t\nMost 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).
\t\nCreate a buffer (vertex buffer, index buffer, or shader-constant buffer).
\t\nThis method returns one of the following Direct3D 10 Return Codes.
For example code, see:
Create an array of 1D textures (see Texture1D).
\t\nIf the method succeeds, the return code is
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
Create an array of 2D textures (see Texture2D).
\t\nIf the method succeeds, the return code is
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
Create a single 3D texture (see Texture3D).
\t\nIf the method succeeds, the return code is
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
Create a shader-resource view for accessing data in a resource.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
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.
\t\nCreate a render-target view for accessing resource data.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
A rendertarget view can be bound to the output merger stage by calling
Create a depth-stencil view for accessing resource data.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
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.
\t\nCreate an input-layout object to describe the input-buffer data for the input-assembler stage.
\t\nIf the method succeeds, the return code is
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.
| Differences between Direct3D 9 and Direct3D 10: Mapping the vertex data to the shader inputs with an input layout is a new way of doing things in Direct3D 10 that improves performance. In Direct3D 10 the vertex data is mapped to the shader inputs when the input layout object is created, whereas in Direct3D 9 this mapping was done at Draw time based on the currently bound vertex declarations, vertex buffers, and vertex shaders. Doing this mapping when the input layout object is created reduces or eliminates extra linkage work for drivers at Draw time because this re-mapping is no longer necessary. |
?
\t\nCreate a vertex-shader object from a compiled shader.
\t\nA reference to the compiled shader. To get this reference see Getting a Pointer to a Compiled Shader.
Size of the compiled vertex shader.
Address of a reference to an
This method returns one of the following Direct3D 10 Return Codes.
Create a geometry shader.
\t\nA reference to the compiled shader. To get this reference see Getting a Pointer to a Compiled Shader.
Size of the compiled geometry shader.
Address of a reference to an
This method returns one of the following Direct3D 10 Return Codes.
Once created, the shader can be set to the device by calling
Creates a geometry shader that can write to streaming output buffers.
\t\nA reference to the compiled geometry shader for a standard geometry shader plus stream output. For info on how to get this reference, see Getting a Pointer to a Compiled Shader.
To create the stream output without using a geometry shader, pass a reference to the output signature for the prior stage. To obtain this output signature, call the
Size of the compiled geometry shader.
Pointer to a
The number of entries in the array pointed to by pSODeclaration. Minimum 0, maximum 64.
The size, in bytes, of each element in the array pointed to by pSODeclaration. This parameter is only used when the output slot is 0 for all entries in pSODeclaration.
Address of a reference to an
This method returns one of the Direct3D 10 Return Codes.
For more info about using CreateGeometryShaderWithStreamOutput, see Create a Geometry-Shader Object with Stream Output.
\t\nCreate a pixel shader.
\t\nA reference to the compiled shader. To get this reference see Getting a Pointer to a Compiled Shader.
Size of the compiled pixel shader.
Address of a reference to an
This method returns one of the following Direct3D 10 Return Codes.
After creating the pixel shader, you can set it to the device using
Create a blend-state object that encapsules blend state for the output-merger stage.
\t\nPointer to a blend-state description (see
Address of a reference to the blend-state object created (see
This method returns one of the following Direct3D 10 Return Codes.
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.
\t\nCreate a depth-stencil state object that encapsulates depth-stencil test information for the output-merger stage.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
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.
\t\nCreate a rasterizer state object that tells the rasterizer stage how to behave.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
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.
\t\nCreate a sampler-state object that encapsulates sampling information for a texture.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
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.
\t\nThis interface encapsulates methods for querying information from the GPU.
\t\nPointer to a query description (see
Address of a reference to the query object created (see
This method returns one of the following Direct3D 10 Return Codes.
Creates a predicate.
\t\nPointer to a query description where the type of query must be a
Address of a reference to a predicate (see
This method returns one of the following Direct3D 10 Return Codes.
Create a counter object for measuring GPU performance.
\t\nPointer to a counter description (see
Address of a reference to a counter (see
If this function succeeds, it will return
E_INVALIDARG is returned whenever an out-of-range well-known or device-dependent counter is requested, or when the simulataneously active counters have been exhausted.
Get the support of a given format on the installed video device.
\t\nA
A bitfield of
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.
\t\nGet the number of quality levels available during multisampling.
\t\nThe texture format. See
The number of samples during multisampling.
Number of quality levels supported by the adapter. See remarks.
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.
\t\nGet a counter's information.
\t\nGet the type, name, units of measure, and a description of an existing counter.
\t\nPointer to a counter description (see
Pointer to the data type of a counter (see
Pointer to the number of hardware counters that are needed for this counter type to be created. All instances of the same counter type use the same hardware counters.
String to be filled with a brief name for the counter. May be
Length of the string returned to szName. Can be
Name of the units a counter measures, provided the memory the reference points to has enough room to hold the string. Can be
Length of the string returned to szUnits. Can be
A description of the counter, provided the memory the reference points to has enough room to hold the string. Can be
Length of the string returned to szDescription. Can be
This method returns one of the following Direct3D 10 Return Codes.
Length parameters can be
Get the flags used during the call to create the device with
A bitfield containing the flags used to create the device. See
Give a device access to a shared resource created on a different Direct3d device.
\t\nA resource handle. See remarks.
The globally unique identifier (
Address of a reference to the resource we are gaining access to.
This method returns one of the following Direct3D 10 Return Codes.
To share a resource between two Direct3D 10 devices the resource must have been created with the
The REFIID, or
When sharing a resource between two Direct3D 10 devices the unique handle of the resource can be obtained by querying the resource for the
* pOtherResource(null );\t\n hr = pOtherDeviceResource->QueryInterface( __uuidof(), (void**)&pOtherResource );\t\n HANDLE sharedHandle;\t\n 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 \t\n pDevice9->CreateTexture(..., pTex2D_9, &sharedHandle); \t\n ... \t\n pDevice10->OpenSharedResource(sharedHandle, __uuidof(), (void**)(&tempResource10)); \t\n tempResource10->QueryInterface(__uuidof(), (void**)(&pTex2D_10)); \t\n tempResource10->Release(); \t\n // now use pTex2D_10 with pDevice10 Textures being shared from D3D9 to D3D10 have the following restrictions.
If a shared texture is updated on one device
Get the reason why the device was removed.
\t\nGet or sets the exception-mode flags.
\t\nAn exception-mode flag is used to elevate an error condition to a non-continuable exception.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
Set the target output buffers for the StreamOutput stage, which enables/disables the pipeline to stream-out data.
\t\nCall
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
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.
\t\nSet the target output buffers for the StreamOutput stage, which enables/disables the pipeline to stream-out data.
\t\nCall
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
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.
\t\nGet the target output buffers for the StreamOutput stage of the pipeline.
\t\nAny 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.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
Bind one or more render targets and the depth-stencil buffer to the output-merger stage.
\t\nA 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
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.
\t\nBind one or more render targets and the depth-stencil buffer to the output-merger stage.
\t\nA 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
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.
\t\nSet the blend state of the output-merger stage.
\t\nBlend 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
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| BlendEnable | |
| SrcBlend | |
| DstBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DstBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask[8] |
?
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.
\t\nSets the depth-stencil state of the output-merger stage.
\t\nTo 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.
\t\nGet references to the render targets and the depth-stencil buffer that are available to the output-merger stage.
\t\nAny 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.
\t\nGet the blend state of the output-merger stage.
\t\nThe 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.
\t\nGets the depth-stencil state of the output-merger stage.
\t\nAny 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.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
Set the rasterizer state for the rasterizer stage of the pipeline.
\t\nTo create a rasterizer state interface, 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.
\t\nBind an array of viewports to the rasterizer stage of the pipeline.
\t\nAll 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.
\t\nBind an array of scissor rectangles to the rasterizer stage.
\t\nThe 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
Get the rasterizer state from the rasterizer stage of the pipeline.
\t\nAny 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.
\t\nGet the array of viewports bound to the rasterizer stage
\t\nGet the array of scissor rectangles bound to the rasterizer stage.
\t\nGet or sets the rasterizer state from the rasterizer stage of the pipeline.
\t\nAny 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.
\t\nThe device interface represents a virtual adapter for Direct3D 10.1; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
This method requires Windows Vista Service Pack 1.
\t\nCreate a shader-resource view for accessing data in a resource.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
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.
\t\nCreate a blend-state object that encapsules blend state for the output-merger stage.
\t\nPointer to a blend-state description (see
Address of a reference to the blend-state object created (see
This method returns one of the following Direct3D 10 Return Codes.
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.
\t\nGets the feature level of the hardware device.
\t\nThe feature level (see
This method requires Windows Vista Service Pack 1.
\t\nGets the feature level of the hardware device.
\t\nThis method requires Windows Vista Service Pack 1.
\t\nAn
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
* pIUnknown = (*)pEffect; pIUnknown->AddRef();\t\n Test an effect to see if it contains valid syntax.
\t\nTRUE if the code syntax is valid; otherwise
Test an effect to see if it is part of a memory pool.
\t\nTRUE if the effect is pooled; otherwise
Get the device that created the effect.
\t\nA reference to an
Returns one of the following Direct3D 10 Return Codes.
An effect is created for a specific device, by calling a function such as
Get an effect description.
\t\nA reference to an effect description (see
Returns one of the following Direct3D 10 Return Codes.
An effect description contains basic information about an effect such as the techniques it contains and the constant buffer resources it requires.
\t\nGet a constant buffer by index.
\t\nA zero-based index.
A reference to a
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.
\t\nGet a constant buffer by name.
\t\nThe constant-buffer name.
A reference to the constant buffer indicated by the Name. See
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.
\t\nGet a variable by index.
\t\nA zero-based index.
A reference to a
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
Get a variable by name.
\t\nThe variable name.
A reference to an
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
Get a variable by semantic.
\t\nThe semantic name.
A reference to the effect variable indicated by the Semantic. See
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
Get a technique by index.
\t\nA zero-based index.
A reference to an
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.
\t\nGet a technique by name.
\t\nThe name of the technique.
A reference to an
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.
\t\nMinimize the amount of memory required for an effect.
\t\nReturns one of the following Direct3D 10 Return Codes.
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
The following methods will fail after Optimize has been called on an effect.
Note that references retrieved with these methods before calling
Test an effect to see if the reflection metadata has been removed from memory.
\t\nTRUE if the effect is optimized; otherwise
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
Test an effect to see if it contains valid syntax.
\t\nTest an effect to see if it is part of a memory pool.
\t\nGet the device that created the effect.
\t\nAn effect is created for a specific device, by calling a function such as
Get an effect description.
\t\nAn effect description contains basic information about an effect such as the techniques it contains and the constant buffer resources it requires.
\t\nTest an effect to see if the reflection metadata has been removed from memory.
\t\nAn 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
The blend-variable interface accesses blend state.
\t\nAn
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.
\t\nThe
The lifetime of an
The
Compare the data type with the data stored.
\t\nTRUE if the syntax is valid; otherwise
This method checks that the data type matches the data stored after casting one interface to another (using any of the As methods).
\t\nGet type information.
\t\nA reference to an
Get a description.
\t\nA reference to an effect-variable description (see
Returns one of the following Direct3D 10 Return Codes.
Get an annotation by index.
\t\nA zero-based index.
A reference to an
Annonations can be attached to a technique, a pass or a gloval variable. For the syntax, see Annotation Syntax (Direct3D 10).
\t\nGet an annotation by name.
\t\nThe annotation name.
A reference to an
Annonations can be attached to a technique, a pass or a gloval variable. For the syntax, see Annotation Syntax (Direct3D 10).
\t\nGet a structure member by index.
\t\nA zero-based index.
A reference to an
If the effect variable is an structure, use this method to look up a member by index.
\t\nGet a structure member by name.
\t\nMember name.
A reference to an
If the effect variable is an structure, use this method to look up a member by name.
\t\nGet a structure member by semantic.
\t\nThe semantic.
A reference to an
If the effect variable is an structure, use this method to look up a member by attached semantic.
\t\nGet an array element.
\t\nA zero-based index; otherwise 0.
A reference to an
If the effect variable is an array, use this method to return one of the elements.
\t\nGet a constant buffer.
\t\nA reference to a
Effect variables are read-from or written-to a constant buffer.
\t\nGet a scalar variable.
\t\nA reference to a scalar variable. See
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.
\t\nGet a vector variable.
\t\nA reference to a vector variable. See
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.
\t\nGet a matrix variable.
\t\nA reference to a matrix variable. See
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.
\t\nGet a string variable.
\t\nA reference to a string variable. See
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.
\t\nGet a shader-resource variable.
\t\nA reference to a shader-resource variable. See
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.
\t\nGet a render-target-view variable.
\t\nA reference to a render-target-view variable. See
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.
\t\nGet a depth-stencil-view variable.
\t\nA reference to a depth-stencil-view variable. See
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.
\t\nGet a constant buffer.
\t\nA reference to a constant buffer. See
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.
\t\nGet a shader variable.
\t\nA reference to a shader variable. See
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.
\t\nGet a effect-blend variable.
\t\nA reference to an effect blend variable. See
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.
\t\nGet a depth-stencil variable.
\t\nA reference to a depth-stencil variable. See
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.
\t\nGet a rasterizer variable.
\t\nA reference to a rasterizer variable. See
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.
\t\nGet a sampler variable.
\t\nA reference to a sampler variable. See
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.
\t\nSet data.
\t\nA reference to the variable.
The offset (in bytes) from the beginning of the reference to the data.
The number of bytes to set.
Returns one of the following Direct3D 10 Return Codes.
This method does no conversion or type checking; it is therefore a very quick way to access array items.
\t\nGet data.
\t\nA reference to the variable.
The offset (in bytes) from the beginning of the reference to the data.
The number of bytes to get.
Returns one of the following Direct3D 10 Return Codes.
This method does no conversion or type checking; it is therefore a very quick way to access array items.
\t\nCompare the data type with the data stored.
\t\nThis method checks that the data type matches the data stored after casting one interface to another (using any of the As methods).
\t\nGet type information.
\t\nGet a description.
\t\nGet a constant buffer.
\t\nEffect variables are read-from or written-to a constant buffer.
\t\nGet a reference to a blend-state interface.
\t\nIndex into an array of blend-state interfaces. If there is only one blend-state interface, use 0.
The address of a reference to a blend-state interface (see
Get a reference to a blend-state variable.
\t\nIndex into an array of blend-state descriptions. If there is only one blend-state variable in the effect, use 0.
A reference to a blend-state description (see
Returns one of the following Direct3D 10 Return Codes.
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.
\t\nA depth-stencil-variable interface accesses depth-stencil state.
\t\nAn
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.
\t\nGet a reference to a depth-stencil interface.
\t\nIndex into an array of depth-stencil interfaces. If there is only one depth-stencil interface, use 0.
The address of a reference to a blend-state interface (see
Get a reference to a variable that contains depth-stencil state.
\t\nIndex into an array of depth-stencil-state descriptions. If there is only one depth-stencil variable in the effect, use 0.
A reference to a depth-stencil-state description (see
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.
\t\nA depth-stencil-view-variable interface accesses a depth-stencil view.
\t\nSet a depth-stencil-view resource.
\t\nA reference to a depth-stencil-view interface. See
Returns one of the following Direct3D 10 Return Codes.
Get a depth-stencil-view resource.
\t\nThe address of a reference to a depth-stencil-view interface. See
Set an array of depth-stencil-view resources.
\t\nA reference to an array of depth-stencil-view interfaces. See
The zero-based array index to set the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
Set an array of depth-stencil-view resources.
\t\nA reference to an array of depth-stencil-view interfaces. See
The zero-based array index to set the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
Get an array of depth-stencil-view resources.
\t\nA reference to an array of depth-stencil-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
A matrix-variable interface accesses a matrix.
\t\nSet a floating-point matrix.
\t\nA reference to the first element in the matrix.
Returns one of the following Direct3D 10 Return Codes.
Get a matrix.
\t\nA reference to the first element in a matrix.
Returns one of the following Direct3D 10 Return Codes.
Set an array of floating-point matrices.
\t\nA reference to the first matrix.
The number of matrix elements to skip from the start of the array.
The number of elements to set.
Returns one of the following Direct3D 10 Return Codes.
Get an array of matrices.
\t\nA reference to the first element of the first matrix in an array of matrices.
The offset (in number of matrices) between the start of the array and the first matrix returned.
The number of matrices in the returned array.
Returns one of the following Direct3D 10 Return Codes.
Transpose and set a floating-point matrix.
\t\nA reference to the first element of a matrix.
Returns one of the following Direct3D 10 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
\t\nTranspose and get a floating-point matrix.
\t\nA reference to the first element of a transposed matrix.
Returns one of the following Direct3D 10 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
\t\nTranspose and set an array of floating-point matrices.
\t\nA reference to an array of matrices.
The offset (in number of matrices) between the start of the array and the first matrix to set.
The number of matrices in the array to set.
Returns one of the following Direct3D 10 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
\t\nTranspose and get an array of floating-point matrices.
\t\nA reference to the first element of an array of tranposed matrices.
The offset (in number of matrices) between the start of the array and the first matrix to get.
The number of matrices in the array to get.
Returns one of the following Direct3D 10 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
\t\nA pass interface encapsulates state assignments within a technique.
The lifetime of an
The
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
Test a pass to see if it contains valid syntax.
\t\nTRUE if the code syntax is valid; otherwise
Get a pass description.
\t\nA reference to a pass description (see
Returns one of the following Direct3D 10 Return Codes.
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.
\t\nGet a vertex-shader description.
\t\nA reference to a vertex-shader description (see
Returns one of the following Direct3D 10 Return Codes.
An effect pass can contain render state assignments and shader object assignments.
\t\nGet a geometry-shader description.
\t\nA reference to a geometry-shader description (see
Returns one of the following Direct3D 10 Return Codes.
An effect pass can contain render state assignments and shader object assignments.
\t\nGet a pixel-shader description.
\t\nA reference to a pixel-shader description (see
Returns one of the following Direct3D 10 Return Codes.
An effect pass can contain render state assignments and shader object assignments.
\t\nGet an annotation by index.
\t\nA zero-based index.
A reference to an
Get an annotation by name.
\t\nThe name of the annotation.
A reference to an
Set the state contained in a pass to the device.
\t\nUnused.
Returns one of the following Direct3D 10 Return Codes.
Generate a mask for allowing/preventing state changes.
\t\nA reference to a state-block mask (see
Returns one of the following Direct3D 10 Return Codes.
Test a pass to see if it contains valid syntax.
\t\nGet a pass description.
\t\nA 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.
\t\nGet a vertex-shader description.
\t\nAn effect pass can contain render state assignments and shader object assignments.
\t\nGet a geometry-shader description.
\t\nAn effect pass can contain render state assignments and shader object assignments.
\t\nGet a pixel-shader description.
\t\nAn effect pass can contain render state assignments and shader object assignments.
\t\nDescribes an effect pass, which contains pipeline state.
\t\nGet a pass description by calling
A string that contains the name of the pass; otherwise
The number of annotations.
A reference to the input signature or the vertex shader; otherwise
The size of the input signature (in bytes).
The stencil-reference value used in the depth-stencil state (see Configuring Depth-Stencil Functionality (Direct3D 10)).
The sample mask for the blend state (see Configuring Blending Functionality (Direct3D 10)).
The per-component blend factors (RGBA) for the blend state (see Configuring Blending Functionality (Direct3D 10)).
Describes an effect variable that contains a shader.
\t\nTo get a shader description, call a method like
A reference to the variable that the shader came from. If it is an inline shader assignment, the returned interface will be an anonymous shader variable, which is not retrievable any other way. Its name in the variable description will be \"$Anonymous\". If there is no assignment of this type in the pass block, this will point to a shader variable that returns false when IsValid is called.
A zero-based array index; otherwise 0.
A pool interface represents a common memory space (or pool) for sharing variables between effects.
\t\nTo create an effect pool, call a function like
Get the effect that created the effect pool.
\t\nA reference to an
A rasterizer-variable interface accesses rasterizer state.
\t\nAn
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.
\t\nGet a reference to a rasterizer interface.
\t\nIndex into an array of rasterizer interfaces. If there is only one rasterizer interface, use 0.
The address of a reference to a rasterizer interface (see
Get a reference to a variable that contains rasteriser state.
\t\nIndex into an array of rasteriser-state descriptions. If there is only one rasteriser variable in the effect, use 0.
A reference to a rasteriser-state description (see
Returns one of the following Direct3D 10 Return Codes.
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.
\t\nGet an array of render-targets.
\t\nSet a render-target.
\t\nA reference to a render-target-view interface. See
Returns one of the following Direct3D 10 Return Codes.
Get a render-target.
\t\nThe address of a reference to a render-target-view interface. See
Set an array of render-targets.
\t\nSet an array of render-target-view interfaces. See
The zero-based array index to store the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
Set an array of render-targets.
\t\nSet an array of render-target-view interfaces. See
The zero-based array index to store the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
Get an array of render-targets.
\t\nA reference to an array of render-target-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
A sampler interface accesses sampler state.
\t\nAn
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.
\t\nGet a reference to a sampler interface.
\t\nIndex into an array of sampler interfaces. If there is only one sampler interface, use 0.
The address of a reference to a sampler interface (see
Get a reference to a variable that contains sampler state.
\t\nIndex into an array of sampler descriptions. If there is only one sampler variable in the effect, use 0.
A reference to a sampler description (see
Returns one of the following Direct3D 10 Return Codes.
Describes an effect shader.
\t\nTo get an effect-shader description, call
Passed into CreateInputLayout. Only valid on a vertex shader or geometry shader. See ID3D10Device_CreateInputLayout.
TRUE is the shader is defined inline; otherwise
A reference to the compiled shader.
The length of pBytecode.
A string that constains a declaration of the stream output from a geometry shader.
The number of entries in the input signature.
The number of entries in the output signature.
A shader-resource interface accesses a shader resource.
\t\nSet a shader resource.
\t\nThe address of a reference to a shader-resource-view interface. See
Returns one of the following Direct3D 10 Return Codes.
Get a shader resource.
\t\nThe address of a reference to a shader-resource-view interface. See
Set an array of shader resources.
\t\nThe address of an array of shader-resource-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
Set an array of shader resources.
\t\nThe address of an array of shader-resource-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
Get an array of shader resources.
\t\nThe address of an array of shader-resource-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 10 Return Codes.
Get an array of floating-point variables.
\t\nSet a floating-point variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 10 Return Codes.
Get a floating-point variable.
\t\nA reference to the variable.
Set an array of floating-point variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Get an array of floating-point variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Set an integer variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 10 Return Codes.
Get an integer variable.
\t\nA reference to the variable.
Set an array of integer variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Get an array of integer variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Set a boolean variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 10 Return Codes.
Get a boolean variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 10 Return Codes.
Set an array of boolean variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Get an array of boolean variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
A string-variable interface accesses a string variable.
\t\nGet the string.
\t\nA reference to the string.
Returns one of the following Direct3D 10 Return Codes.
Get an array of strings.
\t\nA reference to the first string in the array.
The offset (in number of strings) between the start of the array and the first string to get.
The number of strings in the returned array.
Returns one of the following Direct3D 10 Return Codes.
A vector-variable interface accesses a four-component vector.
\t\nSet a four-component vector that contains boolean data.
\t\nA reference to the first component.
Returns one of the following Direct3D 10 Return Codes.
Set a four-component vector that contains integer data.
\t\nA reference to the first component.
Returns one of the following Direct3D 10 Return Codes.
Set a four-component vector that contains floating-point data.
\t\nA reference to the first component.
Returns one of the following Direct3D 10 Return Codes.
Get a four-component vector that contains boolean data.
\t\nA reference to the first component.
Returns one of the following Direct3D 10 Return Codes.
Get a four-component vector that contains integer data.
\t\nA reference to the first component.
Returns one of the following Direct3D 10 Return Codes.
Get a four-component vector that contains floating-point data.
\t\nA reference to the first component.
Returns one of the following Direct3D 10 Return Codes.
Set an array of four-component vectors that contain boolean data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Set an array of four-component vectors that contain integer data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Set an array of four-component vectors that contain floating-point data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Get an array of four-component vectors that contain boolean data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Get an array of four-component vectors that contain integer data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
Get an array of four-component vectors that contain floating-point data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 10 Return Codes.
The
The
The LPD3DX10FONT type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DX10FONT;\t\n Retrieve the Direct3D device associated with the font object.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Note??Calling this method will increase the internal reference count on the
Get a description of the current font object.
\t\nPointer to a
If the method succeeds, the return value is
This method describes Unicode font objects if UNICODE is defined. Otherwise GetDescA is called, which returns a reference to the D3DX10FONT_DESCA structure.
\t\nRetrieve font characteristics.
\t\nPointer to a
Nonzero if the function is successful; otherwise 0.
Return a handle to a display device context (DC) that has the font set onto it.
\t\nHandle to a display DC.
Return information about the placement and orientation of a glyph in a character cell.
\t\nGlyph identifier.
Address of a reference to a ID3D10Texture object that contains the glyph.
Pointer to the smallest rectangle object that completely encloses the glyph. See
Pointer to the two-dimensional vector that connects the origin of the current character cell to the origin of the next character cell. See
If the method succeeds, the return value is
Load a series of characters into video memory to improve the efficiency of rendering to the device.
\t\nID of the first character to be loaded into video memory.
ID of the last character to be loaded into video memory.
If the method succeeds, the return value is
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;
This method internally converts characters to glyphs using the GDI function GetCharacterPlacement.
\t\nLoad a series of glyphs into video memory to improve the efficiency of rendering to the device.
\t\nID of the first glyph to be loaded into video memory.
ID of the last glyph to be loaded into video memory.
If the method succeeds, the return value is
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;
Load formatted text into video memory to improve the efficiency of rendering to the device. This method supports ANSI and Unicode strings.
\t\nPointer to a string of characters to be loaded into video memory. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR; otherwise, the data type resolves to LPCSTR. See Remarks.
Number of characters in the text string.
If the method succeeds, the return value is
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;
This method internally converts characters to glyphs using the GDI function GetCharacterPlacement.
\t\nDraw formatted text. This method supports ANSI and Unicode strings.
\t\nPointer to an
Pointer to a string to draw. If UNICODE is defined, this parameter type resolves to an LPCWSTR, otherwise, the type resolves to an LPCSTR. If the Count parameter is -1, the string must be
The number of characters in the string. If Count is -1, then the pString parameter is assumed to be a reference to a sprite containing a
Pointer to a
Specify the method of formatting the text. It can be any combination of the following values:
| Item | Description |
|---|---|
| DT_BOTTOM | Justify the text to the bottom of the rectangle. This value must be combined with DT_SINGLELINE. |
| DT_CALCRECT | Tell DrawText to automatically calculate the width and height of the rectangle based on the length of the string you tell it to draw. If there are multiple lines of text, |
| DT_CENTER | Center text horizontally in the rectangle. |
| DT_EXPANDTABS | Expand tab characters. The default number of characters per tab is eight. |
| DT_LEFT | Align text to the left. |
| DT_NOCLIP | Draw without clipping. |
| DT_RIGHT | Align text to the right. |
| DT_RTLREADING | Display text in right-to-left reading order for bidirectional text when a Hebrew or Arabic font is selected. The default reading order for all text is left-to-right. |
| DT_SINGLELINE | Display text on a single line only. Carriage returns and line feeds do not break the line. |
| DT_TOP | Top-justify text. |
| DT_VCENTER | Center text vertically (single line only). |
| DT_WORDBREAK | Break words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the pRect parameter. A carriage return/line feed sequence also breaks the line. |
?
Color of the text. See
If the function succeeds, the return value is the height of the text in logical units. If DT_VCENTER or DT_BOTTOM is specified, the return value is the offset from pRect (top to the bottom) of the drawn text. If the function fails, the return value is zero.
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.
\t\nRetrieve the Direct3D device associated with the font object.
\t\nNote??Calling this method will increase the internal reference count on the
Get a description of the current font object.
\t\nThis method describes Unicode font objects if UNICODE is defined. Otherwise GetDescA is called, which returns a reference to the D3DX10FONT_DESCA structure.
\t\nReturn a handle to a display device context (DC) that has the font set onto it.
\t\nIdentifies how to bind a resource to the pipeline.
\t\nIn 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:
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
Bind a buffer as a vertex buffer to the input-assembler stage.
Bind a buffer as an index buffer to the input-assembler stage.
Bind a buffer as a constant buffer to a shader stage; this flag may NOT be combined with any other bind flag.
Bind a buffer or texture to a shader stage; this flag cannot be used with the
Bind an output buffer for the stream-output stage.
Bind a texture as a render target for the output-merger stage.
Bind a texture as a depth-stencil target for the output-merger stage.
RGB or alpha blending operation.
\t\nThe 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.
\t\nAdd source 1 and source 2.
Subtract source 1 from source 2.
Subtract source 2 from source 1.
Find the minimum of source 1 and source 2.
Find the maximum of source 1 and source 2.
Blend options. A blend option identifies the data source and an optional pre-blend operation.
\t\nBlend operations are specified in a blend description.
\t\nThe data source is the color black (0, 0, 0, 0). No pre-blend operation.
The data source is the color white (1, 1, 1, 1). No pre-blend operation.
The data source is color data (RGB) from a pixel shader. No pre-blend operation.
The data source is color data (RGB) from a pixel shader. The pre-blend operation inverts the data, generating 1 - RGB.
The data source is alpha data (A) from a pixel shader. No pre-blend operation.
The data source is alpha data (A) from a pixel shader. The pre-blend operation inverts the data, generating 1 - A.
The data source is alpha data from a rendertarget. No pre-blend operation.
The data source is alpha data from a rendertarget. The pre-blend operation inverts the data, generating 1 - A.
The data source is color data from a rendertarget. No pre-blend operation.
The data source is color data from a rendertarget. The pre-blend operation inverts the data, generating 1 - RGB.
The data source is alpha data from a pixel shader. The pre-blend operation clamps the data to 1 or less. \t\n
The data source is the blend factor set with
The data source is the blend factor set with
The data sources are both color data output by a pixel shader. There is no pre-blend operation. This options supports dual-source color blending.
The data sources are both color data output by a pixel shader. The pre-blend operation inverts the data, generating 1 - RGB. This options supports dual-source color blending.
The data sources are alpha data output by a pixel shader. There is no pre-blend operation. This options supports dual-source color blending.
The data sources are alpha data output by a pixel shader. The pre-blend operation inverts the data, generating 1 - A. This options supports dual-source color blending.
Identify which components of each pixel of a render target are writable during blending.
\t\nThese flags can be combined with a bitwise OR.
\t\nComparison options.
\t\nA 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
Never pass the comparison.
If the source data is less than the destination data, the comparison passes.
If the source data is equal to the destination data, the comparison passes.
If the source data is less than or equal to the destination data, the comparison passes.
If the source data is greater than the destination data, the comparison passes.
If the source data is not equal to the destination data, the comparison passes.
If the source data is greater than or equal to the destination data, the comparison passes.
Always pass the comparison.
Performance counter types.
\t\nIn 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
A device can support one or more of these performance counters, but it is not required to support any of them.
\t\nPercentage of the time that the GPU is idle.
Percentage of the time that the GPU does vertex processing.
Percentage of the time that the GPU does geometry processing.
Percentage of the time that the GPU does pixel processing.
Percentage of the time that the GPU does other processing (not vertex, geometry, or pixel processing).
Percentage of bandwidth used on a host adapter. Value returned by
Percentage of bandwidth used by the local video memory. Value returned by
Percentage of throughput used for vertices. Value returned by
Percentage of throughput used for triangle setup. Value returned by
Percentage of throughput used for the fillrate. Value returned by
Percentage of time that a vertex shader spends sampling resources.
Percentage of time that a vertex shader spends doing computations.
Percentage of time that a geometry shader spends sampling resources.
Percentage of time that a geometry shader spends doing computations.
Percentage of time that a pixel shader spends sampling resources.
Percentage of time that a pixel shader spends doing computations.
Percentage of vertex data that was read from the vertex cache. For example, if 6 vertices were added to the cache and 3 of them were read from the cache, then the hit rate would be 0.5.
Percentage of texel data that was read from the vertex cache. For example, if 6 texels were added to the cache and 3 of them were read from the cache, then the hit rate would be 0.5.
Start of the device-dependent counters. See remarks.
Data type of a performance counter.
\t\nThese flags are an output parameter in
32-bit floating point.
16-bit unsigned integer.
32-bit unsigned integer.
64-bit unsigned integer.
Specifies the types of CPU access allowed for a resource.
\t\nThis enumeration is used in
Applications can combine one or more of these flags with a bitwise OR. When possible, create resources with no CPU access flags, as this enables better resource optimization.
\t\nThe resource is to be mappable so that the CPU can change its contents. Resources created with this flag cannot be set as outputs of the pipeline and must be created with either dynamic or staging usage (see
The resource is to be mappable so that the CPU can read its contents. Resources created with this flag cannot be set as either inputs or outputs to the pipeline and must be created with staging usage (see
Indicates triangles facing a particular direction are not drawn.
\t\nThis enumeration is part of a rasterizer-state object description (see
Always draw all triangles.
Do not draw triangles that are front-facing.
Do not draw triangles that are back-facing.
Specifies the parts of the depth stencil to clear. Usually used with
These flags can be bitwise ORed together.
\t\nSpecifies how to access a resource used in a depth-stencil view.
\t\nThis enumeration is used in
Identify the portion of a depth-stencil buffer for writing depth data.
\t\nDevice creation flags.
\t\nDevice creation flags are used by
An application might dynamically create (and destroy) threads to improve performance especially on a machine with multiple CPU cores. There may be cases, however, when an application needs to prevent extra threads from being created. This can happen when you want to simplify debugging, profile code or develop a tool for instance. For these cases, use
Use this flag if an application will only be calling D3D10 from a single thread. If this flag is not specified, the default behavior of D3D10 is to enter a lock during each API call to prevent multiple threads altering internal state. By using this flag no locks will be taken which can slightly increase performance, but could result in undefine behavior if D3D10 is called from multiple threads.
Create a device that supports the debug layer.
Create both a software (REF) and hardware (HAL) version of the device simultaneously, which allows an application to switch to a reference device to enable debugging. See
Prevents multiple threads from being created. When this flag is used with a WARP device, no additional threads will be created by WARP and all rasterization will occur on the calling thread. This flag is not recommended for general use. See remarks.
Return a
Causes device creation to fail if BGRA support is not available.
BGRA support enables the following formats.
Note that BGRA support may be present even if the application didn't specify
Reserved. This flag is currently not supported. Do not use.
The device-driver type.
\t\nThe device-driver type needs to be specified when the device is created (using
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
\t\nA hardware device; commonly called a HAL device.
A reference device; commonly called a REF device.
A
Reserved for later use.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature level 9_1 through level 10.1 with a high performance software implementation when hardware is not available. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide. Note that WARP is only available with the DirectX 11 Runtime (Windows 7, Windows Server 2008 R2, updated Windows Vista [KB971644]).
The version of hardware acceleration requested.
\t\nUse this enumeration when creating a device with
Note that 10level9 feature levels 9_1, 9_2, and 9_3 are only available with the Direct3D 11 runtime (Windows?7, Windows Server?2008?R2, updated Windows?Vista with Service Pack?2 (SP2) [KB 971644], and updated Windows Server?2008 [KB 971512]).
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
For an overview of the capabilities of each feature level, see Overview For Each Feature Level.
\t\nThe hardware supports Direct3D 10.0 features.
The hardware supports Direct3D 10.1 features.
The hardware supports 9.1 feature level.
The hardware supports 9.2 feature level.
The hardware supports 9.3 feature level.
Determines the fill mode to use when rendering triangles.
\t\nThis enumeration is part of a rasterizer-state object description (see
Draw lines connecting the vertices. Adjacent vertices are not drawn.
Fill the triangles formed by the vertices. Adjacent vertices are not drawn.
Filtering options during texture sampling.
\t\nDuring texture sampling, one or more texels are read and combined (this is calling filtering) to produce a single value. Point sampling reads a single texel while linear sampling reads two texels (endpoints) and linearly interpolates a third value between the endpoints.
HLSL texture-sampling functions also support comparison filtering during texture sampling. Comparison filtering compares each sampled texel against a comparison value. The boolean result is blended the same way that normal texture filtering is blended.
You can use HLSL intrinsic texture-sampling functions that implement texture filtering only or companion functions that use texture filtering with comparison filtering.
| Texture Sampling Function | Texture Sampling Function with Comparison Filtering |
|---|---|
| sample | samplecmp or samplecmplevelzero |
?
Comparison filters only work with textures that have the following formats: R32_FLOAT_X8X24_TYPELESS, R32_FLOAT, R24_UNORM_X8_TYPELESS, R16_UNORM.
\t\nUse point sampling for minification, magnification, and mip-level sampling.
Use point sampling for minification and magnification; use linear interpolation for mip-level sampling.
Use point sampling for minification; use linear interpolation for magnification; use point sampling for mip-level sampling.
Use point sampling for minification; use linear interpolation for magnification and mip-level sampling.
Use linear interpolation for minification; use point sampling for magnification and mip-level sampling.
Use linear interpolation for minification; use point sampling for magnification; use linear interpolation for mip-level sampling.
Use linear interpolation for minification and magnification; use point sampling for mip-level sampling.
Use linear interpolation for minification, magnification, and mip-level sampling.
Use anisotropic interpolation for minification, magnification, and mip-level sampling.
Use point sampling for minification, magnification, and mip-level sampling. Compare the result to the comparison value.
Use point sampling for minification and magnification; use linear interpolation for mip-level sampling. Compare the result to the comparison value.
Use point sampling for minification; use linear interpolation for magnification; use point sampling for mip-level sampling. Compare the result to the comparison value.
Use point sampling for minification; use linear interpolation for magnification and mip-level sampling. Compare the result to the comparison value.
Use linear interpolation for minification; use point sampling for magnification and mip-level sampling. Compare the result to the comparison value.
Use linear interpolation for minification; use point sampling for magnification; use linear interpolation for mip-level sampling. Compare the result to the comparison value.
Use linear interpolation for minification and magnification; use point sampling for mip-level sampling. Compare the result to the comparison value.
Use linear interpolation for minification, magnification, and mip-level sampling. Compare the result to the comparison value.
Use anisotropic interpolation for minification, magnification, and mip-level sampling. Compare the result to the comparison value.
For use in pixel shaders with textures that have the R1_UNORM format.
Texture filtering flags.
\t\nD3DX10 automatically performs gamma correction (to convert color data from RGB space to standard RGB space) when loading texture data. This is automatically done for instance when RGB data is loaded from a .png file into an sRGB texture. Use the SRGB filter flags to indicate if the data does not need to be converted into sRGB space.
\t\nNo scaling or filtering will take place. Pixels outside the bounds of the source image are assumed to be transparent black.
Each destination pixel is computed by sampling the nearest pixel from the source image.
Each destination pixel is computed by sampling the four nearest pixels from the source image. This filter works best when the scale on both axes is less than two.
Every pixel in the source image contributes equally to the destination image. This is the slowest of the filters.
Each pixel is computed by averaging a 2x2(x2) box of pixels from the source image. This filter works only when the dimensions of the destination are half those of the source, as is the case with mipmaps.
Pixels off the edge of the texture on the u-axis should be mirrored, not wrapped.
Pixels off the edge of the texture on the v-axis should be mirrored, not wrapped.
Pixels off the edge of the texture on the w-axis should be mirrored, not wrapped.
Specifying this flag is the same as specifying the
The resulting image must be dithered using a 4x4 ordered dither algorithm. This happens when converting from one format to another.
Do diffuse dithering on the image when changing from one format to another.
Input data is in standard RGB (sRGB) color space. See remarks.
Output data is in standard RGB (sRGB) color space. See remarks.
Same as specifying
Types of magnification or minification sampler filters.
\t\nPoint filtering used as a texture magnification or minification filter. The texel with coordinates nearest to the desired pixel value is used. The texture filter to be used between mipmap levels is nearest-point mipmap filtering. The rasterizer uses the color from the texel of the nearest mipmap texture.
Bilinear interpolation filtering used as a texture magnification or minification filter. A weighted average of a 2 x 2 area of texels surrounding the desired pixel is used. The texture filter to use between mipmap levels is trilinear mipmap interpolation. The rasterizer linearly interpolates pixel color, using the texels of the two nearest mipmap textures.
Which resources are supported for a given format and given device (see
These flags are used by functions which operate on one or more channels in a texture.
\t\nIndicates the red channel should be used.
Indicates the blue channel should be used.
Indicates the green channel should be used.
Indicates the alpha channel should be used.
Indicates the luminaces of the red, green, and blue channels should be used.
Image file formats supported by D3DXCreatexxx and D3DX10Savexxx functions.
\t\nSee Types of Bitmaps (GDI+) for more information on some of these formats.
D3DX10 makes use of the Windows Imaging Component to implement the majority of the supported bitmap file types. See Windows Imaging Component Overview for additional information.\t\n
\t\nWindows bitmap (BMP) file format. Contains a header that describes the resolution of the device on which the rectangle of pixels was created, the dimensions of the rectangle, the size of the array of bits, a logical palette, and an array of bits that defines the relationship between pixels in the bitmapped image and entries in the logical palette. The file extension for this format is .bmp.
Joint Photographic Experts Group (JPEG) compressed file format. Specifies variable compression of 24-bit RGB color and 8-bit gray-scale Tagged Image File Format (TIFF) image document files. The file extension for this format is .jpg.
Portable Network Graphics (PNG) file format. A non-proprietary bitmap format using lossless compression. The file extension for this format is .png.
DirectDraw surface (DDS) file format. Stores textures, volume textures, and cubic environment maps, with or without mipmap levels, and with or without pixel compression. The file extension for this format is .dds.
Tagged Image File Format (TIFF). The file extensions for this format are .tif and .tiff.
Graphics Interchange Format (GIF).The file extension for this format is .gif.
Windows Media Photo format (WMP). This format is also known as HD Photo and JPEG XR. The file extensions for this format are .hdp, .jxr, and .wdp.
To work properly,
Type of data contained in an input slot.
\t\nUse these values to specify the type of data for a particular input element (see
Input data is per-vertex data.
Input data is per-instance data.
Specifies how the CPU should respond when Map is called on a resource being used by the GPU.
\t\nThis enumeration is used by
For more information about potential conflicts between the GPU and CPU during resource mapping, see Copying and Accessing Resource Data (Direct3D 10).
\t\nSpecifies that Map should return
Identifies a resource to be accessed for reading and writing by the CPU. Applications may combine one or more of these flags.
\t\nThis enumeration is used in
These remarks are divided into the following topics:
For example, consider the buffer illustrated in the following diagram. If a Draw call has been issued that uses vertices 4-6, an application that calls Map on this buffer must ensure that it does not write to the vertices that the Draw call will access during rendering.
However, ensuring this can be difficult, because the GPU is often many frames behind the CPU in terms of which frame it is currently processing. Keeping track of which sections of a resource are being used because of calls made 2 to 5 frames ago is difficult and error-prone. Because of this, it is recommended that applications only write to the uninitialized portions of a resource when using
A common use of these two flags involves filling dynamic index/vertex buffers with geometry that can be seen from the camera's current position. The first time that data is entered into the buffer on a given frame, Map is called with
Subsequent writes to the buffer within the same frame should use
Resource is mapped for reading. The resource must have been created with read access (see
Resource is mapped for writing. The resource must have been created with write access (see
Resource is mapped for reading and writing. The resource must have been created with read and write access (see
Resource is mapped for writing; the previous contents of the resource will be undefined. The resource must have been created with write access (see
Resource is mapped for writing; the existing contents of the resource cannot be overwritten (see Remarks). This flag is only valid on vertex and index buffers. The resource must have been created with write access (see
Specifies which pieces of mesh data to discard from the device. Used with
Flags used to specify creation options for a mesh.
\t\nA 32-bit mesh (
The mesh has 32-bit indices instead of 16-bit indices. See Remarks.
Signals that the mesh contains geometry shader adjacency data.
Specifies the type of mesh optimization to be performed.
\t\nThe
The D3DXMESHOPT_SHAREVB flag has been removed from this enumeration. Use
Reorders faces to remove unused vertices and faces.
Reorders faces to optimize for fewer attribute bundle state changes and enhanced DrawSubset performance.
Reorders faces to increase the cache hit rate of vertex caches.
Reorders faces to maximize length of adjacent triangles.
Optimize the faces only; do not optimize the vertices.
While attribute sorting, do not split vertices that are shared between attribute groups.
Affects the vertex cache size. Using this flag specifies a default vertex cache size that works well on legacy hardware.
Categories of debug messages. This will identify the category of a message when retrieving a message with
This is part of the Information Queue feature. See
Debug message severity levels for an information queue.
\t\nUse these values to allow or deny message categories to pass through the storage and retrieval filters for an information queue (see
Defines some type of corruption which has occurred.
Defines an error message.
Defines a warning message.
Defines an information message.
These flags are used to control how
Flags that describe miscellaneous query behavior.
\t\nThis flag is part of a query description (see
Tell the hardware that if it is not yet sure if something is hidden or not to draw it anyway. This is only used with an occlusion predicate. Predication data cannot be returned to your application via
Query types.
\t\nDetermines whether or not the GPU is finished processing commands. When the GPU is finished processing commands GetData will return
Get the number of samples that passed the depth and stencil tests in between Begin and End. GetData returns a UINT64. If a depth or stencil test is disabled, then each of those tests will be counted as a pass.
Get a timestamp value where GetData returns a UINT64. This kind of query is only useful if two timestamp queries are done in the middle of a
Determines whether or not a
Get pipeline statistics, such as the number of pixel shader invocations in between Begin and End. GetData will return a
Similar to
Get streaming output statistics, such as the number of primitives streamed out in between Begin and End. GetData will return a
Determines whether or not any of the streaming output buffers overflowed in between Begin and End. GetData returns a
Specifies how to access a resource used in a render-target view.
\t\nThis enumeration is used in
Identifies the type of resource being used.
\t\nThis enumeration is used in
Identifies other, less common options for resources.
\t\nThis enumeration is used in
These flags can be combined by bitwise OR.
Enables an application to call
Enables the sharing of resource data between two or more Direct3D devices. The only resources that can be shared are 2D non-mipmapped textures.
WARP and REF devices do not support shared resources. Attempting to create a resource with this flag on either a WARP or REF device will cause the create method to return an E_OUTOFMEMORY error code.
Enables an application to create a cube texture from a Texture2DArray that contains 6 textures.
Enables the resource created to be synchronized using the
If any of the listed functions are called with the
WARP and REF devices do not support shared resources. Attempting to create a resource with this flag on either a WARP or REF device will cause the create method to return an E_OUTOFMEMORY error code.
Enables a surface to be used for GDI interoperability. Setting this flag enables rendering on the surface via
Identifies expected resource use during rendering. The usage directly reflects whether a resource is accessible by the CPU and/or the GPU.
\t\nAn application identifies the way a resource is intended to be used (its usage) in a resource description. There are several structures for creating resources including:
| Differences between Direct3D 9 and Direct3D 10: In Direct3D 9, you specify the type of memory a resource should be created in at resource creation time (using In Direct3D 10, an application no longer specifies what type of memory (the pool) to create a resource in. Instead, you specify the intended usage of the resource, and let the runtime (in concert with the driver and a memory manager) choose the type of memory that will achieve the best performance. |
?
Resource Usage RestrictionsEach usage dictates a tradeoff between functionality and performance. In general, resource accessing is accomplished with the following APIs.
Use the following table to choose the usage that best describes how the resource will need to be accessed by the CPU and/or the GPU. Of course, there will be performance tradeoffs.
| Resource Usage | Default | Dynamic | Immutable | Staging |
|---|---|---|---|---|
| GPU-Read | yes | yes1 | yes | yes1, 2 |
| GPU-Write | yes1 | yes1, 2 | ||
| CPU-Read | yes1, 2 | |||
| CPU-Write | yes | yes1, 2 |
?
To maximize performance, not all resource usage options can be used as input or output resources to the pipeline. This table identifies these limitations.
| Resource Can Be Bound As | Default | Dynamic | Immutable | Staging |
|---|---|---|---|---|
| Input to a Stage | yes3 | yes4 | yes | |
| Output from a Stage | yes3 |
?
A resource that requires read and write access by the GPU. This is likely to be the most common usage choice.
A resource that can only be read by the GPU. It cannot be written by the GPU, and cannot be accessed at all by the CPU. This type of resource must be initialized when it is created, since it cannot be changed after creation.
A resource that is accessible by both the GPU and the CPU (write only). A dynamic resource is a good choice for a resource that will be updated by the CPU at least once per frame. To write to a dynamic resource on the CPU, use a Map method. You can write to a dynamic resource on the GPU using CopyResource or CopySubresourceRegion.
A resource that supports data transfer (copy) from the GPU to the CPU.
Sprite flags that tell the sprite drawing API how to behave. These are passed into
After a front-to-back or back-to-front sort is done, it will automatically do a secondary sort by texture. This is helpful for when there are many sprites with the same texture all on the same plane, such as when drawing the user interface in a game.
\t\nThe stencil operations that can be performed during depth-stencil testing.
\t\nIdentify a technique for resolving texture coordinates that are outside of the boundaries of a texture.
\t\nTile the texture at every integer junction. For example, for u values between 0 and 3, the texture is repeated three times.
Flip the texture at every integer junction. For u values between 0 and 1, for example, the texture is addressed normally; between 1 and 2, the texture is flipped (mirrored); between 2 and 3, the texture is normal again; and so on.
Texture coordinates outside the range [0.0, 1.0] are set to the texture color at 0.0 or 1.0, respectively.
Texture coordinates outside the range [0.0, 1.0] are set to the border color specified in
Similar to
The different faces of a cube texture.
\t\nPositive X face.
Negative X face.
Positive Y face.
Negative Y face.
Positive Z face.
Negative Z face.
Create a Direct3D 10.1 device and a swap chain.
\t\nPointer to a
The type of driver for the device. See
A handle to the DLL that implements a software rasterizer. Must be
Optional. Device creation flags (see
The version of hardware that is available for acceleration (see
Bit flag that indicates the version of the SDK. Should be
Description of the swap chain. See
Address of a reference to an
Address of a reference to an
This method returns one of the following Direct3D 10 Return Codes.
To create a device without creating a swap chain, see
This method requires Windows Vista Service Pack 1, Windows Server 2008, or later release of Windows.
\t\nCreate a Direct3D 10.1 device that represents the display adapter.
\t\nPointer to the display adapter (see
The device-driver type (see
This is set to
Optional. Device creation flags (see
The version of hardware that is available for acceleration (see
Bit flag that indicates the version of the SDK. Should be
Address of a reference to the device created (see
This method returns one of the following Direct3D 10 Return Codes.
To create a device and a swap chain at the same time, see
This method requires Windows Vista Service Pack 1, Windows Server 2008, or later release of Windows.
The object returned by
* pDXGIDevice;\t\n hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice); Create an effect pool (or shared memory location), to enable sharing variables between effects.
\t\nA reference to a compiled effect.
Length of pData.
Effect compile options.
A reference to the device (see
A reference to the
Returns one of the following Direct3D 10 Return Codes.
A pool is a shared location in memory. Effect variables that are located in a pool can be updated once, and the effect system will take care of updating each effect that uses that variable. To pool an effect variable, tell the effect to locate the variable in a pool when the effect is created, using a helper function such as
For help compiling an effect, see Compile an Effect (Direct3D 10).
\t\nCreate a state block.
\t\nThe device for which the state block will be created.
Indicates which parts of the device state will be captured when calling
Address of a reference to the buffer created (see
This method returns one of the following Direct3D 10 Return Codes.
A state block is a collection of device state, and is used for saving and restoring device state. Use a state-block mask to enable subsets of state for saving and restoring.
The
| Differences between Direct3D 9 and Direct3D 10: In Direct3D 10, a state block object does not contain any valid information about the state of the device until |
?
\t\nCompile an effect.\t\n
Note??Use D3DX10CompileFromMemory instead of this function.
\t\nReturns one of the following Direct3D 10 Return Codes.
This function uses the version of the HLSL compiler released in the November 2006 DirectX SDK.
For an example, see Compile an Effect (Direct3D 10).
\t\nCreates an
A reference to a compiled effect.
Length of pData.
Effect compile options.
A reference to the device (see
Optional. A reference to an memory space for effect variables that are shared across effects (see
A reference to an
Returns one of the following Direct3D 10 Return Codes.
This method is used to create an
Create a Direct3D 10.0 device and a swap chain.
\t\nPointer to a
The type of driver for the device. See
A handle to the DLL that implements a software rasterizer. Must be
Optional. Device creation flags (see
Bit flag that indicates the version of the SDK. Should be
Description of the swap chain. See
Address of a reference to an
Address of a reference to an
This method returns one of the following Direct3D 10 Return Codes.
To create a device without creating a swap chain, see
Create a Direct3D 10.0 device that represents the display adapter.
\t\nPointer to the display adapter (see
The device-driver type (see
Reserved. Set to
Optional. Device creation flags (see
Bit flag that indicates the version of the SDK. Should always be
Address of a reference to the device created (see
This method returns one of the following Direct3D 10 Return Codes.
This example creates a reference device.
* g_pd3dDevice = null ;\t\n ( null , , null , 0, , &g_pd3dDevice ); To create a device and a swap chain at the same time, see
The object returned by
* pDXGIDevice;\t\n hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice); Get the vertex shader profile best suited to a given device.
\t\nThe shader profile.
Get the geometry shader profile best suited to a given device.
\t\nThe shader profile.
Get the pixel shader profile best suited to a given device.
\t\nThe shader profile.
Get a Direct3D 10.1 device interface reference from a Direct3D 10.0 interface reference.
\t\nPointer to the Direct3D 10.0 device (see the
Pointer to the Direct3D 10.1 device (see the
This function returns one of the following Direct3D 10 Return Codes. If a Direct3D 10.1 device interface can be acquired, this function succeeds and passes a reference to the 10.1 interface using the ppDevice parameter. If a Direct3D 10.1 device interface cannot be acquired, this function returns E_FAIL, and will not return anything for the ppDevice parameter.
For this function to succeed, you must have acquired the supplied
You can only create a Direct3D 10.1 device on computers running Windows Vista Service Pack 1 or later, and with Direct3D 10.1-compatible hardware installed. This function will return E_FAIL on any computer not meeting these requirements.\t\n However, you can call this function on any version of Windows that has the D3DX10 DLL installed.
\t\nCreates a font object for a device and font.
\t\nPointer to an
The height of the characters in logical units.
The width of the characters in logical units.
Typeface weight. One example is bold.
The number of mipmap levels.
True for italic font, false otherwise.
The character set of the font.
Specifies how Windows should attempt to match the desired font sizes and characteristics with actual fonts. Use OUT_TT_ONLY_PRECIS for instance, to ensure that you always get a TrueType font.
Specifies how Windows should match the desired font with a real font. It applies to raster fonts only and should not affect TrueType fonts.
Pitch and family index.
String containing the typeface name. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR. See Remarks.
Returns a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
If you want more information about font parameters, see The Logical Font.
\t\nCreates a font object.
\t\nPointer to an
Pointer to a
Returns a reference to an
The return value is one of the values listed in Direct3D 10 Return Codes.
Create the best Direct3D device and a swap chain.
\t\nPointer to a
The type of driver for the device. See
A handle to the DLL that implements a software rasterizer. Must be
Optional. Device creation flags (see
Description of the swap chain. See
Address of a reference to an
Address of a reference to an
This method returns one of the following Direct3D 10 Return Codes.
To create the best device, this method implements more than one device creation option. First, the method attempts to create a 10.1 device (and swap chain). If that fails, the method attempts to create a 10.0 device. If that fails, the method will fail. If your application needs to create only a 10.1 device, or a 10.0 device only, use these APIs instead:
This method requires Windows Vista Service Pack 1.
\t\nCreate a sprite for drawing a 2D texture.
\t\nA reference to the device (see
The size of the vertex buffer, in number of sprites, that will be sent to the device when
The address of a reference to a sprite interface (see
If the function succeeds, the return value is
Verify that the version of D3DX you compiled with is the version that you are running.
\t\nUse
Use D3DX10_SDK_VERSION. See remarks.
If the version doesn't match, the function will return
Use this function during the initialization of your application.
hr; if( FAILED( (, D3DX10_SDK_VERSION) ) ) return E_FAIL;\t\n Create the best Direct3D 10 device that represents the display adapter. If a Direct3D 10.1-compatible device can be created, it will be possible to acquire an
This function returns one of the following Direct3D 10 Return Codes.
This function attempts to create the best device for the hardware. First, the function attempts to create a 10.1 device. If a 10.1 device cannot be created, the function attempts to create a 10.0 device. If neither device is successfully created, the function returns E_FAIL.
If your application needs to create only a 10.1 device, or a 10.0 device only, use the following functions instead:
A Direct3D 10.1 device can only be created on computers running Windows Vista Service Pack 1 or later, and with Direct3D 10.1-compatible hardware installed. However, it is legal to call this function on computers running any version of Windows that has the D3DX10 DLL installed.
\t\nCreate a shader-resource view from a file.
\t\nA reference to the device (see
Name of the file that contains the shader-resource view. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Identifies the characteristics of a texture (see
Pointer to a thread-pump interface (see
Address of a reference to the shader-resource view (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
Save a texture to a file.
\t\nPointer to the texture to be saved. See
The format the texture will be saved as (see
Name of the destination output file where the texture will be saved. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
The return value is one of the values listed in Direct3D 10 Return Codes; use the return value to see if the DestFormat is supported.
Converts a height map into a normal map. The (x,y,z) components of each normal are mapped to the (r,g,b) channels of the output texture.
\t\nPointer to an
One or more
One
Constant value multiplier that increases (or decreases) the values in the normal map. Higher values usually make bumps more visible, lower values usually make bumps less visible.
Pointer to an
If the function succeeds, the return value is
This method computes the normal by using the central difference with a kernel size of 3x3. RGB channels in the destination contain biased (x,y,z) components of the normal. The central differencing denominator is hardcoded to 2.0.
\t\nGet information about an image already loaded into memory.
\t\nPointer to the image in memory.
Size of the image in memory, in bytes.
Optional thread pump that can be used to load the info asynchronously. Can be
Information about the image in memory.
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
Retrieves information about a given image in a resource.
\t\nModule where the resource is loaded. Set this parameter to
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR. See Remarks.
Optional thread pump that can be used to load the info asynchronously. Can be
Pointer to a
A reference to the return value. May be
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Create a texture resource from a file.
\t\nA reference to the device (see
The name of the file containing the resource. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR. See
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
The address of a reference to the texture resource (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
For a list of supported image formats see
Save a texture to memory.
\t\nPointer to the texture to be saved. See
The format the texture will be saved as. See
Address of a reference to the memory containing the saved texture. See
Optional.
The return value is one of the values listed in Direct3D 10 Return Codes.
Create a shader-resource view from a resource.
\t\nA reference to the device (see
Handle to the resource module containing the shader-resource view. HMODULE can be obtained with GetModuleHandle Function.
Name of the shader resource view in hSrcModule. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
Address of a reference to the shader-resource view (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
Projects a function represented in a cube map into spherical harmonics.
\t\nOrder of the SH evaluation, generates Order^2 coefs, degree is Order-1.
Cubemap that is going to be projected into spherical harmonics. See
Output SH vector for red.
Output SH vector for green.
Output SH vector for blue.
The return value is one of the values listed in Direct3D 10 Return Codes.
Create a texture from another resource.
\t\nA reference to the device (see
A handle to the source resource. HMODULE can be obtained with GetModuleHandle Function.
A string that contains the name of the source resource. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
The address of a reference to the texture resource (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
For a list of supported image formats see
Load a texture from a texture.
\t\nPointer to the source texture. See
Pointer to texture loading parameters. See
Pointer to the destination texture. See
The return value is one of the values listed in Direct3D 10 Return Codes.
Create a shader-resource view from a file in memory.
\t\nA reference to the device (see
Pointer to the file in memory that contains the shader-resource view.
Size of the file in memory.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
Address of a reference to the newly created shader resource view. See
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
Generates mipmap chain using a particular texture filter.
\t\nThe texture object to be filtered. See
The mipmap level whose data is used to generate the rest of the mipmap chain.
Flags controlling how each miplevel is filtered (or D3DX10_DEFAULT for
The return value is one of the values listed in Direct3D 10 Return Codes.
Create a texture resource from a file residing in system memory.
\t\nA reference to the device (see
Pointer to the resource in system memory.
Size of the resource in system memory.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
Address of a reference to the created resource. See
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
For a list of supported image formats see
Retrieves information about a given image file.
\t\nFile name of image to retrieve information about. If UNICODE or _UNICODE are defined, this parameter type is LPCWSTR, otherwise, the type is LPCSTR.
Optional thread pump that can be used to load the info asynchronously. Can be
Pointer to a
A reference to the return value. May be
If the function succeeds, the return value is
This function supports both Unicode and ANSI strings.
\t\nCreates a mesh object using a declarator.
\t\nPointer to an
Array of
The number of elements in pDeclaration.
Semantic that identifies which part of the vertex declaration contains position information.
Number of vertices for the mesh. This parameter must be greater than 0.
Number of faces for the mesh. The valid range for this number is greater than 0, and one less than the maximum DWORD (typically 65534), because the last index is reserved.
Combination of one or more flags from the D3DX10_MESH, specifying options for the mesh.
Address of a reference to an
If the function succeeds, the return value is
Creates an empty skin mesh object using a declarator.
\t\nAddress of a reference to an
If the function succeeds, the return value is
Use the
Create an effect pool from a resource.
\t\nA handle to the resource module containing the effect. HMODULE can be obtained with GetModuleHandle Function.
The name of the resource in hModule. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Effect file name, which is used for error messages only. Can be
A
A reference to an include interface (see ID3D10Include Interface). This parameter can be
A string that specifies the shader profile, or shader model.
HLSL compile options (see D3D10_SHADER Constants).
Effect compile options (see Compile and Effect Flags).
A reference to the device (see
A reference to a thread pump interface (see
The address of a reference to the effect pool (see
The address of a reference to memory (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
Create an effect pool from an effect file.
\t\nThe effect filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
A
A reference to an include interface (see ID3D10Include Interface). This parameter can be
A string that specifies the shader profile, or shader model.
HLSL compile options (see D3D10_SHADER Constants).
Effect compile options (see Compile and Effect Flags).
A reference to the device (see
A reference to a thread pump interface (see
The address of a reference to the effect pool (see
The address of a reference to memory (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
This example creates an effect pool from the effect used in the BasicHLSL10 Sample.
// Create an effect pool from an effect in memory\t\n * l_pEffectPool = null ;\t\n *\tl_pBlob_Errors = null ;\t\n WCHAR str[MAX_PATH];\t\n hr = DXUTFindDXSDKMediaFileCch( str, MAX_PATH, L\"BasicHLSL10.fx\" );\t\n hr = ( str, null , null , D3D10_SHADER_ENABLE_STRICTNESS, 0, pd3dDevice, null , &l_pEffectPool, &l_pBlob_Errors );\t\n Create an effect from a file.
\t\nName of the ASCII effect file. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
A
A reference to an include interface (see ID3D10Include Interface). This parameter can be
A string that specifies the shader profile, or shader model.
HLSL compile options (see D3D10_SHADER Constants).
Effect compile options (see Compile and Effect Flags).
A reference to the device (see
Pointer to an effect pool (see
A reference to a thread pump interface (see
Address of a reference to the effect (see
The address of a reference to memory (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
Create an effect from memory.
\t\nPointer to the effect in memory.
Size of the effect in memory.
Name of the effect file in memory.
A
A reference to an include interface (see ID3D10Include Interface). This parameter can be
A string that specifies the shader profile, or shader model.
HLSL compile options (see D3D10_SHADER Constants).
Effect compile options (see D3D10_EFFECT Constants).
A reference to the device (see
Pointer to an effect pool (see
A reference to a thread pump interface (see
Address of a reference to the effect (see
The address of a reference to memory (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
Create an effect pool from an effect in memory.
\t\nA reference to the effect.
The size of the effect.
The name of the effect file.
A
A reference to an include interface (see ID3D10Include Interface). This parameter can be
A string that specifies the shader profile, or shader model.
HLSL compile options (see D3D10_SHADER Constants).
Effect compile options (see Compile and Effect Flags).
A reference to the device (see
A reference to a thread pump interface (see
The address of a reference to the effect pool (see
The address of a reference to memory (see
A reference to the return value. May be
Returns one of the following Direct3D 10 Return Codes.
Create an effect from a resource.
\t\nA handle to the resource module containing the effect. HMODULE can be obtained with GetModuleHandle Function.
Name of the resource in hModule. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Effect file name, which is used for error messages only. Can be
A
A reference to an include interface (see ID3D10Include Interface). This parameter can be
A string that specifies the shader profile, or shader model.
HLSL compile options (see D3D10_SHADER Constants).
Effect compile options (see Compile and Effect Flags).
A reference to the device (see
Pointer to an effect pool (see
A reference to a thread pump interface (see
Address of a reference to the effect (see
The address of a reference to memory (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 10 Return Codes.
A constant-buffer interface accesses constant buffers or texture buffers.
\t\nUse constant buffers to store many effect constants; grouping constants into buffers based on their frequency of update. This allows you to minimize the number of state changes as well as make the fewest API calls to change state. Both of these factors lead to better performance.
\t\nSet a constant-buffer.
\t\nA reference to a constant-buffer interface. See
Returns one of the following Direct3D 10 Return Codes.
Get a constant-buffer.
\t\nThe address of a reference to a constant-buffer interface. See
Set a texture-buffer.
\t\nA reference to a shader-resource-view interface for accessing a texture buffer.
Returns one of the following Direct3D 10 Return Codes.
Get a texture-buffer.
\t\nThe address of a reference to a shader-resource-view interface for accessing a texture buffer. See
A shader-variable interface accesses a shader variable.
\t\nGet a shader description.
\t\nA zero-based index.
A reference to a shader description (see
Get a vertex shader.
\t\nA zero-based index.
A reference to a
Get a geometry shader.
\t\nA zero-based index.
A reference to a
Get a pixel shader.
\t\nA zero-based index.
A reference to a
Get an input-signature description.
\t\nA zero-based shader index.
A zero-based shader-element index.
A reference to a parameter description (see
An effect contains one or more shaders; each shader has an input and output signature; each signature contains one or more elements (or parameters). The shader index identifies the shader and the element index identifies the element (or parameter) in the shader signature.
\t\nGet an output-signature description.
\t\nA zero-based shader index.
A zero-based element index.
A reference to a parameter description (see
An effect contains one or more shaders; each shader has an input and output signature; each signature contains one or more elements (or parameters). The shader index identifies the shader and the element index identifies the element (or parameter) in the shader signature.
\t\nAn
The lifetime of an
The
An effect contains one or more techniques; each technique contains one or more passes; each pass contains state assignments (see Organizing State in an Effect (Direct3D 10)). The syntax for creating a technique is shown in Effect Technique Syntax (Direct3D 10).
To get an effect-technique interface, call a method like
Test a technique to see if it contains valid syntax.
\t\nTRUE if the code syntax is valid; otherwise
Get a technique description.
\t\nA reference to a technique description (see
Returns one of the following Direct3D 10 Return Codes.
Get an annotation by index.
\t\nThe zero-based index of the interface reference.
A reference to an
Use an annotation to attach a piece of metadata to a technique.
\t\nGet an annotation by name.
\t\nName of the annotation.
A reference to an
Use an annotation to attach a piece of metadata to a technique.
\t\nGet a pass by index.
\t\nA zero-based index.
A reference to a
A technique contains one or more passes; get a pass using a name or an index.
\t\nGet a pass by name.
\t\nThe name of the pass.
A reference to an
A technique contains one or more passes; get a pass using a name or an index.
\t\nCompute a state-block mask to allow/prevent state changes.
\t\nA reference to a state-block mask (see
Returns one of the following Direct3D 10 Return Codes.
Test a technique to see if it contains valid syntax.
\t\nGet a technique description.
\t\nGet an member type by name.
\t\nTests that the effect type is valid.
\t\nTRUE if it is valid; otherwise
Get an effect-type description.
\t\nA reference to an effect-type description. See
Returns one of the following Direct3D 10 Return Codes.
The effect-variable description contains data about the name, annotations, semantic, flags and buffer offset of the effect type.
\t\nGet a member type by index.
\t\nA zero-based index.
A reference to an
Get an member type by name.
\t\nA member's name.
A reference to an
Get a member type by semantic.
\t\nA semantic.
A reference to an
Get the name of a member.
\t\nA zero-based index.
The name of the member.
Get the semantic attached to a member.
\t\nA zero-based index.
A string that contains the semantic.
Tests that the effect type is valid.
\t\nGet an effect-type description.
\t\nThe effect-variable description contains data about the name, annotations, semantic, flags and buffer offset of the effect type.
\t\nA geometry-shader interface manages an executable program (a geometry shader) that controls the geometry-shader stage.
\t\nThe geometry-shader interface has no methods; use HLSL to implement your shader functionality. All shaders in Direct3D 10 are implemented from a common set of features referred to as the common shader core.
To create a geometry shader interface, call either
This interface is defined in D3D10.h.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
Set the constant buffers used by the geometry shader pipeline stage.
\t\nThe 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.
\t\nSet the constant buffers used by the geometry shader pipeline stage.
\t\nThe 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.
\t\nSet a geometry shader to the device.
\t\nPointer to a geometry shader (see
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.
\t\nBind an array of shader resources to the geometry shader stage.
\t\nIf you bind a subresource as an input and an output, this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
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.
\t\nBind an array of shader resources to the geometry shader stage.
\t\nIf you bind a subresource as an input and an output, this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
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.
\t\nSet an array of sampler states to the geometry shader pipeline stage.
\t\nAny sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; 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.
\t\nSet an array of sampler states to the geometry shader pipeline stage.
\t\nAny sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; 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.
\t\nGet the constant buffers used by the geometry shader pipeline stage.
\t\nAny 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.
\t\nGet the geometry shader currently set on the device.
\t\nAddress of a reference to a geometry shader (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.
\t\nGet the geometry shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from.
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources.
Array of shader resource view interfaces to be returned 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.
\t\nGet an array of sampler states from the geometry shader pipeline stage.
\t\nAny 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.
\t\nAn information-queue interface stores, retrieves, and filters debug messages. The queue consists of a message queue, an optional storage filter stack, and a optional retrieval filter stack.
\t\nThis interface is obtained by turning on the debug layer and querying it from the
hr = ( null , g_driverType, null , , , &sd, &g_pSwapChain, &g_pd3dDevice );\t\n ...\t\n * infoQueue;\t\n g_pd3dDevice->QueryInterface(__uuidof(), (void **)&infoQueue); \t\n Set the maximum number of messages that can be added to the message queue.
\t\nMaximum number of messages that can be added to the message queue. -1 means no limit.
This method returns one of the following Direct3D 10 Return Codes.
When the number of messages in the message queue has reached the maximum limit, new messages coming in will push old messages out.
\t\nClear all messages from the message queue.
\t\nGet a message from the message queue.
\t\nIndex into message queue after an optional retrieval filter has been applied. This can be between 0 and the number of messages in the message queue that pass through the retrieval filter (which can be obtained with
Returned message (see
Size of pMessage in bytes, including the size of the message string that the pMessage points to.
This method returns one of the following Direct3D 10 Return Codes.
This method does not remove any messages from the message queue.
This method gets messages from the message queue after an optional retrieval filter has been applied.
Applications should call this method twice to retrieve a message - first to obtain the size of the message and second to get the message. Here is a typical example:
// Get the size of the message\t\n messageLength = 0;\t\n hr = pInfoQueue->GetMessage(0, null , &messageLength); // Allocate space and get the message\t\n * pMessage = (*)malloc(messageLength);\t\n hr = pInfoQueue->GetMessage(0, pMessage, &messageLength);\t\n For an overview see Information Queue Overview.
\t\nGet the number of messages that were allowed to pass through a storage filter.
\t\nNumber of messages allowed by a storage filter.
Get the number of messages that were denied passage through a storage filter.
\t\nNumber of messages denied by a storage filter.
Get the number of messages currently stored in the message queue.
\t\nNumber of messages currently stored in the message queue.
Get the number of messages that are able to pass through a retrieval filter.
\t\nNumber of messages allowed by a retrieval filter.
Get the number of messages that were discarded due to the message count limit.
\t\nNumber of messages discarded.
Get and set the message count limit with
Get the maximum number of messages that can be added to the message queue.
\t\nMaximum number of messages that can be added to the queue. -1 means no limit.
When the number of messages in the message queue has reached the maximum limit, new messages coming in will push old messages out.
\t\nAdd storage filters to the top of the storage-filter stack.
\t\nArray of storage filters (see
This method returns one of the following Direct3D 10 Return Codes.
A storage filter defines a grouping of debug messages that should be allowed into the info queue.
\t\nGet the storage filter at the top of the storage-filter stack.
\t\nStorage filter at the top of the storage-filter stack.
Size of the storage filter in bytes. If pFilter is
This method returns one of the following Direct3D 10 Return Codes.
Remove a storage filter from the top of the storage-filter stack.
\t\nPush an empty storage filter onto the storage-filter stack.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
An empty storage filter allows all messages to pass through.
\t\nPush a copy of storage filter currently on the top of the storage-filter stack onto the storage-filter stack.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
Push a storage filter onto the storage-filter stack.
\t\nPointer to a storage filter (see
This method returns one of the following Direct3D 10 Return Codes.
Pop a storage filter from the top of the storage-filter stack.
\t\nGet the size of the storage-filter stack in bytes.
\t\nSize of the storage-filter stack in bytes.
Add storage filters to the top of the retrieval-filter stack.
\t\nArray of retrieval filters (see
This method returns one of the following Direct3D 10 Return Codes.
A retrieval filter is used to define a subgroup of the messages that are already in the info queue. Retrieval filters affect the messages that will be returned by
The number of messages already in the info queue that will be allowed through the retrieval filter can be determined by calling
Get the retrieval filter at the top of the retrieval-filter stack.
\t\nRetrieval filter at the top of the retrieval-filter stack.
Size of the retrieval filter in bytes. If pFilter is
This method returns one of the following Direct3D 10 Return Codes.
Remove a retrieval filter from the top of the retrieval-filter stack.
\t\nPush an empty retrieval filter onto the retrieval-filter stack.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
An empty retrieval filter allows all messages to pass through.
\t\nPush a copy of retrieval filter currently on the top of the retrieval-filter stack onto the retrieval-filter stack.
\t\nThis method returns one of the following Direct3D 10 Return Codes.
Push a retrieval filter onto the retrieval-filter stack.
\t\nPointer to a retrieval filter (see
This method returns one of the following Direct3D 10 Return Codes.
Pop a retrieval filter from the top of the retrieval-filter stack.
\t\nGet the size of the retrieval-filter stack in bytes.
\t\nSize of the retrieval-filter stack in bytes.
Add a Direct3D 10 debug message to the message queue and send that message to debug output.
\t\nCategory of a message (see
Severity of a message (see
Unique identifier of a message (see
User-defined message.
This method returns one of the following Direct3D 10 Return Codes.
This method is used by the runtime's internal mechanisms to add Direct3D 10 debug messages to the message queue and send them to debug output. For applications to add their own custom messages to the message queue and send them to debug output, call
Add a user-defined message to the message queue and send that message to debug output.
\t\nSeverity of a message (see
Message string.
This method returns one of the following Direct3D 10 Return Codes.
Set a message category to break on when a message with that category passes through the storage filter.
\t\nMessage category to break on (see
Turns this breaking condition on or off (true for on, false for off).
This method returns one of the following Direct3D 10 Return Codes.
Set a message severity level to break on when a message with that severity level passes through the storage filter.
\t\nMessage severity level to break on (see
Turns this breaking condition on or off (true for on, false for off).
This method returns one of the following Direct3D 10 Return Codes.
Set a message identifier to break on when a message with that identifier passes through the storage filter.
\t\nMessage identifier to break on (see
Turns this breaking condition on or off (true for on, false for off).
This method returns one of the following Direct3D 10 Return Codes.
Get a message category to break on when a message with that category passes through the storage filter.
\t\nMessage category to break on (see
Whether this breaking condition is turned on or off (true for on, false for off).
Get a message severity level to break on when a message with that severity level passes through the storage filter.
\t\nMessage severity level to break on (see
Whether this breaking condition is turned on or off (true for on, false for off).
Get a message identifier to break on when a message with that identifier passes through the storage filter.
\t\nMessage identifier to break on (see
Whether this breaking condition is turned on or off (true for on, false for off).
Set a boolean that turns the debug output on or off.
\t\nDisable/Enable the debug output (TRUE to disable or mute the output,
This will stop messages that pass the storage filter from being printed out in the debug output, however those messages will still be added to the message queue.
\t\nGet a boolean that turns the debug output on or off.
\t\nWhether the debug output is on or off (true for on, false for off).
Get or sets the maximum number of messages that can be added to the message queue.
\t\nWhen the number of messages in the message queue has reached the maximum limit, new messages coming in will push old messages out.
\t\nGet the number of messages that were allowed to pass through a storage filter.
\t\nGet the number of messages that were denied passage through a storage filter.
\t\nGet the number of messages currently stored in the message queue.
\t\nGet the number of messages that are able to pass through a retrieval filter.
\t\nGet the number of messages that were discarded due to the message count limit.
\t\nGet and set the message count limit with
Get the size of the storage-filter stack in bytes.
\t\nGet the size of the retrieval-filter stack in bytes.
\t\nGet or sets a boolean that turns the debug output on or off.
\t\nAn input-layout interface accesses the input data for the input-assembler stage.
\t\nThis interface is created by calling
Applications use the methods of the
To obtain the
Retrieves the number of faces in the mesh.
\t\nReturns the number of faces in the mesh.
Get the number of vertices in the mesh. A mesh may contain multiple vertex buffers (i.e. one vertex buffer may contain all position data, another may contains all texture coordinate data, etc.), however each vertex buffer will contain the same number of elements.
\t\nThe number of vertices in the mesh.
Get the number of vertex buffers in the mesh.
\t\nThe number of vertex buffers in the mesh.
Access the mesh's creation flags.
\t\nThe creation flags passed into the options parameter of
Access the vertex description passed into
The return value is one of the values listed in Direct3D 10 Return Codes.
Set vertex data into one of the mesh's vertex buffers.
\t\nThe vertex buffer to be filled with pData.
The vertex data to set.
The return value is one of the values listed in Direct3D 10 Return Codes.
Retrieves the vertex buffer associated with the mesh.
\t\nThe vertex buffer to get. This is an index value.
The vertex buffer. See
Set the mesh's index data.
\t\nThe index data.
The number of indices in pData.
The return value is one of the values listed in Direct3D 10 Return Codes.
Retrieves the data in an index buffer.
\t\nAddress of a reference to a
Set the mesh's attribute data.
\t\nThe attribute data to set.
The return value is one of the values listed in Direct3D 10 Return Codes.
Access the mesh's attribute buffer.
\t\nThe attribute buffer. See
The return value is one of the values listed in Direct3D 10 Return Codes.
Sets the attribute table for a mesh and the number of entries stored in the table.
\t\nPointer to an array of
Number of attributes in the mesh attribute table.
The return value is one of the values listed in Direct3D 10 Return Codes.
If an application keeps track of the information in an attribute table, and rearranges the table as a result of changes to attributes or faces, this method allows the application to update the attribute tables instead of calling
Retrieves either an attribute table for a mesh, or the number of entries stored in an attribute table for a mesh.
\t\nPointer to an array of
Pointer to either the number of entries stored in pAttribTable or a value to be filled in with the number of entries stored in the attribute table for the mesh.
The return value is one of the values listed in Direct3D 10 Return Codes.
An attribute table is used to identify areas of the mesh that need to be drawn with different textures, render states, materials, and so on. In addition, the application can use the attribute table to hide portions of a mesh by not drawing a given attribute identifier when drawing the frame.
\t\nGenerate a list of mesh edges, as well as a list of faces that share each edge.
\t\nSpecifies that vertices that differ in position by less than epsilon should be treated as coincident.
The return value is one of the values listed in Direct3D 10 Return Codes.
After an application generates adjacency information for a mesh, the mesh data can be optimized for better drawing performance.
The order of the entries in the adjacency buffer is determined by the order of the vertex indices in the index buffer. The adjacent triangle 0 always corresponds to the edge between the indices of the corners 0 and 1. The adjacent triangle 1 always corresponds to the edge between the indices of the corners 1 and 2 while the adjacent triangle 2 corresponds to the edge between the indices of the corners 2 and 0.
\t\nAdds adjacency data to the mesh's index buffer. When the mesh is to be sent to a geometry shader that takes adjacency data, it is neccessary for the mesh's index buffer to contain adjacency data.
\t\nThe return value is one of the values listed in Direct3D 10 Return Codes.
Set the mesh's adjacency data.
\t\nThe adjacency data to set.
The return value is one of the values listed in Direct3D 10 Return Codes.
Access the mesh's adjacency buffer.
\t\nThe adjacency buffer. See
Set the point rep data for the mesh.
\t\nThe point rep data to set.
The return value is one of the values listed in Direct3D 10 Return Codes.
Get the mesh's point rep buffer.
\t\nPointer to a mesh buffer containing the mesh's point rep data. See
The return value is one of the values listed in Direct3D 10 Return Codes.
Removes mesh data from the device that has been committed to the device (with
The return value is one of the values listed in Direct3D 10 Return Codes.
Creates a new mesh and fills it with the data of a previously loaded mesh.
\t\nCreation flags to be applied to the new mesh. See D3DX10_MESH.
The semantic name for the position data.
Array of
The number of elements in the pDesc array.
The new mesh.
The return value is one of the values listed in Direct3D 10 Return Codes.
Generates a new mesh with reordered faces and vertices to optimize drawing performance.
\t\nSpecifies the type of optimization to perform. This parameter can be set to a combination of one or more flags from D3DXMESHOPT and D3DXMESH (except
An array of UINTs, one per face, that identifies the original mesh face that corresponds to each face in the optimized mesh. If the value supplied for this argument is
Address of a reference to an
The return value is one of the values listed in Direct3D 10 Return Codes.
This method generates a new mesh. Before running Optimize, an application must generate an adjacency buffer by calling
This method is very similar to the
Generate an attribute buffer from the data in the mesh's attribute table. An attribute buffer is another format for storing the data in the attribute table. Both the attribute buffer and the attribute table are internal data structures in the mesh.
\t\nThe return value is one of the values listed in Direct3D 10 Return Codes.
Applies to: desktop apps only
Determines if a ray intersects with this mesh.
\t\nPointer to a
Pointer to a
The number of times the ray intersected with the mesh.
Pointer to an index value of the face closest to the ray origin, if pHit is TRUE.
Pointer to a barycentric hit coordinate, U.
Pointer to a barycentric hit coordinate, V.
Pointer to a ray intersection parameter distance.
Pointer to an
The return value is one of the values listed in Direct3D 10 Return Codes.
This API provides a way to understand points in and around a triangle, independent of where the triangle is actually located. This function returns the resulting point by using the following equation: V1 + U(V2 - V1) + V(V3 - V1).
Any point in the plane V1V2V3 can be represented by the barycentric coordinate (U,V). The parameter U controls how much V2 gets weighted into the result, and the parameter V controls how much V3 gets weighted into the result. Lastly, the value of [1 - (U + V)] controls how much V1 gets weighted into the result.
Barycentric coordinates are a form of general coordinates. In this context, using barycentric coordinates represents a change in coordinate systems. What holds true for Cartesian coordinates holds true for barycentric coordinates.
Barycentric coordinates define a point inside a triangle in terms of the triangle's vertices. For a more in-depth description of barycentric coordinates, see Mathworld's Barycentric Coordinates Description.
\t\nApplies to: desktop apps only
Determines if a ray intersects with a subset of this mesh.
\t\nAttribute ID identifying the subset of the mesh.
Pointer to a
Pointer to a
The number of times the ray intersected with the mesh.
Pointer to an index value of the face closest to the ray origin, if pHit is TRUE.
Pointer to a barycentric hit coordinate, U.
Pointer to a barycentric hit coordinate, V.
Pointer to a ray intersection parameter distance.
Pointer to an
The return value is one of the values listed in Direct3D 10 Return Codes.
This API provides a way to understand points in and around a triangle, independent of where the triangle is actually located. This function returns the resulting point by using the following equation: V1 + U(V2 - V1) + V(V3 - V1).
Any point in the plane V1V2V3 can be represented by the barycentric coordinate (U,V). The parameter U controls how much V2 gets weighted into the result, and the parameter V controls how much V3 gets weighted into the result. Lastly, the value of [1 - (U + V)] controls how much V1 gets weighted into the result.
Barycentric coordinates are a form of general coordinates. In this context, using barycentric coordinates represents a change in coordinate systems. What holds true for Cartesian coordinates holds true for barycentric coordinates.
Barycentric coordinates define a point inside a triangle in terms of the triangle's vertices. For a more in-depth description of barycentric coordinates, see Mathworld's Barycentric Coordinates Description.
\t\nCommit any changes made to a mesh to the device so that the changes can be rendered. This should be called after a mesh's data is altered and before it is rendered. A mesh cannot be rendered unless it is committed to the device. See remarks.
\t\nThe return value is one of the values listed in Direct3D 10 Return Codes.
When a mesh is loaded, it's data is loaded into staging resources, meaning the data can be altered but not rendered. When CommitToDevice is called, the data from the staging resources are copied into device resources so that they can be rendered. Although the data is committed to the device, the staging resources remain and can be modified. If any modifications are made to the staging resources, the staging resources must be committed to the device again in order for those changes to be rendered on screen.
\t\nDraws a subset of a mesh.
\t\nSpecifies which subset of the mesh to draw. This value is used to differentiate faces in a mesh as belonging to one or more attribute groups.
The return value is one of the values listed in Direct3D 10 Return Codes.
An attribute table is used to identify areas of the mesh that need to be drawn with different textures, render states, materials, and so on. In addition, the application can use the attribute table to hide portions of a mesh by not drawing a given attribute identifier (AttribId) when drawing the frame.
\t\nDraw several instances of the same subset of a mesh.
\t\nSpecifies which subset of the mesh to draw. This value is used to differentiate faces in a mesh as belonging to one or more attribute groups. See remarks.
Number of instances to render.
Which instance to start fetching from in each buffer marked as instance data.
The return value is one of the values listed in Direct3D 10 Return Codes.
A mesh contains an attribute table. The attribute table can divide a mesh into subsets, where each subset is identified with an attribute ID. For example, a mesh with 200 faces, divided into three subsets, might have an attribute table that looks like this:
| AttribID 0 | Faces 0 ~ 50 |
| AttribID 1 | Faces 51 ~ 125 |
| AttribID 2 | Faces 126 ~ 200 |
?
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.
Drawing instances with DrawSubsetInstanced is very similar to the process used with
The following code illustrates extracting the vertex and index buffers from the mesh object.
* vertexBuffer; pDeviceObj->pMesh->GetDeviceVertexBuffer(0, &vertexBuffer); * indexBuffer; pDeviceObj->pMesh->GetDeviceIndexBuffer(&indexBuffer); Access the mesh's vertex buffer after it has been committed to the device with
Access the mesh's index buffer after it has been committed to the device with
If the mesh's index buffer has not already been committed to the device, this API will automatically commit the index buffer before it returns a reference to the buffer.
\t\nRetrieves the number of faces in the mesh.
\t\nGet the number of vertices in the mesh. A mesh may contain multiple vertex buffers (i.e. one vertex buffer may contain all position data, another may contains all texture coordinate data, etc.), however each vertex buffer will contain the same number of elements.
\t\nGet the number of vertex buffers in the mesh.
\t\nA mesh buffer is a buffer that contains data about a mesh. It can contain one of five different types of data: vertex data, index data, adjacency data, attribute data, or point rep data. The structure is used to access these five pieces of data through the following five APIs:
Get a reference to the mesh buffer memory to modify its contents.
\t\nPointer to the buffer data.
Size of the buffer in bytes.
The return value is one of the values listed in Direct3D 10 Return Codes.
| Differences between Direct3D 9 and Direct3D 10: Map() in Direct3D 10 is analogous to resource Map() in Direct3D 9. |
?
\t\nUnmap a buffer.
\t\nThe return value is one of the values listed in Direct3D 10 Return Codes.
| Differences between Direct3D 9 and Direct3D 10: Unmap() in Direct3D 10 is analogous to resource Unlock() in Direct3D 9. |
?
\t\nGet the size of the mesh buffer, in bytes.
\t\nThe size of the mesh buffer, in bytes.
Get the size of the mesh buffer, in bytes.
\t\nA pixel-shader interface manages an executable program (a pixel shader) that controls the pixel-shader stage.
\t\nThe pixel-shader interface has no methods; use HLSL to implement your shader functionality. All shaders in Direct3D 10 are implemented from a common set of features referred to as the common shader core.
To create a pixel shader interface, call
This interface is defined in D3D10.h.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
Bind an array of shader resources to the pixel shader stage.
\t\nIf you bind a subresource as an input and an output, this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
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.
\t\nBind an array of shader resources to the pixel shader stage.
\t\nIf you bind a subresource as an input and an output, this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
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.
\t\nSets a pixel shader to the device.
\t\nPointer to a pixel shader (see
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.
\t\nSet an array of sampler states to the pixel shader pipeline stage.
\t\nAny sampler may be set to
| State | Default Value |
|---|---|
| Filter | |
| AddressU | |
| AddressV | |
| AddressW | |
| MipLODBias | 0 |
| MaxAnisotropy | 1 |
| ComparisonFunc | |
| BorderColor[0] | 1.0f |
| BorderColor[1] | 1.0f |
| BorderColor[2] | 1.0f |
| BorderColor[3] | 1.0f |
| MinLOD | -FLT_MAX |
| MaxLOD | FLT_MAX |
?
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.
\t\nSet an array of sampler states to the pixel shader pipeline stage.
\t\nAny sampler may be set to
| State | Default Value |
|---|---|
| Filter | |
| AddressU | |
| AddressV | |
| AddressW | |
| MipLODBias | 0 |
| MaxAnisotropy | 1 |
| ComparisonFunc | |
| BorderColor[0] | 1.0f |
| BorderColor[1] | 1.0f |
| BorderColor[2] | 1.0f |
| BorderColor[3] | 1.0f |
| MinLOD | -FLT_MAX |
| MaxLOD | FLT_MAX |
?
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.
\t\nSet the constant buffers used by the pixel shader pipeline stage.
\t\nThe 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.
\t\nSet the constant buffers used by the pixel shader pipeline stage.
\t\nThe 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.
\t\nGet the pixel shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from.
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources.
Array of shader resource view interfaces to be returned 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.
\t\nGet the pixel shader currently set on the device.
\t\nAddress of a reference to a pixel shader (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.
\t\nGet an array of sampler states from the pixel shader pipeline stage.
\t\nAny 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.
\t\nGet the constant buffers used by the pixel shader pipeline stage.
\t\nAny 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.
\t\nA predicate interface determines whether geometry should be processed depending on the results of a previous draw call.
\t\nA predicate can be created with
There are two types of predicates in Direct3D 10: stream-output-overflow predicates and occlusion predicates. Stream-output-overflow predicates will cause any geometry residing in stream-output buffers that were overflowed to not be processed. Occlusion predicates will cause any geometry that did not have a single sample pass the depth/stencil tests to not be processed.
For an example of occlusion-predicated rendering, see Draw Predicated Sample.
\t\nA query interface queries information from the GPU.
\t\nA query can be created with
This interface inherits the functionality of an
Query data is typically gathered by issuing an
There are, however, some queries that do not require calls to Begin. For a list of possible queries see
A query is typically executed as shown in the following code:
queryDesc; ... // Fill out queryDesc structure * pQuery;\t\n pDevice->CreateQuery(&queryDesc, &pQuery); pQuery->Begin(); ... // Issue graphis commands, do whatever pQuery->End(); UINT64 queryData; // This data type is different depending on the query type while( != pQuery->GetData(&queryData, sizeof(UINT64), 0) )\t\n {\t\n }\t\n When using a query that does not require a call to Begin, it still requires a call to End. The call to End causes the data returned by GetData to be accurate up until the last call to End.
\t\nGet a query description.
\t\nPointer to a query description (see
Get a query description.
\t\nA rasterizer-state interface accesses rasterizer state for the rasterizer stage.
\t\nA rasterizer-state object is created with
Get the properties of a rasterizer-state object.
\t\nPointer to a rasterizer-state description (see
Get the properties of a rasterizer-state object.
\t\nA render-target-view interface identifies the render-target subresources that can be accessed during rendering.
\t\nTo create a render-target view, call
A rendertarget is a resource that can be written by the output-merger stage at the end of a render pass. Each render-target should also have a corresponding depth-stencil view.
\t\nGet the properties of a render target view.
\t\nPointer to the description of a render target view (see
Get the properties of a render target view.
\t\nA sampler-state interface accesses sampler state for a texture.
\t\nCreate a sampler-state object by calling
To initialize sampler state, bind the sampler-state object to the pipeline by calling
Get the sampler state.
\t\nA reference to the sampler state (see
Get the sampler state.
\t\nA shader-resource-view interface specifies the subresources a shader can access during rendering. Examples of shader resources include a constant buffer, a texture buffer, a texture or a sampler.
\t\nTo create a shader-resource view, call
A shader-resource view is required when binding a resource to a shader stage; the binding occurs by calling
Get the shader resource view's description.
\t\nA reference to a
Get the shader resource view's description.
\t\nA shader-resource-view interface specifies the subresources a shader can access during rendering. Examples of shader resources include a constant buffer, a texture buffer, a texture or a sampler.
\t\nTo create a shader-resource view, call
A shader-resource view is required when binding a resource to a shader stage; the binding occurs by calling
This method requires Windows Vista Service Pack 1.
\t\nGet the shader resource view's description.
\t\nA reference to a
This method requires Windows Vista Service Pack 1.
\t\nGet the shader resource view's description.
\t\nThis method requires Windows Vista Service Pack 1.
\t\nCreate a
The LPD3DX10SKININFO type is defined as a reference to the
typedef struct *LPD3DX10SKININFO;\t\n Get the number of vertices in
The number of vertices in
Get the number of bones in
The number of bones in
Get the number of vertices a bone can maximally influence.
\t\nThe number of vertices a bone can maximally influence.
Allocate space for additional vertices.
\t\nThe number of vertices to add.
If this method succeeds, the return value is
Change which vertices are influenced by which bones.
\t\nThe new number of vertices.
A reference to an array of vertex indices, which describe the remapping. For example, say SkinInfo contains some vertices such that bone0 is mapped to v0, bone1 to v1, and bone2 to v2, and array with 2,1,0 is specified for pBoneRemap. This will cause bone0 to be mapped to v2, bone1 to v1, and bone2 to v0.
If the method succeeds, the return value is
Allocate space for more bones.
\t\nThe number of bones to add.
If this method succeeds, the return value is
Remove a bone.
\t\nAn index that specifies which bone to remove. Must be between 0 and the value returned by
If the method succeeds, the return value is
Change which bones influence which vertices.
\t\nThe new number of bones.
A reference to an array of bone indices, which describe the remapping. For example, say SkinInfo contains some bones such that bone0 is mapped to v0, bone1 to v1, and bone2 to v2, and array with 2,1,0 is specified for pBoneRemap. This will cause bone0 to be mapped to v2, bone1 to v1, and bone2 to v0.
If the method succeeds, the return value is
Enable an existing bone to influence a group of vertices and define how much influence the bone has on each vertex.
\t\nAn index that specifies an existing bone. Must be between 0 and the value returned by
Number of vertices to add to the bone's influence.
Pointer to an array of vertex indices. Each member of this array has a corresponding member in pWeights, such that pIndices[i] corresponds to pWeights[i]. The corresponding value in pWeights[i] determines how much influence BoneIndex will have on the vertex indexed by pIndices[i]. The size of the pIndices array must be equal to or greater than InfluenceCount.
Pointer to an array of bone weights. Each member of this array has a corresponding member in pIndices, such that pWeights[i] corresponds to pIndices[i]. Each value in pWeights is between 0 and 1 and defines the amount of influence the bone has over each vertex. The size of pWeights must be equal to or greater than InfluenceCount.
If the method succeeds, the return value is
Clear a bone's list of vertices that it influences.
\t\nAn index that specifies an existing bone. Must be between 0 and the value returned by
If the method succeeds, the return value is
Get the number of vertices that a given bone influences.
\t\nAn index that specifies an existing bone. Must be between 0 and the value returned by
If the method succeeds, the return value is
Get a list of vertices that a given bone influences and a list of the amount of influence that bone has on each vertex.
\t\nAn index that specifies an existing bone. Must be between 0 and the value returned by
An offset from the top of the bone's list of influenced vertices. This must be between 0 and the value returned by
The number of indices and weights to retrieve. Must be between 0 and the value returned by
A list of indices into the vertex buffer, each one representing a vertex influenced by the bone. These values correspond to the values in pDestWeights, such that pDestIndices[i] corresponds to pDestWeights[i].
A list of the amount of influence the bone has on each vertex. These values correspond to the values in pDestIndices, such that pDestWeights[i] corresponds to pDestIndices[i].f
If the method succeeds, the return value is
Find the index that indicates where a given vertex is in a given bone's list of influenced vertices.
\t\nAn index that specifies an existing bone. Must be between 0 and the value returned by
The index of the vertex in the vertex buffer.
The index of the vertex in the bone's list of influenced vertices.
If the method succeeds, the return value is
Set the amount of influence a given bone has over a given vertex.
\t\nAn index that specifies an existing bone. Must be between 0 and the value returned by
An index into the bone's list of vertices that it influences.
The amount of influence, between 0 and 1, that the bone has over the vertex.
If the method succeeds, the return value is
Get the amount of influence a given bone has over a given vertex.
\t\nAn index that specifies an existing bone. Must be between 0 and the value returned by
An index into the bone's list of vertices that it influences.
The amount of influence, between 0 and 1, that the bone has over the vertex.
If the method succeeds, the return value is
Use
Limit the number of bones that can influence a vertex and/or limit the amount of influence a bone can have on a vertex.
\t\nThe maximum number of bones that can influence any given vertex. This value is ignored if it is greater than the value returned by
A flag describing how to scale the remaining weights on a given vertex after some have been chopped off by MinWeight. If D3DX10_SKININFO_NO_SCALING is specified, the weights will not be scaled at all. If D3DX10_SKININFO_SCALE_TO_1 is specified, the weights greater than MinWeight will be scaled up so that they add up to 1.0. If D3DX10_SKININFO_SCALE_TO_TOTAL is specified, the weights greater than MinWeight will be scaled up so that they add up to the original total.
The minimum percentage of influence, or weight, that any bone can have on any vertex. This value must be between 0 and 1.
If the method succeeds, the return value is
Do software skinning on an array of vertices.
\t\nA 0-based index into pSrcVertices.
Number of vertices to transform.
Pointer to an array of vertices to transform.
The size, in bytes, of a vertex in pSrcVertices.
Pointer to an array of vertices, which will be filled with the transformed vertices.
The size, in bytes, of a vertex in pDestVertices.
An array of matrices that will be used to transform the points mapped to each bone, such that the vertices mapped to bone[i] will be transformed by pBoneMatrices[i]. This array will be used to transform the matrices only if the IsNormal value in pChannelDescs is set to
If this value is
Pointer to a
The number of
If the method succeeds, the return value is
Here is an example of how to use software skinning:
//vertex definition\t\n struct MyVertex\t\n { Position; Weight; TexCoord;\t\n }; //create vertex data\t\n const UINT numVertices = 16;\t\n MyVertex vertices[numVertices] = {...};\t\n MyVertex destVertices[numVertices]; //create bone matrices\t\n boneMatrices[2];\t\n D3DXMatrixIdentity(&boneMatrices[0]);\t\n D3DXMatrixRotationX(&boneMatrices[1], 3.14159f / 180.0f); //create bone indices and weights\t\n UINT boneIndices[numVertices] = {...};\t\n float boneWeights[2][numVertices] = {...}; //create skin info, populate it with bones and vertices, and then map them to each other\t\n *pSkinInfo = null ;\t\n (&pSkinInfo);\t\n pSkinInfo->AddBones(2);\t\n pSkinInfo->AddVertices(numVertices);\t\n pSkinInfo->AddBoneInfluences(0, numVertices, boneIndices, boneWeights[0]);\t\n pSkinInfo->AddBoneInfluences(1, numVertices, boneIndices, boneWeights[1]); //create channel desc\t\n channelDesc;\t\n channelDesc.SrcOffset = 0;\t\n channelDesc.DestOffset = 0;\t\n channelDesc.IsNormal = ; //do the skinning\t\n pSkinInfo->DoSoftwareSkinning(0, numVertices, vertices, sizeof(MyVertex), destVertices, sizeof(MyVertex), boneMatrices, null , &channelDesc, 1);\t\n Get the number of vertices in
Get the number of bones in
Get the number of vertices a bone can maximally influence.
\t\nThe
The
Prepare a device for drawing sprites.
\t\nFlags that control how the sprites will be drawn. See
If the method succeeds, the return value is
Every call to Begin must be matched with a call to
Add an array of sprites to the batch of sprites to be rendered. This must be called in between calls to
If the method succeeds, the return value is
Force all batched sprites to be submitted to the device. Device states remain as they were after the last call to
If the method succeeds, the return value is
Draw an array of sprites. This will immediately send the sprites to the device for rendering, which is different from
If the method succeeds, the return value is
Call this after
If the method succeeds, the return value is
Get the view transform that applies to all sprites.
\t\nPointer to a D3DX10MATRIX that will be set to the transform of the sprite from the original world space.
If the method succeeds, the return value is
Set the view transform that applies to all sprites.
\t\nPointer to a
If the method succeeds, the return value is
Get the sprite projection matrix that is applied to all sprites.
\t\nPointer to a D3DX10MATRIX that will be set to the sprite's projection matrix.
The return value is one of the values listed in Direct3D 10 Return Codes.
Set the projection matrix for all sprites.
\t\nThe projection matrix to be used on all sprites.
The return value is one of the values listed in Direct3D 10 Return Codes.
Retrieve the device associated with the sprite object.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Calling this method will increase the internal reference count on the
Get or sets the view transform that applies to all sprites.
\t\nGet or sets the sprite projection matrix that is applied to all sprites.
\t\nRetrieve the device associated with the sprite object.
\t\nCalling this method will increase the internal reference count on the
A state-block interface encapsulates render states.
\t\nTo create a state-block interface, call
This interface can be used to save and restore pipeline state. It can also be used to capture the current state.
\t\nCapture the current value of states that are included in a stateblock.
\t\nReturns one of the following Direct3D 10 Return Codes.
Capture captures current values for states within an existing state block. It does not capture the entire state of the device. Creating an empty stateblock and calling Capture does nothing if no states have been set.
\t\nApply the state block to the current device state.
\t\nReturns one of the following Direct3D 10 Return Codes.
Release all references to device objects.
\t\nReturns one of the following Direct3D 10 Return Codes.
Each time you return a reference to an interface (by calling
Get the device.
\t\nPointer to the
Returns one of the following Direct3D 10 Return Codes.
Get the device.
\t\nGet a boolean value that indicates the type of device being used.
\t\nA hardware device is commonly referred to as a HAL device, which stands for a hardware accelerated device. This means that the pipeline is rendering all of the pipeline commands in hardware, using the GPU. Operating the pipeline with a HAL device gives the best performance generally, but it can be more difficult to debug since resources exist on the GPU instead of the CPU.
A software device implements rendering in software using the CPU with no hardware acceleration. A software device is commonly referred to as a reference device or REF device. Because a REF device implements rendering on the CPU, it is generally slower, but is easier to debug since it allows access to resources.
\t\nSwitch between a hardware and a software device.
\t\nA boolean value. Set this to TRUE to change to a software device, set this to
The previous value of UseRef.
This API will fail if the device is not switchable; you must have created a device that is switchable by specifying the
Switching from a software device to a hardware device clears all cached objects from system memory. Switching from a hardware device to a software device causes resources to be downloaded to system memory.
\t\nGet a boolean value that indicates the type of device being used.
\t\nTRUE if the device is a software device,
A hardware device is commonly referred to as a HAL device, which stands for a hardware accelerated device. This means that the pipeline is rendering all of the pipeline commands in hardware, using the GPU. Operating the pipeline with a HAL device gives the best performance generally, but it can be more difficult to debug since resources exist on the GPU instead of the CPU.
A software device implements rendering in software using the CPU with no hardware acceleration. A software device is commonly referred to as a reference device or REF device. Because a REF device implements rendering on the CPU, it is generally slower, but is easier to debug since it allows access to resources.
\t\nGet a boolean value that indicates the type of device being used.
\t\nA hardware device is commonly referred to as a HAL device, which stands for a hardware accelerated device. This means that the pipeline is rendering all of the pipeline commands in hardware, using the GPU. Operating the pipeline with a HAL device gives the best performance generally, but it can be more difficult to debug since resources exist on the GPU instead of the CPU.
A software device implements rendering in software using the CPU with no hardware acceleration. A software device is commonly referred to as a reference device or REF device. Because a REF device implements rendering on the CPU, it is generally slower, but is easier to debug since it allows access to resources.
\t\nA 1D texture interface accesses texel data, which is structured memory.
\t\nTo create an empty 1D texture, call
Textures cannot be bound directly to the pipeline; instead, a view must be created and bound. Using a view, texture data can be interpreted at run time within certain restrictions. To use the texture as a render target or depth-stencil resource, call
Get a reference to the data contained in a subresource, and deny the GPU access to that subresource.
\t\nIndex number of the subresource. See D3D10CalcSubresource for more details.
Specifies the CPU's read and write permissions for a resource. For possible values, see
Flag that specifies what the CPU should do when the GPU is busy. This flag is optional.
Pointer to the texture resource data.
If this function succeeds, it returns
Mapping a texture enables the CPU to directly access the underlying data in the subresource of a texture. For the method to succeed, the texture being mapped must be created with the appropriate flags (see
Common failures of Map methods are indicated by the following return values:
| Item | Description |
|---|---|
| | If MapFlags specifies |
| | Map returns |
?
For more information about the preceding return values, see DXGI_ERROR.
Map has the following restrictions:
Applications must cast the void pData reference to the appropriate type to meaningfully access the underlying subresource data. For example, the following code demonstrates how to read each texel of a 1D subresource. It is assumed that the texture was created using
FLOAT* pTexels = (FLOAT*)pData;\t\n for( UINT col = 0; col < width; col++ )\t\n { pTexels[col*4 + 0]; // Alpha pTexels[col*4 + 1]; // Blue pTexels[col*4 + 2]; // Green pTexels[col*4 + 3]; // Red\t\n }\t\n | Differences between Direct3D 9 and Direct3D 10: Map in Direct3D 10 is analogous to resource Lock in Direct3D 9. |
?
\t\nInvalidate the reference to a resource that was retrieved by
A subresource must be mapped before Unmap is called.
| Differences between Direct3D 9 and Direct3D 10: Unmap in Direct3D 10 is analogous to resource Unlock in Direct3D 9. |
?
\t\nGet the properties of the texture resource.
\t\nPointer to a resource description (see
Get the properties of the texture resource.
\t\nA 2D texture interface manages texel data, which is structured memory.
\t\nTo create an empty Texture2D resource, call
Textures cannot be bound directly to the pipeline; instead, a view must be created and bound. Using a view, texture data can be interpreted at run time within certain restrictions. To use the texture as a render target or depth-stencil resource, call
Get a reference to the data contained in a subresource, and deny GPU access to that subresource.
\t\nIndex number of the subresource. See D3D10CalcSubresource for more details.
Integer that specifies the CPU's read and write permissions for a resource. For possible values, see
Flag that specifies what the CPU should do when the GPU is busy. This flag is optional.
Pointer to a structure (
If this function succeeds, it returns
All of the Map methods have identical return values and operating restrictions. These are listed in the remarks section of
Invalidate the reference to the resource that was retrieved by
A subresource must be mapped before Unmap is called.
| Differences between Direct3D 9 and Direct3D 10: Unmap in Direct3D 10 is analogous to resource Unlock in Direct3D 9. |
?
\t\nGet the properties of the texture resource.
\t\nPointer to a resource description (see
Get the properties of the texture resource.
\t\nA 3D texture interface accesses texel data, which is structured memory.
\t\nTo create an empty Texture3D resource, call
Textures cannot be bound directly to the pipeline; instead, a view must be created and bound. Using a view, texture data can be interpreted at run time within certain restrictions. To use the texture as a render target or depth-stencil resource, call
Get a reference to the data contained in a subresource, and deny GPU access to that subresource.
\t\nIndex number of the subresource. See D3D10CalcSubresourcefor more details.
Specifies the CPU's read and write permissions for a resource. For possible values, see
Flag that specifies what the CPU should do when the GPU is busy. This flag is optional.
Pointer to a structure (
If this function succeeds, it returns
Invalidate the reference to the resource retrieved by
A subresource must be mapped before Unmap is called.
| Differences between Direct3D 9 and Direct3D 10: Unmap() in Direct3D 10 is analogous to resource Unlock() in Direct3D 9. |
?
\t\nGet the properties of the texture resource.
\t\nPointer to a resource description (see
Get the properties of the texture resource.
\t\nA vertex-shader interface manages an executable program (a vertex shader) that controls the vertex-shader stage.
\t\nThe vertex-shader interface has no methods; use HLSL to implement your shader functionality. All shaders in Direct3D 10 are implemented from a common set of features referred to as the common shader core.
To create a vertex shader interface, call
This interface is defined in D3D10.h.
\t\nThe device interface represents a virtual adapter for Direct3D 10.0; it is used to perform rendering and create Direct3D resources.
\t\nA device is created using
Set the constant buffers used by the vertex shader pipeline stage.
\t\nThe 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.
\t\nSet the constant buffers used by the vertex shader pipeline stage.
\t\nThe 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.
\t\nSet a vertex shader to the device.
\t\nPointer to a vertex shader (see
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.
\t\nBind an array of shader resources to the vertex shader stage.
\t\nIf you bind a subresource as an input and an output, this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
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.
\t\nBind an array of shader resources to the vertex shader stage.
\t\nIf you bind a subresource as an input and an output, this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
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.
\t\nSet an array of sampler states to the vertex shader pipeline stage.
\t\nAny sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; 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.
\t\nSet an array of sampler states to the vertex shader pipeline stage.
\t\nAny sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; 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.
\t\nGet the constant buffers used by the vertex shader pipeline stage.
\t\nAny 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.
\t\nGet the vertex shader currently set on the device.
\t\nAddress of a reference to a vertex shader (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.
\t\nGet the vertex shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from.
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources.
Array of shader resource view interfaces to be returned 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.
\t\nGet an array of sampler states from the vertex shader pipeline stage.
\t\nAny 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.
\t\nDescribes the blend state.
\t\nTo see how blending is done, see Output-Merger Stage (Direct3D 10).
These are the default values for blend state.
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| BlendEnable[8] | |
| SrcBlend | |
| DestBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DestBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask[8] |
?
\t\nDetermines whether or not to use alpha-to-coverage as a multisampling technique when setting a pixel to a rendertarget.
This blend option specifies the first RGB data source and includes an optional pre-blend operation.
This blend option specifies the second RGB data source and includes an optional pre-blend operation.
This blend operation defines how to combine the RGB data sources.
This blend option specifies the first alpha data source and includes an optional pre-blend operation. Blend options that end in _COLOR are not allowed.
This blend option specifies the second alpha data source and includes an optional pre-blend operation. Blend options that end in _COLOR are not allowed.
This blend operation defines how to combine the alpha data sources.
Enable (or disable) blending. There are eight elements in this array; these correspond to the eight rendertargets that can be set to output-merger stage at one time.
A per-pixel write mask that allows control over which components can be written (see
Describes the blend state for a Direct3D 10.1 device.
\t\nTo see how blending is done, see Output-Merger Stage (Direct3D 10).
These are the default values for the blend description.
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| IndependentBlendEnable | |
| RenderTarget[0].BlendEnable | |
| RenderTarget[0].SrcBlend | |
| RenderTarget[0].DestBlend | |
| RenderTarget[0].BlendOp | |
| RenderTarget[0].SrcBlendAlpha | |
| RenderTarget[0].DestBlendAlpha | |
| RenderTarget[0].BlendOpAlpha | |
| RenderTarget[0].RenderTargetWriteMask |
?
This structure requires Windows Vista Service Pack 1.
If the driver type is set to
Determines whether or not to use the alpha-to-coverage multisampling technique when setting a render-target pixel.
Set to TRUE to enable independent blending in simultaneous render targets. If set to
An array of render-target-blend descriptions (see
Information about the video card's performance counter capabilities.
\t\nThis structure is returned by
Largest device-dependent counter ID that the device supports. If none are supported, this value will be 0. Otherwise it will be greater than or equal to
Number of counters that can be simultaneously supported.
Number of detectable parallel units that the counter is able to discern. Values are 1 ~ 4. Use NumDetectableParallelUnits to interpret the values of the VERTEX_PROCESSING, GEOMETRY_PROCESSING, PIXEL_PROCESSING, and OTHER_GPU_PROCESSING counters. See
Describes a counter.
\t\nType of counter (see
Reserved.
Describes the stencil operations that can be performed based on the results of stencil test.
\t\nThe stencil operation can be set differently based on the outcome of the stencil test by using the StencilFunc member. This can be done for the stencil test portion of depth-stencil testing.
The
Describes depth-stencil state.
\t\nDepth-stencil state controls how depth-stencil testing is performed by the output-merger stage.
The formats that support stenciling are
A Boolean value that enables depth testing. The default value is TRUE.
A member of the
A member of the
A Boolean value that enables stencil testing. The default value is
A value that identifies a portion of the depth-stencil buffer for reading stencil data. The default value is D3D10_DEFAULT_STENCIL_READ_MASK.
A value that identifies a portion of the depth-stencil buffer for writing stencil data. The default value is D3D10_DEFAULT_STENCIL_WRITE_MASK.
A
A
Specifies the subresource(s) from a texture that are accessible using a depth-stencil view.
\t\nThese are valid formats for a depth-stencil view:
A depth-stencil view cannot use a typeless format. If the format chosen is
A depth-stencil-view description is needed when calling
Specifies the subresource(s) from an array 2D textures that are accessible to a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
Specifies the subresource(s) from an array of multisampled 2D textures for a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
Specifies the subresource(s) from an array of 1D textures to use in a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
Specifies the subresource from a 1D texture that is accessible to a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
Specifies the subresource from a multisampled 2D texture that is accessible to a depth-stencil view.
\t\nSince a multisampled 2D texture contains a single subtexture, there is nothing to specify; this unused member is included so that this structure will compile in C.
\t\nSpecifies the subresource from a 2D texture that is accessible to a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
Describes an effect.
\t\nTo get an effect description, call
TRUE if the effect is a child effect; otherwise
The number of constant buffers.
The number of constant buffers shared in an effect pool.
The number of global variables.
The number of global variables shared in an effect pool.
The number of techniques.
Describes an effect technique.
\t\nTo get a technique, call
A string that contains the technique name; otherwise
The number of passes in the technique.
The number of annotations.
Describes an effect-variable type.
\t\nTo get an effect-variable type, call
A string that contains the variable name.
The variable class (see D3D10_SHADER_VARIABLE_CLASS).
The variable type (see D3D10_SHADER_VARIABLE_TYPE).
The number of elements if the variable is an array; otherwise 0.
The number of members if the variable is a structure; otherwise 0.
The number of rows if the variable is a matrix; otherwise 0.
The number of columns if the variable is a matrix; otherwise 0.
The number of bytes that the variable consumes when it is packed tightly by the compiler.
The number of bytes that the variable consumes before it is packed by the compiler.
The number of bytes between elements.
Describes an effect variable.
\t\nTo get an effect-variable description, call
A string that contains the variable name.
The semantic attached to the variable; otherwise
Optional flags for effect variables.
The number of annotations; otherwise 0.
The offset between the beginning of the constant buffer and this variable; otherwise 0.
The register that this variable is bound to. To bind a variable explicitly use the
Defines font attributes.
\t\nThe compiler setting also determines the structure type. If Unicode is defined, the
Possible values of the above members are given in the GDI
Height, in logical units, of the font's character cell or character.
Width, in logical units, of characters in the font.
Weight of the font in the range from 0 through 1000.
Number of mipmap levels requested. If this value is zero or D3DX_DEFAULT, a complete mipmap chain is created. If the value is 1, the texture space is mapped identically to the screen space.
Set to TRUE for an Italic font.
Character set.
Output precision. The output precision defines how closely the output must match the requested font height, width, character orientation, escapement, pitch, and font type.
Output quality.
Pitch and family of the font.
A
Returns a description of the original contents of an image file.
\t\nWidth of original image in pixels.
Height of original image in pixels.
Depth of original image in pixels.
Size of the texture array. ArraySize will be 1 for a single image.
Number of mipmap levels in original image.
Miscellaneous resource properties (see
A value from the
Represents the type of the texture stored in the file. See
Represents the format of the image file. See
Optionally provide information to texture loader APIs to control how textures get loaded. A value of D3DX10_DEFAULT for any of these parameters will cause D3DX to automatically use the value from the source file.
\t\nWhen initializing the structure, you may set any member to D3DX10_DEFAULT and D3DX will initialize it with a default value from the source texture when the texture is loaded.
This structure can be used by APIs that:
The target width of the texture. If the actual width of the texture is larger or smaller than this value then the texture will be scaled up or down to fit this target width.
The target height of the texture. If the actual height of the texture is larger or smaller than this value then the texture will be scaled up or down to fit this target height.
The depth of the texture. This only applies to volume textures.
The highest resolution mipmap level of the texture. If this is greater than 0, then after the texture is loaded FirstMipLevel will be mapped to mipmap level 0.
The maximum number of mipmap levels that the texture will have. Using 0 or D3DX10_DEFAULT will cause a full mipmap chain to be created.
The way the texture resource is intended to be used. See
The pipeline stages that the texture will be allowed to bind to. See
The access permissions the cpu will have for the texture resource. See
Miscellaneous resource properties (see
The format the texture will be in after it is loaded. See
Filter the texture using the specified filter (only when resampling). See
Filter the texture mip levels using the specified filter (only if generating mipmaps). Valid values are
Information about the original image. See
Debug message filter; contains a lists of message types to allow or deny.
\t\nFor use with an
Providing an allow list with non-zero values causes only the specified combination of categories, severities and message IDs to be allowed. Messages that do not match the specified combination will be rejected.
Providing a deny list with non-zero values causes the specified combination of categories, severities and message IDs to be rejected. Messages that do not match the specified combination will be allowed.
\t\nA
A
Allow or deny certain types of messages to pass through a filter.
\t\nNumber of message categories to allow or deny.
Array of message categories to allow or deny. Array must have at least NumCategories members (see
Number of message severity levels to allow or deny.
Array of message severity levels to allow or deny. Array must have at least NumSeverities members (see
Number of message IDs to allow or deny.
Array of message IDs to allow or deny. Array must have at least NumIDs members (see
A description of a single element for the input-assembler stage.
\t\nAn input-layout object contains an array of structures, each structure defines one element being read from an input slot. Create an input-layout object by calling
Stores an attribute table entry.
\t\nAn attribute table is used to identify areas of the mesh that need to be drawn with different textures, render states, materials, and so on. In addition, the application can use the attribute table to hide portions of a mesh by not drawing a given attribute identifier (AttribId) when drawing the frame.
The LPD3DX_ATTRIBUTE_RANGE type is defined as a reference to the D3DX_ATTRIBUTE_RANGE structure.
typedef D3DX_ATTRIBUTE_RANGE* LPD3DX_ATTRIBUTE_RANGE;\t\n Attribute table identifier.
Starting face.
Face count.
Starting vertex.
Vertex count.
Specifies mesh weight attributes.
\t\nThis structure describes how a simplification operation will consider vertex data when calculating relative costs between collapsing edges. For example, if the Normal field is 0.0, the simplification operation will ignore the vertex normal component when calculating the error for the collapse. However, if the Normal field is 1.0, the simplification operation will use the vertex normal component. If the Normal field is 2.0, double the amount of errors; if the Normal field is 4.0, then quadruple the number of errors, and so on.
The LPD3DX_ATTRIBUTE_WEIGHTS type is defined as a reference to the D3DX_ATTRIBUTE_WEIGHTS structure.
typedef D3DX_ATTRIBUTE_WEIGHTS* LPD3DX_ATTRIBUTE_WEIGHTS;\t\n Position.
Blend weight.
Normal.
Diffuse lighting value.
Specular lighting value.
Tangent.
Binormal.
Eight texture coordinates.
Categories of debug messages. This will identify the category of a message when retrieving a message with
This is part of the Information Queue feature. See
Query information about graphics-pipeline activity in between calls to
Query information about the reliability of a timestamp query.
\t\nFor a list of query types see
How frequently the GPU counter increments in Hz.
If this is TRUE, something occurred in between the query's
Describes a query.
\t\nType of query (see
Miscellaneous flags (see
Describes the rasterizer state.
\t\nRasterizer state defines the behavior of the rasterizer stage; to set rasterizer state, call
A member of the
A member of the
Determines if a triangle is front-facing or back-facing. If this parameter is TRUE, then a triangle is considered front-facing if its vertices are counter-clockwise on the render target, and considered back-facing if they are clockwise. If this parameter is
Specifies the depth value added to a given pixel. The default value is 0. For more information, see Depth Bias.
Specifies the maximum depth bias of a pixel. The default value is 0.0f. For more information, see Depth Bias.
Specifies a scalar on a given pixel's slope. The default value is 0.0f. For more information, see Depth Bias.
Enables or disables clipping based on distance. The default value is TRUE.
The hardware always performs x and y clipping of rasterized coordinates. When DepthClipEnable is set to the default value, the hardware also clips the z value (that is, the hardware performs the last step of the following algorithm).\t\n
0 < w\t\n -w <= x <= w (or arbitrarily wider range if implementation uses a guard band to reduce clipping burden)\t\n -w <= y <= w (or arbitrarily wider range if implementation uses a guard band to reduce clipping burden)\t\n 0 <= z <= w\t\n When you set DepthClipEnable to
Enable or disables scissor-rectangle culling. All pixels outside an active scissor rectangle are culled. The default value is
Enables or disables multisample antialiasing. The default value is
Enable or disables line antialiasing. Note that this option only applies when alpha blending is enabled, you are drawing lines, and the MultisampleEnable member is
Describes the blend state for a render target for a Direct3D 10.1 device
\t\nTo see how blending is done, see Output-Merger Stage (Direct3D 10).
These are the default values for blend state.
| State | Default Value |
|---|---|
| BlendEnable | |
| SrcBlend | |
| DestBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DestBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask |
?
\t\nEnable (or disable) blending.
This blend option specifies the first RGB data source and includes an optional pre-blend operation.
This blend option specifies the second RGB data source and includes an optional pre-blend operation.
This blend operation defines how to combine the RGB data sources.
This blend option specifies the first alpha data source and includes an optional pre-blend operation. Blend options that end in _COLOR are not allowed.
This blend option specifies the second alpha data source and includes an optional pre-blend operation. Blend options that end in _COLOR are not allowed.
This blend operation defines how to combine the alpha data sources.
A write mask.
Specifies the subresource(s) from a resource that are accessible using a render-target view.
\t\nA render-target-view description is passed into
A render-target-view cannot use the following formats:
If the format is set to
Specifies the subresource(s) from a 3D texture to use in a render-target view.
\t\nThis structure is one member of a render target view. See
Specifies the subresource(s) from an array of 2D textures to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
Specifies the subresource(s) from a an array of multisampled 2D textures to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
Specifies the elements from a buffer resource to use in a render-target view.
\t\nA render-target view is a member of a render-target-view description (see
Specifies the subresource from a 1D texture to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
Specifies the subresource(s) from an array of 1D textures to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
Specifies the subresource from a 2D texture to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
Specifies the subresource from a multisampled 2D texture to use in a render-target view.
\t\nSince a multisampled 2D texture contains a single subresource, there is actually nothing to specify in
Defines a 3D box.
\t\nThe following diagram shows a 3D box, where the origin is the left, front, top corner.
\t\nThe x position of the left hand side of the box.
The y position of the top of the box.
The z position of the front of the box.
The x position of the right hand side of the box.
The y position of the bottom of the box.
The z position of the back of the box.
Describes a sampler state.
\t\nThese are the default values for sampler state.
| State | Default Value |
|---|---|
| Filter | Min_Mag_Mip_Point |
| AddressU | Clamp |
| AddressV | Clamp |
| AddressW | Clamp |
| MinLOD | 0.0f |
| MaxLOD | 3.402823466e+38F (FLT_MAX) |
| MipMapLODBias | 0.0f |
| MaxAnisotropy | 16 |
| ComparisonFunc | Never |
| BorderColor | float4(0.0f, 0.0f, 0.0f, 0.0f) |
| Texture | N/A |
?
\t\nFiltering method to use when sampling a texture (see
Method to use for resolving a u texture coordinate that is outside the 0 to 1 range (see
Method to use for resolving a v texture coordinate that is outside the 0 to 1 range.
Method to use for resolving a w texture coordinate that is outside the 0 to 1 range.
Offset from the calculated mipmap level. For example, if Direct3D calculates that a texture should be sampled at mipmap level 3 and MipLODBias is 2, then the texture will be sampled at mipmap level 5.
Clamping value used if
A function that compares sampled data against existing sampled data. The function options are listed in
Border color to use if
Lower end of the mipmap range to clamp access to, where 0 is the largest and most detailed mipmap level and any level higher than that is less detailed.
Upper end of the mipmap range to clamp access to, where 0 is the largest and most detailed mipmap level and any level higher than that is less detailed. This value must be greater than or equal to MinLOD. To have no upper limit on LOD set this to a large value such as D3D10_FLOAT32_MAX.
Describes a shader constant-buffer.
\t\nConstants are supplied to shaders in a shader-constant buffer. Get the description of a shader-constant-buffer by calling ID3D10ShaderReflectionConstantBuffer::GetDesc.
\t\nThe name of the buffer.
The intended use of the constant data. See D3D10_CBUFFER_TYPE.
The number of unique variables.
Buffer size (in bytes).
Shader buffer properties. See D3D10_SHADER_CBUFFER_FLAGS.
Describes a shader signature.
\t\nA shader can take n inputs and can produce m outputs. The order of the input (or output) parameters, their associated types, and any attached semantics make up the shader signature. Each shader has an input and an output signature.
When compiling a shader or an effect, some API calls validate shader signatures (such as D3D10CompileShader and
Get a shader-signature from a shader or an effect by calling APIs such as ID3D10ShaderReflection::GetInputParameterDesc or
A per-parameter string that identifies how the data will be used. See Semantics (DirectX HLSL).
Semantic index that modifies the semantic. Used to differentiate different parameters that use the same semantic.
The register that will contain this variable's data.
A predefined string that determines the functionality of certain pipeline stages. See D3D10_NAME.
The per-component-data type that is stored in a register. See D3D10_REGISTER_COMPONENT_TYPE. Each register can store up to four-components of data.
Mask which indicates which components of a register are used.
Mask which indicates whether a given component is never written (if the signature is an output signature) or always read (if the signature is an input signature). The mask is a combination of D3D10_REGISTER_COMPONENT_TYPE values.
Describes a shader-resource view.
\t\nA view is a format-specific way to look at the data in a resource. The view determines what data to look at, and how it is cast when read. For more information about how views work, see Views
When viewing a resource, the resource-view description must specify a typed format, that is compatible with the resource format. So that means that you cannot create a resource-view description using any format with _TYPELESS in the name. You can however view a typeless resource by specifying a typed format for the view. For example, a
Create a shader-resource-view description by calling
The viewing format. See remarks.
The resource type of the view. See D3D10_SRV_DIMENSION. This should be the same as the resource type of the underlying resource. This parameter also determines which _SRV to use in the union below.
View the resource as a buffer using information from a shader-resource view (see
View the resource as a 1D texture using information from a shader-resource view (see
View the resource as a 1D-texture array using information from a shader-resource view (see
View the resource as a 2D-texture using information from a shader-resource view (see
View the resource as a 2D-texture array using information from a shader-resource view (see
View the resource as a 2D-multisampled texture using information from a shader-resource view (see
View the resource as a 2D-multisampled-texture array using information from a shader-resource view (see
View the resource as a 3D texture using information from a shader-resource view (see
View the resource as a 3D-cube texture using information from a shader-resource view (see
Specifies the elements in a buffer resource to use in a shader-resource view.
\t\nThe
Specifies the subresource from a 1D texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Specifies the subresource(s) from an array of 1D textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Specifies the subresource from a 2D texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Specifies the subresource(s) from an array of 2D textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Specifies the subresource(s) from a multisampled 2D texture to use in a shader-resource view.
\t\nSince a multisampled 2D texture contains a single subresource, there is actually nothing to specify in
Specifies the subresource(s) from an array of multisampled 2D textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Specifies the subresource(s) from a 3D texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Specifies the subresource from a cube texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Describes a shader-resource view.
\t\nA view is a format-specific way to look at the data in a resource. The view determines what data to look at, and how it is cast when read. For more information about how views work, see Views
When viewing a resource, the resource-view description must specify a typed format, that is compatible with the resource format. So that means that you cannot create a resource-view description using any format with _TYPELESS in the name. You can however view a typeless resource by specifying a typed format for the view. For example, a
Create a shader-resource-view description by calling
This structure requires Windows Vista Service Pack 1.
\t\nThe viewing format. See remarks.
The resource type of the view. See D3D10_SRV_DIMENSION1. This should be the same as the resource type of the underlying resource. This parameter also determines which _SRV to use in the union below.
View the resource as a buffer using information from a shader-resource view (see
View the resource as a 1D texture using information from a shader-resource view (see
View the resource as a 1D-texture array using information from a shader-resource view (see
View the resource as a 2D-texture using information from a shader-resource view (see
View the resource as a 2D-texture array using information from a shader-resource view (see
View the resource as a 2D-multisampled texture using information from a shader-resource view (see
View the resource as a 2D-multisampled-texture array using information from a shader-resource view (see
View the resource as a 3D texture using information from a shader-resource view (see
View the resource as a 3D-cube texture using information from a shader-resource view (see
View the resource as an array of cube textures using information from a shader-resource view (see
Specifies the subresource(s) from an array of cube textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
This structure requires Windows Vista Service Pack 1.
\t\nThe member of the vertex decl to do the software skinning on. This is used with the
Defines position, texture, and color information about a sprite.
\t\nThe sprite's model-world transformation. This defines the position and orientation of the sprite in world space.
Offset from the upper-left corner of the texture indicating where the sprite image should start in the texture. TexCoord is in texture coordinates.
A vector containing the width and height of the sprite in texture coordinates.
A color that will be multiplied with the pixel color before rendering.
Pointer to a shader-resource view representing the sprite's texture. See
The index of the texture. If pTexture does not represent a texture array, then this should be 0.
Indicates the device state.
\t\nA state-block mask indicates the device states that a pass or a technique changes. The D3D10StateBlockMaskEnableCapture function provides a convenient way of setting a range of bitmasks for the array members of
Boolean value indicating whether to save the vertex shader state.
Boolean value indicating whether to save the geometry shader state.
Boolean value indicating whether to save the pixel shader state.
Boolean value indicating whether to save the index buffer state.
Boolean value indicating whether to save the input layout state.
Boolean value indicating whether to save the primitive topology state.
Boolean value indicating whether to save the render targets states.
Boolean value indicating whether to save the depth-stencil state.
Boolean value indicating whether to save the blend state.
Boolean value indicating whether to save the viewports states.
Boolean value indicating whether to save the scissor rectangles states.
Boolean value indicating whether to save the rasterizer state.
Boolean value indicating whether to save the stream-out buffers states.
Boolean value indicating whether to save the predication state.
Array of vertex-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of vertex-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of vertex-shader constant buffers. The array is a multi-byte bitmask where each bit represents one constant buffer slot.
Array of geometry-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of geometry-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of geometry-shader constant buffers. The array is a multi-byte bitmask where each bit represents one buffer slot.
Array of pixel-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of pixel-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of pixel-shader constant buffers. The array is a multi-byte bitmask where each bit represents one constant buffer slot.
Array of vertex buffers. The array is a multi-byte bitmask where each bit represents one resource slot.
Description of a vertex element in a vertex buffer in an output slot.
\t\nType of output element. Possible values: \"POSITION\", \"NORMAL\", or \"TEXCOORD0\".
Output element's zero-based index. Should be used if, for example, you have more than one texture coordinate stored in each vertex.
Which component of the entry to begin writing out to. Valid values are 0 ~ 3. For example, if you only wish to output to the y and z components of a position, then StartComponent should be 1 and ComponentCount should be 2.
The number of components of the entry to write out to. Valid values are 1 ~ 4. For example, if you only wish to output to the y and z components of a position, then StartComponent should be 1 and ComponentCount should be 2.
The output slot that contains the vertex buffer that contains this output entry.
Query information about the amount of data streamed out to the stream-output buffers in between
Describes a 1D texture.
\t\nThis structure is used in a call to
Describes a 2D texture.
\t\nThis structure is used in a call to
The device places some size restrictions (must be multiples of a minimum size) for a subsampled, block compressed, or bit-format resource.
\t\nDescribes a 3D texture.
\t\nThis structure is used in a call to
The device restricts the size of subsampled, block compressed (see Block Compression (Direct3D 10)), and bit format resources to be multiples of sizes specific to each format.
\t\nDescribes parameters used to load a texture from another texture.
\t\nThis structure is used in a call to
Source texture box (see
Destination texture box (see
Source texture mipmap level, see D3D10CalcSubresource for more detail.
Destination texture mipmap level, see D3D10CalcSubresource for more detail.
Number of mipmap levels in the source texture.
First element of the source texture.
First element of the destination texture.
Number of elements to load.
Filtering options during resampling (see
Filtering options when generating mip levels (see
An
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
Note??
If you call QueryInterface on an
* pIUnknown = (*)pEffect; pIUnknown->AddRef();\t\n Test an effect to see if it contains valid syntax.
\t\nTRUE if the code syntax is valid; otherwise
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet the device that created the effect.
\t\nA reference to an
Returns one of the following Direct3D 11 Return Codes.
An effect is created for a specific device, by calling a function such as
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an effect description.
\t\nA reference to an effect description (see
Returns one of the following Direct3D 11 Return Codes.
An effect description contains basic information about an effect such as the techniques it contains and the constant buffer resources it requires.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a constant buffer by index.
\t\nA zero-based index.
A reference to a
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a constant buffer by name.
\t\nThe constant-buffer name.
A reference to the constant buffer indicated by the Name. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a variable by index.
\t\nA zero-based index.
A reference to a
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
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a variable by name.
\t\nThe variable name.
A reference to an
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 whether or not a variable is found.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a variable by semantic.
\t\nThe semantic name.
A reference to the effect variable indicated by the Semantic. See
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
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets an effect group by index.
\t\nIndex of the effect group.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets an effect group by name.
\t\nName of the effect group.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a technique by index.
\t\nA zero-based index.
A reference to an
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a technique by name.
\t\nThe name of the technique.
A reference to an
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets a class linkage interface.
\t\nReturns a reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nCreates a copy of an effect interface.
\t\nFlags affecting the creation of the cloned effect. Can be 0 or one of the following values.
| Flag | Description |
|---|---|
| D3DX11_EFFECT_CLONE_FORCE_NONSINGLE | Ignore all \"single\" qualifiers on cbuffers. All cbuffers will have their own |
?
Pointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nMinimize the amount of memory required for an effect.
\t\nReturns one of the following Direct3D 11 Return Codes.
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
The following methods will fail after Optimize has been called on an effect.
Note??References retrieved with these methods before calling
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest an effect to see if the reflection metadata has been removed from memory.
\t\nTRUE if the effect is optimized; otherwise
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
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest an effect to see if it contains valid syntax.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet the device that created the effect.
\t\nAn effect is created for a specific device, by calling a function such as
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an effect description.
\t\nAn effect description contains basic information about an effect such as the techniques it contains and the constant buffer resources it requires.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets a class linkage interface.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest an effect to see if the reflection metadata has been removed from memory.
\t\nAn 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
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nThe blend-variable interface accesses blend state.
\t\nAn
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nThe
The lifetime of an
The
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nCompare the data type with the data stored.
\t\nTRUE if the syntax is valid; otherwise
This method checks that the data type matches the data stored after casting one interface to another (using any of the As methods).
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet type information.
\t\nA reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a description.
\t\nA reference to an effect-variable description (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by index.
\t\nA zero-based index.
A reference to an
Annonations can be attached to a technique, a pass, or a global variable.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by name.
\t\nThe annotation name.
A reference to an
Annonations can be attached to a technique, a pass, or a global variable.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a structure member by index.
\t\nA zero-based index.
A reference to an
If the effect variable is an structure, use this method to look up a member by index.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a structure member by name.
\t\nMember name.
A reference to an
If the effect variable is an structure, use this method to look up a member by name.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a structure member by semantic.
\t\nThe semantic.
A reference to an
If the effect variable is an structure, use this method to look up a member by attached semantic.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array element.
\t\nA zero-based index; otherwise 0.
A reference to an
If the effect variable is an array, use this method to return one of the elements.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a constant buffer.
\t\nA reference to a
Effect variables are read-from or written-to a constant buffer.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a scalar variable.
\t\nA reference to a scalar variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a vector variable.
\t\nA reference to a vector variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a matrix variable.
\t\nA reference to a matrix variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a string variable.
\t\nA reference to a string variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a class-instance variable.
\t\nA reference to class-instance variable. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an interface variable.
\t\nA reference to an interface variable. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a shader-resource variable.
\t\nA reference to a shader-resource variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an unordered-access-view variable.
\t\nA reference to an unordered-access-view variable. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a render-target-view variable.
\t\nA reference to a render-target-view variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a depth-stencil-view variable.
\t\nA reference to a depth-stencil-view variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a constant buffer.
\t\nA reference to a constant buffer. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a shader variable.
\t\nA reference to a shader variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a effect-blend variable.
\t\nA reference to an effect blend variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a depth-stencil variable.
\t\nA reference to a depth-stencil variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a rasterizer variable.
\t\nA reference to a rasterizer variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a sampler variable.
\t\nA reference to a sampler variable. See
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet data.
\t\nA reference to the variable.
The offset (in bytes) from the beginning of the reference to the data.
The number of bytes to set.
Returns one of the following Direct3D 11 Return Codes.
This method does no conversion or type checking; it is therefore a very quick way to access array items.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet data.
\t\nA reference to the variable.
The offset (in bytes) from the beginning of the reference to the data.
The number of bytes to get.
Returns one of the following Direct3D 11 Return Codes.
This method does no conversion or type checking; it is therefore a very quick way to access array items.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nCompare the data type with the data stored.
\t\nThis method checks that the data type matches the data stored after casting one interface to another (using any of the As methods).
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet type information.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a description.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a constant buffer.
\t\nEffect variables are read-from or written-to a constant buffer.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a blend-state interface.
\t\nIndex into an array of blend-state interfaces. If there is only one blend-state interface, use 0.
The address of a reference to a blend-state interface (see
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSets an effect's blend-state.
\t\nIndex into an array of blend-state interfaces. If there is only one blend-state interface, use 0.
A reference to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nReverts a previously set blend-state.
\t\nIndex into an array of blend-state interfaces. If there is only one blend-state interface, use 0.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a blend-state variable.
\t\nIndex into an array of blend-state descriptions. If there is only one blend-state variable in the effect, use 0.
A reference to a blend-state description (see
Returns one of the following Direct3D 11 Return Codes.
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA depth-stencil-variable interface accesses depth-stencil state.
\t\nAn
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a depth-stencil interface.
\t\nIndex into an array of depth-stencil interfaces. If there is only one depth-stencil interface, use 0.
The address of a reference to a blend-state interface (see
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSets the depth stencil state.
\t\nIndex into an array of depth-stencil interfaces. If there is only one depth-stencil interface, use 0.
Pointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nReverts a previously set depth stencil state.
\t\nIndex into an array of depth-stencil interfaces. If there is only one depth-stencil interface, use 0.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a variable that contains depth-stencil state.
\t\nIndex into an array of depth-stencil-state descriptions. If there is only one depth-stencil variable in the effect, use 0.
A reference to a depth-stencil-state description (see
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA depth-stencil-view-variable interface accesses a depth-stencil view.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a depth-stencil-view resource.
\t\nA reference to a depth-stencil-view interface. See
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a depth-stencil-view resource.
\t\nThe address of a reference to a depth-stencil-view interface. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of depth-stencil-view resources.
\t\nA reference to an array of depth-stencil-view interfaces. See
The zero-based array index to set the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of depth-stencil-view resources.
\t\nA reference to an array of depth-stencil-view interfaces. See
The zero-based array index to set the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of depth-stencil-view resources.
\t\nA reference to an array of depth-stencil-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA matrix-variable interface accesses a matrix.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a floating-point matrix.
\t\nA reference to the first element in the matrix.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a matrix.
\t\nA reference to the first element in a matrix.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of floating-point matrices.
\t\nA reference to the first matrix.
The number of matrix elements to skip from the start of the array.
The number of elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of matrices.
\t\nA reference to the first element of the first matrix in an array of matrices.
The offset (in number of matrices) between the start of the array and the first matrix returned.
The number of matrices in the returned array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTranspose and set a floating-point matrix.
\t\nA reference to the first element of a matrix.
Returns one of the following Direct3D 11 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTranspose and get a floating-point matrix.
\t\nA reference to the first element of a transposed matrix.
Returns one of the following Direct3D 11 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTranspose and set an array of floating-point matrices.
\t\nA reference to an array of matrices.
The offset (in number of matrices) between the start of the array and the first matrix to set.
The number of matrices in the array to set.
Returns one of the following Direct3D 11 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTranspose and get an array of floating-point matrices.
\t\nA reference to the first element of an array of tranposed matrices.
The offset (in number of matrices) between the start of the array and the first matrix to get.
The number of matrices in the array to get.
Returns one of the following Direct3D 11 Return Codes.
Transposing a matrix will rearrange the data order from row-column order to column-row order (or vice versa).
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nAn
The lifetime of an
The
A pass is a block of code that sets render-state objects and shaders. A pass is declared within a technique.
To get an effect-pass interface, call a method like
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest a pass to see if it contains valid syntax.
\t\nTRUE if the code syntax is valid; otherwise
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a pass description.
\t\nA reference to a pass description (see
Returns one of the following Direct3D 11 Return Codes.
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a vertex-shader description.
\t\nA reference to a vertex-shader description (see
Returns one of the following Direct3D 11 Return Codes.
An effect pass can contain render state assignments and shader object assignments.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a geometry-shader description.
\t\nA reference to a geometry-shader description (see
Returns one of the following Direct3D 11 Return Codes.
An effect pass can contain render state assignments and shader object assignments.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a pixel-shader description.
\t\nA reference to a pixel-shader description (see
Returns one of the following Direct3D 11 Return Codes.
An effect pass can contain render state assignments and shader object assignments.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet hull-shader description.
\t\nA reference to a hull-shader description (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a domain-shader description.
\t\nA reference to a domain-shader description (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a compute-shader description.
\t\nA reference to a compute-shader description (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by index.
\t\nA zero-based index.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by name.
\t\nThe name of the annotation.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet the state contained in a pass to the device.
\t\nUnused.
The
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGenerate a mask for allowing/preventing state changes.
\t\nA reference to a state-block mask (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest a pass to see if it contains valid syntax.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a pass description.
\t\nA 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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a vertex-shader description.
\t\nAn effect pass can contain render state assignments and shader object assignments.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a geometry-shader description.
\t\nAn effect pass can contain render state assignments and shader object assignments.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a pixel-shader description.
\t\nAn effect pass can contain render state assignments and shader object assignments.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet hull-shader description.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a domain-shader description.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a compute-shader description.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nDescribes an effect pass, which contains pipeline state.
\t\nName of this pass (
Number of annotations on this pass.
Signature from the vertex shader or geometry shader (if there is no vertex shader) or
Singature size in bytes.
The stencil-reference value used in the depth-stencil state.
The sample mask for the blend state.
The per-component blend factors (RGBA) for the blend state.
Describes an effect pass.
\t\nIf this is an inline shader assignment, the returned interface will be an anonymous shader variable, which is not retrievable any other way. It's name in the variable description will be \"$Anonymous\". If there is no assignment of this type in the pass block, pShaderVariable !=
The variable that this shader came from.
The element of pShaderVariable (if an array) or 0 if not applicable.
A rasterizer-variable interface accesses rasterizer state.
\t\nAn
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a rasterizer interface.
\t\nIndex into an array of rasterizer interfaces. If there is only one rasterizer interface, use 0.
The address of a reference to a rasterizer interface (see
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSets the rasterizer state.
\t\nIndex into an array of rasterizer interfaces. If there is only one rasterizer interface, use 0.
Pointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nReverts a previously set rasterizer state.
\t\nIndex into an array of rasterizer interfaces. If there is only one rasterizer interface, use 0.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a variable that contains rasteriser state.
\t\nIndex into an array of rasteriser-state descriptions. If there is only one rasteriser variable in the effect, use 0.
A reference to a rasteriser-state description (see
Returns one of the following Direct3D 11 Return Codes.
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA render-target-view interface accesses a render target.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a render-target.
\t\nA reference to a render-target-view interface. See
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a render-target.
\t\nThe address of a reference to a render-target-view interface. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of render-targets.
\t\nSet an array of render-target-view interfaces. See
The zero-based array index to store the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of render-targets.
\t\nSet an array of render-target-view interfaces. See
The zero-based array index to store the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of render-targets.
\t\nA reference to an array of render-target-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA sampler interface accesses sampler state.
\t\nAn
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.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a sampler interface.
\t\nIndex into an array of sampler interfaces. If there is only one sampler interface, use 0.
The address of a reference to a sampler interface (see
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet sampler state.
\t\nIndex into an array of sampler interfaces. If there is only one sampler interface, use 0.
Pointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nRevert a previously set sampler state.
\t\nIndex into an array of sampler interfaces. If there is only one sampler interface, use 0.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a reference to a variable that contains sampler state.
\t\nIndex into an array of sampler descriptions. If there is only one sampler variable in the effect, use 0.
A reference to a sampler description (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nAn effect-scalar-variable interface accesses scalar values.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a floating-point variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a floating-point variable.
\t\nA reference to the variable.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of floating-point variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of floating-point variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an integer variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an integer variable.
\t\nA reference to the variable.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of integer variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of integer variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a boolean variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a boolean variable.
\t\nA reference to the variable.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of boolean variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of boolean variables.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nDescribes an effect shader.
\t\nPassed into CreateInputLayout. Only valid on a vertex shader or geometry shader. See
TRUE is the shader is defined inline; otherwise
Shader bytecode.
The length of pBytecode.
Indicates which stream is rasterized. D3D11 geometry shaders can output up to four streams of data, one of which can be rasterized.
Number of entries in the input signature.
Number of entries in the output signature.
Number of entries in the patch constant signature.
Stream out declaration string (for geometry shader with SO).
A shader-resource interface accesses a shader resource.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a shader resource.
\t\nThe address of a reference to a shader-resource-view interface. See
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a shader resource.
\t\nThe address of a reference to a shader-resource-view interface. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of shader resources.
\t\nThe address of an array of shader-resource-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of shader resources.
\t\nThe address of an array of shader-resource-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of shader resources.
\t\nThe address of an array of shader-resource-view interfaces. See
The zero-based array index to get the first interface.
The number of elements in the array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA string-variable interface accesses a string variable.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet the string.
\t\nA reference to the string.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of strings.
\t\nA reference to the first string in the array.
The offset (in number of strings) between the start of the array and the first string to get.
The number of strings in the returned array.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nAccesses an unordered access view.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an unordered-access-view.
\t\nPointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an unordered-access-view.
\t\nPointer to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA vector-variable interface accesses a four-component vector.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a four-component vector that contains boolean data.
\t\nA reference to the first component.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a four-component vector that contains integer data.
\t\nA reference to the first component.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a four-component vector that contains floating-point data.
\t\nA reference to the first component.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a four-component vector that contains boolean data.
\t\nA reference to the first component.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a four-component vector that contains integer data.
\t\nA reference to the first component.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a four-component vector that contains floating-point data.
\t\nA reference to the first component.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of four-component vectors that contain boolean data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of four-component vectors that contain integer data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet an array of four-component vectors that contain floating-point data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of four-component vectors that contain boolean data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of four-component vectors that contain integer data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an array of four-component vectors that contain floating-point data.
\t\nA reference to the start of the data to set.
Must be set to 0; this is reserved for future use.
The number of array elements to set.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nCreates an effect from a binary effect or file.
\t\nBlob of compiled effect data.
Length of the data blob.
Compilation flags pertaining to Effect compilation, honored by the Effect compiler.
Pointer to the
Address of the newly created
The return value is one of the values listed in Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nAccesses a class instance.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets a class instance.
\t\nPointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets a class instance.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA constant-buffer interface accesses constant buffers or texture buffers.
\t\nUse constant buffers to store many effect constants; grouping constants into buffers based on their frequency of update. This allows you to minimize the number of state changes as well as make the fewest API calls to change state. Both of these factors lead to better performance.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a constant-buffer.
\t\nA reference to a constant-buffer interface. See
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nReverts a previously set constant buffer.
\t\nReturns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a constant-buffer.
\t\nThe address of a reference to a constant-buffer interface. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSet a texture-buffer.
\t\nA reference to a shader-resource-view interface for accessing a texture buffer.
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nReverts a previously set texture buffer.
\t\nReturns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a texture-buffer.
\t\nThe address of a reference to a shader-resource-view interface for accessing a texture buffer. See
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nThe
The lifetime of an
The
To get an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest an effect to see if it contains valid syntax.
\t\nTRUE if the code syntax is valid; otherwise
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets a group description.
\t\nA reference to a
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by index.
\t\nIndex of the annotation.
Pointer to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by name.
\t\nThe name of the annotation.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a technique by index.
\t\nA zero-based index.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a technique by name.
\t\nThe name of the technique.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest an effect to see if it contains valid syntax.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGets a group description.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nAccesses an interface variable.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nSets a class instance.
\t\nPointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a class instance.
\t\nPointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet or sets a class instance.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nA shader-variable interface accesses a shader variable.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a shader description.
\t\nA zero-based index.
A reference to a shader description (see
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a vertex shader.
\t\nA zero-based index.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a geometry shader.
\t\nA zero-based index.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a pixel shader.
\t\nA zero-based index.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a hull shader.
\t\nIndex of the shader.
A reference to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a domain shader.
\t\nIndex of the domain shader.
Pointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a compute shader.
\t\nIndex of the compute shader.
Pointer to an
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an input-signature description.
\t\nA zero-based shader index.
A zero-based shader-element index.
A reference to a parameter description (see
An effect contains one or more shaders; each shader has an input and output signature; each signature contains one or more elements (or parameters). The shader index identifies the shader and the element index identifies the element (or parameter) in the shader signature.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an output-signature description.
\t\nA zero-based shader index.
A zero-based element index.
A reference to a parameter description (see
An effect contains one or more shaders; each shader has an input and output signature; each signature contains one or more elements (or parameters). The shader index identifies the shader and the element index identifies the element (or parameter) in the shader signature.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a patch constant signature description.
\t\nA zero-based shader index.
A zero-based element index.
A reference to a parameter description (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nCompute a state-block mask to allow/prevent state changes.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest a technique to see if it contains valid syntax.
\t\nTRUE if the code syntax is valid; otherwise
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a technique description.
\t\nA reference to a technique description (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by index.
\t\nThe zero-based index of the interface reference.
A reference to an
Use an annotation to attach a piece of metadata to a technique.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an annotation by name.
\t\nName of the annotation.
A reference to an
Use an annotation to attach a piece of metadata to a technique.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a pass by index.
\t\nA zero-based index.
A reference to a
A technique contains one or more passes; get a pass using a name or an index.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a pass by name.
\t\nThe name of the pass.
A reference to an
A technique contains one or more passes; get a pass using a name or an index.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nCompute a state-block mask to allow/prevent state changes.
\t\nA reference to a state-block mask (see
Returns one of the following Direct3D 11 Return Codes.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTest a technique to see if it contains valid syntax.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a technique description.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nThe
The lifetime of an
The
To get information about an effect type from an effect variable, call
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTests that the effect type is valid.
\t\nTRUE if it is valid; otherwise
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an effect-type description.
\t\nA reference to an effect-type description. See
Returns one of the following Direct3D 11 Return Codes.
The effect-variable description contains data about the name, annotations, semantic, flags and buffer offset of the effect type.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a member type by index.
\t\nA zero-based index.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an member type by name.
\t\nA member's name.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet a member type by semantic.
\t\nA semantic.
A reference to an
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet the name of a member.
\t\nA zero-based index.
The name of the member.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet the semantic attached to a member.
\t\nA zero-based index.
A string that contains the semantic.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nTests that the effect type is valid.
\t\nNote??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nGet an effect-type description.
\t\nThe effect-variable description contains data about the name, annotations, semantic, flags and buffer offset of the effect type.
Note??The DirectX SDK does not supply any compiled binaries for effects. You must use Effects 11 source to build your effects-type application. For more information about using Effects 11 source, see Differences Between Effects 10 and Effects 11.
\t\nDescribes an effect.
\t\nNumber of constant buffers in this effect.
Number of global variables in this effect.
Number of global interfaces in this effect.
Number of techniques in this effect.
Number of groups in this effect.
Describes an effect group.
\t\nName of this group (only
Number of techniques contained in group.
Number of annotations on this group.
Describes an effect technique.
\t\nName of this technique (
Number of passes contained in the technique.
Number of annotations on this technique.
Describes an effect-variable type.
\t\nName of the type, for example \"float4\" or \"MyStruct\".
The variable class (see D3D10_SHADER_VARIABLE_CLASS).
The variable type (see D3D10_SHADER_VARIABLE_TYPE).
Number of elements in this type (0 if not an array).
Number of members (0 if not a structure).
Number of rows in this type (0 if not a numeric primitive).
Number of columns in this type (0 if not a numeric primitive).
Number of bytes required to represent this data type, when tightly packed.
Number of bytes occupied by this data type, when laid out in a constant buffer.
Number of bytes to seek between elements, when laid out in a constant buffer.
Describes an effect variable.
\t\nName of this variable, annotation, or structure member.
Semantic string of this variable or structure member (
Optional flags for effect variables.
Number of annotations on this variable (always 0 for annotations).
Offset into containing cbuffer or tbuffer (always 0 for annotations or variables not in constant buffers).
Used if the variable has been explicitly bound using the register keyword. Check Flags for
Indicates the device state.
\t\nA state-block mask indicates the device states that a pass or a technique changes.
\t\nBoolean value indicating whether to save the vertex shader state.
Boolean value indicating whether to save the hull shader state.
Boolean value indicating whether to save the domain shader state.
Boolean value indicating whether to save the geometry shader state.
Boolean value indicating whether to save the pixel shader state.
Boolean value indicating whether to save the pixel shader unordered access views.
Boolean value indicating whether to save the compute shader state.
Boolean value indicating whether to save the compute shader unordered access views.
Boolean value indicating whether to save the index buffer state.
Boolean value indicating whether to save the input layout state.
Boolean value indicating whether to save the primitive topology state.
Boolean value indicating whether to save the render targets states.
Boolean value indicating whether to save the depth-stencil state.
Boolean value indicating whether to save the blend state.
Boolean value indicating whether to save the viewports states.
Boolean value indicating whether to save the scissor rectangles states.
Boolean value indicating whether to save the rasterizer state.
Boolean value indicating whether to save the stream-out buffers states.
Boolean value indicating whether to save the predication state.
Array of vertex-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of vertex-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of vertex-shader constant buffers. The array is a multi-byte bitmask where each bit represents one constant buffer slot.
Array of vertex-shader interfaces. The array is a multi-byte bitmask where each bit represents one interface slot.
Array of hull-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of hull-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of hull-shader constant buffers. The array is a multi-byte bitmask where each bit represents one constant buffer slot.
Array of hull-shader interfaces. The array is a multi-byte bitmask where each bit represents one interface slot.
Array of domain-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of domain-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of domain-shader constant buffers. The array is a multi-byte bitmask where each bit represents one buffer slot.
Array of domain-shader interfaces. The array is a multi-byte bitmask where each bit represents one interface slot.
Array of geometry-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of geometry-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of geometry-shader constant buffers. The array is a multi-byte bitmask where each bit represents one buffer slot.
Array of geometry-shader interfaces. The array is a multi-byte bitmask where each bit represents one interface slot.
Array of pixel-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of pixel-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of pixel-shader constant buffers. The array is a multi-byte bitmask where each bit represents one constant buffer slot.
Array of pixel-shader interfaces. The array is a multi-byte bitmask where each bit represents one interface slot.
Array of compute-shader samplers. The array is a multi-byte bitmask where each bit represents one sampler slot.
Array of compute-shader resources. The array is a multi-byte bitmask where each bit represents one resource slot.
Array of compute-shader constant buffers. The array is a multi-byte bitmask where each bit represents one constant buffer slot.
Array of compute-shader interfaces. The array is a multi-byte bitmask where each bit represents one interface slot.
Array of vertex buffers. The array is a multi-byte bitmask where each bit represents one resource slot.
The blend-state interface holds a description for blending state that you can bind to the output-merger stage.
\t\nBlending applies a simple function to combine output values from a pixel shader with data in a render target. You have control over how the pixels are blended by using a predefined set of blending operations and preblending operations.
To create a blend-state object, call
A device-child interface accesses data used by a device.
\t\nThere are several types of device child interfaces, all of which inherit this interface. They include shaders, state objects, and input layouts.
\t\nGet a reference to the device that created this interface.
\t\nAddress of a reference to a device (see
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.
\t\nGet application-defined data from a device child.
\t\nGuid associated with the data.
A reference to a variable that on input contains the size, in bytes, of the buffer that pData points to, and on output contains the size, in bytes, of the amount of data that GetPrivateData retrieved.
A reference to a buffer that GetPrivateData fills with data from the device child if pDataSize points to a value that specifies a buffer large enough to hold the data.
This method returns one of the codes described in the topic Direct3D 11 Return Codes.
The data stored in the device child is set by calling
Set application-defined data to a device child and associate that data with an application-defined guid.
\t\nGuid associated with the data.
Size of the data.
Pointer to the data to be stored with this device child. If pData is
This method returns one of the following Direct3D 11 Return Codes.
The data stored in the device child with this method can be retrieved with
The debug layer reports memory leaks by outputting a list of object interface references along with their friendly names. The default friendly name is \"<unnamed>\". You can set the friendly name so that you can determine if the corresponding object interface reference caused the leak. To set the friendly name, use the SetPrivateData method and the
static const char c_szName[] = \"My name\";\t\n hr = pContext->SetPrivateData( , sizeof( c_szName ) - 1, c_szName );\t\n Associate an
Guid associated with the interface.
Pointer to an
This method returns one of the following Direct3D 11 Return Codes.
When this method is called ::addref() will be called on the
Get a reference to the device that created this interface.
\t\nAny 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.
\t\nGets the description for blending state that you used to create the blend-state object.
\t\nA reference to a
You use the description for blending state in a call to the
Gets the description for blending state that you used to create the blend-state object.
\t\nYou use the description for blending state in a call to the
Describes the blend state that you use in a call to
Here are the default values for blend state.
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| IndependentBlendEnable | |
| RenderTarget[0].BlendEnable | |
| RenderTarget[0].SrcBlend | |
| RenderTarget[0].DestBlend | |
| RenderTarget[0].BlendOp | |
| RenderTarget[0].SrcBlendAlpha | |
| RenderTarget[0].DestBlendAlpha | |
| RenderTarget[0].BlendOpAlpha | |
| RenderTarget[0].RenderTargetWriteMask |
?
Note??
If the driver type is set to
A buffer interface accesses a buffer resource, which is unstructured memory. Buffers typically store vertex or index data.
\t\nThere are three types of buffers: vertex, index, or a shader-constant buffer. Create a buffer resource by calling
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
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.
\t\nA resource interface provides common actions on all resources.
\t\nA 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).
\t\nGet the type of the resource.
\t\nPointer to the resource type (see
Set the eviction priority of a resource.
\t\nEviction priority for the resource, which is one of the following values:
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,
Changing the priorities of resources should be done carefully. The wrong eviction priorities could be a detriment to performance rather than an improvement.
\t\nGet the eviction priority of a resource.
\t\nOne of the following values, which specifies the eviction priority for the resource:
Get the type of the resource.
\t\nGet or sets the eviction priority of a resource.
\t\nGet the properties of a buffer resource.
\t\nPointer to a resource description (see
Get the properties of a buffer resource.
\t\nDescribes a buffer resource.
\t\nThis structure is used by
In addition to this structure, there is also a derived structure in D3D11.h (CD3D11_BUFFER_DESC) which behaves like an inherited class to help create a buffer description.
If the bind flag is
Size of the buffer in bytes.
Identify how the buffer is expected to be read from and written to. Frequency of update is a key factor. The most common value is typically
Identify how the buffer will be bound to the pipeline. Flags (see
CPU access flags (see
Miscellaneous flags (see
The size of the structure (in bytes) when it represents a structured buffer.
This interface encapsulates an HLSL class.
\t\nThis interface is created by calling
Gets the
For more information about using the
Gets a description of the current HLSL class.
\t\nA reference to a
For more information about using the
An instance is not restricted to being used for a single type in a single shader. An instance is flexible and can be used for any shader that used the same type name or instance name when the instance was generated.
An instance does not replace the importance of reflection for a particular shader since a gotten instance will not know its slot location and a created instance only specifies a type name.
\t\nGets the instance name of the current HLSL class.
\t\nThe instance name of the current HLSL class.
The length of the pInstanceName parameter.
GetInstanceName will return a valid name only for instances acquired using
For more information about using the
Gets the type of the current HLSL class.
\t\nType of the current HLSL class.
The length of the pTypeName parameter.
GetTypeName will return a valid name only for instances acquired using
For more information about using the
Gets the
For more information about using the
Gets a description of the current HLSL class.
\t\nFor more information about using the
An instance is not restricted to being used for a single type in a single shader. An instance is flexible and can be used for any shader that used the same type name or instance name when the instance was generated.
An instance does not replace the importance of reflection for a particular shader since a gotten instance will not know its slot location and a created instance only specifies a type name.
\t\nThis interface encapsulates an HLSL dynamic linkage.
\t\nA class linkage object can hold up to 64K gotten instances. A gotten instance is a handle that references a variable name in any shader that is created with that linkage object. When you create a shader with a class linkage object, the runtime gathers these instances and stores them in the class linkage object. For more information about how a class linkage object is used, see Storing Variables and Types for Shaders to Share.
An
Gets the class-instance object that represents the specified HLSL class.
\t\nThe name of a class for which to get the class instance.
The index of the class instance.
The address of a reference to an
For more information about using the
A class instance must have at least 1 data member in order to be available for the runtime to use with
Initializes a class-instance object that represents an HLSL class instance.
\t\nThe type name of a class to initialize.
Identifies the constant buffer that contains the class data.
The four-component vector offset from the start of the constant buffer where the class data will begin. Consequently, this is not a byte offset.
The texture slot for the first texture; there may be multiple textures following the offset.
The sampler slot for the first sampler; there may be multiple samplers following the offset.
The address of a reference to an
Returns
Instances can be created (or gotten) before or after a shader is created. Use the same shader linkage object to acquire a class instance and create the shader the instance is going to be used in.
For more information about using the
A compute-shader interface manages an executable program (a compute shader) that controls the compute-shader stage.
\t\nThe compute-shader interface has no methods; use HLSL to implement your shader functionality. All shaders are implemented from a common set of features referred to as the common-shader core..
To create a compute-shader interface, call
This interface is defined in D3D11.h.
\t\nDescribes depth-stencil state.
\t\nDepth-stencil state controls how depth-stencil testing is performed by the output-merger stage.
The following table shows the default values of depth-stencil states.
| State | Default Value |
|---|---|
| DepthEnable | TRUE |
| DepthWriteMask | |
| DepthFunc | |
| StencilEnable | |
| StencilReadMask | D3D11_DEFAULT_STENCIL_READ_MASK |
| StencilWriteMask | D3D11_DEFAULT_STENCIL_WRITE_MASK |
| FrontFace.StencilFunc and BackFace.StencilFunc | |
| FrontFace.StencilDepthFailOp and BackFace.StencilDepthFailOp | |
| FrontFace.StencilPassOp and BackFace.StencilPassOp | |
| FrontFace.StencilFailOp and BackFace.StencilFailOp |
?
The formats that support stenciling are
Enable depth testing.
Identify a portion of the depth-stencil buffer that can be modified by depth data (see
A function that compares depth data against existing depth data. The function options are listed in
Enable stencil testing.
Identify a portion of the depth-stencil buffer for reading stencil data.
Identify a portion of the depth-stencil buffer for writing stencil data.
Identify how to use the results of the depth test and the stencil test for pixels whose surface normal is facing towards the camera (see
Identify how to use the results of the depth test and the stencil test for pixels whose surface normal is facing away from the camera (see
Describes rasterizer state.
\t\nRasterizer state defines the behavior of the rasterizer stage; to set rasterizer state, call
These are the default values for rasterizer state.
| State | Default Value |
|---|---|
| FillMode | Solid |
| CullMode | Back |
| FrontCounterClockwise | |
| DepthBias | 0 |
| SlopeScaledDepthBias | 0.0f |
| DepthBiasClamp | 0.0f |
| DepthClipEnable | TRUE |
| ScissorEnable | |
| MultisampleEnable | |
| AntialiasedLineEnable |
?
\t\nDetermines the fill mode to use when rendering (see
Indicates triangles facing the specified direction are not drawn (see
Determines if a triangle is front- or back-facing. If this parameter is true, then a triangle will be considered front-facing if its vertices are counter-clockwise on the render target and considered back-facing if they are clockwise. If this parameter is false then the opposite is true.
Depth value added to a given pixel.
Maximum depth bias of a pixel.
Scalar on a given pixel's slope.
Enable clipping based on distance.
The hardware always performs x and y clipping of rasterized coordinates. When DepthClipEnable is set to the default?TRUE, the hardware also clips the z value (that is, the hardware performs the last step of the following algorithm).\t\n
0 < w\t\n -w <= x <= w (or arbitrarily wider range if implementation uses a guard band to reduce clipping burden)\t\n -w <= y <= w (or arbitrarily wider range if implementation uses a guard band to reduce clipping burden)\t\n 0 <= z <= w\t\n When you set DepthClipEnable to
Enable scissor-rectangle culling. All pixels ouside an active scissor rectangle are culled.
Enable multisample antialiasing.
Enable line antialiasing; only applies if doing line drawing and MultisampleEnable is false.
This interface encapsulates methods for measuring GPU performance.
\t\nA counter can be created with
This is a derived class of
Counter data is gathered by issuing an
Counters are best suited for profiling.
For a list of the types of performance counters, see
This interface encapsulates methods for retrieving data from the GPU asynchronously.
\t\nThere are three types of asynchronous interfaces, all of which inherit this interface:
Get the size of the data (in bytes) that is output when calling
Size of the data (in bytes) that is output when calling GetData.
Get the size of the data (in bytes) that is output when calling
Get a counter description.
\t\nPointer to a counter description (see
Get a counter description.
\t\nGet the swap chain that the runtime will use for automatically calling
The swap chain retrieved by this method will only be used if
Set a bit field of flags that will turn debug features on and off.
\t\nA combination of feature-mask flags that are combined by using a bitwise OR operation. If a flag is present, that feature will be set to on, otherwise the feature will be set to off. For descriptions of the feature-mask flags, see Remarks.
This method returns one of the Direct3D 11 Return Codes.
Setting one of the following feature-mask flags will cause a rendering-operation method (listed below) to do some extra task when called.
| Application will wait for the GPU to finish processing the rendering operation before continuing. | |
| Runtime will additionally call | |
| Runtime will call |
?
These feature-mask flags apply to the following rendering-operation methods:
By setting one of the following feature-mask flags, you can control the behavior of the IDXGIDevice2::OfferResources and IDXGIDevice2::ReclaimResources methods to aid in testing and debugging.
Note??These flags are supported by the Direct3D 11.1 runtime, which is available starting with Windows Developer Preview.
| D3D11_DEBUG_FEATURE_ALWAYS_DISCARD_OFFERED_RESOURCE (0x8) | When you call IDXGIDevice2::OfferResources to offer resources while this flag is enabled, their content is always discarded. Use this flag to test code paths that regenerate resource content on reclaim. You cannot use this flag in combination with D3D11_DEBUG_FEATURE_NEVER_DISCARD_OFFERED_RESOURCE. |
| D3D11_DEBUG_FEATURE_NEVER_DISCARD_OFFERED_RESOURCE (0x10) | When you call IDXGIDevice2::OfferResources to offer resources while this flag is enabled, their content is never discarded. Use this flag to test code paths that do not need to regenerate resource content on reclaim. You cannot use this flag in combination with D3D11_DEBUG_FEATURE_ALWAYS_DISCARD_OFFERED_RESOURCE. |
?
The behavior of the IDXGIDevice2::OfferResources and IDXGIDevice2::ReclaimResources methods depends on system-wide memory pressure. Therefore, the scenario where content is lost and must be regenerated is uncommon for most applications. The preceding new options in the Direct3D debug layer let you simulate that scenario consistently and test code paths.
The following flag is supported by the Direct3D 11.1 runtime.
| D3D11_DEBUG_FEATURE_AVOID_BEHAVIOR_CHANGING_DEBUG_AIDS (0x40) | Disables the following default debugging behavior. |
?
When the debug layer is enabled, it performs certain actions to reveal application problems. By setting the D3D11_DEBUG_FEATURE_AVOID_BEHAVIOR_CHANGING_DEBUG_AIDS feature-mask flag, you can enable the debug layer without getting the following default debugging behavior:
Get a bitfield of flags that indicates which debug features are on or off.
\t\nMask of feature-mask flags bitwise ORed together. If a flag is present, then that feature will be set to on, otherwise the feature will be set to off. See
Set the number of milliseconds to sleep after
This method returns one of the following Direct3D 11 Return Codes.
The application will only sleep if
Get the number of milliseconds to sleep after
Number of milliseconds to sleep after Present is called.
Value is set with
Set a swap chain that the runtime will use for automatically calling
This method returns one of the following Direct3D 11 Return Codes.
The swap chain set by this method will only be used if
Get the swap chain that the runtime will use for automatically calling
This method returns one of the following Direct3D 11 Return Codes.
The swap chain retrieved by this method will only be used if
Check to see if the draw pipeline state is valid.
\t\nA reference to the
This method returns one of the following Direct3D 11 Return Codes.
Use validate prior to calling a draw method (for example,
Report information about a device object's lifetime.
\t\nA value from the
This method returns one of the following Direct3D 11 Return Codes.
ReportLiveDeviceObjects uses the value in Flags to determine the amount of information to report about a device object's lifetime.
\t\nVerifies whether the dispatch pipeline state is valid.
\t\nA reference to the
This method returns one of the return codes described in the topic Direct3D 11 Return Codes.
Use this method before you call a dispatch method (for example,
Get or sets the number of milliseconds to sleep after
Value is set with
Get or sets the swap chain that the runtime will use for automatically calling
The swap chain retrieved by this method will only be used if
The depth-stencil-state interface holds a description for depth-stencil state that you can bind to the output-merger stage.
\t\nTo create a depth-stencil-state object, call
Gets the description for depth-stencil state that you used to create the depth-stencil-state object.
\t\nA reference to a
You use the description for depth-stencil state in a call to the
Gets the description for depth-stencil state that you used to create the depth-stencil-state object.
\t\nYou use the description for depth-stencil state in a call to the
A depth-stencil-view interface accesses a texture resource during depth-stencil testing.
\t\nTo create a depth-stencil view, call
To bind a depth-stencil view to the pipeline, call
A view interface specifies the parts of a resource the pipeline can access during rendering.
\t\nA view interface is the base interface for all views. There are four types of views; a depth-stencil view, a render-target view, a shader-resource view, and an unordered-access view.
All resources must be bound to the pipeline before they can be accessed.
Get the resource that is accessed through this view.
\t\nAddress of a reference to the resource that is accessed through this view. (See
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.
\t\nGet the resource that is accessed through this view.
\t\nThis function increments the reference count of the resource by one, so it is necessary to call Dispose 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.
\t\nGet the resource that is accessed through this view.
\t\nThis 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.
\t\nGet the depth-stencil view.
\t\nPointer to a depth-stencil-view description (see
Get the depth-stencil view.
\t\nThe device interface represents a virtual adapter; it is used to create resources.
\t\nA device is created using
IDXGIResource* pOtherResource(NULL);\n hr = pOtherDeviceResource->QueryInterface( __uuidof(IDXGIResource), (void**)&pOtherResource );\n HANDLE sharedHandle;\n pOtherResource->GetSharedHandle(&sharedHandle); \n 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.\n sharedHandle = NULL; // must be set to NULL to create, can use a valid handle here to open in D3D9\n pDevice9->CreateTexture(..., pTex2D_9, &sharedHandle);\n ...\n pDevice10->OpenSharedResource(sharedHandle, __uuidof(ID3D10Resource), (void**)(&tempResource10));\n tempResource10->QueryInterface(__uuidof(ID3D10Texture2D), (void**)(&pTex2D_10));\n tempResource10->Release();\n // now use pTex2D_10 with pDevice10 \n 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 Creates a buffer (vertex buffer, index buffer, or shader-constant buffer).
\t\nA reference to a
A reference to a
Address of a reference to the
This method returns E_OUTOFMEMORY if there is insufficient memory to create the buffer. See Direct3D 11 Return Codes for other possible return values.
For example code, see How to: Create a Vertex Buffer, How to: Create an Index Buffer or How to: Create a Constant Buffer.
The Direct3D 11.1 runtime, which is available on Windows Developer Preview and later operating systems, provides the following new functionality for CreateBuffer.
You can create a constant buffer that is larger than the maximum constant buffer size that a shader can access (4096 32-bit*4-component constants ? 64KB). When you bind the constant buffer to the pipeline (for example, via PSSetConstantBuffers or PSSetConstantBuffers1), you can define a range of the buffer that the shader can access that fits within the 4096 constant limit.
The runtime will emulate this feature for feature level 9.1, 9.2, and 9.3; therefore, this feature is supported for feature level 9.1, 9.2, and 9.3. This feature is always available on new drivers for feature level 10 and higher. On existing drivers that are implemented to feature level 10 and higher, a call to CreateBuffer to request a constant buffer that is larger than 4096 fails.
\t\nCreates an array of 1D textures.
\t\nIf the method succeeds, the return code is
CreateTexture1D creates a 1D texture resource, which can contain a number of 1D subresources. 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 can supply the data initially as an array of
For a 32 width texture with a full mipmap chain, the pInitialData array has the following 6 elements:\t\n
Create an array of 2D textures.
\t\nIf the method succeeds, the return code is
CreateTexture2D creates a 2D texture resource, which can contain a number of 2D subresources. 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 can supply the data initially as an array of
For a 32 x 32 texture with a full mipmap chain, the pInitialData array has the following 6 elements:\t\n
Create a single 3D texture.
\t\nIf the method succeeds, the return code is
CreateTexture3D creates a 3D texture resource, which can contain a number of 3D subresources. 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 can supply the data initially as an array of
Each element of pInitialData provides all of the slices that are defined for a given miplevel. For example, for a 32 x 32 x 4 volume texture with a full mipmap chain, the array has the following 6 elements:
Create a shader-resource view for accessing data in a resource.
\t\nPointer to the resource that will serve as input to a shader. This resource must have been created with the
Pointer to a shader-resource view description (see
Address of a reference to an
This method returns one of the following Direct3D 11 Return Codes.
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:
Because a view is fully typed, this means that typeless resources become fully typed when bound to the pipeline.
Note??To successfully create a shader-resource view from a typeless buffer (for example,
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, allows you to use CreateShaderResourceView for the following new purpose.
You can create shader-resource views of video resources so that Direct3D shaders can process those shader-resource views. These video resources are either Texture2D or Texture2DArray. The value in the ViewDimension member of the
The runtime read+write conflict prevention logic (which stops a resource from being bound as an SRV and RTV or UAV at the same time) treats views of different parts of the same video surface as conflicting for simplicity. Therefore, the runtime does not allow an application to read from luma while the application simultaneously renders to chroma in the same surface even though the hardware might allow these simultaneous operations.
\t\nCreates a view for accessing an unordered access resource.
\t\nThis method returns one of the Direct3D 11 Return Codes.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, allows you to use CreateUnorderedAccessView for the following new purpose.
You can create unordered-access views of video resources so that Direct3D shaders can process those unordered-access views. These video resources are either Texture2D or Texture2DArray. The value in the ViewDimension member of the
The runtime read+write conflict prevention logic (which stops a resource from being bound as an SRV and RTV or UAV at the same time) treats views of different parts of the same video surface as conflicting for simplicity. Therefore, the runtime does not allow an application to read from luma while the application simultaneously renders to chroma in the same surface even though the hardware might allow these simultaneous operations.
\t\nCreates a render-target view for accessing resource data.
\t\nPointer to a
Pointer to a
Address of a reference to an
This method returns one of the Direct3D 11 Return Codes.
A render-target view can be bound to the output-merger stage by calling
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, allows you to use CreateRenderTargetView for the following new purpose.
You can create render-target views of video resources so that Direct3D shaders can process those render-target views. These video resources are either Texture2D or Texture2DArray. The value in the ViewDimension member of the
The runtime read+write conflict prevention logic (which stops a resource from being bound as an SRV and RTV or UAV at the same time) treats views of different parts of the same video surface as conflicting for simplicity. Therefore, the runtime does not allow an application to read from luma while the application simultaneously renders to chroma in the same surface even though the hardware might allow these simultaneous operations.
\t\nCreate a depth-stencil view for accessing resource data.
\t\nPointer to the resource that will serve as the depth-stencil surface. This resource must have been created with the
Pointer to a depth-stencil-view description (see
Address of a reference to an
This method returns one of the following Direct3D 11 Return Codes.
A depth-stencil view can be bound to the output-merger stage by calling
Create an input-layout object to describe the input-buffer data for the input-assembler stage.
\t\nAn array of the input-assembler stage input data types; each type is described by an element description (see
The number of input-data types in the array of input-elements.
A reference to the compiled shader. The compiled shader code contains a input signature which is validated against the array of elements. See remarks.
Size of the compiled shader.
A reference to the input-layout object created (see
If the method succeeds, the return code is
After creating an input layout object, it must be bound to the input-assembler stage before calling a draw API.
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.
\t\nCreate a vertex-shader object from a compiled shader.
\t\nA reference to the compiled shader.
Size of the compiled vertex shader.
A reference to a class linkage interface (see
Address of a reference to a
This method returns one of the Direct3D 11 Return Codes.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, provides the following new functionality for CreateVertexShader.
The following shader model 5.0 instructions are available to just pixel shaders and compute shaders in the Direct3D 11.0 runtime. For the Direct3D 11.1 runtime, because unordered access views (UAV) are available at all shader stages, you can use these instructions in all shader stages.
Therefore, if you use the following shader model 5.0 instructions in a vertex shader, you can successfully pass the compiled vertex shader to pShaderBytecode. That is, the call to CreateVertexShader succeeds.
If you pass a compiled shader to pShaderBytecode that uses any of the following instructions on a device that doesn?t support UAVs at every shader stage (including existing drivers that are not implemented to support UAVs at every shader stage), CreateVertexShader fails. CreateVertexShader also fails if the shader tries to use a UAV slot beyond the set of UAV slots that the hardware supports.
Create a geometry shader.
\t\nA reference to the compiled shader.
Size of the compiled geometry shader.
A reference to a class linkage interface (see
Address of a reference to a
This method returns one of the following Direct3D 11 Return Codes.
After it is created, the shader can be set to the device by calling
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, provides the following new functionality for CreateGeometryShader.
The following shader model 5.0 instructions are available to just pixel shaders and compute shaders in the Direct3D 11.0 runtime. For the Direct3D 11.1 runtime, because unordered access views (UAV) are available at all shader stages, you can use these instructions in all shader stages.
Therefore, if you use the following shader model 5.0 instructions in a geometry shader, you can successfully pass the compiled geometry shader to pShaderBytecode. That is, the call to CreateGeometryShader succeeds.
If you pass a compiled shader to pShaderBytecode that uses any of the following instructions on a device that doesn?t support UAVs at every shader stage (including existing drivers that are not implemented to support UAVs at every shader stage), CreateGeometryShader fails. CreateGeometryShader also fails if the shader tries to use a UAV slot beyond the set of UAV slots that the hardware supports.
Creates a geometry shader that can write to streaming output buffers.
\t\nA reference to the compiled geometry shader for a standard geometry shader plus stream output. For info on how to get this reference, see Getting a Pointer to a Compiled Shader.
To create the stream output without using a geometry shader, pass a reference to the output signature for the prior stage. To obtain this output signature, call the
Size of the compiled geometry shader.
Pointer to a
The number of entries in the stream output declaration ( ranges from 0 to D3D11_SO_STREAM_COUNT * D3D11_SO_OUTPUT_COMPONENT_COUNT ).
An array of buffer strides; each stride is the size of an element for that buffer.
The number of strides (or buffers) in pBufferStrides (ranges from 0 to D3D11_SO_BUFFER_SLOT_COUNT).
The index number of the stream to be sent to the rasterizer stage (ranges from 0 to D3D11_SO_STREAM_COUNT - 1). Set to D3D11_SO_NO_RASTERIZED_STREAM if no stream is to be rasterized.
A reference to a class linkage interface (see
Address of a reference to an
This method returns one of the Direct3D 11 Return Codes.
For more info about using CreateGeometryShaderWithStreamOutput, see Create a Geometry-Shader Object with Stream Output.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, provides the following new functionality for CreateGeometryShaderWithStreamOutput.
The following shader model 5.0 instructions are available to just pixel shaders and compute shaders in the Direct3D 11.0 runtime. For the Direct3D 11.1 runtime, because unordered access views (UAV) are available at all shader stages, you can use these instructions in all shader stages.
Therefore, if you use the following shader model 5.0 instructions in a geometry shader, you can successfully pass the compiled geometry shader to pShaderBytecode. That is, the call to CreateGeometryShaderWithStreamOutput succeeds.
If you pass a compiled shader to pShaderBytecode that uses any of the following instructions on a device that doesn?t support UAVs at every shader stage (including existing drivers that are not implemented to support UAVs at every shader stage), CreateGeometryShaderWithStreamOutput fails. CreateGeometryShaderWithStreamOutput also fails if the shader tries to use a UAV slot beyond the set of UAV slots that the hardware supports.
Create a pixel shader.
\t\nA reference to the compiled shader.
Size of the compiled pixel shader.
A reference to a class linkage interface (see
Address of a reference to a
This method returns one of the following Direct3D 11 Return Codes.
After creating the pixel shader, you can set it to the device using
Create a hull shader.
\t\nThis method returns one of the Direct3D 11 Return Codes.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, provides the following new functionality for CreateHullShader.
The following shader model 5.0 instructions are available to just pixel shaders and compute shaders in the Direct3D 11.0 runtime. For the Direct3D 11.1 runtime, because unordered access views (UAV) are available at all shader stages, you can use these instructions in all shader stages.
Therefore, if you use the following shader model 5.0 instructions in a hull shader, you can successfully pass the compiled hull shader to pShaderBytecode. That is, the call to CreateHullShader succeeds.
If you pass a compiled shader to pShaderBytecode that uses any of the following instructions on a device that doesn?t support UAVs at every shader stage (including existing drivers that are not implemented to support UAVs at every shader stage), CreateHullShader fails. CreateHullShader also fails if the shader tries to use a UAV slot beyond the set of UAV slots that the hardware supports.
Create a domain shader .
\t\nThis method returns one of the following Direct3D 11 Return Codes.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, provides the following new functionality for CreateDomainShader.
The following shader model 5.0 instructions are available to just pixel shaders and compute shaders in the Direct3D 11.0 runtime. For the Direct3D 11.1 runtime, because unordered access views (UAV) are available at all shader stages, you can use these instructions in all shader stages.
Therefore, if you use the following shader model 5.0 instructions in a domain shader, you can successfully pass the compiled domain shader to pShaderBytecode. That is, the call to CreateDomainShader succeeds.
If you pass a compiled shader to pShaderBytecode that uses any of the following instructions on a device that doesn?t support UAVs at every shader stage (including existing drivers that are not implemented to support UAVs at every shader stage), CreateDomainShader fails. CreateDomainShader also fails if the shader tries to use a UAV slot beyond the set of UAV slots that the hardware supports.
Create a compute shader.
\t\nThis method returns E_OUTOFMEMORY if there is insufficient memory to create the compute shader. See Direct3D 11 Return Codes for other possible return values.
For an example, see How To: Create a Compute Shader and HDRToneMappingCS11 Sample.
\t\nCreates class linkage libraries to enable dynamic shader linkage.
\t\nA reference to a class-linkage interface reference (see
This method returns one of the following Direct3D 11 Return Codes.
The
Create a blend-state object that encapsules blend state for the output-merger stage.
\t\nPointer to a blend-state description (see
Address of a reference to the blend-state object created (see
This method returns E_OUTOFMEMORY if there is insufficient memory to create the blend-state object. See Direct3D 11 Return Codes for other possible return values.
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.
\t\nCreate a depth-stencil state object that encapsulates depth-stencil test information for the output-merger stage.
\t\nPointer to a depth-stencil state description (see
Address of a reference to the depth-stencil state object created (see
This method returns one of the following Direct3D 11 Return Codes.
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 interface with the same state as an existing interface, the same interface will be returned and the total number of unique depth-stencil state objects will stay the same.
\t\nCreate a rasterizer state object that tells the rasterizer stage how to behave.
\t\nPointer to a rasterizer state description (see
Address of a reference to the rasterizer state object created (see
This method returns E_OUTOFMEMORY if there is insufficient memory to create the compute shader. See Direct3D 11 Return Codes for other possible return values.
4096 unique rasterizer state objects can be created on a device at a time.
If an application attempts to create a rasterizer-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique rasterizer state objects will stay the same.
\t\nCreate a sampler-state object that encapsulates sampling information for a texture.
\t\nPointer to a sampler state description (see
Address of a reference to the sampler state object created (see
This method returns one of the following Direct3D 11 Return Codes.
4096 unique sampler state objects can be created on a device at a time.
If an application attempts to create a sampler-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique sampler state objects will stay the same.
\t\nThis interface encapsulates methods for querying information from the GPU.
\t\nPointer to a query description (see
Address of a reference to the query object created (see
This method returns E_OUTOFMEMORY if there is insufficient memory to create the query object. See Direct3D 11 Return Codes for other possible return values.
Creates a predicate.
\t\nPointer to a query description where the type of query must be a
Address of a reference to a predicate (see
This method returns one of the following Direct3D 11 Return Codes.
Create a counter object for measuring GPU performance.
\t\nPointer to a counter description (see
Address of a reference to a counter (see
If this function succeeds, it will return
E_INVALIDARG is returned whenever an out-of-range well-known or device-dependent counter is requested, or when the simulataneously active counters have been exhausted.
Creates a deferred context for play back of command lists.
\t\nReserved for future use. Pass 0.
Upon completion of the method, the passed reference to an
Returns
A deferred context is a thread-safe context that you can use to record graphics commands on a thread other than the main rendering thread. Using a deferred context, you can record graphics commands into a command list that is encapsulated by the
You can create multiple deferred contexts.
Note??If you use the
For more information about deferred contexts, see Immediate and Deferred Rendering.
\t\nGive a device access to a shared resource created on a different device.
\t\nA resource handle. See remarks.
The globally unique identifier (
Address of a reference to the resource we are gaining access to.
This method returns one of the following Direct3D 11 Return Codes.
The REFIID, or
The unique handle of the resource is obtained differently depending on the type of device that originally created the resource.
To share a resource between two Direct3D 11 devices the resource must have been created with the
The REFIID, or
When sharing a resource between two Direct3D 10/11 devices the unique handle of the resource can be obtained by querying the resource for the
* pOtherResource(null );\t\n hr = pOtherDeviceResource->QueryInterface( __uuidof(), (void**)&pOtherResource );\t\n HANDLE sharedHandle;\t\n 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 11 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 \t\n pDevice9->CreateTexture(..., pTex2D_9, &sharedHandle); \t\n ... \t\n pDevice11->OpenSharedResource(sharedHandle, __uuidof(), (void**)(&tempResource11)); \t\n tempResource11->QueryInterface(__uuidof(), (void**)(&pTex2D_11)); \t\n tempResource11->Release(); \t\n // now use pTex2D_11 with pDevice11 Textures being shared from D3D9 to D3D11 have the following restrictions.
If a shared texture is updated on one device
Get the support of a given format on the installed video device.
\t\nA
A bitfield of
Get the number of quality levels available during multisampling.
\t\nThe texture format. See
The number of samples during multisampling.
Number of quality levels supported by the adapter. See remarks.
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 number of quality levels is defined by
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.
Note that FEATURE_LEVEL_10_1 devices are required to support 4x MSAA for all render targets except R32G32B32A32 and R32G32B32. FEATURE_LEVEL_11_0 devices are required to support 4x MSAA for all render target formats, and 8x MSAA for all render target formats except R32G32B32A32 formats.
\t\nGet a counter's information.
\t\nGet the type, name, units of measure, and a description of an existing counter.
\t\nPointer to a counter description (see
Pointer to the data type of a counter (see
Pointer to the number of hardware counters that are needed for this counter type to be created. All instances of the same counter type use the same hardware counters.
String to be filled with a brief name for the counter. May be
Length of the string returned to szName. Can be
Name of the units a counter measures, provided the memory the reference points to has enough room to hold the string. Can be
Length of the string returned to szUnits. Can be
A description of the counter, provided the memory the reference points to has enough room to hold the string. Can be
Length of the string returned to szDescription. Can be
This method returns one of the following Direct3D 11 Return Codes.
Length parameters can be
Gets information about the features that are supported by the current graphics driver.
\t\nA member of the
Upon completion of the method, the passed structure is filled with data that describes the feature support.
The size of the structure passed to the pFeatureSupportData parameter.
Returns
To query for multi-threading support, pass the
Calling CheckFeatureSupport with Feature set to
Get application-defined data from a device.
\t\nGuid associated with the data.
A reference to a variable that on input contains the size, in bytes, of the buffer that pData points to, and on output contains the size, in bytes, of the amount of data that GetPrivateData retrieved.
A reference to a buffer that GetPrivateData fills with data from the device if pDataSize points to a value that specifies a buffer large enough to hold the data.
This method returns one of the codes described in the topic Direct3D 11 Return Codes.
Set data to a device and associate that data with a guid.
\t\nGuid associated with the data.
Size of the data.
Pointer to the data to be stored with this device. If pData is
This method returns one of the following Direct3D 11 Return Codes.
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
The debug layer reports memory leaks by outputting a list of object interface references along with their friendly names. The default friendly name is \"<unnamed>\". You can set the friendly name so that you can determine if the corresponding object interface reference caused the leak. To set the friendly name, use the SetPrivateData method and the
static const char c_szName[] = \"My name\";\t\n hr = pContext->SetPrivateData( , sizeof( c_szName ) - 1, c_szName );\t\n Associate an
Guid associated with the interface.
Pointer to an
This method returns one of the following Direct3D 11 Return Codes.
Gets the feature level of the hardware device.
\t\nA member of the
Feature levels determine the capabilities of your device.
\t\nGet the flags used during the call to create the device with
A bitfield containing the flags used to create the device. See
Get the reason why the device was removed.
\t\nPossible return values include:
For more detail on these return codes, see DXGI_ERROR.
Gets an immediate context which can record command lists.
\t\nUpon completion of the method, the passed reference to an
The GetImmediateContext method returns an
The GetImmediateContext method increments the reference count of the immediate context by one. Therefore, you must call Release on the returned interface reference when you are done with it to avoid a memory leak.
\t\nGet the exception-mode flags.
\t\nA value that contains one or more exception flags; each flag specifies a condition which will cause an exception to be raised. The flags are listed in D3D11_RAISE_FLAG. A default value of 0 means there are no flags.
This method returns one of the following Direct3D 11 Return Codes.
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.
\t\nGet the exception-mode flags.
\t\nA value that contains one or more exception flags; each flag specifies a condition which will cause an exception to be raised. The flags are listed in D3D11_RAISE_FLAG. A default value of 0 means there are no flags.
An exception-mode flag is used to elevate an error condition to a non-continuable exception.
\t\nGets the feature level of the hardware device.
\t\nFeature levels determine the capabilities of your device.
\t\nGet the flags used during the call to create the device with
Get the reason why the device was removed.
\t\nGets an immediate context which can record command lists.
\t\nThe GetImmediateContext method returns an
The GetImmediateContext method increments the reference count of the immediate context by one. Therefore, you must call Release on the returned interface reference when you are done with it to avoid a memory leak.
\t\nGet or sets the exception-mode flags.
\t\nAn exception-mode flag is used to elevate an error condition to a non-continuable exception.
\t\nThe
Set the target output buffers for the stream-output stage of the pipeline.
\t\nThe number of buffer to bind to the device. A maximum of four output buffers can be set. If less than four are defined by the call, the remaining buffer slots are set to
The array of output buffers (see
Array of offsets to the output buffers from ppSOTargets, one offset for each buffer. The offset values must be in bytes.
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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSet the target output buffers for the stream-output stage of the pipeline.
\t\nThe number of buffer to bind to the device. A maximum of four output buffers can be set. If less than four are defined by the call, the remaining buffer slots are set to
The array of output buffers (see
Array of offsets to the output buffers from ppSOTargets, one offset for each buffer. The offset values must be in bytes.
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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nGet the target output buffers for the stream-output stage of the pipeline.
\t\nNumber of buffers to get.
An array of output buffers (see
A maximum of four output buffers can be retrieved.
The offsets to the output buffers pointed to in the returned ppSOTargets array may be assumed to be -1 (append), as defined for use in
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.
\t\nThe
Bind an array of shader resources to the compute-shader stage.
\t\nIndex into the device's zero-based array to begin setting shader resources to (ranges from 0 to
Number of shader resources to set. Up to a maximum of 128 slots are available for shader resources(ranges from 0 to
Array of shader resource view interfaces to set to the device.
If an overlapping resource view is already bound to an output slot, such as a render target, then the method will fill the destination shader resource slot with
For information about creating shader-resource views, see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.\t\n
\t\nSets an array of views for an unordered resource.
\t\nIndex of the first element in the zero-based array to begin setting (ranges from 0 to D3D11_1_UAV_SLOT_COUNT - 1). D3D11_1_UAV_SLOT_COUNT is defined as 64.
Number of views to set (ranges from 0 to D3D11_1_UAV_SLOT_COUNT - StartSlot).
A reference to an array of
An array of append and consume buffer offsets. A value of -1 indicates to keep the current offset. Any other values set the hidden counter for that appendable and consumable UAV. pUAVInitialCounts is only relevant for UAVs that were created with either
Set a compute shader to the device.
\t\nPointer to a compute shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet a compute shader to the device.
\t\nPointer to a compute shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet an array of sampler states to the compute-shader stage.
\t\nIndex into the device's zero-based array to begin setting samplers to (ranges from 0 to
Number of samplers in the array. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (see
Any sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets the constant buffers used by the compute-shader stage.
\t\nIndex into the zero-based array to begin setting constant buffers to (ranges from 0 to
Number of buffers to set (ranges from 0 to
Array of constant buffers (see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, can bind a larger number of
If the application wants the shader to access other parts of the buffer, it must call the CSSetConstantBuffers1 method instead.
\t\nGet the compute-shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from (ranges from 0 to
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources (ranges from 0 to
Array of shader resource view interfaces to be returned 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.
\t\nGets an array of views for an unordered resource.
\t\nIndex of the first element in the zero-based array to return (ranges from 0 to
Number of views to get (ranges from 0 to
A reference to an array of interface references (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.
\t\nGet the compute shader currently set on the device.
\t\nAddress of a reference to a Compute shader (see
Pointer to an array of class instance interfaces (see
The number of class-instance elements in the array.
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.
\t\nGet an array of sampler state interfaces from the compute-shader stage.
\t\nIndex into a zero-based array to begin getting samplers from (ranges from 0 to
Number of samplers to get from a device context. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (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.
\t\nGet the constant buffers used by the compute-shader stage.
\t\nIndex into the device's zero-based array to begin retrieving constant buffers from (ranges from 0 to
Number of buffers to retrieve (ranges from 0 to
Array of constant buffer interface references (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.
\t\nThe
D3D11_BOX sourceRegion;\t\n sourceRegion.left = 120;\t\n sourceRegion.right = 200;\t\n sourceRegion.top = 100;\t\n sourceRegion.bottom = 220;\t\n sourceRegion.front = 0;\t\n sourceRegion.back = 1; pd3dDeviceContext->CopySubresourceRegion( pDestTexture, 0, 10, 20, 0, pSourceTexture, 0, &sourceRegion ); \t\n \t\n Notice, that for a 2D texture, front and back are set to 0 and 1 respectively. \t\n Draw indexed, non-instanced primitives.
\t\nNumber of indices to draw.
The location of the first index read by the GPU from the index buffer.
A value added to each index before reading a vertex from the vertex buffer.
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.
\t\nDraw non-indexed, non-instanced primitives.
\t\nNumber of vertices to draw.
Index of the first vertex, which is usually an offset in a vertex buffer; it could also be used as the first vertex id generated for a shader parameter marked with the SV_TargetId system-value semantic.
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.
\t\nGets a reference to the data contained in a subresource, and denies the GPU access to that subresource.
\t\nA reference to a
Index number of the subresource.
Specifies the CPU's read and write permissions for a resource. For possible values, see
Flag that specifies what the CPU should do when the GPU is busy. This flag is optional.
A reference to the mapped subresource (see
If you call Map on a deferred context, you can only pass
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, can map shader resource views (SRVs) of dynamic buffers with
Invalidate the reference to a resource and re-enable the GPU's access to that resource.
\t\nA reference to a
A subresource to be unmapped.
Draw indexed, instanced primitives.
\t\nNumber of indices read from the index buffer for each instance.
Number of instances to draw.
The location of the first index read by the GPU from the index buffer.
A value added to each index before reading a vertex from the vertex buffer.
A value added to each index before reading per-instance data from a vertex buffer.
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.
\t\nDraw non-indexed, instanced primitives.
\t\nNumber of vertices to draw.
Number of instances to draw.
Index of the first vertex.
A value added to each index before reading per-instance data from a vertex buffer.
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.
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).
\t\nMark the beginning of a series of commands.
\t\nA reference to an
Use
Mark the end of a series of commands.
\t\nA reference to an
Use
Get data from the graphics processing unit (GPU) asynchronously.
\t\nA reference to an
Address of memory that will receive the data. If
Size of the data to retrieve or 0. Must be 0 when pData is
Optional flags. Can be 0 or any combination of the flags enumerated by
This method returns one of the Direct3D 11 Return Codes. A return value of
Queries in a deferred context are limited to predicated drawing. That is, you cannot call
GetData retrieves the data that the runtime collected between calls to
If DataSize is 0, GetData is only used to check status.
An application gathers counter data by calling
Set a rendering predicate.
\t\nPointer to a predicate (see
If TRUE, rendering will be affected by when the predicate's conditions are met. If
The predicate must be in the \"issued\" or \"signaled\" state to be used for predication. While the predicate is set for predication, calls to
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
Draw geometry of an unknown size.
\t\nA draw API submits work to the rendering pipeline. This API submits work of an unknown size that was processed by the input assembler, vertex shader, and stream-output stages; the work may or may not have gone through the geometry-shader stage.
After data has been streamed out to stream-output 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,
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
Draw indexed, instanced, GPU-generated primitives.
\t\nA reference to an
Offset in pBufferForArgs to the start of the GPU generated primitives.
When an application creates a buffer that is associated with the
Draw instanced, GPU-generated primitives.
\t\nA reference to an
Offset in pBufferForArgs to the start of the GPU generated primitives.
When an application creates a buffer that is associated with the
Execute a command list from a thread group.
\t\nThe number of groups dispatched in the x direction. ThreadGroupCountX must be less than
The number of groups dispatched in the y direction. ThreadGroupCountY must be less than
The number of groups dispatched in the z direction. ThreadGroupCountZ must be less than
You call the Dispatch method to execute commands in a compute shader. A compute shader can be run on many threads in parallel, within a thread group. Index a particular thread, within a thread group using a 3D vector given by (x,y,z).
In the following illustration, assume a thread group with 50 threads where the size of the group is given by (5,5,2). A single thread is identified from a thread group with 50 threads in it, using the vector (4,1,1).
The following illustration shows the relationship between the parameters passed to
Execute a command list over one or more thread groups.
\t\nA reference to an
A byte-aligned offset between the start of the buffer and the arguments.
You call the DispatchIndirect method to execute commands in a compute shader.
When an application creates a buffer that is associated with the
Copy a region from a source resource to a destination resource.
\t\nA reference to the destination resource (see
Destination subresource index.
The x-coordinate of the upper left corner of the destination region.
The y-coordinate of the upper left corner of the destination region. For a 1D subresource, this must be zero.
The z-coordinate of the upper left corner of the destination region. For a 1D or 2D subresource, this must be zero.
A reference to the source resource (see
Source subresource index.
A reference to a 3D box (see
The source box must be within the size of the source resource. The destination offsets, (x, y, and z) allow the source box to be offset when writing into the destination resource; however, the dimensions of the source box and the offsets must be within the size of the resource.
If the resources are buffers, all coordinates are in bytes; if the resources are textures, all coordinates are in texels. D3D11CalcSubresource 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:
CopySubresourceRegion only supports copy; it does not support any stretch, color key, blend, or format conversions. An application that needs to copy an entire resource should use
CopySubresourceRegion 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. For more information about pipeline stalls, see performance considerations.
Note??If you use CopySubresourceRegion with a depth-stencil buffer or a multisampled resource, you must copy the whole subresource. In this situation, you must pass 0 to the DstX, DstY, and DstZ parameters and
The following code snippet copies a box (located at (120,100),(200,220)) from a source texture into a reqion (10,20),(90,140) in a destination texture.
sourceRegion;\t\n sourceRegion.left = 120;\t\n sourceRegion.right = 200;\t\n sourceRegion.top = 100;\t\n sourceRegion.bottom = 220;\t\n sourceRegion.front = 0;\t\n sourceRegion.back = 1; pd3dDeviceContext->CopySubresourceRegion( pDestTexture, 0, 10, 20, 0, pSourceTexture, 0, &sourceRegion );\t\n Notice, that for a 2D texture, front and back are set to 0 and 1 respectively.
\t\nCopy the entire contents of the source resource to the destination resource using the GPU.
\t\nA reference to the destination resource (see
A reference to the source resource (see
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:
You cannot use an Immutable resource as a destination. You can use a depth-stencil resource as either a source or a destination. Resources created with multisampling capability (see
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.
An application that only needs to copy a portion of the data in a resource should use
The CPU copies data from memory to a subresource created in non-mappable memory.
\t\nA reference to the destination resource (see
A zero-based index, that identifies the destination subresource. See D3D11CalcSubresource for more details.
A reference to a box that defines the portion of the destination subresource to copy the resource data into. Coordinates are in bytes for buffers and in texels for textures. If
A reference to the source data in memory.
The size of one row of the source data.
The size of one depth slice of source data.
For a shader-constant buffer; set pDstBox to
A resource cannot be used as a destination if:
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.
To better understand the source row pitch and source depth pitch parameters, the following illustration shows 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
To calculate the source row pitch and source depth pitch for a given resource, use the following formulas:
In the case of this example 3D volume texture where the size of each element is 16 bytes, the formulas are as follows:
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;\t\n destRegion.left = 120;\t\n destRegion.right = 200;\t\n destRegion.top = 100;\t\n destRegion.bottom = 220;\t\n destRegion.front = 0;\t\n destRegion.back = 1; pd3dDeviceContext->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );\t\n 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;\t\n destRegion.left = 120\t\n destRegion.right = 200;\t\n destRegion.top = 0;\t\n destRegion.bottom = 1;\t\n destRegion.front = 0;\t\n destRegion.back = 1; pd3dDeviceContext->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );\t\n If your application calls UpdateSubresource on a deferred context with a destination box?to which pDstBox points?that has a non-(0,0,0) offset, and if the driver does not support command lists, UpdateSubresource inappropriately applies that destination-box offset to the pSrcData parameter. To work around this behavior, use the following code:
UpdateSubresource_Workaround( *pDevice, *pDeviceContext, *pDstResource, UINT dstSubresource, const *pDstBox, const void *pSrcData, UINT srcBytesPerElement, UINT srcRowPitch, UINT srcDepthPitch, bool* pDidWorkAround )\t\n { hr = ; bool needWorkaround = false; contextType = pDeviceContext->GetType(); if( pDstBox && ( == contextType) ) { threadingCaps = { , }; hr = pDevice->CheckFeatureSupport( , &threadingCaps, sizeof(threadingCaps) ); if( SUCCEEDED(hr) ) { if( !threadingCaps.DriverCommandLists ) { needWorkaround = true; } } } const void* pAdjustedSrcData = pSrcData; if( needWorkaround ) { alignedBox = *pDstBox; // convert from pixels to blocks if( m_bBC ) { alignedBox.left /= 4; alignedBox.right /= 4; alignedBox.top /= 4; alignedBox.bottom /= 4; } pAdjustedSrcData = ((const BYTE*)pSrcData) - (alignedBox.front * srcDepthPitch) - (alignedBox.top * srcRowPitch) - (alignedBox.left * srcBytesPerElement); } pDeviceContext->UpdateSubresource( pDstResource, dstSubresource, pDstBox, pAdjustedSrcData, srcRowPitch, srcDepthPitch ); if( pDidWorkAround ) { *pDidWorkAround = needWorkaround; } return hr;\t\n }\t\n Copies data from a buffer holding variable length data.
\t\nPointer to
Offset from the start of pDstBuffer to write 32-bit UINT structure (vertex) count from pSrcView.
Pointer to an
Set all the elements in a render target to one value.
\t\nPointer to the rendertarget.
A 4-component array that represents the color to fill the render target with.
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.
| Differences between Direct3D 9 and Direct3D 11/10: Unlike Direct3D 9, the full extent of the resource view is always cleared. Viewport and scissor settings are not applied. |
?
\t\nClears an unordered access resource with bit-precise values.
\t\nThis API copies the lower ni bits from each array element i to the corresponding channel, where ni is the number of bits in the ith channel of the resource format (for example, R8G8B8_FLOAT has 8 bits for the first 3 channels). This works on any UAV with no format conversion. For a raw or structured buffer view, only the first array element value is used.
\t\nClears an unordered access resource with a float value.
\t\nThis API works on FLOAT, UNORM, and SNORM unordered access views (UAVs), with format conversion from FLOAT to *NORM where appropriate. On other UAVs, the operation is invalid and the call will not reach the driver.
\t\nClears the depth-stencil resource.
\t\nPointer to the depth stencil to be cleared.
Identify the type of data to clear (see
Clear the depth buffer with this value. This value will be clamped between 0 and 1.
Clear the stencil buffer with this value.
| Differences between Direct3D 9 and Direct3D 11/10: Unlike Direct3D 9, the full extent of the resource view is always cleared. Viewport and scissor settings are not applied. |
?
\t\nGenerate mipmaps for the given shader resource.
\t\nPointer to an
GenerateMips may be called on any shader-resource view 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
All video adapters support generating mipmaps if you are using any of the following formats:
\t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n \t\n Some video adapters support generating mipmaps if you are using this format:
\t\n For all other unsupported formats, this method will silently fail.
\t\nSets the minimum level-of-detail (LOD) for a resource.
\t\nA reference to an
The level-of-detail, which ranges between 0 and the maximum number of mipmap levels of the resource. For example, the maximum number of mipmap levels of a 1D texture is specified in the MipLevels member of the
To use a resource with SetResourceMinLOD, you must set the
For Direct3D 10 and Direct3D 10.1, when sampling from a texture resource in a shader, the sampler can define a minimum LOD clamp to force sampling from less detailed mip levels. For Direct3D 11, this functionality is extended from the sampler to the entire resource. Therefore, the application can specify the highest-resolution mip level of a resource that is available for access. This restricts the set of mip levels that are required to be resident in GPU memory, thereby saving memory.
The set of mip levels resident per-resource in GPU memory can be specified by the user.
Minimum LOD affects all of the resident mip levels. Therefore, only the resident mip levels can be updated and read from.
All methods that access texture resources must adhere to minimum LOD clamps.
Empty-set accesses are handled as out-of-bounds cases.
\t\nGets the minimum level-of-detail (LOD).
\t\nA reference to an
Returns the minimum LOD.
Copy a multisampled resource into a non-multisampled resource.
\t\nDestination resource. Must be a created with the
A zero-based index, that identifies the destination subresource. Use D3D11CalcSubresource to calculate the index.
Source resource. Must be multisampled.
>The source subresource of the source resource.
A
This API is most useful when re-using the resulting rendertarget of one render pass as an input to a second render pass.
The source and destination resources must be the same resource type and have the same dimensions. In addition, they must have compatible formats. There are three scenarios for this:
| Scenario | Requirements |
|---|---|
| Source and destination are prestructured and typed | Both the source and destination must have identical formats and that format must be specified in the Format parameter. |
| One resource is prestructured and typed and the other is prestructured and typeless | The typed resource must have a format that is compatible with the typeless resource (i.e. the typed resource is |
| Source and destination are prestructured and typeless | Both the source and desintation must have the same typeless format (i.e. both must have For example, given the
|
?
\t\nQueues commands from a command list onto a device.
\t\nA reference to an
A Boolean flag that determines whether the immediate context state is saved prior to and restored after the execution of a command list. Use TRUE to indicate that the runtime needs to save and restore the state. Use
Use this method to play back a command list that was recorded by a deferred context on any thread.
This method performs some runtime validation related to queries. Queries that are begun in a device context cannot be manipulated indirectly by executing a command list (that is, Begin or End was invoked against the same query by the deferred context which generated the command list). If such a condition occurs, the ExecuteCommandList method does not execute the command list. However, the state of the device context is still maintained, as would be expected (
Get the rendering predicate state.
\t\nAddress of a boolean to fill with the predicate comparison value.
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.
\t\nRestore all default settings.
\t\nThis method resets any device context to the default settings. This sets all input/output resource slots, shaders, input layouts, predications, scissor rectangles, depth-stencil state, rasterizer state, blend state, sampler state, and viewports to
For a scenario where you would like to clear a list of commands recorded so far, call
Sends queued-up commands in the command buffer to the graphics processing unit (GPU).
\t\nMost applications don't need to call this method. If an application calls this method when not necessary, it incurs a performance penalty. Each call to Flush incurs a significant amount of overhead.
When Microsoft 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. Typically, the Direct3D runtime sends these commands to the GPU automatically whenever the runtime determines that they need to be sent, such as when the command buffer is full or when an application maps a resource. Flush sends the commands manually.
We recommend that you use Flush when the CPU waits for an arbitrary amount of time (such as when you call the Sleep function).
Because Flush operates asynchronously, it can return either before or after the GPU finishes executing the queued graphics commands. However, the graphics commands eventually always complete. You can call the
Microsoft Direct3D?11 defers the destruction of objects. Therefore, an application can't rely upon objects immediately being destroyed. By calling Flush, you destroy any objects whose destruction was deferred. If an application requires synchronous destruction of an object, we recommend that the application release all its references, call
Direct3D?11 defers the destruction of objects like views and resources until it can efficiently destroy them. This deferred destruction can cause problems with flip presentation model swap chains. Flip presentation model swap chains have the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL flag set. When you create a flip presentation model swap chain, you can associate only one swap chain at a time with an
Most applications typically use the
Gets the type of device context.
\t\nA member of
Gets the initialization flags associated with the current deferred context.
\t\nThe GetContextFlags method gets the flags that were supplied to the ContextFlags parameter of
Create a command list and record graphics commands into it.
\t\nA Boolean flag that determines whether the runtime saves deferred context state before it executes FinishCommandList and restores it afterwards. Use TRUE to indicate that the runtime needs to save and restore the state. Use
Note??This parameter does not affect the command list that the current call to FinishCommandList returns. However, this parameter affects the command list of the next call to FinishCommandList on the same deferred context.
Upon completion of the method, the passed reference to an
Returns
Create a command list from a deferred context and record commands into it by calling FinishCommandList. Play back a command list with an immediate context by calling
Immediate context state is cleared before and after a command list is executed. A command list has no concept of inheritance. Each call to FinishCommandList will record only the state set since any previous call to FinishCommandList.
For example, the state of a device context is its render state or pipeline state. To retrieve device context state, an application can call
For more information about how to use FinishCommandList, see How to: Record a Command List.
\t\nGets the type of device context.
\t\nGets the initialization flags associated with the current deferred context.
\t\nThe GetContextFlags method gets the flags that were supplied to the ContextFlags parameter of
The
Bind a single vertex buffer to the input-assembler stage.
\t\nThe first input slot for binding. The first vertex buffer is explicitly bound to the start slot; this causes each additional vertex buffer in the array to be implicitly bound to each subsequent input slot. The maximum of 16 or 32 input slots (ranges from 0 to
A
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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind an array of vertex buffers to the input-assembler stage.
\t\nThe first input slot for binding. The first vertex buffer is explicitly bound to the start slot; this causes each additional vertex buffer in the array to be implicitly bound to each subsequent input slot. The maximum of 16 or 32 input slots (ranges from 0 to
A reference to an array of
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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind an array of vertex buffers to the input-assembler stage.
\t\nThe first input slot for binding. The first vertex buffer is explicitly bound to the start slot; this causes each additional vertex buffer in the array to be implicitly bound to each subsequent input slot. The maximum of 16 or 32 input slots (ranges from 0 to
A reference to an array of vertex buffers (see
Pointer to an array of stride values; one stride value for each buffer in the vertex-buffer array. Each stride is the size (in bytes) of the elements that are to be used from that vertex buffer.
Pointer to an array of offset values; one offset value for each buffer in the vertex-buffer array. Each offset is the number of bytes between the first element of a vertex buffer and the first element that will be used.
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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind an input-layout object to the input-assembler stage.
\t\nA reference to the input-layout object (see
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind an array of vertex buffers to the input-assembler stage.
\t\nThe first input slot for binding. The first vertex buffer is explicitly bound to the start slot; this causes each additional vertex buffer in the array to be implicitly bound to each subsequent input slot. The maximum of 16 or 32 input slots (ranges from 0 to
The number of vertex buffers in the array. The number of buffers (plus the starting slot) cannot exceed the total number of IA-stage input slots (ranges from 0 to
A reference to an array of vertex buffers (see
Pointer to an array of stride values; one stride value for each buffer in the vertex-buffer array. Each stride is the size (in bytes) of the elements that are to be used from that vertex buffer.
Pointer to an array of offset values; one offset value for each buffer in the vertex-buffer array. Each offset is the number of bytes between the first element of a vertex buffer and the first element that will be used.
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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind an index buffer to the input-assembler stage.
\t\nA reference to an
A
Offset (in bytes) from the start of the index buffer to the first index to use.
For information about creating index buffers, see How to: 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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind information about the primitive type, and data order that describes input data for the input assembler stage.
\t\nThe type of primitive and ordering of the primitive data (see D3D11_PRIMITIVE_TOPOLOGY).
Get a reference to the input-layout object that is bound to the input-assembler stage.
\t\nA reference to the input-layout object (see
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.
\t\nGet the vertex buffers bound to the input-assembler stage.
\t\nThe input slot of the first vertex buffer to get. The first vertex buffer is explicitly bound to the start slot; this causes each additional vertex buffer in the array to be implicitly bound to each subsequent input slot. The maximum of 16 or 32 input slots (ranges from 0 to
The number of vertex buffers to get starting at the offset. The number of buffers (plus the starting slot) cannot exceed the total number of IA-stage input slots.
A reference to an array of vertex buffers returned by the method (see
Pointer to an array of stride values returned by the method; one stride value for each buffer in the vertex-buffer array. Each stride value is the size (in bytes) of the elements that are to be used from that vertex buffer.
Pointer to an array of offset values returned by the method; one offset value for each buffer in the vertex-buffer array. Each offset is the number of bytes between the first element of a vertex buffer and the first element that will be used.
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.
\t\nGet a reference to the index buffer that is bound to the input-assembler stage.
\t\nA reference to an index buffer returned by the method (see
Specifies format of the data in the index buffer (see
Offset (in bytes) from the start of the index buffer, to the first index to use.
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.
\t\nGet information about the primitive type, and data order that describes input data for the input assembler stage.
\t\nA reference to the type of primitive, and ordering of the primitive data (see D3D11_PRIMITIVE_TOPOLOGY).
Get or sets a reference to the input-layout object that is bound to the input-assembler stage.
\t\nFor 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.
\t\nGet or sets information about the primitive type, and data order that describes input data for the input assembler stage.
\t\nThe
Bind one or more render targets atomically and the depth-stencil buffer to the output-merger stage.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nBinds resources to the output-merger stage.
\t\nNumber of render-target views (ppRenderTargetViews) and depth-stencil view (ppDepthStencilView) to bind. If you set NumViews to D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL (0xffffffff), this method does not modify the currently bound render-target views (RTVs) and also does not modify depth-stencil view (DSV).
Pointer to an array of
Pointer to a
Index into a zero-based array to begin setting unordered-access views (ranges from 0 to
For the Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, this value can range from 0 to D3D11_1_UAV_SLOT_COUNT - 1. D3D11_1_UAV_SLOT_COUNT is defined as 64.
For pixel shaders, UAVStartSlot should be equal to the number of render-target views being bound.
Number of unordered-access views (UAVs) in ppUnorderedAccessView. If you set NumUAVs to D3D11_KEEP_UNORDERED_ACCESS_VIEWS (0xffffffff), this method does not modify the currently bound unordered-access views.
For the Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, this value can range from 0 to D3D11_1_UAV_SLOT_COUNT - UAVStartSlot.
Pointer to an array of
An array of append and consume buffer offsets. A value of -1 indicates to keep the current offset. Any other values set the hidden counter for that appendable and consumable UAV. pUAVInitialCounts is relevant only for UAVs that were created with either
For pixel shaders, the render targets and unordered-access views share the same resource slots when being written out. This means that UAVs must be given an offset so that they are placed in the slots after the render target views that are being bound.
Note??RTVs, DSV, and UAVs cannot be set independently; they all need to be set at the same time.
Two RTVs conflict if they share a subresource (and therefore share the same resource).
Two UAVs conflict if they share a subresource (and therefore share the same resource).
An RTV conflicts with a UAV if they share a subresource or share a bind point.
OMSetRenderTargetsAndUnorderedAccessViews operates properly in the following situations:
NumViews != D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL and NumUAVs != D3D11_KEEP_UNORDERED_ACCESS_VIEWS
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews performs the following tasks:
NumViews == D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL
In this situation, OMSetRenderTargetsAndUnorderedAccessViews binds only UAVs.
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews unbinds the following items:
OMSetRenderTargetsAndUnorderedAccessViews binds ppUnorderedAccessView.
OMSetRenderTargetsAndUnorderedAccessViews ignores ppDepthStencilView, and the current depth-stencil view remains bound.
NumUAVs == D3D11_KEEP_UNORDERED_ACCESS_VIEWS
In this situation, OMSetRenderTargetsAndUnorderedAccessViews binds only RTVs and DSV.
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews unbinds the following items:
OMSetRenderTargetsAndUnorderedAccessViews binds ppRenderTargetViews and ppDepthStencilView.
OMSetRenderTargetsAndUnorderedAccessViews ignores UAVStartSlot.
Binds resources to the output-merger stage.
\t\nNumber of render-target views (ppRenderTargetViews) and depth-stencil view (ppDepthStencilView) to bind. If you set NumViews to D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL (0xffffffff), this method does not modify the currently bound render-target views (RTVs) and also does not modify depth-stencil view (DSV).
Pointer to an array of
Pointer to a
Index into a zero-based array to begin setting unordered-access views (ranges from 0 to
For the Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, this value can range from 0 to D3D11_1_UAV_SLOT_COUNT - 1. D3D11_1_UAV_SLOT_COUNT is defined as 64.
For pixel shaders, UAVStartSlot should be equal to the number of render-target views being bound.
Number of unordered-access views (UAVs) in ppUnorderedAccessView. If you set NumUAVs to D3D11_KEEP_UNORDERED_ACCESS_VIEWS (0xffffffff), this method does not modify the currently bound unordered-access views.
For the Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, this value can range from 0 to D3D11_1_UAV_SLOT_COUNT - UAVStartSlot.
Pointer to an array of
An array of append and consume buffer offsets. A value of -1 indicates to keep the current offset. Any other values set the hidden counter for that appendable and consumable UAV. pUAVInitialCounts is relevant only for UAVs that were created with either
For pixel shaders, the render targets and unordered-access views share the same resource slots when being written out. This means that UAVs must be given an offset so that they are placed in the slots after the render target views that are being bound.
Note??RTVs, DSV, and UAVs cannot be set independently; they all need to be set at the same time.
Two RTVs conflict if they share a subresource (and therefore share the same resource).
Two UAVs conflict if they share a subresource (and therefore share the same resource).
An RTV conflicts with a UAV if they share a subresource or share a bind point.
OMSetRenderTargetsAndUnorderedAccessViews operates properly in the following situations:
NumViews != D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL and NumUAVs != D3D11_KEEP_UNORDERED_ACCESS_VIEWS
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews performs the following tasks:
NumViews == D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL
In this situation, OMSetRenderTargetsAndUnorderedAccessViews binds only UAVs.
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews unbinds the following items:
OMSetRenderTargetsAndUnorderedAccessViews binds ppUnorderedAccessView.
OMSetRenderTargetsAndUnorderedAccessViews ignores ppDepthStencilView, and the current depth-stencil view remains bound.
NumUAVs == D3D11_KEEP_UNORDERED_ACCESS_VIEWS
In this situation, OMSetRenderTargetsAndUnorderedAccessViews binds only RTVs and DSV.
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews unbinds the following items:
OMSetRenderTargetsAndUnorderedAccessViews binds ppRenderTargetViews and ppDepthStencilView.
OMSetRenderTargetsAndUnorderedAccessViews ignores UAVStartSlot.
Bind one or more render targets atomically and the depth-stencil buffer to the output-merger stage.
\t\nNumber of render targets to bind (ranges between 0 and D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT).
Pointer to an array of render targets (see
Pointer to a depth-stencil view (see
The maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nBinds resources to the output-merger stage.
\t\nNumber of render-target views (ppRenderTargetViews) and depth-stencil view (ppDepthStencilView) to bind. If you set NumViews to D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL (0xffffffff), this method does not modify the currently bound render-target views (RTVs) and also does not modify depth-stencil view (DSV).
Pointer to an array of
Pointer to a
Index into a zero-based array to begin setting unordered-access views (ranges from 0 to
For the Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, this value can range from 0 to D3D11_1_UAV_SLOT_COUNT - 1. D3D11_1_UAV_SLOT_COUNT is defined as 64.
For pixel shaders, UAVStartSlot should be equal to the number of render-target views being bound.
Number of unordered-access views (UAVs) in ppUnorderedAccessView. If you set NumUAVs to D3D11_KEEP_UNORDERED_ACCESS_VIEWS (0xffffffff), this method does not modify the currently bound unordered-access views.
For the Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, this value can range from 0 to D3D11_1_UAV_SLOT_COUNT - UAVStartSlot.
Pointer to an array of
An array of append and consume buffer offsets. A value of -1 indicates to keep the current offset. Any other values set the hidden counter for that appendable and consumable UAV. pUAVInitialCounts is relevant only for UAVs that were created with either
For pixel shaders, the render targets and unordered-access views share the same resource slots when being written out. This means that UAVs must be given an offset so that they are placed in the slots after the render target views that are being bound.
Note??RTVs, DSV, and UAVs cannot be set independently; they all need to be set at the same time.
Two RTVs conflict if they share a subresource (and therefore share the same resource).
Two UAVs conflict if they share a subresource (and therefore share the same resource).
An RTV conflicts with a UAV if they share a subresource or share a bind point.
OMSetRenderTargetsAndUnorderedAccessViews operates properly in the following situations:
NumViews != D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL and NumUAVs != D3D11_KEEP_UNORDERED_ACCESS_VIEWS
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews performs the following tasks:
NumViews == D3D11_KEEP_RENDER_TARGETS_AND_DEPTH_STENCIL
In this situation, OMSetRenderTargetsAndUnorderedAccessViews binds only UAVs.
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews unbinds the following items:
OMSetRenderTargetsAndUnorderedAccessViews binds ppUnorderedAccessView.
OMSetRenderTargetsAndUnorderedAccessViews ignores ppDepthStencilView, and the current depth-stencil view remains bound.
NumUAVs == D3D11_KEEP_UNORDERED_ACCESS_VIEWS
In this situation, OMSetRenderTargetsAndUnorderedAccessViews binds only RTVs and DSV.
The following conditions must be true for OMSetRenderTargetsAndUnorderedAccessViews to succeed and for the runtime to pass the bind information to the driver:
OMSetRenderTargetsAndUnorderedAccessViews unbinds the following items:
OMSetRenderTargetsAndUnorderedAccessViews binds ppRenderTargetViews and ppDepthStencilView.
OMSetRenderTargetsAndUnorderedAccessViews ignores UAVStartSlot.
Set the blend state of the output-merger stage.
\t\nPointer to a blend-state interface (see
Array of blend factors, one for each RGBA component. This requires a blend state object that specifies the
32-bit sample coverage. The default value is 0xffffffff. See remarks.
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
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| BlendEnable | |
| SrcBlend | |
| DstBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DstBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask[8] |
?
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets the depth-stencil state of the output-merger stage.
\t\nPointer to a depth-stencil state interface (see
Reference value to perform against when doing a depth-stencil test. See remarks.
To create a depth-stencil state interface, call
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nGet references to the resources bound to the output-merger stage.
\t\nNumber of render targets to retrieve.
Pointer to an array of
Pointer to a
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.
\t\nGet references to the resources bound to the output-merger stage.
\t\nThe number of render-target views to retrieve.
Pointer to an array of
Pointer to a
Index into a zero-based array to begin retrieving unordered-access views (ranges from 0 to
Number of unordered-access views to return in ppUnorderedAccessViews. This number ranges from 0 to
Pointer to an array of
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.
\t\nGet the blend state of the output-merger stage.
\t\nAddress of a reference to a blend-state interface (see
Array of blend factors, one for each RGBA component.
Pointer to a sample mask.
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.
\t\nGets the depth-stencil state of the output-merger stage.
\t\nAddress of a reference to a depth-stencil state interface (see
Pointer to the stencil reference value used in the depth-stencil test.
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.
\t\nThe
All scissor rects must be set atomically as one operation. Any scissor rects not defined by the call are disabled.
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
All scissor rects must be set atomically as one operation. Any scissor rects not defined by the call are disabled.
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
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; if a geometry shader does not specify the semantic, Direct3D will use the first viewport in the array.
\t\nAll 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; if a geometry shader does not specify the semantic, Direct3D will use the first viewport in the array.
\t\nAll 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; if a geometry shader does not specify the semantic, Direct3D will use the first viewport in the array.
\t\nSet the rasterizer state for the rasterizer stage of the pipeline.
\t\nTo create a rasterizer state interface, call
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind an array of viewports to the rasterizer stage of the pipeline.
\t\nNumber of viewports to bind.
An array of
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; if a geometry shader does not specify the semantic, Direct3D will use the first viewport in the array.
\t\nBind an array of scissor rectangles to the rasterizer stage.
\t\nNumber of scissor rectangles to bind.
An array of scissor rectangles (see D3D11_RECT).
All scissor rects must be set atomically as one operation. Any scissor rects not defined by the call are disabled.
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
Get the rasterizer state from the rasterizer stage of the pipeline.
\t\nAny 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.
\t\nGet the array of viewports bound to the rasterizer stage
\t\nThe input specifies the number of viewports (ranges from 0 to D3D11_VIEWPORT_AND_SCISSORRECT_OBJECT_COUNT_PER_PIPELINE) in pViewports, the output contains the actual number of viewports returned. If pViewports is
An array of
Get the array of scissor rectangles bound to the rasterizer stage.
\t\nThe number of scissor rectangles (ranges between 0 and D3D11_VIEWPORT_AND_SCISSORRECT_OBJECT_COUNT_PER_PIPELINE) bound; set pRects to
An array of scissor rectangles (see D3D11_RECT). If NumRects is greater than the number of scissor rects currently bound, then unused members of the array will contain 0.
Get or sets the rasterizer state from the rasterizer stage of the pipeline.
\t\nAny 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.
\t\nA domain-shader interface manages an executable program (a domain shader) that controls the domain-shader stage.
\t\nThe domain-shader interface has no methods; use HLSL to implement your shader functionality. All shaders are implemented from a common set of features referred to as the common-shader core..
To create a domain-shader interface, call
This interface is defined in D3D11.h.
\t\nEncapsulates forward and inverse FFTs.
\t\nSets the scale used for forward transforms.
\t\nThe scale to use for forward transforms. Setting ForwardScale to 0 causes the default values of 1 to be used.
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
SetForwardScale sets the scale used by
Gets the scale for forward transforms.
\t\nScale for forward transforms.
Sets the scale used for inverse transforms.
\t\nScale used for inverse transforms. Setting InverseScale to 0 causes the default value of 1/N to be used, where N is the product of the transformed dimension lengths.
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
SetInverseScale sets the scale used by
Get the scale for inverse transforms.
\t\nScale for inverse transforms.
Attaches buffers to an FFT context and performs any required precomputations.
\t\nNumber of buffers in ppTempBuffers.
Temporary buffers to attach.
Number of buffers in ppPrecomputeBuffers.
Buffers to hold precomputed data.
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
The buffers must be no smaller than the corresponding buffer sizes returned by
Attaches buffers to an FFT context and performs any required precomputations.
\t\nNumber of buffers in ppTempBuffers.
Temporary buffers to attach.
Number of buffers in ppPrecomputeBuffers.
Buffers to hold precomputed data.
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
The buffers must be no smaller than the corresponding buffer sizes returned by
Performs a forward FFT.
\t\nPointer to
Pointer to a
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
ForwardTransform can be called after buffers have been attached to the context using
The format of complex data is interleaved components (for example, (Real0, Imag0), (Real1, Imag1) ... , and so on). Data is stored in row major order.
\t\nPerforms an inverse FFT.
\t\nPointer to
Pointer to a
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
Gets or sets the scale for forward transforms.
\t\nGet or sets the scale for inverse transforms.
\t\nOptional flags that control the behavior of
Identifies how to bind a resource to the pipeline.
\t\nIn 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:
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
Bind a buffer as a vertex buffer to the input-assembler stage.
Bind a buffer as an index buffer to the input-assembler stage.
Bind a buffer as a constant buffer to a shader stage; this flag may NOT be combined with any other bind flag.
Bind a buffer or texture to a shader stage; this flag cannot be used with the
Bind an output buffer for the stream-output stage.
Bind a texture as a render target for the output-merger stage.
Bind a texture as a depth-stencil target for the output-merger stage.
Bind an unordered access resource.
RGB or alpha blending operation.
\t\nThe 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.
\t\nAdd source 1 and source 2.
Subtract source 1 from source 2.
Subtract source 2 from source 1.
Find the minimum of source 1 and source 2.
Find the maximum of source 1 and source 2.
Applies to: desktop apps | Metro style apps
Blend options. A blend option identifies the data source and an optional pre-blend operation.
\t\nBlend operations are specified in a blend description.
\t\nThe data source is the color black (0, 0, 0, 0). No pre-blend operation.
The data source is the color white (1, 1, 1, 1). No pre-blend operation.
The data source is color data (RGB) from a pixel shader. No pre-blend operation.
The data source is color data (RGB) from a pixel shader. The pre-blend operation inverts the data, generating 1 - RGB.
The data source is alpha data (A) from a pixel shader. No pre-blend operation.
The data source is alpha data (A) from a pixel shader. The pre-blend operation inverts the data, generating 1 - A.
The data source is alpha data from a rendertarget. No pre-blend operation.
The data source is alpha data from a rendertarget. The pre-blend operation inverts the data, generating 1 - A.
The data source is color data from a rendertarget. No pre-blend operation.
The data source is color data from a rendertarget. The pre-blend operation inverts the data, generating 1 - RGB.
The data source is alpha data from a pixel shader. The pre-blend operation clamps the data to 1 or less. \t\n
The data source is the blend factor set with
The data source is the blend factor set with
The data sources are both color data output by a pixel shader. There is no pre-blend operation. This options supports dual-source color blending.
The data sources are both color data output by a pixel shader. The pre-blend operation inverts the data, generating 1 - RGB. This options supports dual-source color blending.
The data sources are alpha data output by a pixel shader. There is no pre-blend operation. This options supports dual-source color blending.
The data sources are alpha data output by a pixel shader. The pre-blend operation inverts the data, generating 1 - A. This options supports dual-source color blending.
Identify which components of each pixel of a render target are writable during blending.
\t\nThese flags can be combined with a bitwise OR.
\t\nAllow data to be stored in the red component.
Allow data to be stored in the green component.
Allow data to be stored in the blue component.
Allow data to be stored in the alpha component.
Allow data to be stored in all components.
Comparison options.
\t\nA 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
Never pass the comparison.
If the source data is less than the destination data, the comparison passes.
If the source data is equal to the destination data, the comparison passes.
If the source data is less than or equal to the destination data, the comparison passes.
If the source data is greater than the destination data, the comparison passes.
If the source data is not equal to the destination data, the comparison passes.
If the source data is greater than or equal to the destination data, the comparison passes.
Always pass the comparison.
Unordered resource support options for a compute shader resource (see
Describes a counter.
\t\nThis structure is used by
Type of counter (see
Data type of a performance counter.
\t\nThese flags are an output parameter in
32-bit floating point.
16-bit unsigned integer.
32-bit unsigned integer.
64-bit unsigned integer.
Specifies the types of CPU access allowed for a resource.
\t\nThis enumeration is used in
Applications may combine one or more of these flags with a logical OR. When possible, create resources with no CPU access flags, as this enables better resource optimiztion.
\t\nThe resource is to be mappable so that the CPU can change its contents. Resources created with this flag cannot be set as outputs of the pipeline and must be created with either dynamic or staging usage (see
The resource is to be mappable so that the CPU can read its contents. Resources created with this flag cannot be set as either inputs or outputs to the pipeline and must be created with staging usage (see
Indicates triangles facing a particular direction are not drawn.
\t\nThis enumeration is part of a rasterizer-state object description (see
Always draw all triangles.
Do not draw triangles that are front-facing.
Do not draw triangles that are back-facing.
Specifies the parts of the depth stencil to clear.
\t\nThese flags are used when calling
Clear the depth buffer.
Clear the stencil buffer.
Specifies how to access a resource used in a depth-stencil view.
\t\nThis enumeration is used in
The resource will be accessed as a 1D texture.
The resource will be accessed as an array of 1D textures.
The resource will be accessed as a 2D texture.
The resource will be accessed as an array of 2D textures.
The resource will be accessed as a 2D texture with multisampling.
The resource will be accessed as an array of 2D textures with multisampling.
Depth-stencil view options.
\t\nThis enumeration is used by
Limiting a depth-stencil buffer to read-only access allows more than one depth-stencil view to be bound to the pipeline simultaneously, since it is not possible to have a read/write conflicts between separate views.
\t\nIndicates that depth values are read only.
Indicates that stencil values are read only.
Identify the portion of a depth-stencil buffer for writing depth data.
\t\nTurn off writes to the depth-stencil buffer.
Turn on writes to the depth-stencil buffer.
Device context options.
\t\nThis enumeration is used by
The device context is an immediate context.
The device context is a deferred context.
Describes parameters that are used to create a device.
\t\nDevice creation flags are used by
An application might dynamically create (and destroy) threads to improve performance especially on a machine with multiple CPU cores. There may be cases, however, when an application needs to prevent extra threads from being created. This can happen when you want to simplify debugging, profile code or develop a tool for instance. For these cases, use
You should use this flag if your application will only call methods of Direct3D?11 interfaces from a single thread. By default, the
Creates a device that supports the debug layer.
Note??This flag is not supported in Direct3D?11.
Prevents multiple threads from being created. When this flag is used with a Windows Advanced Rasterization Platform (WARP) device, no additional threads will be created by WARP and all rasterization will occur on the calling thread. This flag is not recommended for general use. See remarks.
Required for Direct2D interoperability with Direct3D resources.
FFT creation flags.
\t\nDo not AddRef or Release temp and precompute buffers, caller is responsible for holding references to these buffers.
FFT data types.
\t\nReal numbers.
Complex numbers.
Number of dimensions for FFT data.
\t\nOne dimension.
Two dimensions.
Three dimensions.
Direct3D 11 feature options.
\t\nThis enumeration is used when querying a driver about support for these features by calling
The following table shows the structures associated with each enumerant.
| Enumerant | Associated Structure |
|---|---|
| | |
| | |
| | |
| | |
| | |
| D3D11_FEATURE_D3D11_OPTIONS | D3D11_FEATURE_DATA_D3D11_OPTIONS |
| D3D11_FEATURE_ARCHITECTURE_INFO | D3D11_FEATURE_DATA_ARCHITECTURE_INFO |
| D3D11_FEATURE_D3D9_OPTIONS | D3D11_FEATURE_DATA_D3D9_OPTIONS |
| D3D11_FEATURE_SHADER_MIN_PRECISION_SUPPORT | D3D11_FEATURE_DATA_SHADER_MIN_PRECISION_SUPPORT |
?
\t\nThe driver supports multithreading. To see an example of testing a driver for multithread support, see How To: Check for Driver Support.
Supports the use of the double-precision shaders in HLSL.
Supports the formats in
Supports the formats in
Supports compute shaders and raw and structured buffers.
Determines the fill mode to use when rendering triangles.
\t\nThis enumeration is part of a rasterizer-state object description (see
Draw lines connecting the vertices. Adjacent vertices are not drawn.
Fill the triangles formed by the vertices. Adjacent vertices are not drawn.
Types of magnification or minification sampler filters.
\t\nPoint filtering used as a texture magnification or minification filter. The texel with coordinates nearest to the desired pixel value is used. The texture filter to be used between mipmap levels is nearest-point mipmap filtering. The rasterizer uses the color from the texel of the nearest mipmap texture.
Bilinear interpolation filtering used as a texture magnification or minification filter. A weighted average of a 2 x 2 area of texels surrounding the desired pixel is used. The texture filter to use between mipmap levels is trilinear mipmap interpolation. The rasterizer linearly interpolates pixel color, using the texels of the two nearest mipmap textures.
Texture filtering flags.
\t\nD3DX11 automatically performs gamma correction (to convert color data from RGB space to standard RGB space) when loading texture data. This is automatically done for instance when RGB data is loaded from a .png file into an sRGB texture. Use the SRGB filter flags to indicate if the data does not need to be converted into sRGB space.
\t\nNo scaling or filtering will take place. Pixels outside the bounds of the source image are assumed to be transparent black.
Each destination pixel is computed by sampling the nearest pixel from the source image.
Each destination pixel is computed by sampling the four nearest pixels from the source image. This filter works best when the scale on both axes is less than two.
Every pixel in the source image contributes equally to the destination image. This is the slowest of the filters.
Each pixel is computed by averaging a 2x2(x2) box of pixels from the source image. This filter works only when the dimensions of the destination are half those of the source, as is the case with mipmaps.
Pixels off the edge of the texture on the u-axis should be mirrored, not wrapped.
Pixels off the edge of the texture on the v-axis should be mirrored, not wrapped.
Pixels off the edge of the texture on the w-axis should be mirrored, not wrapped.
Specifying this flag is the same as specifying the
The resulting image must be dithered using a 4x4 ordered dither algorithm. This happens when converting from one format to another.
Do diffuse dithering on the image when changing from one format to another.
Input data is in standard RGB (sRGB) color space. See remarks.
Output data is in standard RGB (sRGB) color space. See remarks.
Same as specifying
Types of magnification or minification sampler filters.
\t\nPoint filtering used as a texture magnification or minification filter. The texel with coordinates nearest to the desired pixel value is used. The texture filter to be used between mipmap levels is nearest-point mipmap filtering. The rasterizer uses the color from the texel of the nearest mipmap texture.
Bilinear interpolation filtering used as a texture magnification or minification filter. A weighted average of a 2 x 2 area of texels surrounding the desired pixel is used. The texture filter to use between mipmap levels is trilinear mipmap interpolation. The rasterizer linearly interpolates pixel color, using the texels of the two nearest mipmap textures.
Which resources are supported for a given format and given device (see
These flags are used by functions which operate on one or more channels in a texture.
\t\nIndicates the red channel should be used.
Indicates the blue channel should be used.
Indicates the green channel should be used.
Indicates the alpha channel should be used.
Indicates the luminaces of the red, green, and blue channels should be used.
Image file formats supported by D3DX11Createxxx and D3DX11Savexxx functions.
\t\nSee Types of Bitmaps (GDI+) for more information on some of these formats.
\t\nWindows bitmap (BMP) file format. Contains a header that describes the resolution of the device on which the rectangle of pixels was created, the dimensions of the rectangle, the size of the array of bits, a logical palette, and an array of bits that defines the relationship between pixels in the bitmapped image and entries in the logical palette. The file extension for this format is .bmp.
Joint Photographic Experts Group (JPEG) compressed file format. Specifies variable compression of 24-bit RGB color and 8-bit gray-scale Tagged Image File Format (TIFF) image document files. The file extension for this format is .jpg.
Portable Network Graphics (PNG) file format. A non-proprietary bitmap format using lossless compression. The file extension for this format is .png.
DirectDraw surface (DDS) file format. Stores textures, volume textures, and cubic environment maps, with or without mipmap levels, and with or without pixel compression. The file extension for this format is .dds.
Tagged Image File Format (TIFF). The file extensions for this format are .tif and .tiff.
Graphics Interchange Format (GIF). The file extension for this format is .gif.
Windows Media Photo format (WMP). This format is also known as HD Photo and JPEG XR. The file extensions for this format are .hdp, .jxr, and .wdp.
To work properly,
Type of data contained in an input slot.
\t\nUse these values to specify the type of data for a particular input element (see
Input data is per-vertex data.
Input data is per-instance data.
Specifies how the CPU should respond when an application calls the
This enumeration is used by
Identifies a resource to be accessed for reading and writing by the CPU. Applications may combine one or more of these flags.
\t\nThis enumeration is used in
These remarks are divided into the following topics:
For example, consider the buffer illustrated in the following diagram. If a Draw call has been issued that uses vertices 4-6, then an application that calls Map on this buffer must ensure that it does not write to the vertices that the Draw call will access during rendering.
However, ensuring this can be difficult, because the GPU is often many frames behind the CPU in terms of which frame it is currently processing. Keeping track of which sections of a resource are being used because of calls made 2 to 5 frames ago is difficult and error-prone. Because of this, it is recommended that applications only write to the uninitialized portions of a resource when using
A common use of these two flags involves filling dynamic index/vertex buffers with geometry that can be seen from the camera's current position. The first time that data is entered into the buffer on a given frame, Map is called with
Subsequent writes to the buffer within the same frame should use
Resource is mapped for reading. The resource must have been created with read access (see
Resource is mapped for writing. The resource must have been created with write access (see
Resource is mapped for reading and writing. The resource must have been created with read and write access (see
Resource is mapped for writing; the previous contents of the resource will be undefined. The resource must have been created with write access and dynamic usage (See
Resource is mapped for writing; the existing contents of the resource cannot be overwritten (see Remarks). This flag is only valid on vertex and index buffers. The resource must have been created with write access (see
Categories of debug messages. This will identify the category of a message when retrieving a message with
This is part of the Information Queue feature. See
Debug message severity levels for an information queue.
\t\nUse these values to allow or deny message categories to pass through the storage and retrieval filters for an information queue (see
Defines some type of corruption which has occurred.
Defines an error message.
Defines a warning message.
Defines an information message.
Normal map options. Any number of these flags may be OR'd together in any combination.
\t\nThese flags are used by
Indicates that pixels off the edge of the texture on the U-axis should be mirrored, not wraped.
Indicates that pixels off the edge of the texture on the V-axis should be mirrored, not wraped.
Same as
Inverts the direction of each normal.
Computes the per pixel occlusion term and encodes it into the alpha. An Alpha of 1 means that the pixel is not obscured in any way, and an alpha of 0 would mean that the pixel is completly obscured.
Flags that describe miscellaneous query behavior.
\t\nThis flag is part of a query description (see
Tell the hardware that if it is not yet sure if something is hidden or not to draw it anyway. This is only used with an occlusion predicate. Predication data cannot be returned to your application via
Query types.
\t\nCreate a query with
Determines whether or not the GPU is finished processing commands. When the GPU is finished processing commands
Get the number of samples that passed the depth and stencil tests in between
Get a timestamp value where
Determines whether or not a
Get pipeline statistics, such as the number of pixel shader invocations in between
Similar to
Get streaming output statistics, such as the number of primitives streamed out in between
Determines whether or not any of the streaming output buffers overflowed in between
Get streaming output statistics for stream 0, such as the number of primitives streamed out in between
Determines whether or not the stream 0 output buffers overflowed in between
Get streaming output statistics for stream 1, such as the number of primitives streamed out in between
Determines whether or not the stream 1 output buffers overflowed in between
Get streaming output statistics for stream 2, such as the number of primitives streamed out in between
Determines whether or not the stream 2 output buffers overflowed in between
Get streaming output statistics for stream 3, such as the number of primitives streamed out in between
Determines whether or not the stream 3 output buffers overflowed in between
These flags identify the type of resource that will be viewed as a render target.
\t\nThis enumeration is used in
Do not use this value, as it will cause
The resource will be accessed as a buffer.
The resource will be accessed as a 1D texture.
The resource will be accessed as an array of 1D textures.
The resource will be accessed as a 2D texture.
The resource will be accessed as an array of 2D textures.
The resource will be accessed as a 2D texture with multisampling.
The resource will be accessed as an array of 2D textures with multisampling.
The resource will be accessed as a 3D texture.
Options for the amount of information to report about a device object's lifetime.
\t\nThis enumeration is used by
Several inline functions exist to combine the options using operators, see the D3D11SDKLayers.h header file for details.
\t\nSpecifies to obtain a summary about a device object's lifetime.
Specifies to obtain detailed information about a device object's lifetime.
Identifies the type of resource being used.
\t\nThis enumeration is used in
Resource is of unknown type.
Resource is a buffer.
Resource is a 1D texture.
Resource is a 2D texture.
Resource is a 3D texture.
Identifies options for resources.
\t\nThis enumeration is used in
These flags can be combined by bitwise OR.
\t\nEnables MIP map generation by using
Enables resource data sharing between two or more Direct3D devices. The only resources that can be shared are 2D non-mipmapped textures.
WARP and REF devices do not support shared resources. If you try to create a resource with this flag on either a WARP or REF device, the create method will return an E_OUTOFMEMORY error code.
Sets a resource to be a cube texture created from a Texture2DArray that contains 6 textures.
Enables instancing of GPU-generated content.
Enables a resource as a byte address buffer.
Enables a resource as a structured buffer.
Enables a resource with MIP map clamping for use with
Enables the resource to be synchronized by using the
If you call any of these methods with the
WARP and REF devices do not support shared resources. If you try to create a resource with this flag on either a WARP or REF device, the create method will return an E_OUTOFMEMORY error code.
Enables a resource compatible with GDI. You must set the
Consider the following programming tips for using
You must set the texture format to one of the following types.
Identifies expected resource use during rendering. The usage directly reflects whether a resource is accessible by the CPU and/or the graphics processing unit (GPU).
\t\nAn application identifies the way a resource is intended to be used (its usage) in a resource description. There are several structures for creating resources including:
| Differences between Direct3D 9 and Direct3D 10/11: In Direct3D 9, you specify the type of memory a resource should be created in at resource creation time (using In Direct3D 10/11, an application no longer specifies what type of memory (the pool) to create a resource in. Instead, you specify the intended usage of the resource, and let the runtime (in concert with the driver and a memory manager) choose the type of memory that will achieve the best performance. |
?
Resource Usage RestrictionsEach usage dictates a tradeoff between accessibility for the CPU and accessibility for the GPU. In general, higher-performance access for one of these two processors means lower-performance access for the other. At either extreme are the
Use the following table to choose the usage that best describes how the resource will need to be accessed by the CPU and/or the GPU. Of course, there will be performance tradeoffs.
| Resource Usage | Default | Dynamic | Immutable | Staging |
|---|---|---|---|---|
| GPU-Read | yes | yes | yes | yes1 |
| GPU-Write | yes | yes1 | ||
| CPU-Read | yes1 | |||
| CPU-Write | yes | yes1 |
?
1 - GPU read or write of a resource with the
Note??You can technically use
Note??
Note??
To maximize performance, not all resource usage options can be used as input or output resources to the pipeline. This table identifies these limitations.
| Resource Can Be Bound As | Default | Dynamic | Immutable | Staging |
|---|---|---|---|---|
| Input to a Stage | yes2 | yes3 | yes | |
| Output from a Stage | yes2 |
?
A resource that requires read and write access by the GPU. This is likely to be the most common usage choice.
A resource that can only be read by the GPU. It cannot be written by the GPU, and cannot be accessed at all by the CPU. This type of resource must be initialized when it is created, since it cannot be changed after creation.
A resource that is accessible by both the GPU (read only) and the CPU (write only). A dynamic resource is a good choice for a resource that will be updated by the CPU at least once per frame. To update a dynamic resource, use a Map method.
A resource that supports data transfer (copy) from the GPU to the CPU.
Type for scan data.
\t\nFLOAT data.
INT data.
UINT data.
Direction to perform scan in.
\t\nScan forward.
Scan backward.
Scan opcodes.
\t\nAdd values.
Take the minimum value.
Take the maximum value.
Multiply the values.
Perform a logical AND on the values.
Perform a logical OR on the values.
Perform a logical XOR on the values.
Identifies how to bind a raw-buffer resource to the pipeline.
\t\nThis enumeration is used by
Bind a raw buffer to the input-assembler stage.
Specifies a multi-sample pattern type.
\t\nPre-defined multi-sample patterns required for DX11 and DX10.1 hardware.
Pattern where all of the samples are located at the pixel center.
The stencil operations that can be performed during depth-stencil testing.
\t\nKeep the existing stencil data.
Set the stencil data to 0.
Set the stencil data to the reference value set by calling
Increment the stencil value by 1, and clamp the result.
Decrement the stencil value by 1, and clamp the result.
Invert the stencil data.
Increment the stencil value by 1, and wrap the result if necessary.
Increment the stencil value by 1, and wrap the result if necessary.
Identify a technique for resolving texture coordinates that are outside of the boundaries of a texture.
\t\nTile the texture at every (u,v) integer junction. For example, for u values between 0 and 3, the texture is repeated three times.
Flip the texture at every (u,v) integer junction. For u values between 0 and 1, for example, the texture is addressed normally; between 1 and 2, the texture is flipped (mirrored); between 2 and 3, the texture is normal again; and so on.
Texture coordinates outside the range [0.0, 1.0] are set to the texture color at 0.0 or 1.0, respectively.
Texture coordinates outside the range [0.0, 1.0] are set to the border color specified in
Similar to
The different faces of a cube texture.
\t\nPositive X face.
Negative X face.
Positive Y face.
Negative Y face.
Positive Z face.
Negative Z face.
Unordered-access-view buffer options.
\t\nResource contains raw, unstructured data. Requires the UAV format to be
Allow data to be appended to the end of the buffer.
Adds a counter to the unordered-access-view buffer.
Unordered-access view options.
\t\nThis enumeration is used by a unordered access-view description (see
The view type is unknown.
View the resource as a buffer.
View the resource as a 1D texture.
View the resource as a 1D texture array.
View the resource as a 2D texture.
View the resource as a 2D texture array.
View the resource as a 3D texture array.
Creates a device that represents the display adapter.
\t\nA reference to the video adapter to use when creating a device. Pass
Note??Do not mix the use of DXGI 1.0 (
The
A handle to a DLL that implements a software rasterizer. If DriverType is
The runtime layers to enable (see
A reference to an array of
{ , , , , , ,}; The number of elements in pFeatureLevels.
The SDK version; use
Returns the address of a reference to an
If successful, returns the first
Returns the address of a reference to an
This method returns one of the following Direct3D 11 Return Codes.
This entry-point is supported by the Direct3D 11 runtime, which is available on Windows 7, Windows Server 2008 R2, and as an update to Windows Vista (KB971644).
Set ppDevice and ppImmediateContext to
For an example, see How To: Create a Device and Immediate Context; to create a device and a swap chain at the same time, use
If you set the pAdapter parameter to a non-
| Differences between Direct3D 10 and Direct3D 11: In Direct3D 10, the presence of pAdapter dictated which adapter to use and the DriverType could mismatch what the adapter was. In Direct3D 11, if you are trying to create a hardware or a software device, set pAdapter !=
On the other hand, if pAdapter ==
|
?
\t\nCreates a device that represents the display adapter and a swap chain used for rendering.
\t\nA reference to the video adapter to use when creating a device. Pass
Note??Do not mix the use of DXGI 1.0 (
The
A handle to a DLL that implements a software rasterizer. If DriverType is
The runtime layers to enable (see
A reference to an array of
{ , , , , , ,}; The number of elements in pFeatureLevels.
The SDK version; use
A reference to a swap chain description (see
Returns the address of a reference to the
Returns the address of a reference to an
Returns a reference to a
Returns the address of a reference to an
This method returns one of the following Direct3D 11 Return Codes.
This entry-point is supported by the Direct3D 11 runtime, which is available on Windows 7, Windows Server 2008 R2, and as an update to Windows Vista (KB971644).
Also, see the remarks section in
If you set the pAdapter parameter to a non-
The
Creates an
Pointer to the
Length of the first dimension of the FFT.
Length of the second dimension of the FFT.
Flag affecting the behavior of the FFT, can be 0 or a combination of flags from
Pointer to a
Pointer to an
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates an
Pointer to the
Length of the first dimension of the FFT.
Flag affecting the behavior of the FFT, can be 0 or a combination of flags from
Pointer to a
Pointer to an
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates an
Pointer to the
Pointer to a
Flag affecting the behavior of the FFT, can be 0 or a combination of flags from
Pointer to a
Pointer to an
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates an
Pointer to the
Length of the first dimension of the FFT.
Length of the second dimension of the FFT.
Flag affecting the behavior of the FFT, can be 0 or a combination of flags from
Pointer to a
Pointer to an
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates a scan context.
\t\nThe
Maximum single scan size, in elements (FLOAT, UINT, or INT)
Maximum number of scans in multiscan.
Pointer to a
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates an
Pointer to the
Length of the first dimension of the FFT.
Length of the second dimension of the FFT.
Length of the third dimension of the FFT.
Flag affecting the behavior of the FFT, can be 0 or a combination of flags from
Pointer to a
Pointer to an
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates an
Pointer to the
Length of the first dimension of the FFT.
Flag affecting the behavior of the FFT, can be 0 or a combination of flags from
Pointer to a
Pointer to an
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates a segmented scan context.
\t\nPointer to an
Maximum single scan size, in elements (FLOAT, UINT, or INT).
Pointer to a
The return value is one of the values listed in Direct3D 11 Return Codes.
Creates an
Pointer to the
Length of the first dimension of the FFT.
Length of the second dimension of the FFT.
Length of the third dimension of the FFT.
Flag affecting the behavior of the FFT, can be 0 or a combination of flags from
Pointer to a
Pointer to an
The return value is one of the values listed in Direct3D 11 Return Codes.
Create a shader-resource view from a file in memory.
\t\nA reference to the device (see
Pointer to the file in memory that contains the shader-resource view.
Size of the file in memory.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
Address of a reference to the newly created shader resource view. See
A reference to the return value. May be
The return value is one of the values listed in Direct3D 11 Return Codes.
Projects a function represented in a cube map into spherical harmonics.
\t\nA reference to an
Order of the SH evaluation, generates Order^2 coefficients whose degree is Order-1. Valid range is between 2 and 6.
A reference to an
Output SH vector for red.
Output SH vector for green.
Output SH vector for blue.
The return value is one of the values listed in Direct3D 11 Return Codes.
Create a texture from another resource.
\t\nA reference to the device (see
A handle to the source resource. HMODULE can be obtained with GetModuleHandle Function.
A string that contains the name of the source resource. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
The address of a reference to the texture resource (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 11 Return Codes.
Save a texture to memory.
\t\nA reference to an
Pointer to the texture to be saved. See
The format the texture will be saved as. See
Address of a reference to the memory containing the saved texture.
Optional.
The return value is one of the values listed in Direct3D 11 Return Codes.
Converts a height map into a normal map. The (x,y,z) components of each normal are mapped to the (r,g,b) channels of the output texture.
\t\nPointer to an
Pointer to an
One or more
One
Constant value multiplier that increases (or decreases) the values in the normal map. Higher values usually make bumps more visible, lower values usually make bumps less visible.
Pointer to an
If the function succeeds, the return value is
This method computes the normal by using the central difference with a kernel size of 3x3. RGB channels in the destination contain biased (x,y,z) components of the normal. The central differencing denominator is hardcoded to 2.0.
\t\nRetrieves information about a given image in a resource.
\t\nModule where the resource is loaded. Set this parameter to
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR. See Remarks.
Optional thread pump that can be used to load the info asynchronously. Can be
Pointer to a
A reference to the return value. May be
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Create a shader-resource view from a file.
\t\nA reference to the device (see
Name of the file that contains the shader-resource view. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Identifies the characteristics of a texture (see
Pointer to a thread-pump interface (see
Address of a reference to the shader-resource view (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 11 Return Codes.
Create a texture resource from a file.
\t\nA reference to the device (see
The name of the file containing the resource. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
The address of a reference to the texture resource (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 11 Return Codes.
Generates mipmap chain using a particular texture filter.
\t\nA reference to an
The texture object to be filtered. See
The mipmap level whose data is used to generate the rest of the mipmap chain.
Flags controlling how each miplevel is filtered (or D3DX11_DEFAULT for
The return value is one of the values listed in Direct3D 11 Return Codes.
Retrieves information about a given image file.
\t\nFile name of image to retrieve information about. If UNICODE or _UNICODE are defined, this parameter type is LPCWSTR, otherwise, the type is LPCSTR.
Optional thread pump that can be used to load the info asynchronously. Can be
Pointer to a
A reference to the return value. May be
If the function succeeds, the return value is
This function supports both Unicode and ANSI strings.
\t\nCreate a shader-resource view from a resource.
\t\nA reference to the device (see
Handle to the resource module containing the shader-resource view. HMODULE can be obtained with GetModuleHandle Function.
Name of the shader resource view in hSrcModule. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
Address of a reference to the shader-resource view (see
A reference to the return value. May be
The return value is one of the values listed in Direct3D 11 Return Codes.
Load a texture from a texture.
\t\nA reference to an
Pointer to the source texture. See
Pointer to texture loading parameters. See
Pointer to the destination texture. See
The return value is one of the values listed in Direct3D 11 Return Codes.
Get information about an image already loaded into memory.
\t\nPointer to the image in memory.
Size of the image in memory, in bytes.
Optional thread pump that can be used to load the info asynchronously. Can be
Information about the image in memory.
A reference to the return value. May be
The return value is one of the values listed in Direct3D 11 Return Codes.
Create a texture resource from a file residing in system memory.
\t\nA reference to the device (see
Pointer to the resource in system memory.
Size of the resource in system memory.
Optional. Identifies the characteristics of a texture (see
A reference to a thread pump interface (see
Address of a reference to the created resource. See
A reference to the return value. May be
The return value is one of the values listed in Direct3D 11 Return Codes.
Save a texture to a file.
\t\nA reference to an
Pointer to the texture to be saved. See
The format the texture will be saved as (see
Name of the destination output file where the texture will be saved. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the data type resolves to LPCSTR.
The return value is one of the values listed in Direct3D 11 Return Codes; use the return value to see if the DestFormat is supported.
The
There is no explicit creation method, simply declare an
Gets the initialization flags associated with the deferred context that created the command list.
\t\nThe context flag is reserved for future use and is always 0.
The GetContextFlags method gets the flags that were supplied to the ContextFlags parameter of
Gets the initialization flags associated with the deferred context that created the command list.
\t\nThe GetContextFlags method gets the flags that were supplied to the ContextFlags parameter of
The
Bind an array of shader resources to the domain-shader stage.
\t\nIndex into the device's zero-based array to begin setting shader resources to (ranges from 0 to
Number of shader resources to set. Up to a maximum of 128 slots are available for shader resources(ranges from 0 to
Array of shader resource view interfaces to set to the device.
If an overlapping resource view is already bound to an output slot, such as a render target, then the method will fill the destination shader resource slot with
For information about creating shader-resource views, see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSet a domain shader to the device.
\t\nPointer to a domain shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet a domain shader to the device.
\t\nPointer to a domain shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet an array of sampler states to the domain-shader stage.
\t\nIndex into the device's zero-based array to begin setting samplers to (ranges from 0 to
Number of samplers in the array. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (see
Any sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets the constant buffers used by the domain-shader stage.
\t\nIndex into the zero-based array to begin setting constant buffers to (ranges from 0 to
Number of buffers to set (ranges from 0 to
Array of constant buffers (see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, can bind a larger number of
If the application wants the shader to access other parts of the buffer, it must call the DSSetConstantBuffers1 method instead.
\t\nGet the domain-shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from (ranges from 0 to
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources (ranges from 0 to
Array of shader resource view interfaces to be returned 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.
\t\nGet the domain shader currently set on the device.
\t\nAddress of a reference to a domain shader (see
Pointer to an array of class instance interfaces (see
The number of class-instance elements in the array.
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.
\t\nGet an array of sampler state interfaces from the domain-shader stage.
\t\nIndex into a zero-based array to begin getting samplers from (ranges from 0 to
Number of samplers to get from a device context. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (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.
\t\nGet the constant buffers used by the domain-shader stage.
\t\nIndex into the device's zero-based array to begin retrieving constant buffers from (ranges from 0 to
Number of buffers to retrieve (ranges from 0 to
Array of constant buffer interface references (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.
\t\nA geometry-shader interface manages an executable program (a geometry shader) that controls the geometry-shader stage.
\t\nThe geometry-shader interface has no methods; use HLSL to implement your shader functionality. All shaders are implemented from a common set of features referred to as the common-shader core..
To create a geometry shader interface, call either
This interface is defined in D3D11.h.
\t\nThe
Sets the constant buffers used by the geometry shader pipeline stage.
\t\nIndex into the device's zero-based array to begin setting constant buffers to (ranges from 0 to
Number of buffers to set (ranges from 0 to
Array of constant buffers (see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
You can't use the
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, can bind a larger number of
If the application wants the shader to access other parts of the buffer, it must call the GSSetConstantBuffers1 method instead.
\t\nSet a geometry shader to the device.
\t\nPointer to a geometry shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet a geometry shader to the device.
\t\nPointer to a geometry shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nBind an array of shader resources to the geometry shader stage.
\t\nIndex into the device's zero-based array to begin setting shader resources to (ranges from 0 to
Number of shader resources to set. Up to a maximum of 128 slots are available for shader resources(ranges from 0 to
Array of shader resource view interfaces to set to the device.
If an overlapping resource view is already bound to an output slot, such as a render target, then the method will fill the destination shader resource slot with
For information about creating shader-resource views, see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSet an array of sampler states to the geometry shader pipeline stage.
\t\nIndex into the device's zero-based array to begin setting samplers to (ranges from 0 to
Number of samplers in the array. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (see
Any sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nGet the constant buffers used by the geometry shader pipeline stage.
\t\nIndex into the device's zero-based array to begin retrieving constant buffers from (ranges from 0 to
Number of buffers to retrieve (ranges from 0 to
Array of constant buffer interface references (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.
\t\nGet the geometry shader currently set on the device.
\t\nAddress of a reference to a geometry shader (see
Pointer to an array of class instance interfaces (see
The number of class-instance elements in the array.
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.
\t\nGet the geometry shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from (ranges from 0 to
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources (ranges from 0 to
Array of shader resource view interfaces to be returned 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.
\t\nGet an array of sampler state interfaces from the geometry shader pipeline stage.
\t\nIndex into a zero-based array to begin getting samplers from (ranges from 0 to
Number of samplers to get from a device context. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (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.
\t\nA hull-shader interface manages an executable program (a hull shader) that controls the hull-shader stage.
\t\nThe hull-shader interface has no methods; use HLSL to implement your shader functionality. All shaders are implemented from a common set of features referred to as the common-shader core..
To create a hull-shader interface, call
This interface is defined in D3D11.h.
\t\nThe
Bind an array of shader resources to the hull-shader stage.
\t\nIf an overlapping resource view is already bound to an output slot, such as a render target, then the method will fill the destination shader resource slot with
For information about creating shader-resource views, see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSet a hull shader to the device.
\t\nPointer to a hull shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet a hull shader to the device.
\t\nPointer to a hull shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet an array of sampler states to the hull-shader stage.
\t\nAny sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSet the constant buffers used by the hull-shader stage.
\t\nThe method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, can bind a larger number of
If the application wants the shader to access other parts of the buffer, it must call the HSSetConstantBuffers1 method instead.
\t\nGet the hull-shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from (ranges from 0 to
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources (ranges from 0 to
Array of shader resource view interfaces to be returned 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.
\t\nGet the hull shader currently set on the device.
\t\nAddress of a reference to a hull shader (see
Pointer to an array of class instance interfaces (see
The number of class-instance elements in the array.
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.
\t\nGet an array of sampler state interfaces from the hull-shader stage.
\t\nAny 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.
\t\nGet the constant buffers used by the hull-shader stage.
\t\nAny 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.
\t\nAn information-queue interface stores, retrieves, and filters debug messages. The queue consists of a message queue, an optional storage filter stack, and a optional retrieval filter stack.
\t\nTo get this interface, turn on debug layer and use IUnknown::QueryInterface from the
Set the maximum number of messages that can be added to the message queue.
\t\nMaximum number of messages that can be added to the message queue. -1 means no limit.
This method returns one of the following Direct3D 11 Return Codes.
When the number of messages in the message queue has reached the maximum limit, new messages coming in will push old messages out.
\t\nClear all messages from the message queue.
\t\nGet a message from the message queue.
\t\nIndex into message queue after an optional retrieval filter has been applied. This can be between 0 and the number of messages in the message queue that pass through the retrieval filter (which can be obtained with
Returned message (see
Size of pMessage in bytes, including the size of the message string that the pMessage points to.
This method returns one of the following Direct3D 11 Return Codes.
This method does not remove any messages from the message queue.
This method gets messages from the message queue after an optional retrieval filter has been applied.
Applications should call this method twice to retrieve a message - first to obtain the size of the message and second to get the message. Here is a typical example:
// Get the size of the message\t\n messageLength = 0;\t\n hr = pInfoQueue->GetMessage(0, null , &messageLength); // Allocate space and get the message\t\n * pMessage = (*)malloc(messageLength);\t\n hr = pInfoQueue->GetMessage(0, pMessage, &messageLength);\t\n For an overview see Information Queue Overview.
\t\nGet the number of messages that were allowed to pass through a storage filter.
\t\nNumber of messages allowed by a storage filter.
Get the number of messages that were denied passage through a storage filter.
\t\nNumber of messages denied by a storage filter.
Get the number of messages currently stored in the message queue.
\t\nNumber of messages currently stored in the message queue.
Get the number of messages that are able to pass through a retrieval filter.
\t\nNumber of messages allowed by a retrieval filter.
Get the number of messages that were discarded due to the message count limit.
\t\nNumber of messages discarded.
Get and set the message count limit with
Get the maximum number of messages that can be added to the message queue.
\t\nMaximum number of messages that can be added to the queue. -1 means no limit.
When the number of messages in the message queue has reached the maximum limit, new messages coming in will push old messages out.
\t\nAdd storage filters to the top of the storage-filter stack.
\t\nArray of storage filters (see
This method returns one of the following Direct3D 11 Return Codes.
Get the storage filter at the top of the storage-filter stack.
\t\nStorage filter at the top of the storage-filter stack.
Size of the storage filter in bytes. If pFilter is
This method returns one of the following Direct3D 11 Return Codes.
Remove a storage filter from the top of the storage-filter stack.
\t\nPush an empty storage filter onto the storage-filter stack.
\t\nThis method returns one of the following Direct3D 11 Return Codes.
An empty storage filter allows all messages to pass through.
\t\nPush a copy of storage filter currently on the top of the storage-filter stack onto the storage-filter stack.
\t\nThis method returns one of the following Direct3D 11 Return Codes.
Push a storage filter onto the storage-filter stack.
\t\nPointer to a storage filter (see
This method returns one of the following Direct3D 11 Return Codes.
Pop a storage filter from the top of the storage-filter stack.
\t\nGet the size of the storage-filter stack in bytes.
\t\nSize of the storage-filter stack in bytes.
Add storage filters to the top of the retrieval-filter stack.
\t\nArray of retrieval filters (see
This method returns one of the following Direct3D 11 Return Codes.
The following code example shows how to use
cats[] = { ..., ..., ... };\t\n sevs[] = { ..., ..., ... };\t\n UINT ids[] = { ..., ..., ... }; filter;\t\n memset( &filter, 0, sizeof(filter) ); // To set the type of messages to allow, \t\n // set filter.AllowList as follows:\t\n filter.AllowList.NumCategories = sizeof(cats / sizeof()); \t\n filter.AllowList.pCategoryList = cats;\t\n filter.AllowList.NumSeverities = sizeof(sevs / sizeof()); \t\n filter.AllowList.pSeverityList = sevs;\t\n filter.AllowList.NumIDs = sizeof(ids) / sizeof(UINT);\t\n filter.AllowList.pIDList = ids; // To set the type of messages to deny, set filter.DenyList \t\n // similarly to the preceding filter.AllowList. // The following single call sets all of the preceding information.\t\n hr = infoQueue->AddRetrievalFilterEntries( &filter );\t\n Get the retrieval filter at the top of the retrieval-filter stack.
\t\nRetrieval filter at the top of the retrieval-filter stack.
Size of the retrieval filter in bytes. If pFilter is
This method returns one of the following Direct3D 11 Return Codes.
Remove a retrieval filter from the top of the retrieval-filter stack.
\t\nPush an empty retrieval filter onto the retrieval-filter stack.
\t\nThis method returns one of the following Direct3D 11 Return Codes.
An empty retrieval filter allows all messages to pass through.
\t\nPush a copy of retrieval filter currently on the top of the retrieval-filter stack onto the retrieval-filter stack.
\t\nThis method returns one of the following Direct3D 11 Return Codes.
Push a retrieval filter onto the retrieval-filter stack.
\t\nPointer to a retrieval filter (see
This method returns one of the following Direct3D 11 Return Codes.
Pop a retrieval filter from the top of the retrieval-filter stack.
\t\nGet the size of the retrieval-filter stack in bytes.
\t\nSize of the retrieval-filter stack in bytes.
Add a debug message to the message queue and send that message to debug output.
\t\nCategory of a message (see
Severity of a message (see
Unique identifier of a message (see
User-defined message.
This method returns one of the following Direct3D 11 Return Codes.
This method is used by the runtime's internal mechanisms to add debug messages to the message queue and send them to debug output. For applications to add their own custom messages to the message queue and send them to debug output, call
Add a user-defined message to the message queue and send that message to debug output.
\t\nSeverity of a message (see
Message string.
This method returns one of the following Direct3D 11 Return Codes.
Set a message category to break on when a message with that category passes through the storage filter.
\t\nMessage category to break on (see
Turns this breaking condition on or off (true for on, false for off).
This method returns one of the following Direct3D 11 Return Codes.
Set a message severity level to break on when a message with that severity level passes through the storage filter.
\t\nA
Turns this breaking condition on or off (true for on, false for off).
This method returns one of the following Direct3D 11 Return Codes.
Set a message identifier to break on when a message with that identifier passes through the storage filter.
\t\nMessage identifier to break on (see
Turns this breaking condition on or off (true for on, false for off).
This method returns one of the following Direct3D 11 Return Codes.
Get a message category to break on when a message with that category passes through the storage filter.
\t\nMessage category to break on (see
Whether this breaking condition is turned on or off (true for on, false for off).
Get a message severity level to break on when a message with that severity level passes through the storage filter.
\t\nMessage severity level to break on (see
Whether this breaking condition is turned on or off (true for on, false for off).
Get a message identifier to break on when a message with that identifier passes through the storage filter.
\t\nMessage identifier to break on (see
Whether this breaking condition is turned on or off (true for on, false for off).
Set a boolean that turns the debug output on or off.
\t\nDisable/Enable the debug output (TRUE to disable or mute the output,
This will stop messages that pass the storage filter from being printed out in the debug output, however those messages will still be added to the message queue.
\t\nGet a boolean that turns the debug output on or off.
\t\nWhether the debug output is on or off (true for on, false for off).
Get or sets the maximum number of messages that can be added to the message queue.
\t\nWhen the number of messages in the message queue has reached the maximum limit, new messages coming in will push old messages out.
\t\nGet the number of messages that were allowed to pass through a storage filter.
\t\nGet the number of messages that were denied passage through a storage filter.
\t\nGet the number of messages currently stored in the message queue.
\t\nGet the number of messages that are able to pass through a retrieval filter.
\t\nGet the number of messages that were discarded due to the message count limit.
\t\nGet and set the message count limit with
Get the size of the storage-filter stack in bytes.
\t\nGet the size of the retrieval-filter stack in bytes.
\t\nGet or sets a boolean that turns the debug output on or off.
\t\nAn input-layout interface holds a definition of how to feed vertex data that is laid out in memory into the input-assembler stage of the graphics pipeline.
\t\nTo create an input-layout object, call
A pixel-shader interface manages an executable program (a pixel shader) that controls the pixel-shader stage.
\t\nThe pixel-shader interface has no methods; use HLSL to implement your shader functionality. All shaders in are implemented from a common set of features referred to as the common-shader core..
To create a pixel shader interface, call
This interface is defined in D3D11.h.
\t\nThe
Bind an array of shader resources to the pixel shader stage.
\t\nIndex into the device's zero-based array to begin setting shader resources to (ranges from 0 to
Number of shader resources to set. Up to a maximum of 128 slots are available for shader resources (ranges from 0 to
Array of shader resource view interfaces to set to the device.
If an overlapping resource view is already bound to an output slot, such as a rendertarget, then this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets a pixel shader to the device.
\t\nPointer to a pixel shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
Set ppClassInstances to
Sets a pixel shader to the device.
\t\nPointer to a pixel shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
Set ppClassInstances to
Set an array of sampler states to the pixel shader pipeline stage.
\t\nIndex into the device's zero-based array to begin setting samplers to (ranges from 0 to
Number of samplers in the array. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (see
Any sampler may be set to
| State | Default Value |
|---|---|
| Filter | |
| AddressU | |
| AddressV | |
| AddressW | |
| MipLODBias | 0 |
| MaxAnisotropy | 1 |
| ComparisonFunc | |
| BorderColor[0] | 1.0f |
| BorderColor[1] | 1.0f |
| BorderColor[2] | 1.0f |
| BorderColor[3] | 1.0f |
| MinLOD | -FLT_MAX |
| MaxLOD | FLT_MAX |
?
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets the constant buffers used by the pixel shader pipeline stage.
\t\nIndex into the device's zero-based array to begin setting constant buffers to (ranges from 0 to
Number of buffers to set (ranges from 0 to
Array of constant buffers (see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The Direct3D 11.1 runtime, which is available on Windows Developer Preview and later operating systems, can bind a larger number of
If the application wants the shader to access other parts of the buffer, it must call the PSSetConstantBuffers1 method instead.
\t\nGet the pixel shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from (ranges from 0 to
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources (ranges from 0 to
Array of shader resource view interfaces to be returned 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.
\t\nGet the pixel shader currently set on the device.
\t\nAddress of a reference to a pixel shader (see
Pointer to an array of class instance interfaces (see
The number of class-instance elements in the array.
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.
\t\nGet an array of sampler states from the pixel shader pipeline stage.
\t\nIndex into a zero-based array to begin getting samplers from (ranges from 0 to
Number of samplers to get from a device context. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Arry of sampler-state interface references (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.
\t\nGet the constant buffers used by the pixel shader pipeline stage.
\t\nIndex into the device's zero-based array to begin retrieving constant buffers from (ranges from 0 to
Number of buffers to retrieve (ranges from 0 to
Array of constant buffer interface references (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.
\t\nA predicate interface determines whether geometry should be processed depending on the results of a previous draw call.
\t\nTo create a predicate object, call
There are two types of predicates: stream-output-overflow predicates and occlusion predicates. Stream-output-overflow predicates cause any geometry residing in stream-output buffers that were overflowed to not be processed. Occlusion predicates cause any geometry that did not have a single sample pass the depth/stencil tests to not be processed.
\t\nA query interface queries information from the GPU.
\t\nA query can be created with
Query data is typically gathered by issuing an
There are, however, some queries that do not require calls to Begin. For a list of possible queries see
A query is typically executed as shown in the following code:
queryDesc;\t\n ... // Fill out queryDesc structure\t\n * pQuery;\t\n pDevice->CreateQuery(&queryDesc, &pQuery);\t\n pDeviceContext->Begin(pQuery); ... // Issue graphics commands pDeviceContext->End(pQuery);\t\n UINT64 queryData; // This data type is different depending on the query type while( != pDeviceContext->GetData(pQuery, &queryData, sizeof(UINT64), 0) )\t\n {\t\n }\t\n When using a query that does not require a call to Begin, it still requires a call to End. The call to End causes the data returned by GetData to be accurate up until the last call to End.
\t\nGet a query description.
\t\nPointer to a query description (see
Get a query description.
\t\nThe rasterizer-state interface holds a description for rasterizer state that you can bind to the rasterizer stage.
\t\nTo create a rasterizer-state object, call
Gets the description for rasterizer state that you used to create the rasterizer-state object.
\t\nA reference to a
You use the description for rasterizer state in a call to the
Create a rasterizer state object that tells the rasterizer stage how to behave.
\t\n4096 unique rasterizer state objects can be created on a device at a time.
If an application attempts to create a rasterizer-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique rasterizer state objects will stay the same.
\t\nGets the description for rasterizer state that you used to create the rasterizer-state object.
\t\nYou use the description for rasterizer state in a call to the
A render-target-view interface identifies the render-target subresources that can be accessed during rendering.
\t\nTo create a render-target view, call
A rendertarget is a resource that can be written by the output-merger stage at the end of a render pass. Each render-target should also have a corresponding depth-stencil view.
\t\nGet the properties of a render target view.
\t\nPointer to the description of a render target view (see
Get the properties of a render target view.
\t\nThe sampler-state interface holds a description for sampler state that you can bind to any shader stage of the pipeline for reference by texture sample operations.
\t\nTo create a sampler-state object, call
To bind a sampler-state object to any pipeline shader stage, call the following methods:
You can bind the same sampler-state object to multiple shader stages simultaneously.
\t\nGets the description for sampler state that you used to create the sampler-state object.
\t\nA reference to a
You use the description for sampler state in a call to the
Gets the description for sampler state that you used to create the sampler-state object.
\t\nYou use the description for sampler state in a call to the
Sets which direction to perform scans in.
\t\nSetScanDirection sets the direction
Sets which direction to perform scans in.
\t\nDirection to perform scans in. See
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
SetScanDirection sets the direction
Performs an unsegmented scan of a sequence.
\t\nThe type of element in the sequence. See
The binary operation to perform. See
Size of scan in elements.
Input sequence on the device. Set pSrc and pDst to the same value for in-place scans.
Output sequence on the device.
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
You must point the parameters pSrc and pDst to typed buffers (and not to raw or structured buffers). For information about buffer types, see Types of Resources. The format of these typed buffers must be
Performs a multiscan of a sequence.
\t\nThe type of element in the sequence. See
The binary operation to perform. See
Size of scan in elements.
Pitch of the next scan in elements.
Number of scans in the multiscan.
Input sequence on the device. Set pSrc and pDst to the same value for in-place scans.
Output sequence on the device.
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
You must point the parameters pSrc and pDst to typed buffers (and not to raw or structured buffers). For information about buffer types, see Types of Resources. The format of these typed buffers must be
Segmented scan context.
\t\nSets which direction to perform scans in.
\t\nDirection to perform scans in. See
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
SetScanDirection sets the direction
Performs a segmented scan of a sequence.
\t\nThe type of element in the sequence. See
The binary operation to perform. See
Size of scan in elements.
Input sequence on the device. Set pSrc and pDst to the same value for in-place scans.
Compact array of bits with one bit per element of pSrc. A set value indicates the start of a new segment.
Output sequence on the device.
Returns one of the return codes described in the topic Direct3D 11 Return Codes.
You must point the parameters pSrc and pDst to typed buffers (and not to raw or structured buffers). For information about buffer types, see Types of Resources. The format of these typed buffers must be
The format of the resource view to which the pSrcElementFlags parameter points must be
A shader-resource-view interface specifies the subresources a shader can access during rendering. Examples of shader resources include a constant buffer, a texture buffer, a texture or a sampler.
\t\nTo create a shader-resource view, call
A shader-resource view is required when binding a resource to a shader stage; the binding occurs by calling
Get the shader resource view's description.
\t\nA reference to a
Get the shader resource view's description.
\t\nNote??The
Note??The
Reserved.
Note??The
Reserved.
Note??The
A 1D texture interface accesses texel data, which is structured memory.
\t\nTo create an empty 1D texture, call
Textures cannot be bound directly to the pipeline; instead, a view must be created and bound. Using a view, texture data can be interpreted at run time within certain restrictions. To use the texture as a render target or depth-stencil resource, call
Get the properties of the texture resource.
\t\nPointer to a resource description (see
Get the properties of the texture resource.
\t\nA 2D texture interface manages texel data, which is structured memory.
\t\nTo create an empty Texture2D resource, call
Textures cannot be bound directly to the pipeline; instead, a view must be created and bound. Using a view, texture data can be interpreted at run time within certain restrictions. To use the texture as a render target or depth-stencil resource, call
Get the properties of the texture resource.
\t\nPointer to a resource description (see
Get the properties of the texture resource.
\t\nA 3D texture interface accesses texel data, which is structured memory.
\t\nTo create an empty Texture3D resource, call
Textures cannot be bound directly to the pipeline; instead, a view must be created and bound. Using a view, texture data can be interpreted at run time within certain restrictions. To use the texture as a render target or depth-stencil resource, call
Get the properties of the texture resource.
\t\nPointer to a resource description (see
Get the properties of the texture resource.
\t\nA view interface specifies the parts of a resource the pipeline can access during rendering.
\t\nTo create a view for an unordered access resource, call
All resources must be bound to the pipeline before they can be accessed. Call
Get a description of the resource.
\t\nPointer to a resource description (see
Get a description of the resource.
\t\nA vertex-shader interface manages an executable program (a vertex shader) that controls the vertex-shader stage.
\t\nThe vertex-shader interface has no methods; use HLSL to implement your shader functionality. All shaders are implemented from a common set of features referred to as the common-shader core..
To create a vertex shader interface, call
This interface is defined in D3D11.h.
\t\nThe
Sets the constant buffers used by the vertex shader pipeline stage.
\t\nIndex into the device's zero-based array to begin setting constant buffers to (ranges from 0 to
Number of buffers to set (ranges from 0 to
Array of constant buffers (see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The Direct3D 11.1 runtime, which is available starting with Windows Developer Preview, can bind a larger number of
If the application wants the shader to access other parts of the buffer, it must call the VSSetConstantBuffers1 method instead.
\t\nSet a vertex shader to the device.
\t\nPointer to a vertex shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nSet a vertex shader to the device.
\t\nPointer to a vertex shader (see
A reference to an array of class-instance interfaces (see
The number of class-instance interfaces in the array.
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
The maximum number of instances a shader can have is 256.
\t\nBind an array of shader resources to the vertex-shader stage.
\t\nIndex into the device's zero-based array to begin setting shader resources to (range is from 0 to
Number of shader resources to set. Up to a maximum of 128 slots are available for shader resources (range is from 0 to
Array of shader resource view interfaces to set to the device.
If an overlapping resource view is already bound to an output slot, such as a rendertarget, then this API will fill the destination shader resource slot with
For information about creating shader-resource views, see
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSet an array of sampler states to the vertex shader pipeline stage.
\t\nIndex into the device's zero-based array to begin setting samplers to (ranges from 0 to
Number of samplers in the array. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Pointer to an array of sampler-state interfaces (see
Any sampler may be set to
//Default sampler state:\t\n SamplerDesc;\t\n SamplerDesc.Filter = ;\t\n SamplerDesc.AddressU = ;\t\n SamplerDesc.AddressV = ;\t\n SamplerDesc.AddressW = ;\t\n SamplerDesc.MipLODBias = 0;\t\n SamplerDesc.MaxAnisotropy = 1;\t\n SamplerDesc.ComparisonFunc = ;\t\n SamplerDesc.BorderColor[0] = 1.0f;\t\n SamplerDesc.BorderColor[1] = 1.0f;\t\n SamplerDesc.BorderColor[2] = 1.0f;\t\n SamplerDesc.BorderColor[3] = 1.0f;\t\n SamplerDesc.MinLOD = -FLT_MAX;\t\n SamplerDesc.MaxLOD = FLT_MAX; The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nGet the constant buffers used by the vertex shader pipeline stage.
\t\nIndex into the device's zero-based array to begin retrieving constant buffers from (ranges from 0 to
Number of buffers to retrieve (ranges from 0 to
Array of constant buffer interface references (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.
\t\nGet the vertex shader currently set on the device.
\t\nAddress of a reference to a vertex shader (see
Pointer to an array of class instance interfaces (see
The number of class-instance elements in the array.
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.
\t\nGet the vertex shader resources.
\t\nIndex into the device's zero-based array to begin getting shader resources from (ranges from 0 to
The number of resources to get from the device. Up to a maximum of 128 slots are available for shader resources (ranges from 0 to
Array of shader resource view interfaces to be returned 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.
\t\nGet an array of sampler states from the vertex shader pipeline stage.
\t\nIndex into a zero-based array to begin getting samplers from (ranges from 0 to
Number of samplers to get from a device context. Each pipeline stage has a total of 16 sampler slots available (ranges from 0 to
Arry of sampler-state interface references (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.
\t\nDescribes an HLSL class instance.
\t\nThe
The members of this structure except InstanceIndex are valid (non default values) if they describe a class instance aquired using
The instance ID of an HLSL class; the default value is 0.
The instance index of an HLSL class; the default value is 0.
The type ID of an HLSL class; the default value is 0.
Describes the constant buffer associated with an HLSL class; the default value is 0.
The base constant buffer offset associated with an HLSL class; the default value is 0.
The base texture associated with an HLSL class; the default value is 127.
The base sampler associated with an HLSL class; the default value is 15.
True if the class was created; the default value is false.
Information about the video card's performance counter capabilities.
\t\nThis structure is returned by
Largest device-dependent counter ID that the device supports. If none are supported, this value will be 0. Otherwise it will be greater than or equal to
Number of counters that can be simultaneously supported.
Number of detectable parallel units that the counter is able to discern. Values are 1 ~ 4. Use NumDetectableParallelUnits to interpret the values of the VERTEX_PROCESSING, GEOMETRY_PROCESSING, PIXEL_PROCESSING, and OTHER_GPU_PROCESSING counters.
Describes a counter.
\t\nThis structure is used by
Type of counter (see
Reserved.
Stencil operations that can be performed based on the results of stencil test.
\t\nAll stencil operations are specified as a
This structure is a member of a depth-stencil description.
\t\nThe stencil operation to perform when stencil testing fails.
The stencil operation to perform when stencil testing passes and depth testing fails.
The stencil operation to perform when stencil testing and depth testing both pass.
A function that compares stencil data against existing stencil data. The function options are listed in
Specifies the subresources of a texture that are accessible from a depth-stencil view.
\t\nThese are valid formats for a depth-stencil view:
A depth-stencil view cannot use a typeless format. If the format chosen is
A depth-stencil-view description is needed when calling
Resource data format (see
Type of resource (see
A value that describes whether the texture is read only. Pass 0 to specify that it is not read only; otherwise, pass one of the members of the
Specifies a 1D texture subresource (see
Specifies an array of 1D texture subresources (see
Specifies a 2D texture subresource (see
Specifies an array of 2D texture subresources (see
Specifies a multisampled 2D texture (see
Specifies an array of multisampled 2D textures (see
Specifies the subresource from a 2D texture that is accessible to a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
The index of the first mipmap level to use.
Specifies the subresources from an array of 1D textures to use in a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
The index of the first mipmap level to use.
The index of the first texture to use in an array of textures.
Number of textures to use.
Specifies the subresource from a 1D texture that is accessible to a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
The index of the first mipmap level to use.
Specifies the subresources from an array 2D textures that are accessible to a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
The index of the first mipmap level to use.
The index of the first texture to use in an array of textures.
Number of textures to use.
Specifies the subresource from a multisampled 2D texture that is accessible to a depth-stencil view.
\t\nBecause a multisampled 2D texture contains a single subtexture, there is nothing to specify; this unused member is included so that this structure will compile in C.
\t\nUnused.
Specifies the subresources from an array of multisampled 2D textures for a depth-stencil view.
\t\nThis structure is one member of a depth-stencil-view description (see
The index of the first texture to use in an array of textures.
Number of textures to use.
Buffer requirements for an FFT.
\t\nThe
Number of temporary buffers needed. Allowed range is 0 to D3DX11_FFT_MAX_TEMP_BUFFERS.
Number of precompute buffers required. Allowed range is 0 to D3DX11_FFT_MAX_PRECOMPUTE_BUFFERS.
Minimum sizes (in FLOATs) of temporary buffers.
Minimum sizes (in FLOATs) for precompute buffers.
Describes an FFT.
\t\nNumber of dimension in the FFT.
Combination of
Length of each dimension in the FFT.
Describes compute shader and raw and structured buffer support in the current graphics driver.
\t\nDirect3D 11 devices (
TRUE if compute shaders and raw and structured buffers are supported; otherwise
Describes double data type support in the current graphics driver.
\t\nIf the runtime sets DoublePrecisionFloatShaderOps to TRUE, the hardware and driver support the following Shader Model 5 instructions:
Note??If DoublePrecisionFloatShaderOps is TRUE, the hardware and driver do not necessarily support double-precision division.
\t\nSpecifies whether double types are allowed. If TRUE, double types are allowed; otherwise
Describes which resources are supported by the current graphics driver for a given format.
\t\n
Combination of
Describes which unordered resource options are supported by the current graphics driver for a given format.
\t\n
Combination of
Describes the multi-threading features that are supported by the current graphics driver.
\t\nUse the
TRUE means resources can be created concurrently on multiple threads while drawing;
TRUE means command lists are supported by the current driver;
Optionally provide information to texture loader APIs to control how textures get loaded. A value of D3DX11_DEFAULT for any of these parameters will cause D3DX to automatically pick use the value from the source file.
\t\nThis structure is used by methods such as:
The target width of the texture. If the actual width of the texture is larger or smaller than this value then the texture will be scaled up or down to fit this target width.
The target height of the texture. If the actual height of the texture is larger or smaller than this value then the texture will be scaled up or down to fit this target height.
The depth of the texture. This only applies to volume textures.
The number of elements in the array.
The maximum number of mipmap levels in the texture. See the remarks in
Miscellaneous resource properties specified with a
A
A
A
Optionally provide information to texture loader APIs to control how textures get loaded. A value of D3DX11_DEFAULT for any of these parameters will cause D3DX to automatically pick use the value from the source file.
\t\nWhen initializing the structure, you may set any member to D3DX11_DEFAULT and D3DX will initialize it with a default value from the source texture when the texture is loaded.
This structure can be used by APIs that:
The default values are:
Width = D3DX11_DEFAULT; Height = D3DX11_DEFAULT; Depth = D3DX11_DEFAULT; FirstMipLevel = D3DX11_DEFAULT; MipLevels = D3DX11_DEFAULT; Usage = () D3DX11_DEFAULT; BindFlags = D3DX11_DEFAULT; CpuAccessFlags = D3DX11_DEFAULT; MiscFlags = D3DX11_DEFAULT; Format = DXGI_FORMAT_FROM_FILE; Filter = D3DX11_DEFAULT; MipFilter = D3DX11_DEFAULT; pSrcInfo = null ;\t\n Here is a brief example that uses this structure to supply the pixel format when loading a texture. For the complete code, see HDRFormats10.cpp in HDRToneMappingCS11 Sample.
* pCubeRV = null ;\t\n WCHAR strPath[MAX_PATH];\t\n LoadInfo; DXUTFindDXSDKMediaFileCch( strPath, MAX_PATH, L\"Light Probes\\\\uffizi_cross.dds\" ); LoadInfo.Format = ; hr = ( pd3dDevice, strPath, &LoadInfo, null , &pCubeRV, null );\t\n The target width of the texture. If the actual width of the texture is larger or smaller than this value then the texture will be scaled up or down to fit this target width.
The target height of the texture. If the actual height of the texture is larger or smaller than this value then the texture will be scaled up or down to fit this target height.
The depth of the texture. This only applies to volume textures.
The highest resolution mipmap level of the texture. If this is greater than 0, then after the texture is loaded FirstMipLevel will be mapped to mipmap level 0.
The maximum number of mipmap levels in the texture. See the remarks in
The way the texture resource is intended to be used. See
The pipeline stages that the texture will be allowed to bind to. See
The access permissions the cpu will have for the texture resource. See
Miscellaneous resource properties (see
A
Filter the texture using the specified filter (only when resampling). See
Filter the texture mip levels using the specified filter (only if generating mipmaps). Valid values are
Information about the original image. See
Debug message filter; contains a lists of message types to allow or deny.
\t\nFor use with an
Types of messages that you want to allow. See
Types of messages that you want to deny.
Allow or deny certain types of messages to pass through a filter.
\t\nNumber of message categories to allow or deny.
Array of message categories to allow or deny. Array must have at least NumCategories members (see
Number of message severity levels to allow or deny.
Array of message severity levels to allow or deny. Array must have at least NumSeverities members (see
Number of message IDs to allow or deny.
Array of message IDs to allow or deny. Array must have at least NumIDs members (see
A description of a single element for the input-assembler stage.
\t\nAn input-layout object contains an array of structures, each structure defines one element being read from an input slot. Create an input-layout object by calling
The HLSL semantic associated with this element in a shader input-signature.
The semantic index for the element. A semantic index modifies a semantic, with an integer index number. A semantic index is only needed in a case where there is more than one element with the same semantic. For example, a 4x4 matrix would have four components each with the semantic name
matrix, however each of the four component would have different semantic indices (0, 1, 2, and 3).
The data type of the element data. See
An integer value that identifies the input-assembler (see input slot). Valid values are between 0 and 15, defined in D3D11.h.
Optional. Offset (in bytes) between each element. Use D3D11_APPEND_ALIGNED_ELEMENT for convenience to define the current element directly after the previous one, including any packing if necessary.
Identifies the input data class for a single input slot (see
The number of instances to draw using the same per-instance data before advancing in the buffer by one element. This value must be 0 for an element that contains per-vertex data (the slot class is set to
A debug message in the Information Queue.
\t\nThis structure is returned from
The category of the message. See
The severity of the message. See
The ID of the message. See
The message string.
The length of pDescription in bytes.
Query information about graphics-pipeline activity in between calls to
Query information about the reliability of a timestamp query.
\t\nFor a list of query types see
How frequently the GPU counter increments in Hz.
If this is TRUE, something occurred in between the query's
Describes a query.
\t\nType of query (see
Miscellaneous flags (see
Describes the blend state for a render target.
\t\nFor info about how blending is done, see the output-merger stage.
Here are the default values for blend state.
| State | Default Value |
|---|---|
| BlendEnable | |
| SrcBlend | |
| DestBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DestBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask |
?
\t\nEnable (or disable) blending.
This blend option specifies the operation to perform on the RGB value that the pixel shader outputs. The BlendOp member defines how to combine the SrcBlend and DestBlend operations.
This blend option specifies the operation to perform on the current RGB value in the render target. The BlendOp member defines how to combine the SrcBlend and DestBlend operations.
This blend operation defines how to combine the SrcBlend and DestBlend operations.
This blend option specifies the operation to perform on the alpha value that the pixel shader outputs. Blend options that end in _COLOR are not allowed. The BlendOpAlpha member defines how to combine the SrcBlendAlpha and DestBlendAlpha operations.
This blend option specifies the operation to perform on the current alpha value in the render target. Blend options that end in _COLOR are not allowed. The BlendOpAlpha member defines how to combine the SrcBlendAlpha and DestBlendAlpha operations.
This blend operation defines how to combine the SrcBlendAlpha and DestBlendAlpha operations.
A write mask.
Specifies the subresources from a resource that are accessible using a render-target view.
\t\nA render-target-view description is passed into
A render-target-view cannot use the following formats:
If the format is set to
The data format (see
The resource type (see
Specifies which buffer elements can be accessed (see
Specifies the subresources in a 1D texture that can be accessed (see
Specifies the subresources in a 1D texture array that can be accessed (see
Specifies the subresources in a 2D texture that can be accessed (see
Specifies the subresources in a 2D texture array that can be accessed (see
Specifies a single subresource because a multisampled 2D texture only contains one subresource (see
Specifies the subresources in a multisampled 2D texture array that can be accessed (see
Specifies subresources in a 3D texture that can be accessed (see
Specifies the subresources from a an array of multisampled 2D textures to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
The index of the first texture to use in an array of textures.
Number of textures to use.
Specifies the subresource from a 1D texture to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
The index of the mipmap level to use mip slice.
Specifies the subresource from a multisampled 2D texture to use in a render-target view.
\t\nSince a multisampled 2D texture contains a single subresource, there is actually nothing to specify in
Integer of any value. See remarks.
Specifies the subresource from a 2D texture to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
The index of the mipmap level to use mip slice.
Specifies the subresources from an array of 1D textures to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
The index of the mipmap level to use mip slice.
The index of the first texture to use in an array of textures.
Number of textures to use.
Specifies the subresources from a 3D texture to use in a render-target view.
\t\nThis structure is one member of a render target view. See
The index of the mipmap level to use mip slice.
First depth level to use.
Number of depth levels to use in the render-target view, starting from FirstWSlice. A value of -1 indicates all of the slices along the w axis, starting from FirstWSlice.
Specifies the subresources from an array of 2D textures to use in a render-target view.
\t\nThis structure is one member of a render-target-view description (see
The index of the mipmap level to use mip slice.
The index of the first texture to use in an array of textures.
Number of textures in the array to use in the render target view, starting from FirstArraySlice.
Specifies the elements in a buffer resource to use in a render-target view.
\t\nA render-target view is a member of a render-target-view description (see
Number of bytes between the beginning of the buffer and the first element to access.
The offset of the first element in the view to access, relative to element 0.
The total number of elements in the view.
The width of each element (in bytes). This can be determined from the format stored in the render-target-view description.
Defines a 3D box.
\t\nThe following diagram shows a 3D box, where the origin is the left, front, top corner.
The values for right, bottom, and back are each one pixel past the end of the pixels that are included in the box region. That is, the values for left, top, and front are included in the box region while the values for right, bottom, and back are excluded from the box region. For example, for a box that is one pixel wide, (right - left) == 1; the box region includes the left pixel but not the right pixel.
\t\nThe x position of the left hand side of the box.
The y position of the top of the box.
The z position of the front of the box.
The x position of the right hand side of the box.
The y position of the bottom of the box.
The z position of the back of the box.
Describes a sampler state.
\t\nThese are the default values for sampler state.
| State | Default Value |
|---|---|
| Filter | MIN_MAG_MIP_LINEAR |
| AddressU | Clamp |
| AddressV | Clamp |
| AddressW | Clamp |
| MinLOD | -3.402823466e+38F (-FLT_MAX) |
| MaxLOD | 3.402823466e+38F (FLT_MAX) |
| MipMapLODBias | 0.0f |
| MaxAnisotropy | 16 |
| ComparisonFunc | Never |
| BorderColor | float4(0.0f,0.0f,0.0f,0.0f) |
| Texture | N/A |
?
\t\nFiltering method to use when sampling a texture (see
Method to use for resolving a u texture coordinate that is outside the 0 to 1 range (see
Method to use for resolving a v texture coordinate that is outside the 0 to 1 range.
Method to use for resolving a w texture coordinate that is outside the 0 to 1 range.
Offset from the calculated mipmap level. For example, if Direct3D calculates that a texture should be sampled at mipmap level 3 and MipLODBias is 2, then the texture will be sampled at mipmap level 5.
Clamping value used if
A function that compares sampled data against existing sampled data. The function options are listed in
Border color to use if
Lower end of the mipmap range to clamp access to, where 0 is the largest and most detailed mipmap level and any level higher than that is less detailed.
Upper end of the mipmap range to clamp access to, where 0 is the largest and most detailed mipmap level and any level higher than that is less detailed. This value must be greater than or equal to MinLOD. To have no upper limit on LOD set this to a large value such as D3D11_FLOAT32_MAX.
Describes a shader-resource view.
\t\nA view is a format-specific way to look at the data in a resource. The view determines what data to look at, and how it is cast when read.
When viewing a resource, the resource-view description must specify a typed format, that is compatible with the resource format. So that means that you cannot create a resource-view description using any format with _TYPELESS in the name. You can however view a typeless resource by specifying a typed format for the view. For example, a
Create a shader-resource-view description by calling
A
The resource type of the view. See D3D11_SRV_DIMENSION. This should be the same as the resource type of the underlying resource. This parameter also determines which _SRV to use in the union below.
View the resource as a buffer using information from a shader-resource view (see
View the resource as a 1D texture using information from a shader-resource view (see
View the resource as a 1D-texture array using information from a shader-resource view (see
View the resource as a 2D-texture using information from a shader-resource view (see
View the resource as a 2D-texture array using information from a shader-resource view (see
View the resource as a 2D-multisampled texture using information from a shader-resource view (see
View the resource as a 2D-multisampled-texture array using information from a shader-resource view (see
View the resource as a 3D texture using information from a shader-resource view (see
View the resource as a 3D-cube texture using information from a shader-resource view (see
View the resource as a 3D-cube-texture array using information from a shader-resource view (see
View the resource as an extended buffer using information from a shader-resource view (see
Specifies the elements in a buffer resource to use in a shader-resource view.
\t\nThe
Number of bytes between the beginning of the buffer and the first element to access.
The offset of the first element in the view to access, relative to element 0.
The total number of elements in the view.
The width of each element (in bytes). This can be determined from the format stored in the shader-resource-view description.
Specifies the subresource from a cube texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Index of the most detailed mipmap level to use; this number is between 0 and MipLevels (from the original TextureCube for which
The maximum number of mipmap levels for the view of the texture. See the remarks in
Set to -1 to indicate all the mipmap levels from MostDetailedMip on down to least detailed.
Specifies the subresources from a multisampled 2D texture to use in a shader-resource view.
\t\nSince a multisampled 2D texture contains a single subresource, there is actually nothing to specify in
Integer of any value. See remarks.
Specifies the subresources from an array of cube textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Index of the most detailed mipmap level to use; this number is between 0 and MipLevels (from the original TextureCube for which
The maximum number of mipmap levels for the view of the texture. See the remarks in
Set to -1 to indicate all the mipmap levels from MostDetailedMip on down to least detailed.
Index of the first 2D texture to use.
Number of cube textures in the array.
Specifies the subresources from a 3D texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Index of the most detailed mipmap level to use; this number is between 0 and MipLevels (from the original Texture3D for which
The maximum number of mipmap levels for the view of the texture. See the remarks in
Set to -1 to indicate all the mipmap levels from MostDetailedMip on down to least detailed.
Specifies the subresource from a 2D texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Index of the most detailed mipmap level to use; this number is between 0 and MipLevels (from the original Texture2D for which
The maximum number of mipmap levels for the view of the texture. See the remarks in
Set to -1 to indicate all the mipmap levels from MostDetailedMip on down to least detailed.
Specifies the subresources from an array of 1D textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Index of the most detailed mipmap level to use; this number is between 0 and MipLevels (from the original Texture1D for which
The maximum number of mipmap levels for the view of the texture. See the remarks in
Set to -1 to indicate all the mipmap levels from MostDetailedMip on down to least detailed.
The index of the first texture to use in an array of textures.
Number of textures in the array.
Specifies the subresource from a 1D texture to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
As an example, assuming MostDetailedMip = 6 and MipLevels = 2, the view will have access to 2 mipmap levels, 6 and 7, of the original texture for which
Index of the most detailed mipmap level to use; this number is between 0 and MipLevels (from the original Texture1D for which
The maximum number of mipmap levels for the view of the texture. See the remarks.
Set to -1 to indicate all the mipmap levels from MostDetailedMip on down to least detailed.
Specifies the subresources from an array of 2D textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
Index of the most detailed mipmap level to use; this number is between 0 and MipLevels (from the original Texture2D for which
The maximum number of mipmap levels for the view of the texture. See the remarks in
Set to -1 to indicate all the mipmap levels from MostDetailedMip on down to least detailed.
The index of the first texture to use in an array of textures.
Number of textures in the array.
Specifies the subresources from an array of multisampled 2D textures to use in a shader-resource view.
\t\nThis structure is one member of a shader-resource-view description (see
The index of the first texture to use in an array of textures.
Number of textures to use.
Describes a raw buffer resource.
\t\nThis structure is used by
The index of the first element to be accessed by the view.
The number of elements in the resource.
Options for binding a raw buffer (see
Description of a vertex element in a vertex buffer in an output slot.
\t\nZero-based, stream number.
Type of output element; possible values include: \"POSITION\", \"NORMAL\", or \"TEXCOORD0\". Note that if SemanticName is
Output element's zero-based index. Should be used if, for example, you have more than one texture coordinate stored in each vertex.
Which component of the entry to begin writing out to. Valid values are 0 to 3. For example, if you only wish to output to the y and z components of a position, then StartComponent should be 1 and ComponentCount should be 2.
The number of components of the entry to write out to. Valid values are 1 to 4. For example, if you only wish to output to the y and z components of a position, then StartComponent should be 1 and ComponentCount should be 2. Note that if SemanticName is
The associated stream output buffer that is bound to the pipeline (see
Query information about the amount of data streamed out to the stream-output buffers in between
Describes a 1D texture.
\t\nThis structure is used in a call to
The texture size range is determined by the feature level at which you create the device and not the Microsoft Direct3D interface version. For example, if you use Microsoft Direct3D?10 hardware at feature level 10 (
Texture width (in texels). The range is from 1 to
The maximum number of mipmap levels in the texture. See the remarks in
Number of textures in the array. The range is from 1 to
Texture format (see
Value that identifies how the texture is to be read from and written to. The most common value is
Flags (see
Flags (see
Flags (see
Describes a 2D texture.
\t\nThis structure is used in a call to
The device places some size restrictions (must be multiples of a minimum size) for a subsampled, block compressed, or bit-format resource.
The texture size range is determined by the feature level at which you create the device and not the Microsoft Direct3D interface version. For example, if you use Microsoft Direct3D?10 hardware at feature level 10 (
Texture width (in texels). The range is from 1 to
Texture height (in texels). The range is from 1 to
The maximum number of mipmap levels in the texture. See the remarks in
Number of textures in the texture array. The range is from 1 to
Texture format (see
Structure that specifies multisampling parameters for the texture. See
Value that identifies how the texture is to be read from and written to. The most common value is
Flags (see
Flags (see
Flags (see
Describes a 3D texture.
\t\nThis structure is used in a call to
The device restricts the size of subsampled, block compressed, and bit format resources to be multiples of sizes specific to each format.
The texture size range is determined by the feature level at which you create the device and not the Microsoft Direct3D interface version. For example, if you use Microsoft Direct3D?10 hardware at feature level 10 (
Texture width (in texels). The range is from 1 to
Texture height (in texels). The range is from 1 to
Texture depth (in texels). The range is from 1 to
The maximum number of mipmap levels in the texture. See the remarks in
Texture format (see
Value that identifies how the texture is to be read from and written to. The most common value is
Flags (see
Flags (see
Flags (see
Describes parameters used to load a texture from another texture.
\t\nThis structure is used in a call to
The default values are:
pSrcBox = null ; pDstBox = null ; SrcFirstMip = 0; DstFirstMip = 0; NumMips = D3DX11_DEFAULT; SrcFirstElement = 0; DstFirstElement = 0; NumElements = D3DX11_DEFAULT; Filter = D3DX11_DEFAULT; MipFilter = D3DX11_DEFAULT;\t\n Source texture box (see
Destination texture box (see
Source texture mipmap level, see D3D11CalcSubresource for more detail.
Destination texture mipmap level, see D3D11CalcSubresource for more detail.
Number of mipmap levels in the source texture.
First element of the source texture.
First element of the destination texture.
Number of elements to load.
Filtering options during resampling (see
Filtering options when generating mip levels (see
Specifies the subresources from a resource that are accessible using an unordered-access view.
\t\nAn unordered-access-view description is passed into
The data format (see
The resource type (see
Specifies which buffer elements can be accessed (see
Specifies the subresources in a 1D texture that can be accessed (see
Specifies the subresources in a 1D texture array that can be accessed (see
Specifies the subresources in a 2D texture that can be accessed (see
Specifies the subresources in a 2D texture array that can be accessed (see
Specifies subresources in a 3D texture that can be accessed (see
Describes an array of unordered-access 1D texture resources.
\t\nThis structure is used by a
The mipmap slice index.
The zero-based index of the first array slice to be accessed.
The number of slices in the array.
Unordered-access-view buffer options.
\t\nResource contains raw, unstructured data. Requires the UAV format to be
Allow data to be appended to the end of the buffer.
Adds a counter to the unordered-access-view buffer.
Describes a unordered-access 1D texture resource.
\t\nThis structure is used by a
The mipmap slice index.
Describes a unordered-access 2D texture resource.
\t\nThis structure is used by a
The mipmap slice index.
Describes an array of unordered-access 2D texture resources.
\t\nThis structure is used by a
The mipmap slice index.
The zero-based index of the first array slice to be accessed.
The number of slices in the array.
Describes a unordered-access 3D texture resource.
\t\nThis structure is used by a
The mipmap slice index.
The zero-based index of the first depth slice to be accessed.
The number of depth slices.
Contains information identifying the adapter.
\t\nThe following pseudocode example illustrates the version format encoded in the DriverVersion, DriverVersionLowPart, and DriverVersionHighPart members.
Product = HIWORD(DriverVersion.HighPart)\t\n Version = LOWORD(DriverVersion.HighPart)\t\n SubVersion = HIWORD(DriverVersion.LowPart)\t\n Build = LOWORD(DriverVersion.LowPart)\t\n See the Platform SDK for more information about the HIWORD macro, the LOWORD macro, and the
MAX_DEVICE_IDENTIFIER_STRING is a constant with the following definition.
#define MAX_DEVICE_IDENTIFIER_STRING 512The VendorId, DeviceId, SubSysId, and Revision members can be used in tandem to identify particular chip sets. However, use these members with caution.
\t\nUsed for presentation to the user. This should not be used to identify particular drivers, because many different strings might be associated with the same device and driver from different vendors.
Used for presentation to the user.
Device name for GDI.
Identify the version of the Direct3D driver. It is legal to do less than and greater than comparisons on the 64-bit signed integer value. However, exercise caution if you use this element to identify problematic drivers. Instead, you should use DeviceIdentifier. See Remarks.
Identify the version of the Direct3D driver. It is legal to do < and > comparisons on the 64-bit signed integer value. However, exercise caution if you use this element to identify problematic drivers. Instead, you should use DeviceIdentifier. See Remarks.
Identify the version of the Direct3D driver. It is legal to do < and > comparisons on the 64-bit signed integer value. However, exercise caution if you use this element to identify problematic drivers. Instead, you should use DeviceIdentifier. See Remarks.
Can be used to help identify a particular chip set. Query this member to identify the manufacturer. The value can be zero if unknown.
Can be used to help identify a particular chip set. Query this member to identify the type of chip set. The value can be zero if unknown.
Can be used to help identify a particular chip set. Query this member to identify the subsystem, typically the particular board. The value can be zero if unknown.
Can be used to help identify a particular chip set. Query this member to identify the revision level of the chip set. The value can be zero if unknown.
Sets a non-transposed matrix.
\t\nA non-transposed matrix contains row-major data. In other words, each vector is contained in a row.
If the destination matrix is smaller than the source matrix, the additional components of the source matrix will be ignored.
\t\nGets the effect description.
\t\nReturns a description of the effect. See
If the method succeeds, the return value is
Gets a parameter or annotation description.
\t\nParameter or annotation handle. See Handles (Direct3D 9).
Returns a description of the specified parameter or annotation. See
Gets a technique description.
\t\nTechnique handle. See Handles (Direct3D 9).
Returns a description of the technique. See
Gets a pass description.
\t\nPass handle. See Handles (Direct3D 9).
Returns a description of the specified pass. See
Note??If an effect is created with
Gets a function description.
\t\nFunction handle. See Handles (Direct3D 9).
Returns a description of the function. See
Gets the handle of a top-level parameter or a structure member parameter.
\t\nHandle of the parameter, or
Parameter index.
Returns the handle of the specified parameter, or
Gets the handle of a top-level parameter or a structure member parameter by looking up its name.
\t\nHandle of the parameter, or
String containing the parameter name.
Returns the handle of the specified parameter, or
Gets the handle of a top-level parameter or a structure member parameter by looking up its semantic with a case-insensitive search.
\t\nHandle of the parameter, or
String containing the semantic name.
Returns the handle of the first parameter that matches the specified semantic, or
Get the handle of an array element parameter.
\t\nHandle of the array. See Handles (Direct3D 9).
Array element index.
Returns the handle of the specified parameter, or
This method is used to get an element of a parameter that is an array.
\t\nGets the handle of a technique.
\t\nTechnique index.
Returns the handle of the specified technique, or
Gets the handle of a technique by looking up its name.
\t\nString containing the technique name.
Returns the handle of the first technique that has the specified name, or
Gets the handle of a pass.
\t\nHandle of the parent technique. See Handles (Direct3D 9).
Index for the pass.
Returns the handle of the specified pass inside the specified technique, or
Gets the handle of a pass by looking up its name.
\t\nHandle of the parent technique. See Handles (Direct3D 9).
String containing the pass name.
Returns the handle of the first pass inside the specified technique that has the specified name, or
Gets the handle of a function.
\t\nFunction index.
Returns the handle of the specified function, or
Gets the handle of a function by looking up its name.
\t\nString containing the function name.
Returns the handle of the specified function, or
Gets the handle of an annotation.
\t\nHandle of a technique, pass, or top-level parameter. See Handles (Direct3D 9).
Annotation index.
Returns the handle of the specified annotation, or
Annotations are user-specific data that can be attached to any technique, pass, or parameter. See Handles (Direct3D 9).
\t\nGets the handle of an annotation by looking up its name.
\t\nHandle of a technique, pass, or top-level parameter. See Handles (Direct3D 9).
String containing the annotation name.
Returns the handle of the specified annotation, or
Set the value of an arbitrary parameter or annotation, including simple types, structs, arrays, strings, shaders and textures.
\t\nUnique identifier. See Handles (Direct3D 9).
Pointer to a buffer containing data.
[in] Number of bytes in the buffer. Pass in D3DX_DEFAULT if you know your buffer is large enough to contain the entire parameter, and you want to skip size validation.
If the method succeeds, the return value is
This method can be used in place of nearly all the effect set API calls.
\t\nGet the value of an arbitrary parameter or annotation, including simple types, structs, arrays, strings, shaders and textures. This method can be used in place of nearly all the Getxxx calls in
If the method succeeds, the return value is
Sets a
Unique identifier. See Handles (Direct3D 9).
Boolean value.
If the method succeeds, the return value is
Gets a
Unique identifier. See Handles (Direct3D 9).
Returns a Boolean value.
If the method succeeds, the return value is
Sets an array of Boolean values.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of Boolean values.
Number of Boolean values in the array.
If the method succeeds, the return value is
Gets an array of
Unique identifier. See Handles (Direct3D 9).
Returns an array of Boolean values.
Number of Boolean values in the array.
If the method succeeds, the return value is
Sets an integer.
\t\nUnique identifier. See Handles (Direct3D 9).
Integer value.
If the method succeeds, the return value is
Gets an integer.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns an integer.
If the method succeeds, the return value is
Sets an array of integers.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of integers.
Number of integers in the array.
If the method succeeds, the return value is
Gets an array of integers.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns an array of integers.
Number of integers in the array.
If the method succeeds, the return value is
Sets a floating point value.
\t\nUnique identifier. See Handles (Direct3D 9).
Floating point value.
If the method succeeds, the return value is
Gets a floating point value.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a floating point value.
If the method succeeds, the return value is
Sets an array of floating point values.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of floating point values.
Number of floating point values in the array.
If the method succeeds, the return value is
Gets an array of floating point values.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns an array of floating point values.
Number of floating point values in the array.
If the method succeeds, the return value is
Sets a vector.
\t\nUnique identifier. See Handles (Direct3D 9).
Pointer to a 4D vector.
If the method succeeds, the return value is
If the destination vector is smaller than the source vector, the additional components of the source vector will be ignored.
\t\nGets a vector.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a 4D vector.
If the method succeeds, the return value is
If the destination vector is larger than the source vector, only the initial components of the destination vector will be filled, and the remaining components will be set to zero.
\t\nSets an array of vectors.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of 4D floating point vectors.
Number of vectors in the array.
If the method succeeds, the return value is
If the destination vectors are smaller than the source vectors, the additional components of the source vectors will be ignored.
\t\nGets an array of vectors.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns an array of 4D floating point vectors.
Number of vectors in the array.
If the method succeeds, the return value is
If the destination vectors are larger than the source vectors, only the initial components of each destination vector will be filled, and the remaining destination vector components will be set to zero.
\t\nSets a non-transposed matrix.
\t\nUnique identifier. See Handles (Direct3D 9).
Pointer to a nontransposed matrix. See
If the method succeeds, the return value is
A non-transposed matrix contains row-major data. In other words, each vector is contained in a row.
If the destination matrix is smaller than the source matrix, the additional components of the source matrix will be ignored.
\t\nGets a nontransposed matrix.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a nontransposed matrix. See
If the method succeeds, the return value is
A nontransposed matrix contains row-major data; that is, each vector is contained in a row.
If the destination matrix is larger than the source matrix, only the upper-left components of the destination matrix will be filled, and the remaining components will be set to zero.
\t\nSets an array of nontransposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of nontransposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A nontransposed matrix contains row-major data; that is, each vector is contained in a row.
If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.
\t\nGets an array of nontransposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns an array of nontransposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A nontransposed matrix contains row-major data; that is, each vector is contained in a row.
If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.
\t\nSets an array of references to nontransposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of references to nontransposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A nontransposed matrix contains row-major data; that is, each vector is contained in a row.
If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.
\t\nGets an array of references to nontransposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of references to nontransposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A nontransposed matrix contains row-major data; that is, each vector is contained in a row.
If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.
\t\nSets a transposed matrix.
\t\nUnique identifier. See Handles (Direct3D 9).
Pointer to a transposed matrix. See
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
If the destination matrix is smaller than the source matrix, the additional components of the source matrix will be ignored.
\t\nGets a transposed matrix.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a transposed matrix. See
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
If the destination matrix is larger than the source matrix, only the upper-left elements of the destination matrix will be filled, and the remaining destination matrix components will be set to zero.
\t\nSets an array of transposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.
\t\nGets an array of transposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns an array of transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.
\t\nSets an array of references to transposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of references to transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
If the destination matrices are smaller than the source matrices, the additional components of the source matrices will be ignored.
\t\nGets an array of references to transposed matrices.
\t\nUnique identifier. See Handles (Direct3D 9).
Array of references to transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
If the destination matrices are larger than the source matrices, only the upper-left components of each destination matrix will be filled, and the remaining destination matrix components will be set to zero.
\t\nSets a string.
\t\nUnique identifier. See Handles (Direct3D 9).
String to set.
If the method succeeds, the return value is
Gets a string.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a string identified by hParameter.
Sets a texture.
\t\nUnique identifier. See Handles (Direct3D 9).
Texture object. See
If the method succeeds, the return value is
Gets a texture.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a texture object. See
Gets a pixel shader.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a pixel shader object. See
Gets a vertex shader.
\t\nUnique identifier. See Handles (Direct3D 9).
Returns a vertex shader object. See
Set the range of an array to pass to the device.
\t\nUnique identifier. See Handles (Direct3D 9).
Start index.
Stop index.
If the method succeeds, the return value is
Gets the effect description.
\t\nApplications use the methods of the
The
The LPDIRECT3DBASETEXTURE9 and PDIRECT3DBASETEXTURE9 types are defined as references to the
typedef struct *LPDIRECT3DBASETEXTURE9, *PDIRECT3DBASETEXTURE9; Applications use the methods of the
To create a texture resource, you can call one of the following methods.
To create a geometry-oriented resource, you can call one of the following methods.
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DRESOURCE9 and PDIRECT3DRESOURCE9 types are defined as references to the
typedef struct *LPDIRECT3DRESOURCE9, *PDIRECT3DRESOURCE9;\t\n Retrieves the device associated with a resource.
\t\nAddress of a reference to an
If the method succeeds, the return value is
This method allows navigation to the owning device object.
Calling this method will increase the internal reference count on the
Associates data with the resource that is intended for use by the application, not by Direct3D. Data is passed by value, and multiple sets of data can be associated with a single resource.
\t\nReference to the globally unique identifier that identifies the private data to set.
Pointer to a buffer that contains the data to be associated with the resource.
Size of the buffer at pData, in bytes.
Value that describes the type of data being passed, or indicates to the application that the data should be invalidated when the resource changes.
| Item | Description |
|---|---|
| (none) | If no flags are specified, Direct3D allocates memory to hold the data within the buffer and copies the data into the new buffer. The buffer allocated by Direct3D is automatically freed, as appropriate. |
| D3DSPD_IUNKNOWN | The data at pData is a reference to an |
?
If the method succeeds, the return value is
Direct3D does not manage the memory at pData. If this buffer was dynamically allocated, it is the calling application's responsibility to free the memory.
\t\nCopies the private data associated with the resource to a provided buffer.
\t\nThe globally unique identifier that identifies the private data to retrieve.
Pointer to a previously allocated buffer to fill with the requested private data if the call succeeds. The application calling this method is responsible for allocating and releasing this buffer. If this parameter is
Pointer to the size of the buffer at pData, in bytes. If this value is less than the actual size of the private data (such as 0), the method sets this parameter to the required buffer size and the method returns
If the method succeeds, the return value is
This method is inherited by the following interfaces:
Frees the specified private data associated with this resource.
\t\nReference to the globally unique identifier that identifies the private data to free.
If the method succeeds, the return value is
Direct3D calls this method automatically when a resource is released.
\t\nAssigns the priority of a resource for scheduling purposes.
\t\nPriority to assign to a resource.
| Differences between Direct3D 9 and Direct3D 9 for Windows Vista The priority can be any DWORD value; Direct3D 9 for Windows Vista also supports any of these pre-defined values D3D9_RESOURCE_PRIORITY. |
?
Returns the previous priority value for the resource.
This method is used to change the priority of managed resources (resources created with the
Priorities are used to determine when managed resources are to be removed from memory. A resource assigned a low priority is removed before a resource with a high priority. If two resources have the same priority, the resource that was used more recently is kept in memory; the other resource is removed. Managed resources have a default priority of 0.
Windows Vista only - When this method is called using an
Retrieves the priority for this resource.
\t\nReturns a DWORD value, indicating the priority of the resource.
Priorities are used to determine when managed resources are to be removed from memory. A resource assigned a low priority is removed before a resource with a high priority. If two resources have the same priority, the resource that was used more recently is kept in memory; the other resource is removed. Managed resources have a default priority of 0.
\t\nPreloads a managed resource.
\t\nCalling this method indicates that the application will need this managed resource shortly. This method has no effect on nonmanaged resources.
Returns the type of the resource.
\t\nReturns a member of the
Retrieves the device associated with a resource.
\t\nThis method allows navigation to the owning device object.
Calling this method will increase the internal reference count on the
Retrieves the priority for this resource.
\t\nPriorities are used to determine when managed resources are to be removed from memory. A resource assigned a low priority is removed before a resource with a high priority. If two resources have the same priority, the resource that was used more recently is kept in memory; the other resource is removed. Managed resources have a default priority of 0.
\t\nReturns the type of the resource.
\t\nSets the most detailed level-of-detail for a managed texture.
\t\nMost detailed level-of-detail value to set for the mipmap chain.
A DWORD value, clamped to the maximum level-of-detail value (one less than the total number of levels). Subsequent calls to this method will return the clamped value, not the level-of-detail value that was previously set.
This method applies to the following interfaces, which inherit from
SetLOD is used for level-of-detail control of managed textures. This method returns 0 on nonmanaged textures.
SetLOD communicates to the Direct3D texture manager the most detailed mipmap in the chain that should be loaded into local video memory. For example, in a five-level mipmap chain, setting LODNew to 2 indicates that the texture manager should load only mipmap levels 2 through 4 into local video memory at any given time.
More specifically, if the texture was created with the dimensions of 256x256, setting the most detailed level to 0 indicates that 256 x 256 is the largest mipmap available, setting the most detailed level to 1 indicates that 128 x 128 is the largest mipmap available, and so on, up to the most detailed mip level (the smallest texture size) for the chain.
\t\nReturns a value clamped to the maximum level-of-detail set for a managed texture (this method is not supported for an unmanaged texture).
\t\nA DWORD value, clamped to the maximum level-of-detail value (one less than the total number of levels). Calling GetLOD on an unmanaged texture is not supported and will result in a D3DERR error code being returned.
Returns the number of texture levels in a multilevel texture.
\t\nA DWORD value indicating the number of texture levels in a multilevel texture.
This method applies to the following interfaces, which inherit from
Set the filter type that is used for automatically generated mipmap sublevels.
\t\nFilter type. See
If the method succeeds, the return value is
Changing the filter type \"dirties\" the mipmap sublevels and causes them to be regenerated.
The (default) filter type set at texture creation time is
This method has no effect if the texture is not created with
Get the filter type that is used for automatically generated mipmap sublevels.
\t\nFilter type. See
Changing the filter type \"dirties\" the mipmap sublevels and causes them to be regenerated.
The (default) filter type set at texture creation time is
This method has no effect if the texture is not created with
Generate mipmap sublevels.
\t\nAn application can generate mipmap sublevels at any time by calling GenerateMipSubLevels. To have mipmap sublevels generated automatically at texture creation time (see Automatic Generation of Mipmaps (Direct3D 9)), specify
Returns the number of texture levels in a multilevel texture.
\t\nThis method applies to the following interfaces, which inherit from
Get or sets the filter type that is used for automatically generated mipmap sublevels.
\t\nChanging the filter type \"dirties\" the mipmap sublevels and causes them to be regenerated.
The (default) filter type set at texture creation time is
This method has no effect if the texture is not created with
Describes a subset of the mesh that has the same attribute and bone combination.
\t\nThe subset of the mesh described by
Attribute table identifier.
Starting face.
Face count.
Starting vertex.
Vertex count.
Pointer to an array of values that identify each of the bones that can be drawn in a single drawing call. Note that the array can be of variable length to accommodate variable length bone combinations of ConvertToIndexedBlendedMesh.
The size of the array varies based on the type of mesh generated. A non-indexed mesh array size is equal to the number of weights per vertex (pMaxVertexInfl in ConvertToBlendedMesh). An indexed mesh array size is equal to the number of bone matrix palette entries (paletteSize in ConvertToIndexedBlendedMesh).
The
The LPD3DXCONSTANTTABLE type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DXCONSTANTTABLE;\t\n Gets a reference to the buffer that contains the constant table.
\t\nReturns a reference the buffer.
Gets the buffer size of the constant table.
\t\nReturns the size of the buffer, in bytes.
Gets a description of the constant table.
\t\nDescription of the constant table. See
If the method succeeds, the return value is
Gets a reference to an array of constant descriptions in the constant table.
\t\nUnique identifier to a constant. See
Returns a reference to an array of descriptions. See
The input supplied must be the maximum size of the array. The output is the number of elements that are filled in the array when the function returns.
If the method succeeds, the return value is
Because a sampler can appear more than once in a constant table, this method can return an array of descriptions, each one with a different register index.
\t\nReturns the sampler index.
\t\nThe sampler handle.
Returns the sampler index number from the constant table.
Gets a constant by looking up its index.
\t\nUnique identifier to the parent data structure. If the constant is a top-level parameter (there is no parent data structure), use
Zero-based index of the constant.
Returns a unique identifier to the constant.
To get a constant from an array of constants, use
Gets a constant by looking up its name.
\t\nUnique identifier to the parent data structure. If the constant is a top-level parameter (there is no parent data structure), use
Name of the constant.
Returns a unique identifier to the constant.
Gets a constant from an array of constants. An array is made up of elements.
\t\nUnique identifier to the array of constants. This value may not be
Zero-based index of the element in the array.
Returns a unique identifier to the element constant.
To get a constant that is not part of an array, use
Sets the constants to their default values. The default values are declared in the variable declarations in the shader.
\t\nPointer to an
If the method succeeds, the return value is
Sets the contents of the buffer to the constant table.
\t\nPointer to an
Unique identifier to a constant. See
Buffer containing data.
Size of the buffer, in bytes.
If the method succeeds, the return value is
Sets a Boolean value.
\t\nPointer to an
Unique identifier to the constant. See
Boolean value.
If the method succeeds, the return value is
Sets an array of Boolean values.
\t\nPointer to an
Unique identifier to the array of constants. See
Array of Boolean values.
Number of Boolean values in the array.
If the method succeeds, the return value is
Sets an integer value.
\t\nPointer to an
Unique identifier to the constant. See
Integer.
If the method succeeds, the return value is
Sets an array of integers.
\t\nPointer to an
Unique identifier to the array of constants. See
Array of integers.
Number of integers in the array.
If the method succeeds, the return value is
Sets a floating-point number.
\t\nPointer to an
Unique identifier to the constant. See
Floating-point number.
If the method succeeds, the return value is
Sets an array of floating-point numbers.
\t\nPointer to an
Unique identifier to the array of constants. See
Array of floating-point numbers.
Number of floating-point values in the array.
If the method succeeds, the return value is
Sets a 4D vector.
\t\nPointer to an
Unique identifier to the vector constant. See
Pointer to a 4D vector.
If the method succeeds, the return value is
Sets an array of 4D vectors.
\t\nPointer to an
Unique identifier to the array of vector constants. See
Array of 4D vectors.
Number of vectors in the array.
If the method succeeds, the return value is
Sets a nontransposed matrix.
\t\nPointer to an
Unique identifier to the matrix of constants. See
Pointer to a nontransposed matrix. See
If the method succeeds, the return value is
Sets an array of nontransposed matrices.
\t\nPointer to an
Unique identifier to the array of constant matrices. See
Array of nontransposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
Sets an array of references to nontransposed matrices.
\t\nPointer to an
Unique identifier to an array of constant matrices. See
Array of references to nontransposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A nontransposed matrix contains row-major data; that is, each vector is contained in a row.
\t\nSets a transposed matrix.
\t\nPointer to an
Unique identifier to the matrix of constants. See
Pointer to a transposed matrix. See
If the method succeeds, the return value is
Sets an array of transposed matrices.
\t\nPointer to an
Unique identifier to the array of matrix constants. See
Array of transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
Sets an array of references to transposed matrices.
\t\nPointer to an
Unique identifier to the array of matrix constants. See
Array of references to transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
\t\nGets a reference to the buffer that contains the constant table.
\t\nGets the buffer size of the constant table.
\t\nGets a description of the constant table.
\t\nInformation about the properties of a display mode.
\t\nThis structure is used in various methods to create and manage Direct3D 9Ex devices (
The size of this structure. This should always be set to sizeof(
Width of the display mode.
Height of the display mode.
Refresh rate of the display mode.
Format of the display mode. See
Indicates whether the scanline order is progressive or interlaced. See
Describes the display mode.
\t\nScreen width, in pixels.
Screen height, in pixels.
Refresh rate. The value of 0 indicates an adapter default.
Member of the
Applications use the methods of the
The
This interface inherits additional functionality from the
This interface, like all COM interfaces, inherits additional functionality from the
The LPDIRECT3DCUBETEXTURE9 and PDIRECT3DCubeTexture9 types are defined as references to the
typedef struct *LPDIRECT3DCUBETEXTURE9, *PDIRECT3DCubeTexture9;\t\n Retrieves a description of one face of the specified cube texture level.
\t\nSpecifies a level of a mipmapped cube texture.
Pointer to a
The
Retrieves a cube texture map surface.
\t\nMember of the
Specifies a level of a mipmapped cube texture.
Address of a reference to an
Calling this method will increase the internal reference count on the
Locks a rectangle on a cube texture resource.
\t\nMember of the
Specifies a level of a mipmapped cube texture.
Pointer to a
Pointer to a rectangle to lock. Specified by a reference to a
Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
You may not specify a subrect when using
If the method succeeds, the return value is
For performance reasons, dirty regions are only recorded for level zero of a texture. Dirty regions are automatically recorded when
Cube textures created with
The only lockable format for a depth-stencil texture is
Unlocks a rectangle on a cube texture resource.
\t\nMember of the
Specifies a level of a mipmapped cube texture.
If the method succeeds, the return value is
Adds a dirty region to a cube texture resource.
\t\nMember of the
Pointer to a
If the method succeeds, the return value is
For performance reasons, dirty regions are only recorded for level zero of a texture. For sublevels, it is assumed that the corresponding (scaled) rectangle or box is also dirty. Dirty regions are automatically recorded when
Using
Applications use the methods of the
The
This interface, like all COM interfaces, inherits the
The LPDIRECT3DDEVICE9 and PDIRECT3DDEVICE9 types are defined as references to the
typedef struct *LPDIRECT3DDEVICE9, *PDIRECT3DDEVICE9;\t\n Reports the current cooperative-level status of the Direct3D device for a windowed or full-screen application.
\t\nIf the method succeeds, the return value is
If the device is lost but cannot be restored at the current time,
A call to
Returns an estimate of the amount of available texture memory.
\t\nThe function returns an estimate of the available texture memory.
The returned value is rounded to the nearest MB. This is done to reflect the fact that video memory estimates are never precise due to alignment and other issues that affect consumption by certain resources. Applications can use this value to make gross estimates of memory availability to make large-scale resource decisions such as how many levels of a mipmap to attempt to allocate, but applications cannot use this value to make small-scale decisions such as if there is enough memory left to allocate another resource.
\t\nEvicts all managed resources, including both Direct3D and driver-managed resources.
\t\nIf the method succeeds, the return value is
This function causes only the
Returns an interface to the instance of the Direct3D object that created the device.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Calling
Retrieves the capabilities of the rendering device.
\t\nPointer to a
If the method succeeds, the return value is
Retrieves the display mode's spatial resolution, color resolution, and refresh frequency.
\t\nAn unsigned integer specifying the swap chain.
Pointer to a
Retrieves the creation parameters of the device.
\t\nPointer to a
If the method succeeds, the return value is
You can query the AdapterOrdinal member of the returned
Sets properties for the cursor.
\t\nX-coordinate offset (in pixels) that marks the center of the cursor. The offset is relative to the upper-left corner of the cursor. When the cursor is given a new position, the image is drawn at an offset from this new position determined by subtracting the hot spot coordinates from the position.
Y-coordinate offset (in pixels) that marks the center of the cursor. The offset is relative to the upper-left corner of the cursor. When the cursor is given a new position, the image is drawn at an offset from this new position determined by subtracting the hot spot coordinates from the position.
Pointer to an
If the method succeeds, the return value is
An operating system cursor is created and used under either of these conditions:
Otherwise, DirectX uses an emulated cursor. An application uses
It is recommended for applications to always trap WM_MOUSEMOVE events and call DXSetCursorPosition.
Direct3D cursor functions use either GDI cursor or software emulation, depending on the hardware. Users typically want to respond to a WM_SETCURSOR message. For example, they might want to write the message handler as follows:
case WM_SETCURSOR:\t\n // Turn off window cursor. \t\n SetCursor( null );\t\n m_pd3dDevice->ShowCursor( TRUE );\t\n return TRUE; // Prevent Windows from setting cursor to window class cursor.\t\n break;\t\n Or, users might want to call the
The application can determine what hardware support is available for cursors by examining appropriate members of the
The cursor does not survive when the device is lost. This method must be called after the device is reset.
\t\nSets the cursor position and update options.
\t\nThe new X-position of the cursor in virtual desktop coordinates. See Remarks.
The new Y-position of the cursor in virtual desktop coordinates. See Remarks.
Specifies the update options for the cursor. Currently, only one flag is defined.
| Value | Meaning |
|---|---|
| Update cursor at the refresh rate. If this flag is specified, the system guarantees that the cursor will be updated at a minimum of half the display refresh rate, but never more frequently than the display refresh rate. Otherwise, the method delays cursor updates until the next |
?
When running in full-screen mode, screen space coordinates are the back buffer coordinates appropriately scaled to the current display mode. When running in windowed mode, screen space coordinates are the desktop coordinates. The cursor image is drawn at the specified position minus the hotspot-offset specified by the SetCursorProperties method.
If the cursor has been hidden by ShowCursor, the cursor is not drawn.
\t\nDisplays or hides the cursor.
\t\nIf bShow is TRUE, the cursor is shown. If bShow is
Value indicating whether the cursor was previously visible. TRUE if the cursor was previously visible, or
Direct3D cursor functions use either GDI cursor or software emulation, depending on the hardware. Users usually want to respond to a WM_SETCURSOR message. For example, the users might want to write the message handler like this:
case WM_SETCURSOR: // Turn off window cursor SetCursor( null ); m_pd3dDevice->ShowCursor( TRUE ); return TRUE; // prevent Windows from setting cursor to window class cursor break;\t\n Or users might want to call the
Creates an additional swap chain for rendering multiple views.
\t\nPointer to a
Calling this method changes the value of members of the
Address of a reference to an
If the method succeeds, the return value is
There is always at least one swap chain (the implicit swap chain) for each device because Direct3D 9 has one swap chain as a property of the device.
Note that any given device can support only one full-screen swap chain.
Gets a reference to a swap chain.
\t\nThe swap chain ordinal value. For more information, see NumberOfAdaptersInGroup in
Pointer to an
Gets the number of implicit swap chains.
\t\nNumber of implicit swap chains. See Remarks.
Implicit swap chains are created by the device during
An application may create additional swap chains using
Resets the type, size, and format of the swap chain.
\t\nPointer to a
When switching to full-screen mode, Direct3D will try to find a desktop format that matches the back buffer format, so that back buffer and front buffer formats will be identical (to eliminate the need for color conversion).
When this method returns:
Possible return values include:
If a call to
Calling
There are two different types of swap chains: full-screen or windowed. If the new swap chain is full-screen, the adapter will be placed in the display mode that matches the new size.
Direct3D 9 applications can expect messages to be sent to them during this call (for example, before this call is returned); applications should take precautions not to call into Direct3D at this time. In addition, when
A call to
Pixel shaders and vertex shaders survive
When trying to reset more than one display adapter in a group, set pPresentationParameters to point to an array of
If a multihead device was created with
Presents the contents of the next buffer in the sequence of back buffers owned by the device.
\t\nPointer to a value that must be
Pointer to a value that must be
Pointer to a destination window whose client area is taken as the target for this presentation. If this value is
Value must be
Possible return values include:
If necessary, a stretch operation is applied to transfer the pixels within the source rectangle to the destination rectangle in the client area of the target window.
Present will fail, returning
Retrieves a back buffer from the device's swap chain.
\t\nAn unsigned integer specifying the swap chain.
Index of the back buffer object to return. Back buffers are numbered from 0 to the total number of back buffers minus one. A value of 0 returns the first back buffer, not the front buffer. The front buffer is not accessible through this method. Use
Stereo view is not supported in Direct3D 9, so the only valid value for this parameter is
Address of a reference to an
Calling this method will increase the internal reference count on the
Returns information describing the raster of the monitor on which the swap chain is presented.
\t\nAn unsigned integer specifying the swap chain.
Pointer to a
This method allows the use of GDI dialog boxes in full-screen mode applications.
\t\nTRUE to enable GDI dialog boxes, and
If the method succeeds, the return value is
The GDI dialog boxes must be created as child to the device window. They should also be created within the same thread that created the device because this enables the parent window to manage redrawing the child window.
The method has no effect for windowed mode applications, but this setting will be respected if the application resets the device into full-screen mode. If SetDialogBoxMode succeeds in a windowed mode application, any subsequent reset to full-screen mode will be checked against the restrictions listed above. Also, SetDialogBoxMode causes all back buffers on the swap chain to be discarded, so an application is expected to refresh its content for all back buffers after this call.
\t\nSets the gamma correction ramp for the implicit swap chain. This method will affect the entire screen (not just the active window if you are running in windowed mode).
\t\nUnsigned integer specifying the swap chain.
Indicates whether correction should be applied. Gamma correction results in a more consistent display, but can incur processing overhead and should not be used frequently. Short-duration effects, such as flashing the whole screen red, should not be calibrated, but long-duration gamma changes should be calibrated. One of the following values can be set:
| Item | Description |
|---|---|
| D3DSGR_CALIBRATE | If a gamma calibrator is installed, the ramp will be modified before being sent to the device to account for the system and monitor response curves. If a calibrator is not installed, the ramp will be passed directly to the device. |
| D3DSGR_NO_CALIBRATION | No gamma correction is applied. The supplied gamma table is transferred directly to the device. |
?
Pointer to a
There is always at least one swap chain (the implicit swap chain) for each device, because Direct3D 9 has one swap chain as a property of the device. The gamma ramp takes effect immediately; there is no wait for a vertical sync.
If the device does not support gamma ramps in the swap chain's current presentation mode (full-screen or windowed), no error return is given. Applications can check the
For windowed gamma correction presentation, use
Retrieves the gamma correction ramp for the swap chain.
\t\nAn unsigned integer specifying the swap chain.
Creates a texture resource.
\t\nWidth of the top-level of the texture, in pixels. The pixel dimensions of subsequent levels will be the truncated value of half of the previous level's pixel dimension (independently). Each dimension clamps at a size of 1 pixel. Thus, if the division by 2 results in 0, 1 will be taken instead.
Height of the top-level of the texture, in pixels. The pixel dimensions of subsequent levels will be the truncated value of half of the previous level's pixel dimension (independently). Each dimension clamps at a size of 1 pixel. Thus, if the division by 2 results in 0, 1 will be taken instead.
Number of levels in the texture. If this is zero, Direct3D will generate all texture sublevels down to 1 by 1 pixels for hardware that supports mipmapped textures. Call
Usage can be 0, which indicates no usage value. However, if usage is desired, use a combination of one or more
Member of the
Member of the
Pointer to an
Reserved. Set this parameter to
If the method succeeds, the return value is
An application can discover support for Automatic Generation of Mipmaps (Direct3D 9) in a particular format by calling
In Windows Vista CreateTexture can create a texture from a system memory reference allowing the application more flexibility over the use, allocation and deletion of the system memory. For example, an application could pass a GDI system memory bitmap reference and get a Direct3D texture interface around it. Using a system memory reference with CreateTexture has the following restrictions.
Creates a volume texture resource.
\t\nWidth of the top-level of the volume texture, in pixels. This value must be a power of two if the
Height of the top-level of the volume texture, in pixels. This value must be a power of two if the
Depth of the top-level of the volume texture, in pixels. This value must be a power of two if the
Number of levels in the texture. If this is zero, Direct3D will generate all texture sublevels down to 1x1 pixels for hardware that supports mipmapped volume textures. Call
Usage can be 0, which indicates no usage value. If usage is desired, use
Member of the
Member of the
Address of a reference to an
Reserved. Set this parameter to
If the method succeeds, the return value is
Creates a cube texture resource.
\t\nSize of the edges of all the top-level faces of the cube texture. The pixel dimensions of subsequent levels of each face will be the truncated value of half of the previous level's pixel dimension (independently). Each dimension clamps at a size of 1 pixel. Thus, if the division by 2 results in 0 (zero), 1 will be taken instead.
Number of levels in each face of the cube texture. If this is zero, Direct3D will generate all cube texture sublevels down to 1x1 pixels for each face for hardware that supports mipmapped cube textures. Call
Usage can be 0, which indicates no usage value. However, if usage is desired, use a combination of one or more
Member of the
Member of the
Address of a reference to an
Reserved. Set this parameter to
If the method succeeds, the return value is
A mipmap (texture) is a collection of successively downsampled (mipmapped) surfaces. On the other hand, a cube texture (created by
An application can discover support for Automatic Generation of Mipmaps (Direct3D 9) in a particular format by calling
Creates a vertex buffer.
\t\nSize of the vertex buffer, in bytes. For FVF vertex buffers, Length must be large enough to contain at least one vertex, but it need not be a multiple of the vertex size. Length is not validated for non-FVF buffers. See Remarks.
Usage can be 0, which indicates no usage value. However, if usage is desired, use a combination of one or more
Combination of
Member of the
Address of a reference to an
Reserved. Set this parameter to
If the method succeeds, the return value is
A vertex buffer can be used with either hardware or software vertex processing. This is determined by how the device and the vertex buffer are created.
When a device is created, CreateDevice uses the behavior flag to determine whether to process vertices in hardware or software. There are three possibilities:
Mixed-mode devices might need to switch between software and hardware processing (using
When a vertex buffer is created, CreateVertexBuffer uses the usage parameter to decide whether to process vertices in hardware or software.
To use a vertex buffer with a mixed mode device, create a single vertex buffer which can be used for both hardware or software processing. Use
The
When set to a nonzero value, which must be a valid FVF code, the FVF parameter indicates that the buffer content is to be characterized by an FVF code. A vertex buffer that is created with an FVF code is referred to as an FVF vertex buffer. For more information, see FVF Vertex Buffers (Direct3D 9).
Non-FVF buffers can be used to interleave data during multipass rendering or multitexture rendering in a single pass. To do this, one buffer contains geometry data and the others contain texture coordinates for each texture to be rendered. When rendering, the buffer containing the geometry data is interleaved with each of the buffers containing the texture coordinates. If FVF buffers were used instead, each of them would need to contain identical geometry data in addition to the texture coordinate data specific to each texture rendered. This would result in either a speed or memory penalty, depending on the strategy used. For more information about texture coordinates, see Texture Coordinates (Direct3D 9).
\t\nCreates an index buffer.
\t\nSize of the index buffer, in bytes.
Usage can be 0, which indicates no usage value. However, if usage is desired, use a combination of one or more
Member of the
| Item | Description |
|---|---|
| | Indices are 16 bits each. |
| | Indices are 32 bits each. |
?
Member of the
Address of a reference to an
This parameter can be used in Direct3D?9 for Windows?Vista to share resources; set it to
If the method succeeds, the return value is
Index buffers are memory resources used to hold indices, they are similar to both surfaces and vertex buffers. The use of index buffers enables Direct3D to avoid unnecessary data copying and to place the buffer in the optimal memory type for the expected usage.
To use index buffers, create an index buffer, lock it, fill it with indices, unlock it, pass it to
The MaxVertexIndex member of the
Creates a render-target surface.
\t\nWidth of the render-target surface, in pixels.
Height of the render-target surface, in pixels.
Member of the
Member of the
Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by
Render targets are not lockable unless the application specifies TRUE for Lockable.
Note that lockable render targets reduce performance on some graphics hardware. The readback performance (moving data from video memory to system memory) depends on the type of hardware used (AGP vs. PCI Express) and is usually far lower than upload performance (moving data from system to video memory). If you need read access to render targets, use GetRenderTargetData instead of lockable render targets.
Reserved. Set this parameter to
Address of a reference to an
Render-target surfaces are placed in the
The creation of lockable, multisampled render targets is not supported.
\t\nCreates a depth-stencil resource.
\t\nWidth of the depth-stencil surface, in pixels.
Height of the depth-stencil surface, in pixels.
Member of the
Member of the
Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by
Set this flag to TRUE to enable z-buffer discarding, and
This flag has the same behavior as the constant,
Reserved. Set this parameter to
Address of a reference to an
The memory class of the depth-stencil buffer is always
Copies rectangular subsets of pixels from one surface to another.
\t\nPointer to an
Pointer to a rectangle on the source surface. Specifying
Pointer to an
Pointer to the upper left corner of the destination rectangle. Specifying
If the method succeeds, the return value is
This method is similar to CopyRects in DirectX 8.
This function has the following restrictions.
The following table shows the supported combinations.
| Dest formats | |||||
|---|---|---|---|---|---|
| Texture | RT texture | RT | Off-screen plain | ||
| Src formats | Texture | Yes | Yes | Yes* | Yes |
| RT texture | No | No | No | No | |
| RT | No | No | No | No | |
| Off-screen plain | Yes | Yes | Yes | Yes |
?
* If the driver does not support the requested copy, it will be emulated using lock and copy.
If the application needs to copy data from a
Updates the dirty portions of a texture.
\t\nPointer to an
Pointer to an
If the method succeeds, the return value is
You can dirty a portion of a texture by locking it, or by calling one of the following methods.
For performance reasons, dirty regions are only recorded for level zero of a texture. For sublevels, it is assumed that the corresponding (scaled) rectangle or box is also dirty. Dirty regions are automatically recorded when LockRect or
This method fails if the textures are of different types, if their bottom-level buffers are of different sizes, or if their matching levels do not match. For example, consider a six-level source texture with the following dimensions.
32x16, 16x8, 8x4, 4x2, 2x1, 1x1\t\n This six-level source texture could be the source for the following one-level destination.
1x1\t\n For the following two-level destination.
2x1, 1x1\t\n Or, for the following three-level destination.
4x2, 2x1, 1x1\t\n In addition, this method will fail if the textures are of different formats. If the destination texture has fewer levels than the source, only the matching levels are copied. If the source texture has fewer levels than the destination, the method will fail.
If the source texture has dirty regions, the copy can be optimized by restricting the copy to only those regions. It is not guaranteed that only those bytes marked dirty will be copied.
Here are the possibilities for source and destination surface combinations:
Copies the render-target data from device memory to system memory.
\t\nPointer to an
Pointer to an
If the method succeeds, the return value is
The destination surface must be either an off-screen plain surface or a level of a texture (mipmap or cube texture) created with
The source surface must be a regular render target or a level of a render-target texture (mipmap or cube texture) created with POOL_DEFAULT.
This method will fail if:
Generates a copy of the device's front buffer and places that copy in a system memory buffer provided by the application.
\t\nAn unsigned integer specifying the swap chain.
Pointer to an
For windowed mode, the size of the destination surface should be the size of the desktop. For full-screen mode, the size of the destination surface should be the screen size.
If the method succeeds, the return value is
The buffer pointed to by pDestSurface will be filled with a representation of the front buffer, converted to the standard 32 bits per pixel format
This method is the only way to capture an antialiased screen shot.
This function is very slow, by design, and should not be used in any performance-critical path.
For more information, see Lost Devices and Retrieved Data.
\t\nCopy the contents of the source rectangle to the destination rectangle. The source rectangle can be stretched and filtered by the copy. This function is often used to change the aspect ratio of a video stream.
\t\nPointer to the source surface. See
Pointer to the source rectangle. A
Pointer to the destination surface. See
Pointer to the destination rectangle. A
Filter type. Allowable values are
If the method succeeds, the return value is
StretchRect Restrictions
Additional Restrictions for Depth and Stencil Surfaces
Using StretchRect to downsample a Multisample Rendertarget
You can use StretchRect to copy from one rendertarget to another. If the source rendertarget is multisampled, this results in downsampling the source rendertarget. For instance you could:
Note that use of the extra surface involved in using StretchRect to downsample a Multisample Rendertarget will result in a performance hit.
Driver Support
There are many restrictions as to which surface combinations are valid for StretchRect. Factors include whether the driver is a Direct3D 9 driver or older, and whether the operation will result in stretching/shrinking. Since applications are not expected to recognize if the driver is a Direct3D 9 driver or not, the runtime will automatically set a new cap,
| DirectX 8 Driver (no stretching) | |||||
|---|---|---|---|---|---|
| Dest formats | |||||
| Texture | RT texture | RT | Off-screen plain | ||
| Src formats | Texture | No | No | No | No |
| RT texture | No | Yes | Yes | No | |
| RT | No | Yes | Yes | No | |
| Off-screen plain | Yes | Yes | Yes | Yes |
?
| DirectX 8 Driver (stretching) | |||||
|---|---|---|---|---|---|
| Dest formats | |||||
| Texture | RT texture | RT | Off-screen plain | ||
| Src formats | Texture | No | No | No | No |
| RT texture | No | No | No | No | |
| RT | No | Yes | Yes | No | |
| Off-screen plain | No | Yes | Yes | No |
?
| Direct3D 9 Driver (no stretching) | |||||
|---|---|---|---|---|---|
| Dest formats | |||||
| Texture | RT texture | RT | Off-screen plain | ||
| Src formats | Texture | No | Yes | Yes | No |
| RT texture | No | Yes | Yes | No | |
| RT | No | Yes | Yes | No | |
| Off-screen plain | No | Yes | Yes | Yes |
?
| Direct3D 9 Driver (stretching) | |||||
|---|---|---|---|---|---|
| Dest formats | |||||
| Texture | RT texture | RT | Off-screen plain | ||
| Src formats | Texture | No | Yes | Yes | No |
| RT texture | No | Yes | Yes | No | |
| RT | No | Yes | Yes | No | |
| Off-screen plain | No | Yes | Yes | No |
?
\t\nAllows an application to fill a rectangular area of a
Pointer to the surface to be filled.
Pointer to the source rectangle. Using
Color used for filling.
If the method succeeds, the return value is
This method can only be applied to a render target, a render-target texture surface, or an off-screen plain surface with a pool type of
When using a DirectX 7 or DirectX 8.x driver, the only YUV formats supported are
Create an off-screen surface.
\t\nWidth of the surface.
Height of the surface.
Format of the surface. See
Surface pool type. See
Reserved. Set this parameter to
Pointer to the
Off-screen plain surfaces are always lockable, regardless of their pool types.
\t\nSets a new color buffer for the device.
\t\nIndex of the render target. See Remarks.
Pointer to a new color buffer. If
If the method succeeds, the return value is
The device can support multiple render targets. The number of render targets supported by a device is contained in the NumSimultaneousRTs member of
Setting a new render target will cause the viewport (see Viewports and Clipping (Direct3D 9)) to be set to the full size of the new render target.
Some hardware tests the compatibility of the depth stencil buffer with the color buffer. If this is done, it is only done in a debug build.
Restrictions for using this method include the following:
These restrictions are validated only when using the debug runtime when any of the
Cube textures differ from other surfaces in that they are collections of surfaces. To call
Retrieves a render-target surface.
\t\nIndex of the render target. See Remarks.
Address of a reference to an
Typically, methods that return state will not work on a device that is created using
The device can now support multiple render targets. The number of render targets supported by a device is contained in the NumSimultaneousRTs member of
Calling this method will increase the internal reference count on the
Sets the depth stencil surface.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Restrictions for using this method include the following:
These restrictions are validated only when using the debug runtime when any of the
Cube textures differ from other surfaces in that they are collections of surfaces. To call
Gets the depth-stencil surface owned by the Direct3DDevice object.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Calling this method will increase the internal reference count on the
Begins a scene.
\t\nIf the method succeeds, the return value is
Applications must call
If
There should be one
Ends a scene that was begun by calling
If the method succeeds, the return value is
When this method succeeds, the scene has been queued up for rendering by the driver. This is not a synchronous method, so the scene is not guaranteed to have completed rendering when this method returns.
Applications must call
If
There should be at most one
Clears one or more surfaces such as a render target, multiple render targets, a stencil buffer, and a depth buffer.
\t\nIf the method succeeds, the return value is
Use this method to clear a surface including: a render target, all render targets in an MRT, a stencil buffer, or a depth buffer. Flags determines how many surfaces are cleared. Use pRects to clear a subset of a surface defined by an array of rectangles.
Sets a single device transformation-related state.
\t\nDevice-state variable that is being modified. This parameter can be any member of the
Pointer to a
If the method succeeds, the return value is
Retrieves a matrix describing a transformation state.
\t\nDevice state variable that is being modified. This parameter can be any member of the
Pointer to a
This method will not return device state for a device that is created using
Multiplies a device's world, view, or projection matrices by a specified matrix.
\t\nMember of the
Pointer to a
If the method succeeds, the return value is
The multiplication order is pMatrix times State.
An application might use the
shoulder_transformation upper_arm geometry elbow transformation lower_arm geometry wrist transformation hand geometry\t\n An application might use the following series of calls to render this hierarchy. Not all the parameters are shown in this pseudocode.
(D3DTS_WORLDMATRIX(0), shoulder_transform)\t\n (upper_arm)\t\n (D3DTS_WORLDMATRIX(0), elbow_transform)\t\n (lower_arm)\t\n (D3DTS_WORLDMATRIX(0), wrist_transform)\t\n (hand) Sets the viewport parameters for the device.
\t\nPointer to a
If the method succeeds, the return value is
Direct3D sets the following default values for the viewport.
vp;\t\n vp.X = 0;\t\n vp.Y = 0;\t\n vp.Width = RenderTarget.Width;\t\n vp.Height = RenderTarget.Height;\t\n vp.MinZ = 0.0f;\t\n vp.MaxZ = 1.0f;\t\n To draw multiple views within a scene, repeat the
Retrieves the viewport parameters currently set for the device.
\t\nPointer to a
If the method succeeds, the return value is
Typically, methods that return state will not work on a device that is created using
Sets the material properties for the device.
\t\nPointer to a
If the method succeeds, the return value is
Retrieves the current material properties for the device.
\t\nPointer to a
If the method succeeds, the return value is
This method will not return device state for a device that is created using
Assigns a set of lighting properties for this device.
\t\nZero-based index of the set of lighting properties to set. If a set of lighting properties exists at this index, it is overwritten by the new properties specified in pLight.
Pointer to a
If the method succeeds, the return value is
Set light properties by preparing a
The system allocates memory to accommodate a set of lighting properties each time you call the
The following example prepares and sets properties for a white point-light whose emitted light will not attenuate over distance.
// Assume d3dDevice is a valid reference to an interface.\t\n d3dLight;\t\n hr; // Initialize the structure.\t\n ZeroMemory(&d3dLight, sizeof(d3dLight)); // Set up a white point light.\t\n d3dLight.Type = ;\t\n d3dLight.Diffuse.r = 1.0f;\t\n d3dLight.Diffuse.g = 1.0f;\t\n d3dLight.Diffuse.b = 1.0f;\t\n d3dLight.Ambient.r = 1.0f;\t\n d3dLight.Ambient.g = 1.0f;\t\n d3dLight.Ambient.b = 1.0f;\t\n d3dLight.Specular.r = 1.0f;\t\n d3dLight.Specular.g = 1.0f;\t\n d3dLight.Specular.b = 1.0f; // Position it high in the scene and behind the user.\t\n // Remember, these coordinates are in world space, so\t\n // the user could be anywhere in world space, too. \t\n // For the purposes of this example, assume the user\t\n // is at the origin of world space.\t\n d3dLight.Position.x = 0.0f;\t\n d3dLight.Position.y = 1000.0f;\t\n d3dLight.Position.z = -100.0f; // Don't attenuate.\t\n d3dLight.Attenuation0 = 1.0f; \t\n d3dLight.Range = 1000.0f; // Set the property information for the first light.\t\n hr = d3dDevice->SetLight(0, &d3dLight);\t\n if (SUCCEEDED(hr)) // Handle Success\t\n else // Handle failure\t\n Enable a light source by calling the
Retrieves a set of lighting properties that this device uses.
\t\nZero-based index of the lighting property set to retrieve. This method will fail if a lighting property has not been set for this index by calling the
Pointer to a
This method will not return device state for a device that is created using
Retrieve all the properties for an existing light source by calling the
// Assume d3dDevice is a valid reference to an interface.\t\n hr;\t\n D3DLight9 light; // Get the property information for the first light.\t\n hr = pd3dDevice->GetLight(0, &light);\t\n if (SUCCEEDED(hr)) // Handle Success\t\n else // Handle failure\t\n If you supply an index outside the range of the light sources assigned in the device, the
When you assign a set of light properties for a light source in a scene, the light source can be activated by calling the
// Assume d3dDevice is a valid reference to an interface.\t\n hr; hr = pd3dDevice->LightEnable(0, TRUE);\t\n if (SUCCEEDED(hr)) // Handle Success\t\n else // Handle failure\t\n Check the MaxActiveLights member of the
If you enable or disable a light that has no properties that are set with
Enables or disables a set of lighting parameters within a device.
\t\nZero-based index of the set of lighting parameters that are the target of this method.
Value that indicates if the set of lighting parameters are being enabled or disabled. Set this parameter to TRUE to enable lighting with the parameters at the specified index, or
If the method succeeds, the return value is
If a value for LightIndex is outside the range of the light property sets assigned within the device, the
| Member | Default |
|---|---|
| Type | |
| Diffuse | (R:1, G:1, B:1, A:0) |
| Specular | (R:0, G:0, B:0, A:0) |
| Ambient | (R:0, G:0, B:0, A:0) |
| Position | (0, 0, 0) |
| Direction | (0, 0, 1) |
| Range | 0 |
| Falloff | 0 |
| Attenuation0 | 0 |
| Attenuation1 | 0 |
| Attenuation2 | 0 |
| Theta | 0 |
| Phi | 0 |
?
\t\nRetrieves the activity status - enabled or disabled - for a set of lighting parameters within a device.
\t\nZero-based index of the set of lighting parameters that are the target of this method.
Pointer to a variable to fill with the status of the specified lighting parameters. After the call, a nonzero value at this address indicates that the specified lighting parameters are enabled; a value of 0 indicates that they are disabled.
This method will not return device state for a device that is created using
Sets the coefficients of a user-defined clipping plane for the device.
\t\nIndex of the clipping plane for which the plane equation coefficients are to be set.
Pointer to an address of a four-element array of values that represent the clipping plane coefficients to be set, in the form of the general plane equation. See Remarks.
If the method succeeds, the return value is
The coefficients that this method sets take the form of the general plane equation. If the values in the array at pPlane were labeled A, B, C, and D in the order that they appear in the array, they would fit into the general plane equation so that Ax + By + Cz + Dw = 0. A point with homogeneous coordinates (x, y, z, w) is visible in the half space of the plane if Ax + By + Cz + Dw >= 0. Points that exist behind the clipping plane are clipped from the scene.
When the fixed function pipeline is used the plane equations are assumed to be in world space. When the programmable pipeline is used the plane equations are assumed to be in the clipping space (the same space as output vertices).
This method does not enable the clipping plane equation being set. To enable a clipping plane, set the corresponding bit in the DWORD value applied to the
Retrieves the coefficients of a user-defined clipping plane for the device.
\t\nIndex of the clipping plane for which the plane equation coefficients are retrieved.
Pointer to a four-element array of values that represent the coefficients of the clipping plane in the form of the general plane equation. See Remarks.
This method will not return device state for a device that is created using
The coefficients that this method reports take the form of the general plane equation. If the values in the array at pPlane were labeled A, B, C, and D in the order that they appear in the array, they would fit into the general plane equation so that Ax + By + Cz + Dw = 0. A point with homogeneous coordinates (x, y, z, w) is visible in the half space of the plane if Ax + By + Cz + Dw >= 0. Points that exist on or behind the clipping plane are clipped from the scene.
The plane equation used by this method exists in world space and is set by a previous call to the
Sets a single device render-state parameter.
\t\nDevice state variable that is being modified. This parameter can be any member of the
New value for the device render state to be set. The meaning of this parameter is dependent on the value specified for State. For example, if State were
If the method succeeds, the return value is
Retrieves a render-state value for a device.
\t\nDevice state variable that is being queried. This parameter can be any member of the
Pointer to a variable that receives the value of the queried render state variable when the method returns.
If the method succeeds, the return value is
This method will not return device state for a device that is created using
Creates a new state block that contains the values for all device states, vertex-related states, or pixel-related states.
\t\nType of state data that the method should capture. This parameter can be set to a value defined in the
Pointer to a state block interface. See
If the method succeeds, the return value is
Vertex-related device states typically refer to those states that affect how the system processes vertices. Pixel-related states generally refer to device states that affect how the system processes pixel or depth-buffer data during rasterization. Some states are contained in both groups.
| Differences between Direct3D 9 and Direct3D 10: In Direct3D 9, a state block contains state data, for the states it was requested to capture, when the object is created. To change the value of the state block, call |
?
\t\nSignals Direct3D to begin recording a device-state block.
\t\nIf the method succeeds, the return value is
Applications can ensure that all recorded states are valid by calling the
The following methods can be recorded in a state block, after calling
The ordering of state changes in a state block is not guaranteed. If the same state is specified multiple times in a state block, only the last value is used.
\t\nSignals Direct3D to stop recording a device-state block and retrieve a reference to the state block interface.
\t\nPointer to a state block interface. See
Sets the clip status.
\t\nPointer to a
If the method succeeds, the return value is
Clip status is used during software vertex processing. Therefore, this method is not supported on pure or nonpure hardware processing devices. For more information about pure devices, see
When clipping is enabled during vertex processing (by
Clip status is not updated by
Retrieves the clip status.
\t\n Pointer to a
If the method succeeds, the return value is
When clipping is enabled during vertex processing (by
Clip status is not updated by
Clip status is used during software vertex processing. Therefore, this method is not supported on pure or nonpure hardware processing devices. For more information about pure devices, see
Retrieves a texture assigned to a stage for a device.
\t\nStage identifier of the texture to retrieve. Stage identifiers are zero-based.
Address of a reference to an
Typically, methods that return state will not work on a device that is created using
Calling this method will increase the internal reference count on the
Assigns a texture to a stage for a device.
\t\nZero based sampler number. Textures are bound to samplers; samplers define sampling state such as the filtering mode and the address wrapping mode. Textures are referenced differently by the programmable and the fixed function pipeline:
There are two other special cases for stage/sampler numbers.
Pointer to an
If the method succeeds, the return value is
SetTexture is not allowed if the texture is created with a pool type of
Retrieves a state value for an assigned texture.
\t\nStage identifier of the texture for which the state is retrieved. Stage identifiers are zero-based. Devices can have up to eight set textures, so the maximum value allowed for Stage is 7.
Texture state to retrieve. This parameter can be any member of the
Pointer a variable to fill with the retrieved state value. The meaning of the retrieved value is determined by the Type parameter.
If the method succeeds, the return value is
This method will not return device state for a device that is created using
Sets the state value for the currently assigned texture.
\t\nStage identifier of the texture for which the state value is set. Stage identifiers are zero-based. Devices can have up to eight set textures, so the maximum value allowed for Stage is 7.
Texture state to set. This parameter can be any member of the
State value to set. The meaning of this value is determined by the Type parameter.
If the method succeeds, the return value is
Gets the sampler state value.
\t\nThe sampler stage index.
This parameter can be any member of the
State value to get. The meaning of this value is determined by the Type parameter.
If the method succeeds, the return value is
This method will not return device state for a device that is created using
Sets the sampler state value.
\t\nThe sampler stage index.
This parameter can be any member of the
State value to set. The meaning of this value is determined by the Type parameter.
If the method succeeds, the return value is
Reports the device's ability to render the current texture-blending operations and arguments in a single pass.
\t\nPointer to a DWORD value to fill with the number of rendering passes needed to complete the desired effect through multipass rendering.
If the method succeeds, the return value is
The
Current hardware does not necessarily implement all possible combinations of operations and arguments. You can determine whether a particular blending operation can be performed with given arguments by setting the desired blending operation, and then calling the
The
For best performance, call
Using diffuse iterated values, either as an argument or as an operation (D3DTA_DIFFUSED3DTOP_BLENDDIFFUSEALPHA) is rarely supported on current hardware. Most hardware can introduce iterated color data only at the last texture operation stage.
Try to specify the texture (
Many cards do not support use of diffuse or scalar values at arbitrary texture stages. Often, these are available only at the first or last texture-blending stage.
Many cards do not have a blending unit associated with the first texture that is capable of more than replicating alpha to color channels or inverting the input. Therefore, your application might need to use only the second texture stage, if possible. On such hardware, the first unit is presumed to be in its default state, which has the first color argument set to
Operations on the output alpha that are more intricate than or substantially different from the color operations are less likely to be supported.
Some hardware does not support simultaneous use of
Many cards do not support simultaneous use of multiple textures and mipmapped trilinear filtering. If trilinear filtering has been requested for a texture involved in multitexture blending operations and validation fails, turn off trilinear filtering and revalidate. In this case, you might want to perform multipass rendering instead.
\t\nSets palette entries.
\t\nAn ordinal value identifying the particular palette upon which the operation is to be performed.
Pointer to a
If the method succeeds, the return value is
For Direct3D 9 applications, any palette sent to this method must conform to the
A single logical palette is associated with the device, and is shared by all texture stages.
\t\nRetrieves palette entries.
\t\nAn ordinal value identifying the particular palette to retrieve.
Pointer to a
If the method succeeds, the return value is
For more information about
Note??As of Direct3D 9, the peFlags member of the
Sets the current texture palette.
\t\nValue that specifies the texture palette to set as the current texture palette.
If the method succeeds, the return value is
A single logical palette is associated with the device, and is shared by all texture stages.
\t\nRetrieves the current texture palette.
\t\nPointer to a returned value that identifies the current texture palette.
If the method succeeds, the return value is
Sets the scissor rectangle.
\t\nPointer to a
If the method succeeds, the return value is
The scissor rectangle is used as a rectangular clipping region.
See Rectangles (Direct3D 9) for further information on the use of rectangles in DirectX.
\t\nGets the scissor rectangle.
\t\nReturns a reference to a
If the method succeeds, the return value is
The scissor rectangle is used as a rectangular clipping region.
See Rectangles (Direct3D 9) for further information on the use of rectangles in DirectX.
\t\nUse this method to switch between software and hardware vertex processing.
\t\nTRUE to specify software vertex processing;
If the method succeeds, the return value is
The restrictions for changing modes are as follows:
An application can create a mixed-mode device to use both the software vertex processing and the hardware vertex processing. To switch between the two vertex processing modes in DirectX 8.x, use IDirect3DDevice8::SetRenderState with the render state D3DRS_SOFTWAREVERTEXPROCESSING and the appropriate DWORD argument. The drawback of the render state approach was the difficulty in defining the semantics for state blocks. Applications and the runtime had to do extra work and be careful while recording and playing back state blocks.
In Direct3D 9, use SetSoftwareVertexProcessing instead. This new API is not recorded by StateBlocks.
\t\nGets the vertex processing (hardware or software) mode.
\t\nReturns TRUE if software vertex processing is set. Otherwise, it returns
An application can create a mixed-mode device to use both the software vertex processing and the hardware vertex processing. To switch between the two vertex processing modes in DirectX 8.x, use
In Direct3D 9, use
Enable or disable N-patches.
\t\nSpecifies the number of subdivision segments. If the number of segments is less than 1.0, N-patches are disabled. The default value is 0.0.
If the method succeeds, the return value is
Gets the N-patch mode segments.
\t\nSpecifies the number of subdivision segments. If the number of segments is less than 1.0, N-patches are disabled. The default value is 0.0.
Renders a sequence of nonindexed, geometric primitives of the specified type from the current set of data input streams.
\t\nMember of the
Index of the first vertex to load. Beginning at StartVertex the correct number of vertices will be read out of the vertex buffer.
Number of primitives to render. The maximum number of primitives allowed is determined by checking the MaxPrimitiveCount member of the
If the method succeeds, the return value is
When converting a legacy application to Direct3D 9, you must add a call to either
Based on indexing, renders the specified geometric primitive into an array of vertices.
\t\nMember of the
Offset from the start of the vertex buffer to the first vertex. See Scenario 4.
Minimum vertex index for vertices used during this call. This is a zero based index relative to BaseVertexIndex.
Number of vertices used during this call. The first vertex is located at index: BaseVertexIndex + MinIndex.
Index of the first index to use when accesssing the vertex buffer. Beginning at StartIndex to index vertices from the vertex buffer.
Number of primitives to render. The number of vertices used is a function of the primitive count and the primitive type. The maximum number of primitives allowed is determined by checking the MaxPrimitiveCount member of the
If the method succeeds, the return value is
This method draws indexed primitives from the current set of data input streams. MinIndex and all the indices in the index stream are relative to the BaseVertexIndex.
The MinIndex and NumVertices parameters specify the range of vertex indices used for each
The
When converting a legacy application to Direct3D 9, you must add a call to either
Renders data specified by a user memory reference as a sequence of geometric primitives of the specified type.
\t\nMember of the
Number of primitives to render. The maximum number of primitives allowed is determined by checking the MaxPrimitiveCount member of the
User memory reference to the vertex data.
The number of bytes of data for each vertex. This value may not be 0.
If the method succeeds, the return value is
This method is intended for use in applications that are unable to store their vertex data in vertex buffers. This method supports only a single vertex stream. The effect of this call is to use the provided vertex data reference and stride for vertex stream 0. It is invalid to have the declaration of the current vertex shader refer to vertex streams other than stream 0.
Following any
The vertex data passed to
When converting a legacy application to Direct3D 9, you must add a call to either
Renders the specified geometric primitive with data specified by a user memory reference.
\t\nMember of the
Minimum vertex index. This is a zero-based index.
Number of vertices used during this call. The first vertex is located at index: MinVertexIndex.
Number of primitives to render. The maximum number of primitives allowed is determined by checking the MaxPrimitiveCount member of the
User memory reference to the index data.
Member of the
User memory reference to the vertex data. The vertex data must be in stream 0.
The number of bytes of data for each vertex. This value may not be 0.
If the method succeeds, the return value is
This method is intended for use in applications that are unable to store their vertex data in vertex buffers. This method supports only a single vertex stream, which must be declared as stream 0.
Following any
The vertex data passed to
When converting a legacy application to Direct3D 9, you must add a call to either
Applies the vertex processing defined by the vertex shader to the set of input data streams, generating a single stream of interleaved vertex data to the destination vertex buffer.
\t\nIndex of first vertex to load.
Index of first vertex in the destination vertex buffer into which the results are placed.
Number of vertices to process.
Pointer to an
Pointer to an
Processing options. Set this parameter to 0 for default processing. Set to D3DPV_DONOTCOPYDATA to prevent the system from copying vertex data not affected by the vertex operation into the destination buffer. The D3DPV_DONOTCOPYDATA value may be combined with one or more
If the method succeeds, the return value is
The order of operations for this method is as follows:
The destination vertex buffer, pDestBuffer, must be created with a nonzero FVF parameter in
When Direct3D generates texture coordinates, or copies or transforms input texture coordinates, and the output texture coordinate format defines more texture coordinate components than Direct3D generates, Direct3D does not change these extra components.
\t\nCreate a vertex shader declaration from the device and the vertex elements.
\t\nAn array of
Pointer to an
If the method succeeds, the return value is
See the Vertex Declaration (Direct3D 9) page for a detailed description of how to map vertex declarations between different versions of DirectX.
\t\nSets a Vertex Declaration (Direct3D 9).
\t\nIf the method succeeds, the return value is
A vertex declaration is an
Gets a vertex shader declaration.
\t\nPointer to an
If the method succeeds, the return value is
Sets the current vertex stream declaration.
\t\nDWORD containing the fixed function vertex type. For more information, see
If the method succeeds, the return value is
Here are the steps necessary to initialize and use vertices that have a position, diffuse and specular color, and texture coordinates:
struct LVertex\t\n { FLOAT x, y, z; specular, diffuse; FLOAT tu, tv;\t\n }; const DWORD VertexFVF = ( | | | );\t\n g_d3dDevice->CreateVertexBuffer( 4*sizeof(LVertex), , VertexFVF, , &pBigSquareVB, null );\t\n LVertex * v;\t\n pBigSquareVB->Lock( 0, 0, (BYTE**)&v, 0 ); v[0].x = 0.0f; v[0].y = 10.0; v[0].z = 10.0f;\t\n v[0].diffuse = 0xffff0000;\t\n v[0].specular = 0xff00ff00;\t\n v[0].tu = 0.0f; v[0].tv = 0.0f; v[1].x = 0.0f; v[1].y = 0.0f; v[1].z = 10.0f;\t\n v[1].diffuse = 0xff00ff00;\t\n v[1].specular = 0xff00ffff;\t\n v[1].tu = 0.0f; v[1].tv = 0.0f; v[2].x = 10.0f; v[2].y = 10.0f; v[2].z = 10.0f;\t\n v[2].diffuse = 0xffff00ff;\t\n v[2].specular = 0xff000000;\t\n v[2].tu = 0.0f; v[2].tv = 0.0f; v[3].x = 0.0f; v[3].y = 10.0f; v[3].z = 10.0f;\t\n v[3].diffuse = 0xffffff00;\t\n v[3].specular = 0xffff0000;\t\n v[3].tu = 0.0f; v[3].tv = 0.0f; pBigSquareVB->Unlock();\t\n g_d3dDevice->SetFVF(VertexFVF);\t\n g_d3dDevice->SetStreamSource(0, pBigSquareVB, 0, sizeof(LVertex));\t\n g_d3dDevice->DrawPrimitive(, 0 ,2);\t\n Here are the steps necessary to initialize and use vertices that have a position, a normal, and texture coordinates:
struct Vertex\t\n { FLOAT x, y, z; FLOAT nx, ny, nz; FLOAT tu, tv;\t\n }; const DWORD VertexFVF = ( | | );\t\n Vertex * v;\t\n pBigSquareVB->Lock(0, 0, (BYTE**)&v, 0); v[0].x = 0.0f; v[0].y = 10.0; v[0].z = 10.0f;\t\n v[0].nx = 0.0f; v[0].ny = 1.0f; v[0].nz = 0.0f;\t\n v[0].tu = 0.0f; v[0].tv = 0.0f; v[1].x = 0.0f; v[1].y = 0.0f; v[1].z = 10.0f;\t\n v[1].nx = 0.0f; v[1].ny = 1.0f; v[1].nz = 0.0f;\t\n v[1].tu = 0.0f; v[1].tv = 0.0f; v[2].x = 10.0f; v[2].y = 10.0f; v[2].z = 10.0f;\t\n v[2].nx = 0.0f; v[2].ny = 1.0f; v[2].nz = 0.0f;\t\n v[2].tu = 0.0f; v[2].tv = 0.0f; v[3].x = 0.0f; v[3].y = 10.0f; v[3].z = 10.0f;\t\n v[3].nx = 0.0f; v[3].ny = 1.0f; v[3].nz = 0.0f;\t\n v[3].tu = 0.0f; v[3].tv = 0.0f; pBigSquareVB->Unlock();\t\n Gets the fixed vertex function declaration.
\t\nA DWORD reference to the fixed function vertex type. For more information, see
If the method succeeds, the return value is
The fixed vertex function declaration is a set of FVF flags that determine how vertices processed by the fixed function pipeline will be used.
\t\nCreates a vertex shader.
\t\nPointer to an array of tokens that represents the vertex shader, including any embedded debug and symbol table information.
Pointer to the returned vertex shader interface (see
If the method succeeds, the return value is
When a device is created,
For an example using
Sets the vertex shader.
\t\nVertex shader interface. For more information, see
If the method succeeds, the return value is
To set a fixed-function vertex shader (after having set a programmable vertex shader), call
Retrieves the currently set vertex shader.
\t\nPointer to a vertex shader interface.
If the method succeeds, the return value is
Typically, methods that return state will not work on a device that is created using
Sets a floating-point vertex shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four float vectors in the array of constants.
If the method succeeds, the return value is
Gets a floating-point vertex shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four float vectors in the array of constants.
If the method succeeds, the return value is
Sets an integer vertex shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four integer vectors in the array of constants.
If the method succeeds, the return value is
Gets an integer vertex shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four integer vectors in the array of constants.
If the method succeeds, the return value is
Sets a Boolean vertex shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of boolean values in the array of constants.
If the method succeeds, the return value is
Gets a Boolean vertex shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of Boolean values in the array of constants.
If the method succeeds, the return value is
Binds a vertex buffer to a device data stream. For more information, see Setting the Stream Source (Direct3D 9).
\t\nIf the method succeeds, the return value is
When a FVF vertex shader is used, the stride of the vertex stream must match the vertex size, computed from the FVF. When a declaration is used, the stride should be greater than or equal to the stream size computed from the declaration.
When calling SetStreamSource, the stride is normally required to be equal to the vertex size. However, there are times when you may want to draw multiple instances of the same or similar geometry (such as when using instancing to draw). For this case, use a zero stride to tell the runtime not to increment the vertex buffer offset (ie: use the same vertex data for all instances). For more information about instancing, see Efficiently Drawing Multiple Instances of Geometry (Direct3D 9).
\t\nRetrieves a vertex buffer bound to the specified data stream.
\t\nSpecifies the data stream, in the range from 0 to the maximum number of streams minus one.
Address of a reference to an
Pointer containing the offset from the beginning of the stream to the beginning of the vertex data. The offset is measured in bytes. See Remarks.
Pointer to a returned stride of the component, in bytes. See Remarks.
If the method succeeds, the return value is
A stream is defined as a uniform array of component data, where each component consists of one or more elements representing a single entity such as position, normal, color, and so on.
When a FVF vertex shader is used, the stride of the vertex stream must match the vertex size, computed from the FVF. When a declaration is used, the stride should be greater than or equal to the stream size computed from the declaration.
Calling this method will increase the internal reference count on the
Sets the stream source frequency divider value. This may be used to draw several instances of geometry.
\t\nStream source number.
This parameter may have two different values. See remarks.
If the method succeeds, the return value is
There are two constants defined in d3d9types.h that are designed to use with SetStreamSourceFreq:
Gets the stream source frequency divider value.
\t\nStream source number.
Returns the frequency divider value.
If the method succeeds, the return value is
Vertex shaders can now be invoked more than once per vertex. See Drawing Non-Indexed Geometry.
\t\nSets index data.
\t\nPointer to an
If the method succeeds, the return value is
When an application no longer holds a references to this interface, the interface will automatically be freed.
The
Retrieves index data.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Calling this method will increase the internal reference count on the
Creates a pixel shader.
\t\nPointer to the pixel shader function token array, specifying the blending operations. This value cannot be
Pointer to the returned pixel shader interface. See
If the method succeeds, the return value is
Sets the current pixel shader to a previously created pixel shader.
\t\nPixel shader interface.
If the method succeeds, the return value is
Retrieves the currently set pixel shader.
\t\nPointer to a pixel shader interface.
If the method succeeds, the return value is
This method will not work on a device that is created using
Sets a floating-point shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four float vectors in the array of constants.
If the method succeeds, the return value is
Gets a floating-point shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four float vectors in the array of constants.
If the method succeeds, the return value is
Sets an integer shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four integer vectors in the array of constants.
If the method succeeds, the return value is
Gets an integer shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of four integer vectors in the array of constants.
If the method succeeds, the return value is
Sets a Boolean shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of boolean values in the array of constants.
If the method succeeds, the return value is
Gets a Boolean shader constant.
\t\nRegister number that will contain the first constant value.
Pointer to an array of constants.
Number of Boolean values in the array of constants.
If the method succeeds, the return value is
Draws a rectangular patch using the currently set streams.
\t\nHandle to the rectangular patch to draw.
Pointer to an array of four floating-point values that identify the number of segments each edge of the rectangle patch should be divided into when tessellated. See
Pointer to a
If the method succeeds, the return value is
For static patches: Set the vertex shader, set the appropriate streams, supply patch information in the pRectPatchInfo parameter, and specify a handle so that Direct3D can capture and cache information. Call
Calling
For dynamic patches, the patch data changes for every rendering of the patch, so it is not efficient to cache information. The application can convey this to Direct3D by setting Handle to 0. In this case, Direct3D draws the patch using the currently set streams and the pNumSegs values, and does not cache any information. It is not valid to simultaneously set Handle to 0 and pRectPatchInfo to
Draws a triangular patch using the currently set streams.
\t\nHandle to the triangular patch to draw.
Pointer to an array of three floating-point values that identify the number of segments each edge of the triangle patch should be divided into when tessellated. See
Pointer to a
If the method succeeds, the return value is
For static patches: Set the vertex shader, set the appropriate streams, supply patch information in the pTriPatchInfo parameter, and specify a handle so that Direct3D can capture and cache information. To efficiently draw the patch, call
Calling
For dynamic patches, the patch data changes for every rendering of the patch so it is not efficient to cache information. The application can convey this to Direct3D by setting Handle to 0. In this case, Direct3D draws the patch using the currently set streams and the pNumSegs values, and does not cache any information. It is not valid to simultaneously set Handle to 0 and pTriPatchInfo to
Frees a cached high-order patch.
\t\nHandle of the cached high-order patch to delete.
If the method succeeds, the return value is
Creates a status query.
\t\nIdentifies the query type. For more information, see
Returns a reference to the query interface that manages the query object. See
This parameter can be set to
If the method succeeds, the return value is
This method is provided for both synchronous and asynchronous queries. It takes the place of GetInfo, which is no longer supported in Direct3D 9.
Synchronous and asynchronous queries are created with
Returns an interface to the instance of the Direct3D object that created the device.
\t\nCalling
Retrieves the capabilities of the rendering device.
\t\nRetrieves the creation parameters of the device.
\t\nYou can query the AdapterOrdinal member of the returned
Gets the number of implicit swap chains.
\t\nImplicit swap chains are created by the device during
An application may create additional swap chains using
This method allows the use of GDI dialog boxes in full-screen mode applications.
\t\nThe GDI dialog boxes must be created as child to the device window. They should also be created within the same thread that created the device because this enables the parent window to manage redrawing the child window.
The method has no effect for windowed mode applications, but this setting will be respected if the application resets the device into full-screen mode. If SetDialogBoxMode succeeds in a windowed mode application, any subsequent reset to full-screen mode will be checked against the restrictions listed above. Also, SetDialogBoxMode causes all back buffers on the swap chain to be discarded, so an application is expected to refresh its content for all back buffers after this call.
\t\nGets or sets the depth-stencil surface owned by the Direct3DDevice object.
\t\nCalling this method will increase the internal reference count on the
Retrieves or sets the viewport parameters currently set for the device.
\t\nTypically, methods that return state will not work on a device that is created using
Retrieves or sets the current material properties for the device.
\t\nThis method will not return device state for a device that is created using
Retrieves or sets the clip status.
\t\nWhen clipping is enabled during vertex processing (by
Clip status is not updated by
Clip status is used during software vertex processing. Therefore, this method is not supported on pure or nonpure hardware processing devices. For more information about pure devices, see
Retrieves or sets the current texture palette.
\t\nGets or sets the scissor rectangle.
\t\nThe scissor rectangle is used as a rectangular clipping region.
See Rectangles (Direct3D 9) for further information on the use of rectangles in DirectX.
\t\nGets or sets the vertex processing (hardware or software) mode.
\t\nAn application can create a mixed-mode device to use both the software vertex processing and the hardware vertex processing. To switch between the two vertex processing modes in DirectX 8.x, use
In Direct3D 9, use
Gets or sets the N-patch mode segments.
\t\nGets or sets a vertex shader declaration.
\t\nGets or sets the fixed vertex function declaration.
\t\nThe fixed vertex function declaration is a set of FVF flags that determine how vertices processed by the fixed function pipeline will be used.
\t\nRetrieves or sets the currently set vertex shader.
\t\nTypically, methods that return state will not work on a device that is created using
Retrieves or sets index data.
\t\n Calling this method will increase the internal reference count on the
Retrieves or sets the currently set pixel shader.
\t\nThis method will not work on a device that is created using
Applications use the methods of the
The
The LPDIRECT3DDEVICE9EX and PDIRECT3DDEVICE9EX types are defined as references to the
typedef struct *LPDIRECT3DDEVICE9EX, *PDIRECT3DDEVICE9EX;\t\n Follow these two steps to initialize a Direct3D device:
Here is an example:
*pDirect3DEx;\t\n LPDIRECT3DDEVICE9EX pDeviceEx;\t\n DWORD behaviorFlags = ; Direct3DCreate9Ex(, &pDirect3DEx);\t\n pDirect3DEx->CreateDeviceEx(D3DADAPTER_DEFAULT, , hWnd, behaviorFlags, &d3dpp, null , &pDeviceEx);\t\n Prepare the texture sampler for monochrome convolution filtering on a single-color texture.
\t\nThe width of the filter kernel; ranging from 1 - D3DCONVOLUTIONMONO_MAXWIDTH. The default value is 1.
The height of the filter kernel; ranging from 1 - D3DCONVOLUTIONMONO_MAXHEIGHT. The default value is 1.
An array of weights, one weight for each kernel sub-element in the width. This parameter must be
An array of weights, one weight for each kernel sub-element in the height. This parameter must be
If the method succeeds, the return value is
This method is designed to filter a single color texture. A monochrome convolution filter is a 2D box filter with all of the weights set to 1.0; the filter kernel resolution ranges from 1 x 1 to 7 x 7. When monochrome texture filtering is set to a texture sampler and texture sampling is performed at location, then Direct3D performs convolution.
Restrictions include:
Copy a text string to one surface using an alphabet of glyphs on another surface. Composition is done by the GPU using bitwise operations.
\t\nA reference to a source surface (prepared by
A reference to the destination surface (prepared by
A reference to a vertex buffer (see
The number of rectangles or glyphs that are used in the operation. The number applies to both the source and destination surfaces. The range is 0 to D3DCOMPOSERECTS_MAXNUMRECTS.
A reference to a vertex buffer (see
Specifies how to combine the source and destination surfaces. See
A value added to the x coordinates of all destination rectangles. This value can be negative, which may cause the glyph to be rejected or clipped if the result is beyond the bounds of the surface.
A value added to the y coordinates of all destination rectangles. This value can be negative, which may cause the glyph to be rejected or clipped if the result is beyond the bounds of the surface.
If the method succeeds, the return value is
Glyphs from a one-bit source surface are put together into another one-bit texture surface with this method. The destination surface can then be used as the source for a normal texturing operation that will filter and scale the strings of text onto some other non-monochrome surface.
This method has several constraints (which are similar to StretchRect):
The method is not recorded in state blocks.
\t\nSwap the swapchain's next buffer with the front buffer.
\t\nPointer to a
Pointer to
Pointer to a destination window handle whose client area is taken as the target for this presentation. If this value is
Pointer to a
If this value is non-
Allows the application to request that the method return immediately when the driver reports that it cannot schedule a presentation. Valid values are 0, or any combination of
Possible return values include:
| Differences between Direct3D 9 and Direct3D 9Ex: |
?
Similar to the
When the swapchain is created with
Get the priority of the GPU thread.
\t\nCurrent GPU priority. Valid values range from -7 to 7.
Possible return values include:
Use
This method will retrieve the priority of the thread stored with the Direct3D device even if it was created with the
Set the priority on the GPU thread.
\t\nThe thread priority, ranging from -7 to 7.
Possible return values include:
GPU thread priority is not reset when a device is lost. The effects of calls to this method are not recorded in state blocks.
\t\nSuspend execution of the calling thread until the next vertical blank signal.
\t\nSwap chain index. This is an optional, zero-based index used to specify a swap chain on a multihead card.
This method will always return
This method allows applications to efficiently throttle their frame rate to that of the monitor associated with the device. Following a vertical blank, the amount of time it takes for the thread to wake up is typically very short.
In some scenarios the hardware may stop generating vertical blank signals when nothing is being displayed on the monitor. In this case, the method will wait approximately 100ms and return with
Checks an array of resources to determine if it is likely that they will cause a large stall at Draw time because the system must make the resources GPU-accessible.
\t\nAn array of
A value indicating the number of resources passed into the pResourceArray parameter up to a maximum of 65535.
If all the resources are in GPU-accessible memory, the method will return
If no allocation that comprises the resources is on disk, but at least one allocation is not in GPU-accessible memory, the method will return
If at least one allocation that comprises the resources is on disk, this method will return S_NOT_RESIDENT. The system may need to perform a copy to promote the resource.
This API is no more than a reasonable guess at residency, since resources may have been demoted by the time the application uses them.
The expected usage pattern is as follows. If the application determines that a set of resources are not resident, then the application will substitute a lower-LOD version of the resource and continue with rendering. The video memory manager API, offers a feature to allow the application to express that it would like these lower-LOD resources to be made more likely to stay resident in GPU-accessible memory. It is the app's responsibility to create, fill and destroy these lower-LOD versions, if it so chooses.
The application also needs to begin promotion of the higher-LOD versions when the residency check indicates that the resource is not resident in GPU-accessible memory. Since a per-process lock exists in kernel mode, a performant implementation will spawn a separate process whose sole job is to promote resources. The application communicates resource identity between the two process by means of the Sharing Resources shared surfaces API and promotes them by means of the SetPriority.
\t\nChecks an array of resources to determine if it is likely that they will cause a large stall at Draw time because the system must make the resources GPU-accessible.
\t\nAn array of
A value indicating the number of resources passed into the pResourceArray parameter up to a maximum of 65535.
If all the resources are in GPU-accessible memory, the method will return
If no allocation that comprises the resources is on disk, but at least one allocation is not in GPU-accessible memory, the method will return
If at least one allocation that comprises the resources is on disk, this method will return S_NOT_RESIDENT. The system may need to perform a copy to promote the resource.
This API is no more than a reasonable guess at residency, since resources may have been demoted by the time the application uses them.
The expected usage pattern is as follows. If the application determines that a set of resources are not resident, then the application will substitute a lower-LOD version of the resource and continue with rendering. The video memory manager API, offers a feature to allow the application to express that it would like these lower-LOD resources to be made more likely to stay resident in GPU-accessible memory. It is the app's responsibility to create, fill and destroy these lower-LOD versions, if it so chooses.
The application also needs to begin promotion of the higher-LOD versions when the residency check indicates that the resource is not resident in GPU-accessible memory. Since a per-process lock exists in kernel mode, a performant implementation will spawn a separate process whose sole job is to promote resources. The application communicates resource identity between the two process by means of the Sharing Resources shared surfaces API and promotes them by means of the SetPriority.
\t\nSet the number of frames that the system is allowed to queue for rendering.
\t\nThe maximum number of back buffer frames that a driver can queue. The value is typically 3, but can range from 1 to 20. A value of 0 will reset latency to the default. For multi-head devices, MaxLatency is specified per-head.
Possible return values include:
Frame latency is the number of frames that are allowed to be stored in a queue, before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue.
It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
\t\nRetrieves the number of frames of data that the system is allowed to queue.
\t\nReturns the number of frames that can be queued for render. The value is typically 3, but can range from 1 to 20.
Possible return values include:
Frame latency is the number of frames that are allowed to be stored in a queue, before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue.
It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
\t\nReports the current cooperative-level status of the Direct3D device for a windowed or full-screen application.
\t\nThe destination window handle to check for occlusion. When this parameter is
Possible return values include:
This method replaces
We recommend not to call CheckDeviceState every frame. Instead, call CheckDeviceState only if the
See Lost Device Behavior Changes for more information about lost, hung, and removed devices.
\t\nCreates a render-target surface.
\t\nWidth of the render-target surface, in pixels.
Height of the render-target surface, in pixels.
Member of the
Member of the
Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by
Render targets are not lockable unless the application specifies TRUE for Lockable.
Note that lockable render targets reduce performance on some graphics hardware. The readback performance (moving data from video memory to system memory) depends on the type of hardware used (AGP vs. PCI Express) and is usually far lower than upload performance (moving data from system to video memory). If you need read access to render targets, use GetRenderTargetData instead of lockable render targets.
Reserved. Set this parameter to
Combination of one or more
Address of a reference to an
Render-target surfaces are placed in the
The creation of lockable, multisampled render targets is not supported.
\t\nCreate an off-screen surface.
\t\nWidth of the surface.
Height of the surface.
Format of the surface. See
Surface pool type. See
Reserved. Set this parameter to
Combination of one or more
Pointer to the
Off-screen plain surfaces are always lockable, regardless of their pool types.
\t\nCreates a depth-stencil surface.
\t\nWidth of the depth-stencil surface, in pixels.
Height of the depth-stencil surface, in pixels.
Member of the
Member of the
Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by
Set this flag to TRUE to enable z-buffer discarding, and
This flag has the same behavior as the constant,
Reserved. Set this parameter to
Combination of one or more
Address of a reference to an
The memory class of the depth-stencil buffer is always
Resets the type, size, and format of the swap chain with all other surfaces persistent.
\t\nPointer to a
When switching to full-screen mode, Direct3D will try to find a desktop format that matches the back buffer format, so that back buffer and front buffer formats will be identical (to eliminate the need for color conversion).
When this method returns:
Pointer to a
The method can return:
If this method returns
If a call to
Unlike previous versions of DirectX, calling
Pixel shaders and vertex shaders survive
There are two different types of swap chains: full-screen or windowed. If the new swap chain is full-screen, the adapter will be placed in the display mode that matches the new size.
Applications can expect messages to be sent to them during this call (for example, before this call is returned); applications should take precautions not to call into Direct3D at this time.
A call to
When trying to reset more than one display adapter in a group, set pPresentationParameters to point to an array of
If a multihead device was created with
Retrieves the display mode's spatial resolution, color resolution, refresh frequency, and rotation settings.
\t\nAn unsigned integer specifying the swap chain.
Pointer to a
Pointer to a
Get or sets the priority of the GPU thread.
\t\nUse
This method will retrieve the priority of the thread stored with the Direct3D device even if it was created with the
Retrieves or sets the number of frames of data that the system is allowed to queue.
\t\nFrame latency is the number of frames that are allowed to be stored in a queue, before submission for rendering. Latency is often used to control how the CPU chooses between responding to user input and frames that are in the render queue.
It is often beneficial for applications that have no user input (for example, video playback) to queue more than 3 frames of data.
\t\nApplications use the methods of the
The
The LPDIRECT3D9 and PDIRECT3D9 types are defined as references to the
typedef struct *LPDIRECT3D9, *PDIRECT3D9; LPDIRECT3D9 g_pD3D = NULL; if( NULL == (g_pD3D = Direct3DCreate9(D3D_SDK_VERSION))) return E_FAIL; \t\n \t\n The IDirect3D9 interface supports enumeration of active display adapters and allows the creation of Registers a pluggable software device. Software devices provide software rasterization enabling applications to access a variety of software rasterizers.
\t\nPointer to the initialization function for the software device to be registered.
If the method succeeds, the return value is
If the user's computer provides no special hardware acceleration for 3D operations, your application might emulate 3D hardware in software. Software rasterization devices emulate the functions of color 3D hardware in software. A software device runs more slowly than a hal. However, software devices take advantage of any special instructions supported by the CPU to increase performance. Instruction sets include the AMD 3DNow! instruction set on some AMD processors and the MMX instruction set supported by many Intel processors. Direct3D uses the 3D-Now! instruction set to accelerate transformation and lighting operations and the MMX instruction set to accelerate rasterization.
Software devices communicate with Direct3D through an interface similar to the hardware device driver interface (DDI).
Software devices are loaded by the application and registered with the
The Direct3D Driver Development Kit (DDK) provides the documentation and headers for developing pluggable software devices.
\t\nReturns the number of adapters on the system.
\t\nA UINT value that denotes the number of adapters on the system at the time this
Describes the physical display adapters present in the system when the
Returns the number of display modes available on this adapter.
\t\nOrdinal number that denotes the display adapter. D3DADAPTER_DEFAULT is always the primary display adapter.
Identifies the format of the surface type using
This method returns the number of display modes on this adapter or zero if Adapter is greater than or equal to the number of adapters on the system.
Queries the device to determine whether the specified adapter supports the requested format and display mode. This method could be used in a loop to enumerate all the available adapter modes.
\t\nOrdinal number denoting the display adapter to enumerate. D3DADAPTER_DEFAULT is always the primary display adapter. This method returns
Allowable pixel formats. See Remarks.
Represents the display-mode index which is an unsigned integer between zero and the value returned by GetAdapterModeCount minus one.
A reference to the available display mode of type
An application supplies a display mode and a format to EnumAdapterModes which returns a display mode. This method could be used in a loop to enumerate all available display modes.
The application specifies a format and the enumeration is restricted to those display modes that exactly match the format (alpha is ignored). Allowed formats (which are members of
In addition, EnumAdapterModes treats pixel formats 565 and 555 as equivalent, and returns the correct version. The difference comes into play only when the application locks the back buffer and there is an explicit flag that the application must set in order to accomplish this.
\t\nRetrieves the current display mode of the adapter.
\t\nOrdinal number that denotes the display adapter to query. D3DADAPTER_DEFAULT is always the primary display adapter.
Pointer to a
GetAdapterDisplayMode will not return the correct format when the display is in an extended format, such as 2:10:10:10. Instead, it returns the format X8R8G8B8.
\t\nVerifies whether a hardware accelerated device type can be used on this adapter.
\t\nOrdinal number denoting the display adapter to enumerate. D3DADAPTER_DEFAULT is always the primary display adapter. This method returns
Member of the
Member of the
Back buffer format. For more information about formats, see
Value indicating whether the device type will be used in full-screen or windowed mode. If set to TRUE, the query is performed for windowed applications; otherwise, this value should be set
If the device can be used on this adapter,
A hal device type requires hardware acceleration. Applications can use CheckDeviceType to determine if the needed hardware and drivers are present to support a hal device.
Full-screen applications should not specify a DisplayFormat that contains an alpha channel. This will result in a failed call. Note that an alpha channel can be present in the back buffer but the two display formats must be identical in all other respects. For example, if DisplayFormat =
The following code fragment shows how you could use CheckDeviceType to test whether a certain device type can be used on this adapter.
if(SUCCEEDED(pD3Device->CheckDeviceType(D3DADAPTER_DEFAULT, , DisplayFormat, BackBufferFormat, bIsWindowed))) return ;\t\n // There is no HAL on this adapter using this render-target format. \t\n // Try again, using another format.\t\n This code returns
Using CheckDeviceType to test for compatibility between a back buffer that differs from the display format will return appropriate values. This means that the call will reflect device capabilities. If the device cannot render to the requested back-buffer format, the call will still return
Determines whether a surface format is available as a specified resource type and can be used as a texture, depth-stencil buffer, or render target, or any combination of the three, on a device representing this adapter.
\t\nOrdinal number denoting the display adapter to query. D3DADAPTER_DEFAULT is always the primary display adapter. This method returns
Member of the
Member of the
Requested usage options for the surface. Usage options are any combination of
Resource type requested for use with the queried format. Member of
Format of the surfaces which may be used, as defined by Usage. Member of
If the format is compatible with the specified device for the requested usage, this method returns
Here are some examples using CheckDeviceFormat to check for hardware support of:
IsDepthFormatExisting( DepthFormat, AdapterFormat ) \t\n { hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT, , AdapterFormat, , , DepthFormat); return SUCCEEDED( hr );\t\n } See Selecting a Device (Direct3D 9) for more detail on the enumeration process.
IsTextureFormatOk( TextureFormat, AdapterFormat ) \t\n { hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT, , AdapterFormat, 0, , TextureFormat); return SUCCEEDED( hr );\t\n } When migrating code from Direct3D 9 to Direct3D 10, the Direct3D 10 equivalent to CheckDeviceFormat is CheckFormatSupport.
\t\nDetermines if a multisampling technique is available on this device.
\t\nOrdinal number denoting the display adapter to query. D3DADAPTER_DEFAULT is always the primary display adapter. This method returns
Member of the
Member of the
bool value. Specify TRUE to inquire about windowed multisampling, and specify
Member of the
pQualityLevels returns the number of device-specific sampling variations available with the given sample type. For example, if the returned value is 3, then quality levels 0, 1 and 2 can be used when creating resources with the given sample count. The meanings of these quality levels are defined by the device manufacturer and cannot be queried through D3D. For example, for a particular device different quality levels at a fixed sample count might refer to different spatial layouts of the sample locations or different methods of resolving. This can be
If the device can perform the specified multisampling method, this method returns
This method is intended for use with both render-target and depth-stencil surfaces because you must create both surfaces multisampled if you want to use them together.
The following code fragment shows how you could use CheckDeviceMultiSampleType to test for devices that support a specific multisampling method.
if( SUCCEEDED(pD3D->CheckDeviceMultiSampleType( pCaps->AdapterOrdinal, pCaps->DeviceType, BackBufferFormat, , , null ) ) && SUCCEEDED(pD3D->CheckDeviceMultiSampleType( pCaps->AdapterOrdinal, pCaps->DeviceType, DepthBufferFormat, , , null ) ) ) return ;\t\n The preceding code will return
See the remarks in
Determines whether a depth-stencil format is compatible with a render-target format in a particular display mode.
\t\nOrdinal number denoting the display adapter to query. D3DADAPTER_DEFAULT is always the primary display adapter.
Member of the
Member of the
Member of the
Member of the
If the depth-stencil format is compatible with the render-target format in the display mode, this method returns
This method is provided to enable applications to work with hardware requiring that certain depth formats can only work with certain render-target formats.
The behavior of this method has been changed for DirectX 8.1. This method now pays attention to the D24x8 and D32 depth-stencil formats. The previous version assumed that these formats would always be usable with 32- or 16-bit render targets. This method will now return
The following code fragment shows how you could use CheckDeviceFormat to validate a depth stencil format.
IsDepthFormatOk( DepthFormat, AdapterFormat, BackBufferFormat)\t\n { // Verify that the depth format exists hr = pD3D->CheckDeviceFormat(D3DADAPTER_DEFAULT, , AdapterFormat, , , DepthFormat); if(FAILED(hr)) return ; // Verify that the depth format is compatible hr = pD3D->CheckDepthStencilMatch(D3DADAPTER_DEFAULT, , AdapterFormat, BackBufferFormat, DepthFormat); return SUCCEEDED(hr); }\t\n The preceding call will return
Tests the device to see if it supports conversion from one display format to another.
\t\nDisplay adapter ordinal number. D3DADAPTER_DEFAULT is always the primary display adapter. This method returns
Device type. Member of the
Source adapter format. Member of the
Target adapter format. Member of the
If the method succeeds, the return value is
Using CheckDeviceType to test for compatibility between a back buffer that differs from the display format will return appropriate values. This means that the call will reflect device capabilities. If the device cannot render to the requested back buffer format, the call will still return
CheckDeviceFormatConversion can also be used to determine which combinations of source surface formats and destination surface formats are permissible in calls to StretchRect.
Color conversion is restricted to the following source and target formats.
?
Retrieves device-specific information about a device.
\t\nOrdinal number that denotes the display adapter. D3DADAPTER_DEFAULT is always the primary display adapter.
Member of the
Pointer to a
The application should not assume the persistence of vertex processing capabilities across Direct3D device objects. The particular capabilities that a physical device exposes may depend on parameters supplied to CreateDevice. For example, the capabilities may yield different vertex processing capabilities before and after creating a Direct3D Device Object with hardware vertex processing enabled. For more information see the description of
Returns the handle of the monitor associated with the Direct3D object.
\t\nOrdinal number that denotes the display adapter. D3DADAPTER_DEFAULT is always the primary display adapter.
Handle of the monitor associated with the Direct3D object.
As shown in the following code fragment, which illustrates how to obtain a handle to the monitor associated with a given device, use GetDirect3D to return the Direct3D enumerator from the device and use GetCreationParameters to retrieve the value for Adapter.
if( FAILED( pDevice->GetCreationParameters( &Parameters ) ) ) return ; if( FAILED( pDevice->GetDirect3D(&pD3D) ) ) return ; hMonitor = pD3D->GetAdapterMonitor(Parameters.AdapterOrdinal); pD3D->Release();\t\n Creates a device to represent the display adapter.
\t\nOrdinal number that denotes the display adapter. D3DADAPTER_DEFAULT is always the primary display adapter.
Member of the
The focus window alerts Direct3D when an application switches from foreground mode to background mode. See Remarks. \t
Combination of one or more options that control device creation. For more information, see
Pointer to a
For Windows 2000 and Windows XP, the full-screen device display refresh rate is set in the following order:
An unsupported refresh rate will default to the closest supported refresh rate below it. For example, if the application specifies 63 hertz, 60 hertz will be used. There are no supported refresh rates below 57 hertz.
pPresentationParameters is both an input and an output parameter. Calling this method may change several members including:
Address of a reference to the returned
If the method succeeds, the return value is
This method returns a fully working device interface, set to the required display mode (or windowed), and allocated with the appropriate back buffers. To begin rendering, the application needs only to create and set a depth buffer (assuming EnableAutoDepthStencil is
When you create a Direct3D device, you supply two different window parameters: a focus window (hFocusWindow) and a device window (the hDeviceWindow in
This method should not be run during the handling of WM_CREATE. An application should never pass a window handle to Direct3D while handling WM_CREATE. Any call to create, release, or reset the device must be done using the same thread as the window procedure of the focus window.
Note that
Back buffers created as part of the device are only lockable if
The methods Reset,
If you attempt to create a device on a 0x0 sized window, CreateDevice will fail.
\t\nReturns the number of adapters on the system.
\t\nApplications use the methods of the
The
The LPDIRECT3D9EX and PDIRECT3D9EX types are defined as references to the
typedef struct *LPDIRECT3D9EX, *PDIRECT3D9EX;\t\n Returns the number of display modes available.
\t\nOrdinal number denoting the display adapter from which to retrieve the display mode count.
Specifies the characteristics of the desired display mode. See
The number of display modes available. A return of value zero from this method is an indication that no such display mode is supported or simply this monitor is no longer available.
Events such as display mode changes on other heads of the same hardware, monitor change or its connection status change, and desktop extension/unextension could all affect the number of display mode available.
To fullscreen applications,
To increase the chance of setting a currently available display mode successfully, fullscreen applications should try to requery the available display mode list upon receiving
This method returns the actual display mode info based on the given mode index.
\t\nOrdinal number denoting the display adapter to enumerate. D3DADAPTER_DEFAULT is always the primary display adapter. This method returns
See
Represents the display-mode index which is an unsigned integer between zero and the value returned by GetAdapterModeCount minus one.
A reference to the available display mode of type
Retrieves the current display mode and rotation settings of the adapter.
\t\nOrdinal number that denotes the display adapter to query. D3DADAPTER_DEFAULT is always the primary display adapter.
Pointer to a
Pointer to a
GetAdapterDisplayModeEx does not return the correct format when the display is in an extended format, such as 2:10:10:10. Instead, it returns the format X8R8G8B8.
To windowed applications, a value of
Creates a device to represent the display adapter.
\t\nOrdinal number that denotes the display adapter. D3DADAPTER_DEFAULT is always the primary display adapter.
Specifies the type of device. See
The focus window alerts Direct3D when an application switches from foreground mode to background mode. For full-screen mode, the window specified must be a top-level window. For windowed mode, this parameter may be
Combination of one or more options (see
Pointer to a
This parameter is both an input and an output parameter. Calling this method may change several members including:
The display mode for when the device is set to fullscreen. See
Address of a reference to the returned
This method returns
This method returns a unique identifier for the adapter that is specific to the adapter hardware. Applications can use this identifier to define robust mappings across various APIs (Direct3D 9, DXGI).
\t\nOrdinal number denoting the display adapter from which to retrieve the
A unique identifier for the given adapter.
Used to set and query effects, and to choose techniques. An effect object can contain multiple techniques to render the same effect.
\t\nThe
The LPD3DXEFFECT type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXEFFECT;\t\n Gets a reference to the pool of shared parameters.
\t\nPointer to a
This method always returns the value
Pools contain shared parameters between effects. See Cloning and Sharing (Direct3D 9).
\t\nSets the active technique.
\t\nUnique handle to the technique. See Handles (Direct3D 9).
If the method succeeds, the return value is
Gets the current technique.
\t\nA unique identifier to the current technique. See Handles (Direct3D 9).
Validate a technique.
\t\nUnique identifier. See Handles (Direct3D 9).
If the method succeeds, the return value is
Searches for the next valid technique, starting at the technique after the specified technique.
\t\nUnique identifier to a technique. See Handles (Direct3D 9). Specify
Pointer to an identifier for the next technique.
Determines if a parameter is used by the technique.
\t\nUnique identifier for the parameter. See Handles (Direct3D 9).
Unique identifier for the technique. See Handles (Direct3D 9).
Returns TRUE if the parameter is being used and returns
Starts an active technique.
\t\nDWORD that determines if state modified by an effect is saved and restored. The default value 0 specifies that
Pointer to a value returned that indicates the number of passes needed to render the current technique.
An application sets one active technique in the effect system by calling
Within the
Begins a pass, within the active technique.
\t\nA zero-based integer index into the technique.
If the method succeeds, the return value is
An application sets one active pass (within one active technique) in the effect system by calling
If the application changes any effect state using any of the Effect::Setx methods inside of a
Propagate state changes that occur inside of an active pass to the device before rendering.
\t\nIf the method succeeds, the return value is
If the application changes any effect state using any of the ID3DXEffect::Setx methods inside of an
This is slightly different for any shared parameters in a cloned effect. When a technique is active on a cloned effect (that is, when
End an active pass.
\t\nThis method always returns the value
An application signals the end of rendering an active pass by calling
Each matching pair of
If the application changes any effect state using any of the Effect::Setx methods inside of a
Ends an active technique.
\t\nThis method always returns the value
All rendering in an effect is done within a matching pair of
By default, the effect system takes care of saving state prior to a technique, and restoring state after a technique. If you choose to disable this save and restore functionality, see
Retrieves the device associated with the effect.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Calling this method will increase the internal reference count for the
Use this method to release all references to video memory resources and delete all stateblocks. This method should be called whenever a device is lost, or before resetting a device.
\t\nIf the method succeeds, the return value is
This method should be called whenever the device is lost or before the user calls
Use this method to re-acquire resources and save initial state.
\t\nIf the method succeeds, the return value is
Set the effect state manager.
\t\nA reference to the state manager. See
If the method succeeds, the return value is
The
Get the effect state manager.
\t\nReturns a reference to the state manager. See
If the method succeeds, the return value is
The
Start capturing state changes in a parameter block.
\t\nIf the method succeeds, the return value is
Capture effect parameter state changes until EndParameterBlock is called. Effect parameters include any state changes outside of a pass. Delete parameter blocks if they are no longer needed by calling DeleteParameterBlock.
\t\nStop capturing effect parameter state changes.
\t\nReturns a handle to the parameter state block.
All effect parameters that change state (after calling BeginParameterBlock and before calling EndParameterBlock) will be saved in an effect parameter state block. Use ApplyParameterBlock to apply this block of state changes to the effect system. Once you are finished with a state block use DeleteParameterBlock to free the memory.
\t\nApply the values in a state block to the current effect system state.
\t\nA handle to the parameter block. This is the handle returned by
If the method succeeds, the return value is
Capture effect parameter state changes in a parameter block by calling BeginParameterBlock; stop capturing state changes by calling EndParameterBlock. These state changes include any effect parameter changes that occur inside of a technique (including those outside of a pass). Once you are done with the parameter block, call DeleteParameterBlock to recover memory.
\t\nDelete a parameter block.
\t\nA handle to the parameter block. This is the handle returned by
If the method succeeds, the return value is
Parameter blocks are blocks of effect states. Use a parameter block to record state changes so that they can be applied later on with a single API call. When no longer needed, delete the parameter block to reduce memory usage.
\t\nCreates a copy of an effect.
\t\nPointer to an
Pointer to an
Note??This function will not clone an effect if the user specifies
To update shared and non-shared parameters in an active technique of a cloned effect, see
Set a contiguous range of shader constants with a memory copy.
\t\nHandle to the value to set, or the name of the value passed in as a string. Passing in a handle is more efficient. See Handles (Direct3D 9).
Pointer to a buffer containing the data to be set. SetRawValue checks for valid memory, but does not do any checking for valid data.
Number of bytes between the beginning of the effect data and the beginning of the effect constants you are going to set.
The size of the buffer to be set, in bytes.
If the method succeeds, the return value is
SetRawValue is a very fast way to set effect constants since it performs a memory copy without performing validation or any data conversion (like converting a row-major matrix to a column-major matrix). Use SetRawValue to set a series of contiguous effect constants. For instance, you could set an array of twenty matrices with 20 calls to
All values are expected to be either matrix4x4s or float4s and all matrices are expected to be in column-major order. Int or float values are cast into a float4; therefore, it is highly recommended that you use SetRawValue with only float4 or matrix4x4 data.
\t\nGets a reference to the pool of shared parameters.
\t\nPools contain shared parameters between effects. See Cloning and Sharing (Direct3D 9).
\t\nRetrieves the device associated with the effect.
\t\nCalling this method will increase the internal reference count for the
Get or sets the effect state manager.
\t\nThe
Compiles a shader from an effect that contains one or more functions.
\t\nTargets can be specified for vertex shaders, pixel shaders, and texture fill functions.
| Vertex shader targets | vs_1_1, vs_2_0, vs_2_sw, vs_3_0 |
| Pixel shader targets | ps_1_1, ps_1_2, ps_1_3, ps_1_4, ps_2_0, ps_2_sw, ps_3_0 |
| Texture fill targets | tx_0, tx_1 |
?
This method compiles a shader from a function that is written in a C-like language. For more information, see HLSL.
\t\nToggles the literal status of a parameter. A literal parameter has a value that doesn't change during the lifetime of an effect.
\t\nUnique identifier to a parameter. See Handles (Direct3D 9).
Set to TRUE to make the parameter a literal, and
If the method succeeds, the return value is
This methods only changes whether the parameter is a literal or not. To change the value of a parameter, use a method like
This function must be called before the effect is compiled. Here is an example of how one might use this function:
LPD3DXEFFECTCOMPILER pEffectCompiler; char errors[1000]; hr; hr = (\"shader.fx\", null , null , 0, &pEffectCompiler, &errors); //In the fx file, literalInt is declared as an int. //By calling this function, the compiler will treat //it as a literal (i.e. #define) hr = pEffectCompiler->SetLiteral(\"literalInt\", TRUE); //create ten different variations of the same effect LPD3DXBUFFER pEffects[10]; LPD3DXBUFFER pErrors; for(int i = 0; i < 10; ++i) { hr = pEffectCompiler->SetInt(\"literalInt\", i); hr = pEffectCompiler->CompileEffect(0, &pEffects[i], &pErrors); }\t\n Gets a literal status of a parameter. A literal parameter has a value that doesn't change during the lifetime of an effect.
\t\nUnique identifier to a parameter. See Handles (Direct3D 9).
Returns True if the parameter is a literal, and False otherwise.
This methods only changes whether the parameter is a literal or not. To change the value of a parameter, use a method like
Compile an effect.
\t\nCompile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Buffer containing the compiled effect. For more information about accessing the buffer, see
Buffer containing at least the first compile error message that occurred. This includes effect compiler errors and high-level language compile errors. For more information about accessing the buffer, see
If the method succeeds, the return value is
If the arguments are invalid, the method will return
If the method fails, the return value will be E_FAIL.
Compiles a shader from an effect that contains one or more functions.
\t\nUnique identifier to the function to be compiled. This value must not be
Pointer to a shader profile which determines the shader instruction set. See
Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Buffer containing the compiled shader. The compiler shader is an array of DWORDs. For more information about accessing the buffer, see
Buffer containing at least the first compile error message that occurred. This includes effect compiler errors and high-level language compile errors. For more information about accessing the buffer, see
Returns an
If the method succeeds, the return value is
If the arguments are invalid, the method will return
If the method fails, the return value will be E_FAIL.
Targets can be specified for vertex shaders, pixel shaders, and texture fill functions.
| Vertex shader targets | vs_1_1, vs_2_0, vs_2_sw, vs_3_0 |
| Pixel shader targets | ps_1_1, ps_1_2, ps_1_3, ps_1_4, ps_2_0, ps_2_sw, ps_3_0 |
| Texture fill targets | tx_0, tx_1 |
?
This method compiles a shader from a function that is written in a C-like language. For more information, see HLSL.
\t\nEffect default parameters.
\t\nParameter name.
Data type in pValue. For more information, see
Size, in bytes, of the data pointed to by pValue.
Pointer to the memory location that contains the data.
Data type for managing a set of default effect parameters.
\t\nName of the effect file.
Number of default parameters.
Pointer to an array of
Applications use the
The
The LPD3DXEFFECTPOOL type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXEFFECTPOOL;\t\n The
The
The LPD3DXFONT type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DXFONT;\t\n Retrieves the Direct3D device associated with the font object.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Note??Calling this method will increase the internal reference count on the
Gets a description of the current font object. GetDescW and GetDescA are identical to this method, except that a reference is returned to a
If the method succeeds, the return value is
This method describes Unicode font objects if UNICODE is defined. Otherwise GetDescA is called, which returns a reference to the D3DXFONT_DESCA structure.
\t\nRetrieves font characteristics that are identified in a
Nonzero if the function is successful; otherwise 0.
The compiler setting also determines the structure type. If Unicode is defined, the function returns a
Returns a handle to a display device context (DC) that has the font set.
\t\nHandle to a display DC.
Returns information about the placement and orientation of a glyph in a character cell.
\t\nGlyph identifier.
Address of a reference to a
Pointer to the smallest rectangle object that completely encloses the glyph.
Pointer to the two-dimensional vector that connects the origin of the current character cell to the origin of the next character cell. See
If the method succeeds, the return value is
Loads a series of characters into video memory to improve the efficiency of rendering to the device.
\t\nID of the first character to be loaded into video memory.
ID of the last character to be loaded into video memory.
If the method succeeds, the return value is
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; DrawText must still be called to render the characters. However, by pre-loading characters into video memory, DrawText will use substantially fewer CPU resources.
This method internally converts characters to glyphs using the GDI function GetCharacterPlacement.
\t\nLoads a series of glyphs into video memory to improve the efficiency of rendering to the device.
\t\nID of the first glyph to be loaded into video memory.
ID of the last glyph to be loaded into video memory.
If the method succeeds, the return value is
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; DrawText must still be called to render the glyphs. However, by pre-loading glyphs into video memory, DrawText will use substantially fewer CPU resources.
\t\nLoads formatted text into video memory to improve the efficiency of rendering to the device. This method supports ANSI and Unicode strings.
\t\nPointer to a string of characters to be loaded into video memory. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR; otherwise, the data type resolves to LPCSTR. See Remarks.
Number of characters in the text string.
If the method succeeds, the return value is
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; DrawText must still be called to render the text. However, by preloading text into video memory, DrawText will use substantially fewer CPU resources.
This method internally converts characters to glyphs using the GDI function GetCharacterPlacement.
\t\nDraws formatted text. This method supports ANSI and Unicode strings.
\t\nPointer to an
Pointer to a string to draw. If the Count parameter is -1, the string must be null-terminated.
Specifies the number of characters in the string. If Count is -1, then the pString parameter is assumed to be a reference to a null-terminated string and DrawText computes the character count automatically.
Pointer to a
Specifies the method of formatting the text. It can be any combination of the following values:
| Value | Meaning |
|---|---|
| Justifies the text to the bottom of the rectangle. This value must be combined with DT_SINGLELINE. |
| Determines the width and height of the rectangle. If there are multiple lines of text, DrawText uses the width of the rectangle pointed to by the pRect parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawText returns the height of the formatted text but does not draw the text. |
| Centers text horizontally in the rectangle. |
| Expands tab characters. The default number of characters per tab is eight. |
| Aligns text to the left. |
| Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used. |
| Aligns text to the right. |
| Displays text in right-to-left reading order for bidirectional text when a Hebrew or Arabic font is selected. The default reading order for all text is left-to-right. |
| Displays text on a single line only. Carriage returns and line feeds do not break the line. |
| Top-justifies text. |
| Centers text vertically (single line only). |
| Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the pRect parameter. A carriage return/line feed sequence also breaks the line. |
?
Color of the text. For more information, see
If the function succeeds, the return value is the height of the text in logical units. If DT_VCENTER or DT_BOTTOM is specified, the return value is the offset from pRect (top to the bottom) of the drawn text. If the function fails, the return value is zero.
The parameters of this method are very similar to those of the GDI DrawText function.
This method supports both ANSI and Unicode strings.
This method must be called inside a BeginScene ... EndScene block. The only exception is when an application calls DrawText with DT_CALCRECT to calculate the size of a given block of text.
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.
\t\nUse this method to release all references to video memory resources and delete all stateblocks. This method should be called whenever a device is lost, or before resetting a device.
\t\nIf the method succeeds, the return value is
This method should be called whenever the device is lost or before the user calls Reset. Even if the device was not actually lost, OnLostDevice is responsible for freeing stateblocks and other resources that may need to be released before resetting the device. As a result, the font object cannot be used again before calling Reset and then OnResetDevice.
\t\nUse this method to re-acquire resources and save initial state.
\t\nIf the method succeeds, the return value is
OnResetDevice should be called each time the device is reset (using Reset), before any other methods are called. This is a good place to re-acquire video-memory resources and capture state blocks.
\t\nRetrieves the Direct3D device associated with the font object.
\t\nNote??Calling this method will increase the internal reference count on the
Gets a description of the current font object. GetDescW and GetDescA are identical to this method, except that a reference is returned to a
This method describes Unicode font objects if UNICODE is defined. Otherwise GetDescA is called, which returns a reference to the D3DXFONT_DESCA structure.
\t\nReturns a handle to a display device context (DC) that has the font set.
\t\nDefines constants that describe the type of back buffer.
\t\nDirect3D 9 does not support stereo view, so Direct3D does not use the
Specifies a nonstereo swap chain.
Specifies the left side of a stereo pair in a swap chain.
Specifies the right side of a stereo pair in a swap chain.
Defines the basis type of a high-order patch surface.
\t\nThe members of
Input vertices are treated as a series of B?zier patches. The number of vertices specified must be divisible by 4. Portions of the mesh beyond this criterion will not be rendered. Full continuity is assumed between sub-patches in the interior of the surface rendered by each call. Only the vertices at the corners of each sub-patch are guaranteed to lie on the resulting surface.
Input vertices are treated as control points of a B-spline surface. The number of apertures rendered is two fewer than the number of apertures in that direction. In general, the generated surface does not contain the control vertices specified.
An interpolating basis defines the surface so that the surface goes through all the input vertices specified. In DirectX 8, this was D3DBASIS_INTERPOLATE.
Defines the supported blend mode.
\t\nIn the preceding member descriptions, the RGBA values of the source and destination are indicated by the s and d subscripts.
The values in this enumerated type are used by the following render states:
See
Direct3D 9Ex has improved text rendering capabilities. Rendering clear-type fonts would normally require two passes. To eliminate the second pass, a pixel shader can be used to output two colors, which we can call PSOutColor[0] and PSOutColor[1]. The first color would contain the standard 3 color components (RGB). The second color would contain 3 alpha components (one for each component of the first color).
These new blending modes are only used for text rendering on the first render target.
\t\nBlend factor is (0, 0, 0, 0).
Blend factor is (1, 1, 1, 1).
Blend factor is (Rs, Gs, Bs, As).
Blend factor is (1 - Rs, 1 - Gs, 1 - Bs, 1 - As).
Blend factor is (As, As, As, As).
Blend factor is ( 1 - As, 1 - As, 1 - As, 1 - As).
Blend factor is (Ad Ad Ad Ad).
Blend factor is (1 - Ad 1 - Ad 1 - Ad 1 - Ad).
Blend factor is (Rd, Gd, Bd, Ad).
Blend factor is (1 - Rd, 1 - Gd, 1 - Bd, 1 - Ad).
Blend factor is (f, f, f, 1); where f = min(As, 1 - Ad).
Obsolete. Starting with DirectX 6, you can achieve the same effect by setting the source and destination blend factors to
Source blend factor is (1 - As, 1 - As, 1 - As, 1 - As), and destination blend factor is (As, As, As, As); the destination blend selection is overridden. This blend mode is supported only for the
Constant color blending factor used by the frame-buffer blender. This blend mode is supported only if
Inverted constant color-blending factor used by the frame-buffer blender. This blend mode is supported only if the
Blend factor is (PSOutColor[1]r, PSOutColor[1]g, PSOutColor[1]b, not used). See Render.
| Differences between Direct3D 9 and Direct3D 9Ex: This flag is available in Direct3D 9Ex only. |
?
Blend factor is (1 - PSOutColor[1]r, 1 - PSOutColor[1]g, 1 - PSOutColor[1]b, not used)). See Render.
| Differences between Direct3D 9 and Direct3D 9Ex: This flag is available in Direct3D 9Ex only. |
?
Defines the supported blend operations. See Remarks for definitions of terms.
\t\nSource, Destination, and Result are defined as:
| Term | Type | Description |
|---|---|---|
| Source | Input | Color of the source pixel before the operation. |
| Destination | Input | Color of the pixel in the destination buffer before the operation. |
| Result | Output | Returned value that is the blended color resulting from the operation. |
?
This enumerated type defines values used by the following render states:
The result is the destination added to the source. Result = Source + Destination
The result is the destination subtracted from to the source. Result = Source - Destination
The result is the source subtracted from the destination. Result = Destination - Source
The result is the minimum of the source and destination. Result = MIN(Source, Destination)
The result is the maximum of the source and destination. Result = MAX(Source, Destination)
Flags used to obtain callback information.
\t\nExclude callbacks located at the initial position from the search.
Reverse the callback search direction.
Driver capability flags.
\t\nDriver capability flags.
\t\nDefines operations to perform on vertices in preparation for mesh cleaning.
\t\nMerge triangles that share the same vertex indices but have face normals pointing in opposite directions (back-facing triangles). Unless the triangles are not split by adding a replicated vertex, mesh adjacency data from the two triangles may conflict.
If a vertex is the apex of two triangle fans (a bowtie) and mesh operations will affect one of the fans, then split the shared vertex into two new vertices. Bowties can cause problems for operations such as mesh simplification that remove vertices, because removing one vertex affects two distinct sets of triangles.
Use this flag to prevent infinite loops during skinning setup mesh operations.
Use this flag to prevent infinite loops during mesh optimization operations.
Use this flag to prevent infinite loops during mesh simplification operations.
These flags identify a surface to reset when calling Clear.
\t\nDefines the supported compare functions.
\t\nThe values in this enumerated type define the supported compare functions for the
Always fail the test.
Accept the new pixel if its value is less than the value of the current pixel.
Accept the new pixel if its value equals the value of the current pixel.
Accept the new pixel if its value is less than or equal to the value of the current pixel.
Accept the new pixel if its value is greater than the value of the current pixel.
Accept the new pixel if its value does not equal the value of the current pixel.
Accept the new pixel if its value is greater than or equal to the value of the current pixel.
Always pass the test.
Specifies how to combine the glyph data from the source and destination surfaces in a call to ComposeRects.
\t\nDefines the compression mode used for storing compressed animation set data.
\t\nImplements fast compression.
A combination of one or more flags that control the device create behavior.
\t\nDefines the faces of a cubemap.
\t\nPositive x-face of the cubemap.
Negative x-face of the cubemap.
Positive y-face of the cubemap.
Negative y-face of the cubemap.
Positive z-face of the cubemap.
Negative z-face of the cubemap.
Driver cursor capability flags.
\t\nDefines the vertex declaration method which is a predefined operation performed by the tessellator (or any procedural geometry routine on the vertex data during tessellation).
\t\nThe tessellator looks at the method to determine what data to calculate from the vertex data during tessellation. Mesh data should use the default value. Patches can use any of the other implemented types.
Vertex data is declared with an array of
In addition to using
Default value. The tessellator copies the vertex data (spline data for patches) as is, with no additional calculations. When the tessellator is used, this element is interpolated. Otherwise vertex data is copied into the input register. The input and output type can be any value, but are always the same type.
Computes the tangent at a point on the rectangle or triangle patch in the U direction. The input type can be one of the following:\t\n
The output type is always
Computes the tangent at a point on the rectangle or triangle patch in the V direction. The input type can be one of the following:\t\n
The output type is always
Computes the normal at a point on the rectangle or triangle patch by taking the cross product of two tangents. The input type can be one of the following:\t\n
The output type is always
Copy out the U, V values at a point on the rectangle or triangle patch. This results in a 2D float. The input type must be set to
Look up a displacement map. The input type can be one of the following:\t\n
Only the .x and .y components are used for the texture map lookup. The output type is always
Look up a presampled displacement map. The input type must be set to
Defines a vertex declaration data type.
\t\nVertex data is declared with an array of
Use the DirectX Caps Viewer Tool tool to see which types are supported on your device.
\t\nOne-component float expanded to (float, 0, 0, 1).
Two-component float expanded to (float, float, 0, 1).
Three-component float expanded to (float, float, float, 1).
Four-component float expanded to (float, float, float, float).
Four-component, packed, unsigned bytes mapped to 0 to 1 range. Input is a
Four-component, unsigned byte.
Two-component, signed short expanded to (value, value, 0, 1).
Four-component, signed short expanded to (value, value, value, value).
Four-component byte with each byte normalized by dividing with 255.0f.
Normalized, two-component, signed short, expanded to (first short/32767.0, second short/32767.0, 0, 1).
Normalized, four-component, signed short, expanded to (first short/32767.0, second short/32767.0, third short/32767.0, fourth short/32767.0).
Normalized, two-component, unsigned short, expanded to (first short/65535.0, short short/65535.0, 0, 1).
Normalized, four-component, unsigned short, expanded to (first short/65535.0, second short/65535.0, third short/65535.0, fourth short/65535.0).
Three-component, unsigned, 10 10 10 format expanded to (value, value, value, 1).
Three-component, signed, 10 10 10 format normalized and expanded to (v[0]/511.0, v[1]/511.0, v[2]/511.0, 1).
Two-component, 16-bit, floating point expanded to (value, value, 0, 1).
Four-component, 16-bit, floating point expanded to (value, value, value, value).
Type field in the declaration is unused. This is designed for use with
Constants describing the vertex data types supported by a device.
\t\nIdentifies the intended use of vertex data.
\t\nVertex data is declared with an array of
For more information about vertex declarations, see Vertex Declaration (Direct3D 9).
\t\nPosition data ranging from (-1,-1) to (1,1). Use
Blending weight data. Use
Blending indices data. Use
Vertex normal data. Use
Point size data. Use
Texture coordinate data. Use
Vertex tangent data.
Vertex binormal data.
Single positive floating point value. Use
Vertex data contains transformed position data ranging from (0,0) to (viewport width, viewport height). Use
Vertex data contains diffuse or specular color. Use
Vertex data contains fog data. Use
Vertex data contains depth data.
Vertex data contains sampler data. Use
Defines the degree of the variables in the equation that describes a curve.
\t\nThe values in this enumeration are used to describe the curves used by rectangle and triangle patches. For more information, see
Curve is described by variables of first order.
Curve is described by variables of second order.
Curve is described by variables of third order.
Curve is described by variables of fourth order.
Defines device types.
\t\nAll methods of the
A
If D3dref9.dll is installed, Direct3D will use the reference rasterizer to create a
Hardware rasterization. Shading is done with software, hardware, or mixed transform and lighting.
Initialize Direct3D on a computer that has neither hardware nor reference rasterization available, and enable resources for 3D content creation. See Remarks.
Direct3D features are implemented in software; however, the reference rasterizer does make use of special CPU instructions whenever it can.
A pluggable software device that has been registered with
Specifies how the monitor being used to display a full-screen application is rotated.
\t\nThis enumeration is used in
Applications may choose to handle monitor rotation themselves by using the
Display is not rotated.
Display is rotated 90 degrees.
Display is rotated 180 degrees.
Display is rotated 270 degrees.
Effect data types. The data is contained in the pValue member of
Describes the type of events that can be keyed by the animation controller.
\t\nTrack speed.
Track weight.
Track position.
Enable flag.
Priority blend value.
The following flags are used to specify which channels in a texture to operate on.
\t\nTexture filtering constants.
\t\nDefines the various types of surface formats.
typedef enum _D3DFORMAT {There are several types of formats:
All formats are listed from left to right, most-significant bit to least-significant bit. For example, D3DFORMAT_ARGB is ordered from the most-significant bit channel A (alpha), to the least-significant bit channel B (blue). When traversing surface data, the data is stored in memory from least-significant bit to most-significant bit, which means that the channel order in memory is from least-significant bit (blue) to most-significant bit (alpha).
The default value for formats that contain undefined channels (G16R16, A8, and so on) is 1. The only exception is the A8 format, which is initialized to 000 for the three color channels.
The order of the bits is from the most significant byte first, so
Pixel formats have been chosen to enable the expression of hardware-vendor-defined extension formats, as well as to include the well-established FOURCC method. The set of formats understood by the Direct3D runtime is defined by
Note that formats are supplied by independent hardware vendors (IHVs) and many FOURCC codes are not listed. The formats in this enumeration are unique in that they are sanctioned by the runtime, meaning that the reference rasterizer will operate on all these types. IHV-supplied formats will be supported by the individual IHVs on a card-by-card basis.
BackBuffer or Display FormatsThese formats are the only valid formats for a back buffer or a display.
| Format | Back buffer | Display |
|---|---|---|
| A2R10G10B10 | x | x (full-screen mode only) |
| A8R8G8B8 | x | |
| X8R8G8B8 | x | x |
| A1R5G5B5 | x | |
| X1R5G5B5 | x | x |
| R5G6B5 | x | x |
?
Buffer FormatsDepth, stencil, vertex, and index buffers each have unique formats.
| Buffer flags | Value | Format |
|---|---|---|
| 70 | 16-bit z-buffer bit depth. | |
| 71 | 32-bit z-buffer bit depth. | |
| 73 | 16-bit z-buffer bit depth where 15 bits are reserved for the depth channel and 1 bit is reserved for the stencil channel. | |
| 75 | 32-bit z-buffer bit depth using 24 bits for the depth channel and 8 bits for the stencil channel. | |
| 77 | 32-bit z-buffer bit depth using 24 bits for the depth channel. | |
| 79 | 32-bit z-buffer bit depth using 24 bits for the depth channel and 4 bits for the stencil channel. | |
| 82 | A lockable format where the depth value is represented as a standard IEEE floating-point number. | |
| 83 | A non-lockable format that contains 24 bits of depth (in a 24-bit floating point format - 20e4) and 8 bits of stencil. | |
| 84 | A lockable 32-bit depth buffer.\t\n Differences between Direct3D 9 and Direct3D 9Ex:??This flag is available in Direct3D 9Ex only. | |
| 84 | A lockable 8-bit stencil buffer.\t\n Differences between Direct3D 9 and Direct3D 9Ex:??This flag is available in Direct3D 9Ex only. | |
| 80 | 16-bit z-buffer bit depth. | |
| 100 | Describes a vertex buffer surface. | |
| 101 | 16-bit index buffer bit depth. | |
| 102 | 32-bit index buffer bit depth. |
?
All depth-stencil formats except
These flags are used for compressed textures:
| DXTn Compressed Texture flags | Value | Format |
|---|---|---|
| MAKEFOURCC('D', 'X', 'T', '1') | DXT1 compression texture format | |
| MAKEFOURCC('D', 'X', 'T', '2') | DXT2 compression texture format | |
| MAKEFOURCC('D', 'X', 'T', '3') | DXT3 compression texture format | |
| MAKEFOURCC('D', 'X', 'T', '4') | DXT4 compression texture format | |
| MAKEFOURCC('D', 'X', 'T', '5') | DXT5 compression texture format |
?
The runtime will not allow an application to create a surface using a DXTn format unless the surface dimensions are multiples of 4. This applies to offscreen-plain surfaces, render targets, 2D textures, cube textures, and volume textures.
Floating-Point FormatsThese flags are used for floating-point surface formats. These 16-bits-per-channel formats are also known as s10e5 formats.
| Floating-point flags | Value | Format |
|---|---|---|
| 111 | 16-bit float format using 16 bits for the red channel. | |
| 112 | 32-bit float format using 16 bits for the red channel and 16 bits for the green channel. | |
| 113 | 64-bit float format using 16 bits for the each channel (alpha, blue, green, red). |
?
FOURCC FormatsData in a FOURCC format is compressed data.
MAKEFOURCCA macro for generating four-character codes follows:
#define MAKEFOURCC(ch0, ch1, ch2, ch3) \\ ((DWORD)(BYTE)(ch0) | ((DWORD)(BYTE)(ch1) << 8) | \\ ((DWORD)(BYTE)(ch2) << 16) | ((DWORD)(BYTE)(ch3) << 24 ))Here are the defined FOURCC formats:
| FOURCC flags | Value | Format |
|---|---|---|
| MAKEFOURCC('M','E','T','1') | MultiElement texture (not compressed) | |
| MAKEFOURCC('G', 'R', 'G', 'B') | A 16-bit packed RGB format analogous to YUY2 (Y0U0, Y1V0, Y2U2, and so on). It requires a pixel pair in order to properly represent the color value. The first pixel in the pair contains 8 bits of green (in the high 8 bits) and 8 bits of red (in the low 8 bits). The second pixel contains 8 bits of green (in the high 8 bits) and 8 bits of blue (in the low 8 bits). Together, the two pixels share the red and blue components, while each has a unique green component (G0R0, G1B0, G2R2, and so on). The texture sampler does not normalize the colors when looking up into a pixel shader; they remain in the range of 0.0f to 255.0f. This is true for all programmable pixel shader models. For the fixed function pixel shader, the hardware should normalize to the 0.f to 1.f range and essentially treat it as the YUY2 texture. Hardware that exposes this format must have the PixelShader1xMaxValue member of | |
| MAKEFOURCC('R', 'G', 'B', 'G') | A 16-bit packed RGB format analogous to UYVY (U0Y0, V0Y1, U2Y2, and so on). It requires a pixel pair in order to properly represent the color value. The first pixel in the pair contains 8 bits of green (in the low 8 bits) and 8 bits of red (in the high 8 bits). The second pixel contains 8 bits of green (in the low 8 bits) and 8 bits of blue (in the high 8 bits). Together, the two pixels share the red and blue components, while each has a unique green component (R0G0, B0G1, R2G2, and so on). The texture sampler does not normalize the colors when looking up into a pixel shader; they remain in the range of 0.0f to 255.0f. This is true for all programmable pixel shader models. For the fixed function pixel shader, the hardware should normalize to the 0.f to 1.f range and essentially treat it as the YUY2 texture. Hardware that exposes this format must have PixelShader1xMaxValue member of | |
| MAKEFOURCC('U', 'Y', 'V', 'Y') | UYVY format (PC98 compliance) | |
| MAKEFOURCC('Y', 'U', 'Y', '2') | YUY2 format (PC98 compliance) |
?
IEEE FormatsThese flags are used for floating-point surface formats. These 32-bits-per-channel formats are also known as s23e8 formats.
| Floating-point flags | Value | Format |
|---|---|---|
| 114 | 32-bit float format using 32 bits for the red channel. | |
| 115 | 64-bit float format using 32 bits for the red channel and 32 bits for the green channel. | |
| 116 | 128-bit float format using 32 bits for the each channel (alpha, blue, green, red). |
?
Mixed FormatsData in mixed formats can contain a combination of unsigned data and signed data.
| Mixed format flags | Value | Format |
|---|---|---|
| 61 | 16-bit bump-map format with luminance using 6 bits for luminance, and 5 bits each for v and u. | |
| 62 | 32-bit bump-map format with luminance using 8 bits for each channel. | |
| 67 | 32-bit bump-map format using 2 bits for alpha and 10 bits each for w, v, and u. |
?
Signed FormatsData in a signed format can be both positive and negative. Signed formats use combinations of (U), (V), (W), and (Q) data.
| Signed format flags | Value | Format |
|---|---|---|
| 60 | 16-bit bump-map format using 8 bits each for u and v data. | |
| 63 | 32-bit bump-map format using 8 bits for each channel. | |
| 64 | 32-bit bump-map format using 16 bits for each channel. | |
| 110 | 64-bit bump-map format using 16 bits for each component. | |
| 117 | 16-bit normal compression format. The texture sampler computes the C channel from: C = sqrt(1 - U2 - V2). |
?
Unsigned FormatsData in an unsigned format must be positive. Unsigned formats use combinations of (R)ed, (G)reen, (B)lue, (A)lpha, (L)uminance, and (P)alette data. Palette data is also referred to as color indexed data because the data is used to index a color palette.
| Unsigned format flags | Value | Format |
|---|---|---|
| 20 | 24-bit RGB pixel format with 8 bits per channel. | |
| 21 | 32-bit ARGB pixel format with alpha, using 8 bits per channel. | |
| 22 | 32-bit RGB pixel format, where 8 bits are reserved for each color. | |
| 23 | 16-bit RGB pixel format with 5 bits for red, 6 bits for green, and 5 bits for blue. | |
| 24 | 16-bit pixel format where 5 bits are reserved for each color. | |
| 25 | 16-bit pixel format where 5 bits are reserved for each color and 1 bit is reserved for alpha. | |
| 26 | 16-bit ARGB pixel format with 4 bits for each channel. | |
| 27 | 8-bit RGB texture format using 3 bits for red, 3 bits for green, and 2 bits for blue. | |
| 28 | 8-bit alpha only. | |
| 29 | 16-bit ARGB texture format using 8 bits for alpha, 3 bits each for red and green, and 2 bits for blue. | |
| 30 | 16-bit RGB pixel format using 4 bits for each color. | |
| 31 | 32-bit pixel format using 10 bits for each color and 2 bits for alpha. | |
| 32 | 32-bit ARGB pixel format with alpha, using 8 bits per channel. | |
| 33 | 32-bit RGB pixel format, where 8 bits are reserved for each color. | |
| 34 | 32-bit pixel format using 16 bits each for green and red. | |
| 35 | 32-bit pixel format using 10 bits each for red, green, and blue, and 2 bits for alpha. | |
| 36 | 64-bit pixel format using 16 bits for each component. | |
| 40 | 8-bit color indexed with 8 bits of alpha. | |
| 41 | 8-bit color indexed. | |
| 50 | 8-bit luminance only. | |
| 81 | 16-bit luminance only. | |
| 51 | 16-bit using 8 bits each for alpha and luminance. | |
| 52 | 8-bit using 4 bits each for alpha and luminance. | |
| 118 | 1-bit monochrome.\t\n Differences between Direct3D 9 and Direct3D 9Ex:??This flag is available in Direct3D 9Ex only. | |
| 119 | 2.8-biased fixed point.\t\n Differences between Direct3D 9 and Direct3D 9Ex:??This flag is available in Direct3D 9Ex only. | |
| 199 | Binary format indicating that the data has no inherent type.\t\n Differences between Direct3D 9 and Direct3D 9Ex:??This flag is available in Direct3D 9Ex only. |
?
OtherThis flag is used for undefined formats.
| Other flags | Value | Format |
|---|---|---|
| 0 | Surface format is unknown |
?
\t\nOptions for saving and creating effects.
The constants in the following table are defined in d3dx9effect.h.
\t\nThe following flags are used to specify which channels in a texture to operate on.
\t\nDescribes the supported image file formats. See Remarks for descriptions of these formats.
\t\nFunctions that begin with D3DXLoadxxx support all of the formats listed. Functions that begin with D3DXSavexxx support all of the formats listed except the Truevision (.tga) and portable pixmap (.ppm) formats.
The following table lists the available input and output formats.
| File Extension | Description |
|---|---|
| .bmp | Windows bitmap format. Contains a header that describes the resolution of the device on which the rectangle of pixels was created, the dimensions of the rectangle, the size of the array of bits, a logical palette, and an array of bits that defines the relationship between pixels in the bitmapped image and entries in the logical palette. |
| .dds | DirectDraw Surface file format. Stores textures, volume textures, and cubic environment maps, with or without mipmap levels, and with or without pixel compression. See DDS. |
| .dib | Windows DIB. Contains an array of bits combined with structures that specify width and height of the bitmapped image, color format of the device where the image was created, and resolution of the device used to create that image. |
| .hdr | HDR format. Encodes each pixel as an RGBE 32-bit color, with 8 bits of mantissa for red, green, and blue, and a shared 8-bit exponent. Each channel is separately compressed with run-length encoding (RLE). |
| .jpg | JPEG standard. Specifies variable compression of 24-bit RGB color and 8-bit gray-scale Tagged Image File Format (TIFF) image document files. |
| .pfm | Portable float map format. A raw floating point image format, without any compression. The file header specifies image width, height, monochrome or color, and machine word order. Pixel data is stored as 32-bit floating point values, with 3 values per pixel for color, and one value per pixel for monochrome. |
| .png | PNG format. A non-proprietary bitmap format using lossless compression. |
| .ppm | Portable Pixmap format. A binary or ASCII file format for color images that includes image height and width and the maximum color component value. |
| .tga | Targa or Truevision Graphics Adapter format. Supports depths of 8, 15, 16, 24, and 32 bits, including 8-bit gray scale, and contains optional color palette data, image (x, y) origin and size data, and pixel data. |
?
See Types of Bitmaps for more information on some of these formats.
\t\nWindows bitmap (BMP) file format.
Joint Photographics Experts Group (JPEG) compressed file format.
Truevision (Targa, or TGA) image file format.
Portable Network Graphics (PNG) file format.
DirectDraw surface (DDS) file format.
Portable pixmap (PPM) file format.
Windows device-independent bitmap (DIB) file format.
High dynamic range (HDR) file format.
Portable float map file format.
Describes the location for the include file.
\t\nLook in the local project for the include file.
Look in the system path for the include file.
This macro creates a value used by Issue to issue a query end.
#defineThis macro changes the query state to nonsignaled.
A combination of zero or more locking options that describe the type of lock to perform.
\t\nDefines the type of mesh data present in
Flags used to specify creation options for a mesh.
\t\nA 32-bit mesh (
The mesh has 32-bit indices instead of 16-bit indices. See Remarks.
Use the
Use the
Use the
Specifying this flag causes the vertex and index buffer of the mesh to be created with
Use the
Use the
Use the
Use the
Use the
Use the
Use the
Use the
Use the
Use the
Forces the cloned meshes to share vertex buffers.
Use hardware processing only. For mixed-mode device, this flag will cause the system to use hardware (if supported in hardware) or will default to software processing.
Equivalent to specifying both
Equivalent to specifying both
Equivalent to specifying both
Equivalent to specifying both
Equivalent to specifying both
Specifies the type of mesh optimization to be performed.
\t\nThe
The D3DXMESHOPT_SHAREVB flag has been removed from this enumeration. Use
Reorders faces to remove unused vertices and faces.
Reorders faces to optimize for fewer attribute bundle state changes and enhanced
Reorders faces to increase the cache hit rate of vertex caches.
Reorders faces to maximize length of adjacent triangles.
Optimize the faces only; do not optimize the vertices.
While attribute sorting, do not split vertices that are shared between attribute groups.
Affects the vertex cache size. Using this flag specifies a default vertex cache size that works well on legacy hardware.
Specifies simplification options for a mesh.
\t\nThe mesh will be simplified by the number of vertices specified in the MinValue parameter.
The mesh will be simplified by the number of faces specified in the MinValue parameter.
Defines the levels of full-scene multisampling that the device can apply.
\t\nIn addition to enabling full-scene multisampling at
Multisampling is valid only on a swap chain that is being created or reset with the
The multisample antialiasing value can be set with the parameters (or sub-parameters) in the following methods.
| Method | Parameters | Sub-parameters |
|---|---|---|
| | MultiSampleType and pQualityLevels | |
| | pPresentationParameters | MultiSampleType and pQualityLevels |
| | pPresentationParameters | MultiSampleType and pQualityLevels |
| | MultiSampleType and pQualityLevels | |
| | MultiSampleType and pQualityLevels | |
| | pPresentationParameters | MultiSampleType and pQualityLevels |
?
It is not good practice to switch from one multisample type to another to raise the quality of the antialiasing.
Whether the display device supports maskable multisampling (more than one sample for a multiple-sample render-target format plus antialias support) or just non-maskable multisampling (only antialias support), the driver for the device provides the number of quality levels for the
The quality levels supported by the device can be obtained with the pQualityLevels parameter of
See
No level of full-scene multisampling is available.
Enables the multisample quality value. See Remarks.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Level of full-scene multisampling available.
Normal maps generation constants.
\t\nThe type of object.
\t\nConstant is a scalar.
Constant is a vector.
Constant is a row major matrix.
Constant is a column major matrix.
Constant is either a texture, shader, or a string.
Constant is a structure.
These flags provide additional information about effect parameters.
Effect parameter constants are used by
Describes the data contained by the enumeration.
\t\nParameter is a void reference.
Parameter is a Boolean. Any non-zero value passed into
Parameter is an integer. Any floating-point values passed into
Parameter is a floating-point number.
Parameter is a string.
Parameter is a texture.
Parameter is a 1D texture.
Parameter is a 2D texture.
Parameter is a 3D texture.
Parameter is a cube texture.
Parameter is a sampler.
Parameter is a 1D sampler.
Parameter is a 2D sampler.
Parameter is a 3D sampler.
Parameter is a cube sampler.
Parameter is a pixel shader.
Parameter is a vertex shader.
Parameter is a pixel shader fragment.
Parameter is a vertex shader fragment.
Parameter is not supported.
Defines whether the current tessellation mode is discrete or continuous.
\t\nNote that continuous tessellation produces a completely different tessellation pattern from the discrete one for the same tessellation values (this is more apparent in wireframe mode). Thus, 4.0 continuous is not the same as 4 discrete.
\t\nDiscrete edge style. In discrete mode, you can specify float tessellation but it will be truncated to integers.
Continuous edge style. In continuous mode, tessellation is specified as float values that can be smoothly varied to reduce \"popping\" artifacts.
Mesh patch types.
\t\nTriangle patches have three sides and are described in
Rectangle patch mesh type.
Triangle patch mesh type.
N-patch mesh type.
Defines the type of animation set looping modes used for playback.
\t\nThe animation repeats endlessly.
The animation plays once, and then it stops on the last frame.
The animation alternates endlessly between playing forward and playing backward.
Defines the memory class that holds the buffers for a resource.
\t\nAll pool types are valid with all resources including: vertex buffers, index buffers, textures, and surfaces.
The following tables indicate restrictions on pool types for render targets, depth stencils, and dynamic and mipmap usages. An x indicates a compatible combination; lack of an x indicates incompatibility.
| Pool | ||
|---|---|---|
| x | x | |
?
| Pool | ||
|---|---|---|
| x | x | |
| x | ||
| x |
?
For more information about usage types, see
Pools cannot be mixed for different objects contained within one resource (mip levels in a mipmap) and, when a pool is chosen, it cannot be changed.
Applications should use
For dynamic textures, it is sometimes desirable to use a pair of video memory and system memory textures, allocating the video memory using
Resources are placed in the memory pool most appropriate for the set of usages requested for the given resource. This is usually video memory, including both local video memory and AGP memory. The
When creating resources with
Resources are copied automatically to device-accessible memory as needed. Managed resources are backed by system memory and do not need to be recreated when a device is lost. See Managing Resources (Direct3D 9) for more information. Managed resources can be locked. Only the system-memory copy is directly modified. Direct3D copies your changes to driver-accessible memory as needed.
| Differences between Direct3D 9 and Direct3D 9Ex: |
?
Resources are placed in memory that is not typically accessible by the Direct3D device. This memory allocation consumes system RAM but does not reduce pageable RAM. These resources do not need to be recreated when a device is lost. Resources in this pool can be locked and can be used as the source for a
Resources are placed in system RAM and do not need to be recreated when a device is lost. These resources are not bound by device size or format restrictions. Because of this, these resources cannot be accessed by the Direct3D device nor set as textures or render targets. However, these resources can always be created, locked, and copied.
Describes the relationship between the adapter refresh rate and the rate at which Present or Present operations are completed. These values also serve as flag values for the PresentationIntervals field of
Windowed mode supports
Full-screen mode supports similar usage as windowed mode by supporting
Constants used by
Miscellaneous driver primitive capability flags.
\t\nDefines the primitives supported by Direct3D.
\t\nUsing Triangle Strips or Triangle Fans (Direct3D 9) is often more efficient than using triangle lists because fewer vertices are duplicated.
\t\nRenders the vertices as a collection of isolated points. This value is unsupported for indexed primitives.
Renders the vertices as a list of isolated straight line segments.
Renders the vertices as a single polyline.
Renders the specified vertices as a sequence of isolated triangles. Each group of three vertices defines a separate triangle.
Back-face culling is affected by the current winding-order render state.
Renders the vertices as a triangle strip. The backface-culling flag is automatically flipped on even-numbered triangles.
Renders the vertices as a triangle fan.
Identifies the query type. For information about queries, see Queries (Direct3D 9)
\t\nData type of the register.
\t\nBoolean value.
4D integer number.
4D floating-point number.
The register contains 4D sampler data.
The
#define D3DRENDERSTATE_EVICTMANAGEDTEXTURES 61\t\n #define D3DRENDERSTATE_SCENECAPTURE 62\t\n #define D3DRS_DELETERTPATCH 169\t\n #define D3DRS_MAXVERTEXSHADERINST 196\t\n #define D3DRS_MAXPIXELSHADERINST 197
Enumerators
Determines whether textures are evicted from memory.\t\n The driver uses a
This render state determines whether the driver evicts textures that it manages (as opposed to textures managed by the Direct3D runtime) from video memory. If the render state value is TRUE, the driver evicts the textures. Otherwise, the driver does not evict those textures.
Specifies either begin scene information or end scene information for geometric data captured within a frame.\t\n The driver uses a
The driver responds to D3DRENDERSTATE_SCENECAPTURE first with TRUE for begin scene information and next with
Care must be taken in updating a driver that implements the legacy D3DHALCallbacks->D3dSceneCapture callback routine to one using the D3DRENDERSTATE_SCENECAPTURE render state. The D3dSceneCapture callback routine uses the constants D3DHAL_SCENE_CAPTURE_START and D3DHAL_SCENE_CAPTURE_END to indicate, respectively, the beginning and end of a scene. The values of these constants are, respectively, 0 and 1. If you use these constants in place of TRUE and
DirectX 8.0 and later versions only.
Deletes either a rectangular or triangular patch from memory. \t\n The driver uses a DWORD data type without a default value to detect the patch to delete.
This render state notifies the driver that a patch is to be deleted. The value of this render state is the handle to the patch affected. All cached information should be freed and the handle should be removed from the driver's patch handle table. This render state is not visible to applications but is generated internally when an application calls the DeletePatch function. This render state is sent to the driver only when patches are deleted by DeletePatch explicitly. All other patches should be cleaned up when the device is destroyed.
DirectX 9.0 and later versions only.
Determines the maximum number of instructions that the vertex shader assembler can execute.
The driver uses a DWORD data type with a default value of D3DINFINITEINSTRUCTIONS (0xffffffff) to report the maximum number of vertex-shader instructions.\t\n This maximum number depends on the version of the vertex shader that the display device supports as shown in the following table.
| Version | Maximum number |
|---|---|
| earlier than 2_0 | 0 |
| 2_0 and later | From 216 (0x0000ffff) to D3DINFINITEINSTRUCTIONS |
?
D3DINFINITEINSTRUCTIONS represents a virtually unlimited amount.
Valid values for this render state are numbers that are powers of 2; if the driver sets any other integer, the runtime uses the next nearest power of 2 number.
The runtime sets the MaxVShaderInstructionsExecuted member of the
DirectX 9.0 and later versions only.
Determines the maximum number of instructions that the pixel shader assembler can execute.
The driver uses a DWORD data type with a default value of D3DINFINITEINSTRUCTIONS (0xffffffff) to report the maximum number of pixel-shader instructions.\t\n This maximum number depends on the version of the pixel shader that the display device supports as shown in the following table.
| Version | Maximum number |
|---|---|
| earlier than 2_0 | 0 |
| 2_0 | From 96 to D3DINFINITEINSTRUCTIONS |
| 3_0 and later | From 216 (0x0000ffff) to D3DINFINITEINSTRUCTIONS |
?
D3DINFINITEINSTRUCTIONS represents a virtually unlimited amount.
Valid values for this render state are numbers that are powers of 2; if the driver sets any other integer, the runtime uses the next nearest power of 2 number.
The runtime sets the MaxVShaderInstructionsExecuted member of the
The driver uses these render states when it performs graphics rendering. Only render states that are specific to drivers are included in the Windows Driver Kit (WDK) documentation. The render states accessible to DirectX applications are included in the DirectX SDK documentation. These application-level render states include such characteristics as whether alpha blending is enabled, whether dithering is enabled, whether Direct3D lighting is used, and the type of shading to be used.
To update a particular render state, Direct3D stores information about the render state, and then calls the driver's D3dDrawPrimitives2 callback routine. The information provided to the driver enables it to:
Determine that it should update one or more render states.
Identify which render states to update, and what the new render state values should be.
Note that for certain render states to be honored, the driver must have previously set capability flags in the relevant member of the D3DPRIMCAPS structure.
In order to indicate a specific render state update, Direct3D inserts a D3DHAL_DP2COMMAND structure into the command buffer, setting the bCommand member of this structure to D3DDP2OP_RENDERSTATE (see the description for D3DDP2OP_RENDERSTATE in D3DHAL_DP2OPERATION), and setting the wStateCount member of the same structure to the number of render states to be updated.
Immediately following the D3DHAL_DP2COMMAND structure, Direct3D inserts one D3DHAL_DP2RENDERSTATE structure into the command buffer for each render state to be updated. The RenderState member of this structure identifies the render state to be changed; the new value of this render state is specified in either the dwState member (for DWORD values) or the fState member (for D3DVALUE values).
The following figure shows a portion of the command buffer containing a D3DDP2OP_RENDERSTATE command and two D3DHAL_DP2RENDERSTATE structures. The first of the three structures indicates that two render states are to be updated. The second structure indicates that the D3DRENDERSTATE_FILLMODE render state is to be changed to
Additional Notes
See the
Some changes have been made to the
Multitexture macro ops and D3DRENDERSTATE_TEXTUREFACTOR override all of the per-texture stage blending controls (COLOR{OP,ARG1,ARG2} & ALPHA{OP,ARG1,ARG2}).
\t\n Determines whether textures are evicted from memory.\t\n The driver uses a
This render state determines whether the driver evicts textures that it manages (as opposed to textures managed by the Direct3D runtime) from video memory. If the render state value is TRUE, the driver evicts the textures. Otherwise, the driver does not evict those textures.
Specifies either begin scene information or end scene information for geometric data captured within a frame.\t\n The driver uses a
The driver responds to D3DRENDERSTATE_SCENECAPTURE first with TRUE for begin scene information and next with
Care must be taken in updating a driver that implements the legacy D3DHALCallbacks->D3dSceneCapture callback routine to one using the D3DRENDERSTATE_SCENECAPTURE render state. The D3dSceneCapture callback routine uses the constants D3DHAL_SCENE_CAPTURE_START and D3DHAL_SCENE_CAPTURE_END to indicate, respectively, the beginning and end of a scene. The values of these constants are, respectively, 0 and 1. If you use these constants in place of TRUE and
DirectX 8.0 and later versions only.
Deletes either a rectangular or triangular patch from memory. \t\n The driver uses a DWORD data type without a default value to detect the patch to delete.
This render state notifies the driver that a patch is to be deleted. The value of this render state is the handle to the patch affected. All cached information should be freed and the handle should be removed from the driver's patch handle table. This render state is not visible to applications but is generated internally when an application calls the DeletePatch function. This render state is sent to the driver only when patches are deleted by DeletePatch explicitly. All other patches should be cleaned up when the device is destroyed.
DirectX 9.0 and later versions only.
Determines the maximum number of instructions that the vertex shader assembler can execute.
The driver uses a DWORD data type with a default value of D3DINFINITEINSTRUCTIONS (0xffffffff) to report the maximum number of vertex-shader instructions.\t\n This maximum number depends on the version of the vertex shader that the display device supports as shown in the following table.
| Version | Maximum number |
|---|---|
| earlier than 2_0 | 0 |
| 2_0 and later | From 216 (0x0000ffff) to D3DINFINITEINSTRUCTIONS |
?
D3DINFINITEINSTRUCTIONS represents a virtually unlimited amount.
Valid values for this render state are numbers that are powers of 2; if the driver sets any other integer, the runtime uses the next nearest power of 2 number.
The runtime sets the MaxVShaderInstructionsExecuted member of the
DirectX 9.0 and later versions only.
Determines the maximum number of instructions that the pixel shader assembler can execute.
The driver uses a DWORD data type with a default value of D3DINFINITEINSTRUCTIONS (0xffffffff) to report the maximum number of pixel-shader instructions.\t\n This maximum number depends on the version of the pixel shader that the display device supports as shown in the following table.
| Version | Maximum number |
|---|---|
| earlier than 2_0 | 0 |
| 2_0 | From 96 to D3DINFINITEINSTRUCTIONS |
| 3_0 and later | From 216 (0x0000ffff) to D3DINFINITEINSTRUCTIONS |
?
D3DINFINITEINSTRUCTIONS represents a virtually unlimited amount.
Valid values for this render state are numbers that are powers of 2; if the driver sets any other integer, the runtime uses the next nearest power of 2 number.
The runtime sets the MaxVShaderInstructionsExecuted member of the
Sampler states define texture sampling operations such as texture addressing and texture filtering. Some sampler states set-up vertex processing, and some set-up pixel processing. Sampler states can be saved and restored using stateblocks (see State Blocks Save and Restore State (Direct3D 9)).
\t\nDefines the sampler texture types for vertex shaders.
\t\nUninitialized value. The value of this element is D3DSP_TEXTURETYPE_SHIFT.
Declaring a 2D texture. The value of this element is D3DSP_TEXTURETYPE_SHIFT * 4.
Declaring a cube texture. The value of this element is D3DSP_TEXTURETYPE_SHIFT * 8.
Declaring a volume texture. The value of this element is D3DSP_TEXTURETYPE_SHIFT * 16.
Flags indicating the method the rasterizer uses to create an image on a surface.
\t\nThis enumeration is used as a member in
The image is created from the first scanline to the last without skipping any.
The image is created using the interlaced method in which odd-numbered lines are drawn on odd-numbered passes and even lines are drawn on even-numbered passes.
The following flags are used for parsing, compiling, or assembling shaders:
Applying Compiler or Assembler to the incorrect API will fail shader validation. Check the Direct3D error code return value from the function (with the DirectX Error Lookup Tool) to help track down this error.
\t\nThe following flags are used to specify sprite rendering options to the flags parameter in the Begin method:
\t\nDriver stencil capability flags.
\t\nDefines stencil-buffer operations.
\t\nStencil-buffer entries are integer values ranging from 0 through 2n - 1, where n is the bit depth of the stencil buffer.
\t\nDo not update the entry in the stencil buffer. This is the default value.
Set the stencil-buffer entry to 0.
Replace the stencil-buffer entry with a reference value.
Increment the stencil-buffer entry, clamping to the maximum value.
Decrement the stencil-buffer entry, clamping to zero.
Invert the bits in the stencil-buffer entry.
Increment the stencil-buffer entry, wrapping to zero if the new value exceeds the maximum value.
Decrement the stencil-buffer entry, wrapping to the maximum value if the new value is less than zero.
Defines swap effects.
\t\nThe state of the back buffer after a call to Present is well-defined by each of these swap effects, and whether the Direct3D device was created with a full-screen swap chain or a windowed swap chain has no effect on this state. In particular, the
Applications that use
An invisible window cannot receive user-mode events; furthermore, an invisible-fullscreen window will interfere with the presentation of another applications' windowed-mode window. Therefore, each application needs to ensure that a device window is visible when a swapchain is presented in fullscreen mode.
\t\nWhen a swap chain is created with a swap effect of
Like a swap chain that uses
An application that uses this swap effect cannot make any assumptions about the contents of a discarded back buffer and should therefore update an entire back buffer before invoking a Present operation that would display it. Although this is not enforced, the debug version of the runtime will overwrite the contents of discarded back buffers with random data to enable developers to verify that their applications are updating the entire back buffer surfaces correctly.
The swap chain might include multiple back buffers and is best envisaged as a circular queue that includes the front buffer. Within this queue, the back buffers are always numbered sequentially from 0 to (n - 1), where n is the number of back buffers, so that 0 denotes the least recently presented buffer. When Present is invoked, the queue is \"rotated\" so that the front buffer becomes back buffer (n - 1), while the back buffer 0 becomes the new front buffer.
This swap effect may be specified only for a swap chain comprising a single back buffer. Whether the swap chain is windowed or full-screen, the runtime will guarantee the semantics implied by a copy-based Present operation, namely that the operation leaves the content of the back buffer unchanged, instead of replacing it with the content of the front buffer as a flip-based Present operation would.
For a full-screen swap chain, the runtime uses a combination of flip operations and copy operations, supported if necessary by hidden back buffers, to accomplish the Present operation. Accordingly, the presentation is synchronized with the display adapter's vertical retrace and its rate is constrained by the chosen presentation interval. A swap chain specified with the
Use a dedicated area of video memory that can be overlayed on the primary surface. No copy is performed when the overlay is displayed. The overlay operation is performed in hardware, without modifying the data in the primary surface.
| Differences between Direct3D 9 and Direct3D 9Ex: |
?
Designates when an application is adopting flip mode, during which time an application's frame is passed instead of copied to the Desktop Window Manager(DWM) for composition when the application is presenting in windowed mode. Flip mode allows an application to more efficiently use memory bandwidth as well as enabling an application to take advantage of full-screen-present statistics. Flip mode does not affect full-screen behavior. A sample application that uses
| Differences between Direct3D 9 and Direct3D 9Ex: |
?
Defines settings used for mesh tangent frame computations.
\t\nTexture coordinate values in the u direction are between 0 and 1. In this case a texture coordinate set will be chosen that minimizes the perimeter of the triangle. See Texture Wrapping (Direct3D 9).
Texture coordinate values in the v direction are between 0 and 1. In this case a texture coordinate set will be chosen that minimizes the perimeter of the triangle. See Texture Wrapping (Direct3D 9).
Texture coordinate values in both u and v directions are between 0 and 1. In this case a texture coordinate set will be chosen that minimizes the perimeter of the triangle. See Texture Wrapping (Direct3D 9).
Do not normalize partial derivatives with respect to texture coordinates. If not normalized, the scale of the partial derivatives is proportional to the scale of the 3D model divided by the scale of the triangle in (u, v) space. This scale value provides a measure of how much the texture is stretched in a given direction. The resulting vector length is a weighted sum of the lengths of the partial derivatives.
Do not transform texture coordinates to orthogonal Cartesian coordinates. Mutually exclusive with
Compute the partial derivative with respect to texture coordinate v independently for each vertex, and then compute the partial derivative with respect to u as the cross product of the partial derivative with respect to v and the normal vector. Mutually exclusive with
Compute the partial derivative with respect to texture coordinate u independently for each vertex, and then compute the partial derivative with respect to v as the cross product of the normal vector and the partial derivative with respect to u. Mutually exclusive with
Weight the direction of the computed per-vertex normal or partial derivative vector according to the areas of triangles attached to that vertex. Mutually exclusive with
Compute a unit-length normal vector for each triangle of the input mesh. Mutually exclusive with
Vertices are ordered in a clockwise direction around each triangle. The computed normal vector direction is therefore inverted 180 degrees from the direction computed using counterclockwise vertex ordering.
Compute the per-vertex normal vector for each triangle of the input mesh, and ignore any normal vectors already in the input mesh.
The results are stored in the original input mesh, and the output mesh is not used.
Texture argument constants are used as values for the following members of the
Set and retrieve texture arguments by calling the SetTextureStageState and GetTextureStageState methods.
Argument flags
You can combine an argument flag with a modifier, but two argument flags cannot be combined.
\t\nDriver texture coordinate capability flags.
\t\nDefines texture filtering modes for a texture stage.
\t\nTo check if a format supports texture filter types other than
Set a texture stage's magnification filter by calling
Set a texture stage's minification filter by calling
Set the texture filter to use between-mipmap levels by calling
Not all valid filtering modes for a device will apply to volume maps. In general,
When used with
When used with D3DSAMP_ MAGFILTER or
When used with D3DSAMP_ MAGFILTER or
When used with D3DSAMP_ MAGFILTER or
A 4-sample tent filter used as a texture magnification or minification filter. Use with
A 4-sample Gaussian filter used as a texture magnification or minification filter. Use with
Convolution filter for monochrome textures. See
| Differences between Direct3D 9 and Direct3D 9Ex: This flag is available in Direct3D 9Ex only. |
?
Use with
Defines texture coordinate transformation values.
\t\nTexture coordinates can be transformed using a 4 x 4 matrix before the results are passed to the rasterizer. The texture coordinate transforms are set by calling
Texture coordinates are passed directly to the rasterizer.
The rasterizer should expect 1D texture coordinates. This value is used by fixed function vertex processing; it should be set to 0 when using a programmable vertex shader.
The rasterizer should expect 2D texture coordinates. This value is used by fixed function vertex processing; it should be set to 0 when using a programmable vertex shader.
The rasterizer should expect 3D texture coordinates. This value is used by fixed function vertex processing; it should be set to 0 when using a programmable vertex shader.
The rasterizer should expect 4D texture coordinates. This value is used by fixed function vertex processing; it should be set to 0 when using a programmable vertex shader.
This flag is honored by the fixed function pixel pipeline, as well as the programmable pixel pipeline in versions ps_1_1 to ps_1_3. When texture projection is enabled for a texture stage, all four floating point values must be written to the corresponding texture register. Each texture coordinate is divided by the last element before being passed to the rasterizer. For example, if this flag is specified with the
Defines the priority type to which an animation track is assigned.
\t\nTracks with the same priority are blended together, and the two resulting values are then blended using the priority blend factor.
\t\nTrack should be blended with all the low-priority tracks before the low-priority blend is mixed with the high-priority blend.
Track should be blended with all the high-priority tracks before the high-priority blend is mixed with the low-priority blend.
Defines the transition style between values of a mesh animation.
\t\nThe calculation for the ramp from ease in to ease out is calculated as follows:
where the ramp is a function Q(t) with the following properties:
Mathematically, this translates into:
Solving for A, B, C, D:
Therefore:
Linear transition between values.
Ease-in, ease-out spline transition between values.
Usage options that identify how resources are to be used.
The following table summarizes the available usage options.
\t\nUsages are either specified when a resource is created, or specified with CheckDeviceType to test the capability of an existing resource. The following table identifies which usages can be applied to which resource types.
| Usage | Vertex buffer create | Index buffer create | Texture create | Cube texture create | Volume texture create | Surface create | Check device format |
|---|---|---|---|---|---|---|---|
| x | x | x | |||||
| x | x | x | x | ||||
| x | x | ||||||
| x | x | ||||||
| x | x | x | x | x | x | ||
| x | x | x | x | x | x | x | |
| x | x | ||||||
| x | x | ||||||
| x | x | ||||||
| x | x | x | x | ||||
| x | x | x | x | x | x | ||
| x | x | ||||||
| x | x |
?
Use CheckDeviceFormat to check hardware support for these usages.
Each of the resource creation methods is listed here.
The D3DXCreatexxx texturing functions also use some of these constant values for resource creation.
For more information about pool types and their restrictions with certain usages, see
Texture wrapping options for IMT computation APIs.
\t\nThe texture wraps in the U direction.
The texture wraps in the V direction.
The texture wraps in both the U and V direction.
Defines flags used to control the number or matrices that the system applies when performing multimatrix vertex blending.
\t\nMembers of this type are used with the
Geometry blending (multimatrix vertex blending) requires that your application use a vertex format that has blending (beta) weights for each vertex.
\t\nDisable vertex blending; apply only the world matrix set by the D3DTS_WORLDMATRIX macro, where the index value for the transformation state is 0.
Enable vertex blending between the two matrices set by the D3DTS_WORLDMATRIX macro, where the index value for the transformation states are 0 and 1.
Enable vertex blending between the three matrices set by the D3DTS_WORLDMATRIX macro, where the index value for the transformation states are 0, 1, and 2.
Enable vertex blending between the four matrices set by the D3DTS_WORLDMATRIX macro, where the index value for the transformation states are 0, 1, 2, and 3.
Vertex blending is done by using the value assigned to
Use a single matrix with a weight of 1.0.
Flexible Vertex Format Constants, or FVF codes, are used to describe the contents of vertices interleaved in a single data stream that will be processed by the fixed-function pipeline.
\t\nThis constant is the maximum number of vertex declarators for a mesh.
\t\nMAXD3DDECLLENGTH is defined as a maximum of 64 (see d3d9types.h). This does not include the \"end\" marker vertex element.
\t\nThe maximum number of elements in the vertex declaration. The additional (+1) is for D3DDECL_END.
A combination of one or more flags that control the device create behavior.
\t\nVertex shader caps constants. These constants are used by the VS20Caps member of
Vertex texture sampler constants.
These constants identify the texture samplers used by vertex shaders.
\t\nSpecifies the type of I/O bus used by the graphics adapter.
\t\nAs many as three flags can be set. Flags in the range 0x00 through 0x04 (D3DBUSTYPE_Xxx) provide the basic bus type. Flags in the range 0x10000 through 0x50000 (D3DBUSIMPL_MODIFIER_Xxx) modify the basic description. The driver sets one bus-type flag, and can set zero or one modifier flag. If the driver sets a modifier flag, it also sets the
Indicates a type of bus other than the types listed here.\t\n
PCI bus.\t\n
PCI-X bus.\t\n
PCI Express bus.\t\n
Accelerated Graphics Port (AGP) bus.\t\n
The implementation for the graphics adapter is in a motherboard chipset's north bridge. This flag implies that data never goes over an expansion bus (such as PCI or AGP) when it is transferred from main memory to the graphics adapter.
Indicates that the graphics adapter is connected to a motherboard chipset's north bridge by tracks on the motherboard and all of the graphics adapter's chips are soldered to the motherboard. This flag implies that data never goes over an expansion bus (such as PCI or AGP) when it is transferred from main memory to the graphics adapter.
The graphics adapter is connected to a motherboard chipset's north bridge by tracks on the motherboard, and all of the graphics adapter's chips are connected through sockets to the motherboard.\t\n
The graphics adapter is connected to the motherboard through a daughterboard connector.\t\n
The graphics adapter is connected to the motherboard through a daughterboard connector, and the graphics adapter is inside an enclosure that is not user accessible.\t\n
One of the D3DBUSIMPL_MODIFIER_MODIFIER_Xxx flags is set.\t\n
Options for welding together vertices.
\t\nWeld together all vertices that are at the same location. Using this flag avoids an epsilon comparison between vertex components.
If a given vertex component is within epsilon, modify partially matched vertices so that both components are identical. If all components are equal, remove one of the vertices.
Instructs the weld to allow only modifications to vertices and not removal. This flag is valid only if
Instructs the weld not to split vertices that are in separate attribute groups. When the
Creates an
The
The
Pass the
Note??Direct3DCreate9Ex is supported only in Windows Vista, Windows Server 2008, and Windows 7. Earlier versions of the D3D9.dll library do not include Direct3D9Ex and Direct3DCreate9Ex.
\t\nCreate an
The value of this parameter should be
If successful, this function returns a reference to an
The Direct3D object is the first Direct3D COM object that your graphical application needs to create and the last object that your application needs to release. Functions for enumerating and retrieving capabilities of a device are accessible through the Direct3D object. This enables applications to select devices without creating them.
Create an
LPDIRECT3D9 g_pD3D = null ; if( null == (g_pD3D = Direct3DCreate9())) return E_FAIL;\t\n The
For an example, see Creating a Device (Direct3D 9).
\t\nMark an instantaneous event. PIX can use this event to trigger an action.
\t\nInstantaneous user events do not bracket or group other events. For example, when the user fires a weapon in a game, a Shot Fired event could be created by a
Set profiler options specified by the target program.
\t\nDetermine the current state of the profiler from the target program.
\t\nReturns a non-zero value when PIX is profiling the target program; otherwise, returns zero.
Mark a series of frames with the specified color and name in the PIXRun file. This function is not currently supported by PIX.
\t\nTo make analysis easier, the target program can use color to mark each level of a target program.
\t\nMark the end of a user-defined event. PIX can use this event to trigger an action.
\t\nThe level of the hierarchy in which the event is ending. If an error occurs, this value is negative.
Marks the beginning of a user-defined event. PIX can use this event to trigger an action.
\t\nThe zero-based level of the hierarchy that this event is starting in. If an error occurs, the return value will be negative.
User-defined events group together other events in a way that is meaningful to the target program so that they can be better represented in performance profiling tools. For example, a Draw Spaceship event might bracket a number of Direct3D calls that handle drawing a spaceship in a game. Events can be nested.
Each
Determine whether a performance profiler is requesting that the current frame be resubmitted to Direct3D for performance analysis. This function is not currently supported by PIX.
\t\nIf the return value is TRUE, the caller should repeat the same sequence of calls. If
The function should be called immediately after
Adds a child frame to a frame.
\t\nPointer to the parent node.
Pointer to the child node.
If the function succeeds, the return value is
Loads the first frame hierarchy from a .x file.
\t\nPointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Combination of one or more flags from the D3DXMESH enumeration that specify creation options for the mesh.
Pointer to an
Pointer to an
Application provided interface that allows loading of user data. See
Returns a reference to the loaded frame hierarchy. See
Returns a reference to the animation controller corresponding to animation in the .x file. This is created with default tracks and events. See
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
All the meshes in the file will be collapsed into one output mesh. If the file contains a frame hierarchy, all the transformations will be applied to the mesh.
During the load, CreateFrame and LoadFrameChildData are called back on each frame to control loading and allocation of the frame. The application defines these methods to control how frames are stored. CreateMeshContainer and LoadMeshChildData are called back on each mesh object to control loading and allocation of mesh objects. LoadTopLevelData is called back for each top level object that doesn't get loaded by the other methods.
To free this data, call ID3DXAnimationController::Release to free the animation sets, and D3DXFRAMEDestroy, passing in the root node of the frame hierarchy and an object of your derived
Given a frame hierarchy, registers all the named matrices in the animation mixer.
\t\nThe top level node in the frame hierarchy.
Pointer to the animation controller object.
If the function succeeds, the return value is
Loads the first frame hierarchy from a .x file.
\t\nPointer to a buffer that contains the mesh hierarchy.
Size of the pMemory buffer, in bytes.
Combination of one or more flags from the D3DXMESH enumeration that specify creation options for the mesh.
Pointer to an
Pointer to an
Application provided interface that allows loading of user data. See
Returns a reference to the loaded frame hierarchy. See
Returns a reference to the animation controller corresponding to animation in the .x file. This is created with default tracks and events. See
If the function succeeds, the return value is
All the meshes in the file will be collapsed into one output mesh. If the file contains a frame hierarchy, all the transformations will be applied to the mesh.
\t\nCreates a
If the function succeeds, the return value is
Creates a .x file and saves the mesh hierarchy and corresponding animations in it.
\t\nPointer to a string that specifies the name of the .x file identifying the saved mesh. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Format of the .x file (text or binary, compressed or not). See
Root node of the hierarchy to be saved. See
Animation controller that has animation sets to be stored. See
Application-provided interface that allows saving of user data. See
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function does not save compressed animation sets.
\t\nComputes the bounding sphere of all the meshes in the frame hierarchy.
\t\nPointer to the root node.
Returns the center of the bounding sphere.
Returns the radius of the bounding sphere.
If the function succeeds, the return value is
Creates an animation controller object.
\t\nMaximum number of animation outputs the controller can support.
Maximum number of animation sets that can be mixed.
Maximum number of animation sets that can be mixed simultaneously.
Maximum number of outstanding events that the controller will support.
Pointer to the animation controller object created. See
If the function succeeds, the return value is
An animation controller controls an animation mixer. The controller adds methods to modify blending parameters over time to enable smooth transitions.
\t\nFinds the child frame of a root frame.
\t\nPointer to the root frame. See
Name of the child frame to find.
Returns the child frame if it is found, or
Creates a
If the function succeeds, the return value is
Destroys the subtree of frames under the root, including the root.
\t\nPointer to the root node.
Allocation interface used to deallocate nodes of the frame hierarchy.
If the function succeeds, the return value is
Counts number of frames in a subtree that have non-null names.
\t\nPointer to the root node of the subtree.
Returns the frame count.
Creates a render environment map.
\t\nPointer to an
Size of the render surface.
The number of mipmap levels.
Member of the
If TRUE, the render surface supports a depth-stencil surface. Otherwise, this member is set to
If DepthStencil is set to TRUE, this parameter is a member of the
Address of a reference to an
If the function succeeds, the return value is
Returns the driver level.
\t\nPointer to an
The driver level. See remarks.
This method returns the driver version, which is one of the following:
Creates a font object for a device and font.
\t\nPointer to an
The height of the characters in logical units.
The width of the characters in logical units.
Typeface weight. One example is bold.
The number of mipmap levels.
True for italic font, false otherwise.
The character set of the font.
Specifies how Windows should attempt to match the desired font sizes and characteristics with actual fonts. Use OUT_TT_ONLY_PRECIS for instance, to ensure that you always get a TrueType font.
Specifies how Windows should match the desired font with a real font. It applies to raster fonts only and should not affect TrueType fonts.
Pitch and family index.
String containing the typeface name. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Returns a reference to an
If the function succeeds, the return value is
The creation of an
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
If you want more information about font parameters, see The Logical Font.
\t\nCreates a render surface.
\t\nPointer to an
Width of the render surface, in pixels.
Height of the render surface, in pixels.
Member of the
If TRUE, the render surface supports a depth-stencil surface. Otherwise, this member is set to
If DepthStencil is set to TRUE, this parameter is a member of the
Address of a reference to an
If the function succeeds, the return value is
Creates a sprite object which is associated with a particular device. Sprite objects are used to draw 2D images to the screen.
\t\nPointer to an
Address of a reference to an
If the function succeeds, the return value is
This interface can be used to draw two dimensional images in screen space of the associated device.
\t\nCreates a font object indirectly for both a device and a font.
\t\nPointer to an
Pointer to a
Returns a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Uses a left-handed coordinate system to create a line.
\t\nPointer to an
Pointer to an
If the function succeeds, the return value is
This function creates a mesh with the
Turns on or off all D3DX debug output.
\t\nIf TRUE, debugger output is halted; if
Returns the previous value of Mute.
Verify that the version of D3DX you compiled with is the version that you are running.
\t\nUse
Use
Returns TRUE if the version of D3DX you compiled against is the version you are running with; otherwise,
Use this function during the initialization of your application like this:
CD3DXMyApplication::Initialize( hInstance, LPCSTR szWindowName, LPCSTR szClassName, UINT uWidth, UINT uHeight)\t\n { hr; if (!(, )) return E_FAIL; ...\t\n }\t\n Use Direct3DCreate9 to verify that the correct runtime is installed.
\t\nCreate an effect from an ASCII or binary effect description.
\t\nPointer to the device that will create the effect. See
Pointer to a buffer containing an effect description.
Length of the effect data, in bytes.
An optional
Optional interface reference,
If pSrcData contains a text effect, flags can be a combination of
Pointer to a
Returns a reference to an
Returns a buffer containing a listing of compile errors.
If the function succeeds, the return value is
Disassemble an effect.
\t\nPointer to an
Enable color coding to make the disassembly easier to read.
Returns a buffer containing the disassembled shader. See
If the function succeeds, the return value is
Create an effect from an ASCII or binary effect description. This is an extended version of
If the function succeeds, the return value is
This function is an extended version of
This function checks each constant in pSkipConstants to see that:
If a constant is named in the string that is not present in the effect, it is ignored.
If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the LPCTSTR data type resolves to LPCSTR.
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Create an effect from an ASCII or binary effect description.
\t\nPointer to the device.
Handle to a module containing the effect description. If this parameter is
Pointer to the resource. This parameter supports both Unicode and ANSI strings. See Remarks.
An optional
Optional interface reference,
If hSrcModule contains a text effect, flags can be a combination of
Pointer to a
Returns a buffer containing the compiled effect.
Returns a buffer containing a listing of compile errors.
If the function succeeds, the return value is
If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the LPCTSTR data type resolves to LPCSTR.
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Creates an effect compiler from an ASCII effect description.
\t\nPointer to a buffer containing an effect description.
Length, in bytes, of the effect data.
An optional
Optional interface reference,
Compile options identified by various flags (see
Address of a reference to an
Address of a reference to an
If the function succeeds, the return value is
Create an effect from an ASCII or binary effect description. This function is an extended version of
If the function succeeds, the return value is
This function is an extended version of
This function checks each constant in pSkipConstants to see that:
If a constant is named in the string that is not present in the effect, it is ignored.
If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the LPCTSTR data type resolves to LPCSTR.
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Creates an effect compiler from an ASCII effect description.
\t\nPointer to the filename. This parameter supports both Unicode and ANSI strings. See Remarks.
An optional
Optional interface reference,
Compile options identified by various flags (see
Address of a reference to an
Address of a reference to an
If the function succeeds, the return value is
If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the LPCTSTR data type resolves to LPCSTR.
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Creates an
If the function succeeds, the return value is
If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the LPCTSTR data type resolves to LPCSTR.
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Create an effect from an ASCII or binary effect description.
\t\nPointer to the device that will create the effect. See
Pointer to the filename. This parameter supports both Unicode and ANSI strings. See Remarks.
Optional
Optional interface reference,
If pSrcFile contains a text effect, flags can be a combination of
Pointer to a
Returns a reference to a buffer containing the compiled effect. See
Returns a reference to a buffer containing a listing of compile errors. See
If the function succeeds, the return value is
If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the LPCTSTR data type resolves to LPCSTR.
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Create an effect pool. A pool is used to share parameters between effects.
\t\nReturns a reference to the created pool.
If the method succeeds, the return value is
If the arguments are invalid, the method will return
If the method fails, the return value will be E_FAIL.
For effects within a pool, shared parameters with the same name share values.
\t\nCreates an effect from an ASCII or binary effect description. This function is an extended version of
If the function succeeds, the return value is
This function is an extended version of
This function checks each constant in pSkipConstants to see that:
If a constant is named in the string that is not present in the effect, it is ignored.
\t\nSaves a mesh to a .x file.
\t\nPointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Pointer to an
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh. This parameter may be
Pointer to an array of
Pointer to an array of effect instances, one per attribute group in the mesh. This parameter may be
Number of
A combination of file format and save options when saving an .x file. See D3DX X File Constants.
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
The default file format is binary; however, if a file is specified as both a binary and a text file, it will be saved as a text file. Regardless of the file format, you may also use the compressed format to reduce the file size.
The following is a typical code example of how to use this function.
* m_pMesh; // Mesh object to be saved to a .x file\t\n * m_pMaterials; // Array of material structs in the mesh\t\n DWORD m_dwNumMaterials; // Number of material structs in the mesh DWORD dwFormat = ; // Binary-format .x file (default)\t\n // DWORD dwFormat = ; // Text-format .x file // Load mesh into m_pMesh and determine values of m_pMaterials and \t\n // m_dwNumMaterials with calls to D3DXLoadMeshxxx or other D3DX functions // ... ( L\"outputxfilename.x\", m_pMesh, null , m_pMaterials, null , m_dwNumMaterials, dwFormat );\t\n Returns a declarator from a flexible vertex format (FVF) code.
\t\nCombination of
An array of
If the function succeeds, the return value is
Compute tangent, binormal, and normal vectors for a mesh.
\t\nPointer to an input
Combination of one or more
Use
If the function succeeds, the return value is
This function simply calls
(pMesh, , 0, , 0, , 0, , 0, dwOptions | , null , 0.01f, 0.25f, 0.01f, null , null );\t\n Singularities are handled as required by grouping edges and splitting vertices. If any vertices need to be split, the function will fail. The computed normal vector at each vertex is always normalized to have unit length.
The most robust solution for computing orthogonal Cartesian coordinates is to not set flags
Generates an optimized face remapping for a triangle list.
\t\nPointer to triangle list indices to use for ordering vertices.
Number of faces in the triangle list. For 16-bit meshes, this is limited to 2^16 - 1 (65535) or fewer faces.
Number of vertices referenced by the triangle list.
Flag indicating index type: TRUE if indices are 32-bit (more than 65535 indices),
Pointer to the original mesh face that was split to generate the current face.
If the function succeeds, the return value is
This function's optimization procedure is functionally equivalent to calling
Welds together replicated vertices that have equal attributes. This method uses specified epsilon values for equality comparisons.
\t\nPointer to an
Combination of one or more flags from D3DXWELDEPSILONSFLAGS.
Pointer to a D3DXWeldEpsilons structure, specifying the epsilon values to be used for this method. Use
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the source mesh. If the edge has no adjacent faces, the value is 0xffffffff. If this parameter is set to
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the optimized mesh. If the edge has no adjacent faces, the value is 0xffffffff.
An array of DWORDs, one per face, that identifies the original mesh face that corresponds to each face in the welded mesh.
Address of a reference to an
If the function succeeds, the return value is
This function uses supplied adjacency information to determine the points that are replicated. Vertices are merged based on an epsilon comparison. Vertices with equal position must already have been calculated and represented by point-representative data.
This function combines logically-welded vertices that have similar components, such as normals or texture coordinates within pEpsilons.
The following example code calls this function with welding enabled. Vertices are compared using epsilon values for normal vector and vertex position. A reference is returned to a face remapping array (pFaceRemap).
TCHAR strMediaPath[512]; // X-file path \t\n LPD3DXBUFFER pAdjacencyBuffer = null ; // adjacency data buffer\t\n LPD3DXBUFFER pD3DXMtrlBuffer = null ; // material buffer\t\n LPD3DXMESH pMesh = null ; // mesh object\t\n DWORD m_dwNumMaterials; // number of materials\t\n Epsilons; // structure with epsilon values\t\n DWORD *pFaceRemap[65536]; // face remapping array\t\n DWORD i; // internal variable // Load the mesh from the specified file hr = ( strMediaPath, , m_pd3dDevice, &pAdjacencyBuffer, &pD3DXMtrlBuffer, null , &m_dwNumMaterials, &pMesh ) ) if( FAILED( hr ) ) goto End; // Go to error handling // Set epsilon values Epsilons.Normal = 0.001; Epsilons.Position = 0.1; // Weld the vertices for( i=0; i < 65536; i++ ) { pFaceRemap[i] = 0; } hr = ( pMesh, , &Epsilons, (DWORD*)pAdjacencyBuffer->GetBufferPointer(), (DWORD*)pAdjacencyBuffer->GetBufferPointer(), (DWORD*)pFaceRemap, null ) if( FAILED( hr ) ) goto End; // Go to error handling\t\n Generates an output vertex declaration from the input declaration. The output declaration is intended for use by the mesh tessellation functions.
\t\nPointer to the output vertex declaration. See
Pointer to the input vertex declaration. See
If the function succeeds, the return value is
Creates a buffer object.
\t\nSize of the buffer to create, in bytes.
Address of a reference to an
If the function succeeds, the return value is
Loads a patch mesh from an
If the function succeeds, the return value is
For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the
The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of \"Texture0\" with an annotation called \"Name.\" This will contain the string file name for the texture.
\t\nTessellates the given mesh using the N-patch tessellation scheme.
\t\nPointer to an
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the source mesh. This parameter may be
Number of segments per edge to tessellate.
Set to TRUE to use quadratic interpolation for normals; set to
Address of a reference to an
Address of a reference to an
If the function succeeds, the return value is
This function tessellates by using the N-patch algorithm.
\t\nGenerates an optimized vertex remapping for a triangle list. This function is commonly used after applying the face remapping generated by
If the function succeeds, the return value is
By default, a mesh uses 16 bit indices when it is created unless the application specifies otherwise. To check whether an existing mesh uses 16-bit or 32-bit indices, call
Calculates per-triangle IMT's from a custom application-specified signal that varies over the surface of the mesh (generally at a higher frequency than vertex data). The signal is evaluated via a user-specified callback function.
\t\nA reference to an input mesh (see
Zero-based texture coordinate index that identifies which set of texture coordinates to use.
The number of components in each data point in the signal.
The maximum distance between vertices; the algorithm continues subdividing until the distance between all vertices is less than or equal to fMaxUVDistance.
Texture wrap options. This is a combination of one or more
A reference to a user-provided evaluator function, which will be used to compute the signal value at arbitrary U,V coordinates. The function follows the prototype of LPD3DXIMTSIGNALCALLBACK.
A reference to a user-defined value which is passed to the signal callback function. Typically used by an application to pass a reference to a data structure that provides context information for the callback function.
A reference to a callback function to monitor IMT computation progress.
A reference to a user-defined variable which is passed to the status callback function. Typically used by an application to pass a reference to a data structure that provides context information for the callback function.
A reference to the buffer (see
If the function succeeds, the return value is
This function requires that the input mesh contain a signal-to-mesh texture mapping (ie. texture coordinates). It allows the user to define a signal arbitrarily over the surface of the mesh.
\t\nValidates a patch mesh, returning the number of degenerate vertices and patches.
\t\nPointer to an
Returns the number of degenerate vertices in the patch mesh.
Returns the number of degenerate patches in the patch mesh.
Returns a reference to a buffer containing a string of errors and warnings that explain the problems found in the patch mesh.
If the function succeeds, the return value is
This method validates the mesh by checking for invalid indices. Error information is available from the debugger output.
\t\nValidates a mesh.
\t\nPointer to an
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh to be tested.
Returns a buffer containing a string of errors and warnings, which explain the problems found in the mesh.
If the function succeeds, the return value is
This method validates the mesh by checking for invalid indices. Error information is available from the debugger output.
\t\nCreate a UV atlas for a mesh.
\t\nPointer to an input mesh (see
The maximum number of charts to partition the mesh into. See remarks about the partitioning modes. Use 0 to tell D3DX that the atlas should be parameterized based on stretch.
The amount of stretching allowed. 0 means no stretching is allowed, 1 means any amount of stretching can be used.
Zero-based texture coordinate index that identifies which set of texture coordinates to use.
A reference to an array of adjacency data with 3 DWORDs per face, indicating which triangles are adjacent to each other (see
An array with 3 DWORDS per face. Each face indicates if an edge is false or not. A non-false edge is indicated by -1, a false edge is indicated by any other value. This enables the parameterization of a mesh of quads where the edges down the middle of each quad will not be cut.
A reference to an array of integrated metric tensors that describes how to stretch a triangle (see IntegratedMetricTensor).
A reference to a callback function (see LPD3DXUVATLASCB) that is useful for monitoring progress.
Specify how often D3DX will call the callback; a reasonable default value is 0.0001f.
Pointer to a user-defined value that is passed to the callback function; typically used by an application to pass a reference to a data structure that provides context information for the callback function.
Specify the quality of the charts generated by combining one or more D3DXUVATLAS flags.
Pointer to the created mesh with the atlas (see
A reference to an array of the final face-partitioning data. Each element contains one DWORD per face (see
A reference to an array of remapped vertices. Each array element identifies the original vertex each final vertex came from (if the vertex was split during remapping). Each array element contains one DWORD per vertex.
Address of a reference to an
A reference to the maximum stretch value generated by the atlas algorithm. The range is between 0.0 and 1.0.
A reference to the number of charts created by the atlas algorithm. If dwMaxChartNumber is too low, this parameter will return the minimum number of charts required to create an atlas.
If the function succeeds, the return value is
Splits a mesh into meshes smaller than the specified size.
\t\nPointer to an
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh to be simplified.
Maximum number of vertices in the resulting mesh.
Option flags for the new meshes.
Number of meshes returned.
Buffer containing an array of
Buffer containing an array of adjacency arrays (DWORDs) for the new meshes. See
Buffer containing an array of face remap arrays (DWORDs) for the new meshes. See
Buffer containing an array of vertex remap arrays for the new meshes. See
If the function succeeds, the return value is
A common use of this function is to split a mesh with 32-bit indices (more than 65535 vertices) into more than one mesh, each of which has 16-bit indices.
The adjacency, vertex remap and face remap arrays are arrays are DWORDs where each array contains n DWORD references, followed by the DWORD data referenced by the references. For example, to obtain the face remap information for face 3 in mesh 2, the following code could be used, assuming the face remap data was returned in a variable named ppFaceRemapArrayOut.
const DWORD **face_remaps = static_cast<DWORD **>(ppFaceRemapArrayOut->GetBufferPointer());\t\n const DWORD remap = face_remaps[2][3];\t\n Computes the tangent vectors for the texture coordinates given in the texture stage. Provided to support legacy applications. Use
If the function succeeds, the return value is
If the mesh vertex declaration specifies tangent or binormal fields,
This function simply calls
( Mesh, , TexStageIndex, ( BinormIndex == D3DX_DEFAULT ) ? D3DX_DEFAULT : , // provides backward function compatibility BinormIndex, ( TangentIndex == D3DX_DEFAULT ) ? D3DX_DEFAULT : , TangentIndex, D3DX_DEFAULT, // do not store normals 0, ( Wrap ? : 0 ) | | , pAdjacency, -1.01f, -0.01f, -1.01f, null , null );\t\n Determines if a ray intersects with a mesh.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to a
Pointer to an index value of the face closest to the ray origin, if pHit is TRUE.
Pointer to a barycentric hit coordinate, U.
Pointer to a barycentric hit coordinate, V.
Pointer to a ray intersection parameter distance.
Pointer to an
Pointer to a DWORD that contains the number of entries in the ppAllHits array.
If the function succeeds, the return value is
The
Any point in the plane V1V2V3 can be represented by the barycentric coordinate (U,V). The parameter U controls how much V2 gets weighted into the result, and the parameter V controls how much V3 gets weighted into the result. Lastly, the value of [1 - (U + V)] controls how much V1 gets weighted into the result.
Barycentric coordinates are a form of general coordinates. In this context, using barycentric coordinates represents a change in coordinate systems. What holds true for Cartesian coordinates holds true for barycentric coordinates.
Barycentric coordinates define a point inside a triangle in terms of the triangle's vertices. For a more in-depth description of barycentric coordinates, see Mathworld's Barycentric Coordinates Description.
\t\nPack mesh partitioning data into an atlas.
\t\nPointer to an input mesh (see
Texture width.
Texture height.
The minimum distance, in texels, between two charts on the atlas. The gutter is always scaled by the width; so, if a gutter of 2.5 is used on a 512x512 texture, then the minimum distance between two charts is 2.5 / 512.0 texels.
Zero-based texture coordinate index that identifies which set of texture coordinates to use.
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh. It should be derived from the ppPartitionResultAdjacency returned from
A reference to a callback function (see LPD3DXUVATLASCB) that is useful for monitoring progress.
Specify how often D3DX will call the callback; a reasonable default value is 0.0001f.
A void reference to be passed back to the callback function.
This options parameter is currently reserved.
A reference to an
If the function succeeds, the return value is
Creates an N-patch mesh from a triangle mesh.
\t\nAddress of a reference to an
Address of a reference to an
If the function succeeds, the return value is
Loads a skin mesh from a DirectX .x file data object.
\t\nPointer to an
Combination of one or more flags, from the D3DXMESH enumeration, specifying creation options for the mesh.
Pointer to an
Address of a reference to an
Address of a reference to an
Pointer to a buffer containing an array of effect instances, one per attribute group in the returned mesh. An effect instance is a particular instance of state information used to initialize an effect. See
Pointer to the number of
Address of a reference to an
Address of a reference to an
If the function succeeds, the return value is
This method takes a reference to an internal object in the .x file, enabling you to load the frame hierarchy.
For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the
The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of \"Texture0\" with an annotation called \"Name.\" This will contain the string file name for the texture.
\t\nCreates an empty skin mesh object using a flexible vertex format (FVF) code.
\t\nNumber of vertices for the skin mesh.
Combination of
Number of bones for the skin mesh.
Address of a reference to an
If the function succeeds, the return value is
Use SetBoneInfluence to populate the empty skin mesh object returned by this method.
\t\nIntersects the specified ray with the given mesh subset. This provides similar functionality to
If the function succeeds, the return value is
The
Any point in the plane V1V2V3 can be represented by the barycentric coordinate (U,V). The parameter U controls how much V2 gets weighted into the result and the parameter V controls how much V3 gets weighted into the result. Lastly, the value of [1 - (U + V)] controls how much V1 gets weighted into the result.
Barycentric coordinates are a form of general coordinates. In this context, using barycentric coordinates represents a change in coordinate systems. What holds true for Cartesian coordinates holds true for barycentric coordinates.
Barycentric coordinates define a point inside a triangle in terms of the triangle's vertices. For a more in-depth description of barycentric coordinates, see Mathworld's Barycentric Coordinates Description.
\t\nReturns the size of a vertex for a flexible vertex format (FVF).
\t\nFVF to be queried. A combination of
The FVF vertex size, in bytes.
Returns the number of elements in the vertex declaration.
\t\nA reference to the vertex declaration. See
The number of elements in the vertex declaration.
Cleans a mesh, preparing it for simplification.
\t\nVertex operations to perform in preparation for mesh cleaning. See
Pointer to an
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh to be cleaned.
Address of a reference to an
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the output mesh.
Returns a buffer containing a string of errors and warnings, which explain the problems found in the mesh.
If the function succeeds, the return value is
This function cleans a mesh using the cleaning method and options specified in the CleanType parameter. See the
Computes the intersection of a ray and a triangle.
\t\nPointer to a
Pointer to a
Pointer to a
Pointer to a
Pointer to a
Barycentric hit coordinates, U.
Barycentric hit coordinates, V.
Ray-intersection parameter distance.
Returns TRUE if the ray intersects the area of the triangle. Otherwise, returns
The
Any point in the plane V1V2V3 can be represented by the barycentric coordinate (U,V). The parameter U controls how much V2 gets weighted into the result, and the parameter V controls how much V3 gets weighted into the result. Lastly, the value of [1 - (U + V)] controls how much V1 gets weighted into the result.
Barycentric coordinates are a form of general coordinates. In this context, using barycentric coordinates represents a change in coordinate systems. What holds true for Cartesian coordinates holds true for barycentric coordinates.
Barycentric coordinates define a point inside a triangle in terms of the triangle's vertices. For a more in-depth description of barycentric coordinates, see Mathworld's Barycentric Coordinates Description.
\t\nConverts the specified mesh subset into a single triangle strip.
\t\nPointer to an
Attribute ID of the mesh subset to convert to strips.
Combination of one or more flags from the D3DXMESH enumeration, specifying options for creating the index buffer. Cannot be
Pointer to an
Number of indices in the buffer returned in the ppIndexBuffer parameter.
If the function succeeds, the return value is
Before running this function, call Optimize or
Creates an empty skin mesh object using a declarator.
\t\nNumber of vertices for the skin mesh.
Array of
Number of bones for the skin mesh.
Address of a reference to an
If the function succeeds, the return value is
Use SetBoneInfluence to populate the empty skin mesh object returned by this method.
\t\nReturns the size of a vertex from the vertex declaration.
\t\nA reference to the vertex declaration. See
The zero-based stream index.
The vertex declaration size, in bytes.
Tessellates a rectangular higher-order surface patch into a triangle mesh.
\t\nVertex buffer containing the patch data.
Pointer to an array of four floating-point values that identify the number of segments into which each edge of the rectangle patch should be divided when tessellated. See
Vertex declaration structure that defines the vertex data. See
Describes a rectangular patch. See
Pointer to the created mesh. See
If the function succeeds, the return value is
Use
Returns a flexible vertex format (FVF) code from a declarator.
\t\nArray of
Pointer to a DWORD value, representing the returned combination of
This function will fail for any declarator that does not map directly to an FVF.
\t\nCreates a skin mesh from another mesh.
\t\nPointer to an
The length of the array attached to the BoneId. See
Pointer to an array of bone combinations. See
Address of a reference to an
If the function succeeds, the return value is
Performs tangent frame computations on a mesh. Tangent, binormal, and optionally normal vectors are generated. Singularities are handled as required by grouping edges and splitting vertices.
\t\nPointer to an input
Specifies the texture coordinate input semantic. If D3DX_DEFAULT, the function assumes that there are no texture coordinates, and the function will fail unless normal vector calculation is specified.
If a mesh has multiple texture coordinates, specifies the texture coordinate to use for the tangent frame computations. If zero, the mesh has only a single texture coordinate.
Specifies the output semantic for the type, typically
Specifies the semantic index at which to store the partial derivative with respect to the U texture coordinate.
Specifies the
Specifies the semantic index at which to store the partial derivative with respect to the V texture coordinate.
Specifies the output normal semantic, typically
Specifies the semantic index at which to store the normal vector at each vertex.
Combination of one or more
| Description | |
|---|---|
| Weight the normal vector length by the angle, in radians, subtended by the two edges leaving the vertex. | & !( |
| Compute orthogonal Cartesian coordinates from texture coordinates (u, v). See Remarks. | & !( |
| Textures are not wrapped in either u or v directions | & !( |
| Partial derivatives with respect to texture coordinates are normalized. | & !( |
| Vertices are ordered in a counterclockwise direction around each triangle. | & !( |
| Use per-vertex normal vectors already present in the input mesh. | & !( |
?
If
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh. The number of bytes in this array must be at least 3 * GetNumFaces * sizeof(DWORD).
Specifies the maximum cosine of the angle at which two partial derivatives are deemed to be incompatible with each other. If the dot product of the direction of the two partial derivatives in adjacent triangles is less than or equal to this threshold, then the vertices shared between these triangles will be split.
Specifies the maximum magnitude of a partial derivative at which a vertex will be deemed singular. As multiple triangles are incident on a point that have nearby tangent frames, but altogether cancel each other out (such as at the top of a sphere), the magnitude of the partial derivative will decrease. If the magnitude is less than or equal to this threshold, then the vertex will be split for every triangle that contains it.
Similar to fPartialEdgeThreshold, specifies the maximum cosine of the angle between two normals that is a threshold beyond which vertices shared between triangles will be split. If the dot product of the two normals is less than the threshold, the shared vertices will be split, forming a hard edge between neighboring triangles. If the dot product is more than the threshold, neighboring triangles will have their normals interpolated.
Address of a reference to an output
Address of a reference to an output
If the function succeeds, the return value is
A simplified version of this function is available as
The computed normal vector at each vertex is always normalized to have unit length.
The most robust solution for computing orthogonal Cartesian coordinates is to not set flags
Determines if a ray intersects the volume of a sphere's bounding box.
\t\nPointer to a
Radius of the sphere.
Pointer to a
Pointer to a
Returns TRUE if the ray intersects the volume of the sphere's bounding box. Otherwise, returns
Create a UV atlas for a mesh.
\t\nPointer to an input mesh (see
The maximum number of charts to partition the mesh into. See remarks about the partitioning modes. Use 0 to tell D3DX that the atlas should be parameterized based on stretch.
The amount of stretching allowed. 0 means no stretching is allowed, 1 means any amount of stretching can be used.
Texture width.
Texture height.
The minimum distance, in texels, between two charts on the atlas. The gutter is always scaled by the width; so, if a gutter of 2.5 is used on a 512x512 texture, then the minimum distance between two charts is 2.5 / 512.0 texels.
Zero-based texture coordinate index that identifies which set of texture coordinates to use.
A reference to an array of adjacency data. with 3 DWORDs per face, indicating which triangles are adjacent to each other (see
An array with 3 DWORDS per face. Each face indicates if an edge is false or not. A non-false edge is indicated by -1, a false edge is indicated by any other value. This enables the parameterization of a mesh of quads where the edges down the middle of each quad will not be cut.
A reference to an array of integrated metric tensors that describes how to stretch a triangle (see IntegratedMetricTensor).
A reference to a callback function (see LPD3DXUVATLASCB) that is useful for monitoring progress.
Specify how often D3DX will call the callback; a reasonable default value is 0.0001f.
Pointer to a user-defined value which is passed to the callback function; typically used by an application to pass a reference to a data structure that provides context information for the callback function.
Specify the quality of the charts generated. See D3DXUVATLAS.
Pointer to the created mesh with the atlas (see
A reference to an array of the final face-partitioning data. Each element contains one DWORD per face (see
A reference to an array of remapped vertices. Each array element identifies the original vertex that each final vertex came from (if the vertex was split during remapping). Each array element contains one DWORD per vertex.
A reference to the maximum stretch value generated by the atlas algorithm. The range is between 0.0 and 1.0.
A reference to the number of charts created by the atlas algorithm. If dwMaxChartNumber is too low, this parameter will return the minimum number of charts required to create an atlas.
If the function succeeds, the return value is
Calculates per-triangle IMT's from a texture mapped onto a mesh, to be used optionally as input to the D3DX UVAtlas Functions.
\t\nIf the function succeeds, the return value is
Given a texture that maps over the surface of the mesh, the algorithm computes the IMT for each face. This will cause triangles containing lower-frequency signal data to take up less space in the final texture atlas when parameterized with the UVAtlas functions. The texture is assumed to be interpolated over the mesh bilinearly.
\t\nConcatenates a group of meshes into one common mesh. This method can optionally apply a matrix transformation to each input mesh and its texture coordinates.
\t\nArray of input mesh references (see
Number of input meshes to concatenate.
Mesh creation options; this is a combination of one or more D3DXMESH flags. The mesh creation options are equivalent to the options parameter required by
Optional array of geometry transforms. The number of elements in the array is NumMeshes; each element is a transformation matrix (see
Optional array of texture transforms. The number of elements in the array is NumMeshes; each element is a transformation matrix (see
Optional reference to a vertex declaration (see
Pointer to a
Address of a reference to the mesh created (see
If the function succeeds, the return value is
If no vertex declaration is given as part of the Options mesh creation parameter, the method will generate a union of all of the vertex declarations of the submeshes, promoting channels and types if necessary. The method will create an attribute table from attribute tables of the input meshes. To ensure creation of an attribute table, call Optimize with Flags set to
Determines whether a ray intersects the volume of a box's bounding box.
\t\nPointer to a
Pointer to a
Pointer to a
Pointer to a
Returns TRUE if the ray intersects the volume of the box's bounding box. Otherwise, returns
The values passed to
xmax, ymax, zmax\t\n xmax, ymax, zmin\t\n xmax, ymin, zmax\t\n xmax, ymin, zmin\t\n xmin, ymax, zmax\t\n xmin, ymax, zmin\t\n xmin, ymin, zmax\t\n xmin, ymin, zmin\t\n The depth of the bounding box in the z direction is zmax - zmin, in the y direction is ymax - ymin, and in the x direction is xmax - xmin. For example, with the following minimum and maximum vectors, min (-1, -1, -1) and max (1, 1, 1), the bounding box is defined in the following manner.
1, 1, 1 1, 1, -1 1, -1, 1 1, -1, -1\t\n -1, 1, 1\t\n -1, 1, -1\t\n -1, -1, 1\t\n -1, -1, -l\t\n Loads a mesh from a resource.
\t\nHandle to the module where the resource is located, or
Pointer to a string that specifies the resource to create the mesh from. See remarks.
Pointer to a string that specifies the resource type. See remarks.
Combination of one or more flags from the D3DXMESH enumeration that specify creation options for the mesh.
Pointer to an
Address of a reference to an
Address of a reference to an
Pointer to a buffer containing an array of effect instances, one per attribute group in the returned mesh. An effect instance is a particular instance of state information used to initialize an effect. See
Pointer to the number of
Address of a reference to an
If the function succeeds, the return value is
See FindResource to find out more about the Module, Name and Type parameters.
All the meshes in the file will be collapsed into one output mesh. If the file contains a frame hierarchy, all the transformations will be applied to the mesh.
For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the
The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of \"Texture0\" with an annotation called \"Name.\" This will contain the string file name for the texture.
\t\nGenerates a simplified mesh using the provided weights that come as close as possible to the given MinValue.
\t\nPointer to an
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh to be simplified.
Pointer to a
Pointer to an array of vertex weights. If this parameter is set to
Number of vertices or faces, depending on the flag set in the Options parameter, by which to simplify the source mesh.
Specifies simplification options for the mesh. One of the flags in D3DXMESHSIMP can be set.
Address of a reference to an
If the function succeeds, the return value is
This function generates a mesh that has MinValue vertices or faces.
If the simplification process cannot reduce the mesh to MinValue, the call still succeeds because MinValue is a desired minimum, not an absolute minimum.
If pVertexAttributeWeights is set to
AttributeWeights; AttributeWeights.Position = 1.0;\t\n AttributeWeights.Boundary = 1.0;\t\n AttributeWeights.Normal = 1.0;\t\n AttributeWeights.Diffuse = 0.0;\t\n AttributeWeights.Specular = 0.0;\t\n AttributeWeights.Tex[8] = {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};\t\n This default structure is what most applications should use because it considers only geometric and normal adjustment. Only in special cases will the other member fields need to be modified.
\t\nComputes a coordinate-axis oriented bounding box.
\t\nPointer to the first position.
Number of vertices.
Count or number of bytes between vertices.
Pointer to a
Pointer to a
If the function succeeds, the return value is
Creates a mesh object using a flexible vertex format (FVF) code.
\t\nNumber of faces for the mesh. The valid range for this number is greater than 0, and one less than the max DWORD value, typically 232 - 1, because the last index is reserved.
Number of vertices for the mesh. This parameter must be greater than 0.
Combination of one or more flags from the D3DXMESH enumeration, specifying creation options for the mesh.
Combination of
Pointer to an
Address of a reference to an
If the function succeeds, the return value is
Calculate per-triangle IMT's from from per-vertex data. This function allows you to calculate the IMT based off of any value in a mesh (color, normal, etc).
\t\nA reference to an input mesh (see
A reference to an array of per-vertex data from which IMT will be computed. The array size is uSignalStride * v, where v is the number of vertices in the mesh.
The number of floats per vertex.
The number of bytes per vertex in the array. This must be a multiple of sizeof(float)
Texture wrap options. This is a combination of one or more
A reference to a callback function to monitor IMT computation progress.
A reference to a user-defined variable which is passed to the status callback function. Typically used by an application to pass a reference to a data structure that provides context information for the callback function.
A reference to the buffer (see
If the function succeeds, the return value is
Loads a mesh from an
If the function succeeds, the return value is
For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the
The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of \"Texture0\" with an annotation called \"Name.\" This will contain the string file name for the texture.
\t\nCreates a mesh object using a declarator.
\t\nNumber of faces for the mesh. The valid range for this number is greater than 0, and one less than the maximum DWORD (typically 65534), because the last index is reserved.
Number of vertices for the mesh. This parameter must be greater than 0.
Combination of one or more flags from the D3DXMESH enumeration, specifying options for the mesh.
Array of
Pointer to an
Address of a reference to an
If the function succeeds, the return value is
Creates a mesh from a control-patch mesh.
\t\nPatch information structure. For more information, see
Number of patches.
Number of control vertices in the patch.
Unused. Reserved for later use.
Array of
Pointer the device that creates the patch mesh. See
Pointer to the
If the function succeeds, the return value is
This method takes an input patch mesh and converts it to a tessellated mesh. Patch meshes use 16-bit index buffers. Therefore, indices to LockIndexBuffer are 16 bits.
\t\nGets the size of the rectangle patch.
\t\nNumber of segments per edge to tessellate.
Pointer to a DWORD that contains the number of triangles in the patch.
Pointer to a DWORD that contains the number of vertices in the patch.
If the function succeeds, the return value is
Tessellates a triangular higher-order surface patch into a triangle mesh.
\t\nVertex buffer containing the patch data.
Pointer to an array of three floating-point values that identify the number of segments into which each edge of the triangle patch should be divided when tessellated. See
Vertex declaration structure that defines the vertex data. See
Describes a triangle patch. See
Pointer to the created mesh. See
If the function succeeds, the return value is
Use
Computes a bounding sphere for the mesh.
\t\nPointer to first position.
Number of vertices.
Number of bytes between position vectors. Use GetNumBytesPerVertex,
Radius of the returned bounding sphere.
If the function succeeds, the return value is
Loads a mesh from a DirectX .x file.
\t\nPointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Combination of one or more flags from the D3DXMESH enumeration, which specifies creation options for the mesh.
Pointer to an
Pointer to a buffer that contains adjacency data. The adjacency data contains an array of three DWORDs per face that specify the three neighbors for each face in the mesh. For more information about accessing the buffer, see
Pointer to a buffer containing materials data. The buffer contains an array of
Pointer to a buffer containing an array of effect instances, one per attribute group in the returned mesh. An effect instance is a particular instance of state information used to initialize an effect. See
Pointer to the number of
Address of a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
All the meshes in the file will be collapsed into one output mesh. If the file contains a frame hierarchy, all the transformations will be applied to the mesh.
For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the
The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of \"Texture0\" with an annotation called \"Name.\" This will contain the string file name for the texture.
\t\nLoads a mesh from memory.
\t\nPointer to the memory buffer which contains the mesh data.
Size of the file in memory, in bytes.
Combination of one or more flags from the D3DXMESH enumeration, specifying creation options for the mesh.
Pointer to an
Address of a reference to an
Address of a reference to an
Pointer to a buffer containing an array of effect instances, one per attribute group in the returned mesh. An effect instance is a particular instance of state information used to initialize an effect. See
Pointer to the number of
Address of a reference to an
If the function succeeds, the return value is
All the meshes in the file will be collapsed into one output mesh. If the file contains a frame hierarchy, all the transformations will be applied to the mesh.
For mesh files that do not contain effect instance information, default effect instances will be generated from the material information in the .x file. A default effect instance will have default values that correspond to the members of the
The default texture name is also filled in, but is handled differently. The name will be Texture0@Name, which corresponds to an effect variable by the name of \"Texture0\" with an annotation called \"Name.\" This will contain the string file name for the texture.
\t\nConvert the specified mesh subset into a series of strips.
\t\nPointer to an
Attribute ID of the mesh subset to convert to strips.
Combination of one or more flags from the D3DXMESH enumeration, specifying options for creating the index buffer. Cannot be
Pointer to an
Number of indices in the buffer returned in the ppIndexBuffer parameter.
Buffer containing an array of one DWORD per strip, which specifies the number of triangles in the that strip.
Number of individual strips in the index buffer and corresponding strip length array.
If the function succeeds, the return value is
Before running this function, call Optimize or
Calculate per-triangle IMT's from per-texel data. This function is similar to
If the function succeeds, the return value is
Gets the size of the triangle patch.
\t\nNumber of segments per edge to tessellate.
Pointer to a DWORD that contains the number of triangles in the patch.
Pointer to a DWORD that contains the number of vertices in the triangle patch.
If the function succeeds, the return value is
Computes unit normals for each vertex in a mesh. Provided to support legacy applications. Use
If the function succeeds, the return value is
The input mesh must have the
A normal for a vertex is generated by averaging the normals of all faces that share that vertex.
If adjacency is provided, replicated vertices are ignored and \"smoothed\" over. If adjacency is not provided, replicated vertices will have normals averaged in from only the faces explicitly referencing them.
This function simply calls
( pMesh, D3DX_DEFAULT, 0, D3DX_DEFAULT, 0, D3DX_DEFAULT, 0, , 0, | , pAdjacency, -1.01f, -0.01f, -1.01f, null , null );\t\n Preprocesses a shader without performing compilation. This resolves all #defines and #includes, providing a self-contained shader for subsequent compilation.
\t\nPointer to a string that contains the shader.
Length of the data in bytes.
An optional
Optional interface reference,
Returns a buffer containing a single large string that represents the resulting formatted token stream.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
If the function succeeds, the return value is
Compile a shader file.
\t\nPointer to a string that specifies the filename.
An optional
Optional interface reference,
Pointer to the shader entry point function where execution begins.
Pointer to a shader profile which determines the shader instruction set. See
Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Returns a buffer containing the created shader. This buffer contains the compiled shader code, as well as any embedded debug and symbol table information.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
Returns an
If the function succeeds, the return value is
Creates a texture shader object from the compiled shader.
\t\nPointer to the function DWORD stream.
Returns an
If the function succeeds, the return value is
Get the semantics for all shader output elements.
\t\nPointer to the shader function DWORD stream.
Pointer to an array of
Returns the number of elements in pSemantics.
If the function succeeds, the return value is
Gets the semantics for the shader inputs. Use this method to determine the input vertex format.
\t\nPointer to the shader function DWORD stream.
Pointer to an array of
Returns the number of elements in pSemantics.
If the function succeeds, the return value is
Use
Returns the name of the highest high-level shader language (HLSL) profile supported by a given device.
\t\nPointer to the device. See
The HLSL profile name.
If the device does not support pixel shaders then the function returns
A shader profile specifies the assembly shader version to use and the capabilities available to the HLSL compiler when compiling a shader. The following table lists the pixel shader profiles that are supported.
| Shader Profile | Description |
|---|---|
| ps_1_1 | Compile to ps_1_1 version. |
| ps_1_2 | Compile to ps_1_2 version. |
| ps_1_3 | Compile to ps_1_3 version. |
| ps_1_4 | Compile to ps_1_4 version. |
| ps_2_0 | Compile to ps_2_0 version. |
| ps_2_a | Same as the ps_2_0 profile, with the following additional capabilities available for the compiler to target:
|
| ps_2_b | Same as the ps_2_0 profile, with the following additional capabilities available for the compiler to target:
|
| ps_3_0 | Compile to ps_3_0 version. |
?
For more information about the differences between shader versions, see Pixel Shader Differences.
\t\nSearches through a shader for a particular comment. The comment is identified by a four-character code (FOURCC) in the first DWORD of the comment.
\t\nPointer to the shader function DWORD stream.
FOURCC code that identifies the comment block. See FourCC Formats.
Returns a reference to the comment data (not including the comment token and FOURCC code). This value can be
Returns the size of the comment data in bytes. This value can be
If the function succeeds, the return value is
Assemble a shader.
\t\nHandle to a module containing the effect description. If this parameter is
Pointer to a string that specifies the resource name. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
An optional
Optional interface reference,
Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Returns a buffer containing the created shader. This buffer contains the compiled shader code, as well as any embedded debug and symbol table information.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Assemble a shader.
\t\nPointer to a memory buffer that contains the shader data.
Length of the effect data, in bytes.
An optional
Optional interface reference,
Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Returns a buffer containing the created shader. This buffer contains the compiled shader code, as well as any embedded debug and symbol table information.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
If the function succeeds, the return value is
Compile a shader file.
\t\nPointer to a string that contains the shader.
Length of the data in bytes.
An optional
Optional interface reference,
Pointer to a string that contains the name of the shader entry point function where execution begins.
Pointer to a shader profile which determines the shader instruction set. See
Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Returns a buffer containing the created shader. This buffer contains the compiled shader code, as well as any embedded debug and symbol table information.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
Returns an
If the function succeeds, the return value is
Get the sampler names referenced in a shader.
\t\nPointer to the shader function DWORD stream.
Pointer to an array of LPCSTRs. The function will fill this array with references to the sampler names contained within pFunction. The maximum array size is the maximum number of sampler registers (16 for vs_3_0 and ps_3_0).
To find the number of samplers used, check pCount after calling
Returns the number of samplers referenced by the shader.
If the function succeeds, the return value is
Gets the shader-constant table embedded inside a shader.
\t\nPointer to the function DWORD stream.
Returns the constant table interface (see
A constant table is generated by
Assemble a shader.
\t\nPointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
An optional
Optional interface reference,
Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Returns a buffer containing the created shader. This buffer contains the compiled shader code, as well as any embedded debug and symbol table information.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Gets the shader-constant table embedded inside a shader.
\t\nPointer to the function DWORD stream.
Use the D3DXCONSTTABLE_LARGEADDRESSAWARE flag to access up to 4 GB of virtual address space (instead of the default of 2 GB). If you do not need the additional virtual address space, use
Returns the constant table interface (see
If the function succeeds, the return value is
A constant table is generated by
Returns the name of the highest high-level shader language (HLSL) profile supported by a given device.
\t\nPointer to the device. See
The HLSL profile name.
If the device does not support vertex shaders then the function returns
A shader profile specifies the assembly shader version to use and the capabilities available to the HLSL compiler when compiling a shader. The following table lists the vertex shader profiles that are supported.
| Shader Profile | Description |
|---|---|
| vs_1_1 | Compile to vs_1_1 version. |
| vs_2_0 | Compile to vs_2_0 version. |
| vs_2_a | Same as the vs_2_0 profile, with the following additional capabilities available for the compiler to target:
|
| vs_3_0 | Compile to vs_3_0 version. |
?
For more information about the differences between shader versions, see Vertex Shader Differences.
\t\nPreprocesses a shader resource without performing compilation. This resolves all #defines and #includes, providing a self-contained shader for subsequent compilation.
\t\nHandle to the module that holds the shader resource. If this value is
String that represents the name of the resource in the module.
An optional
Optional interface reference,
Returns a buffer containing a single large string that represents the resulting formatted token stream.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
If the function succeeds, the return value is
Compile a shader file.
\t\nHandle to a module containing the effect description. If this parameter is
Pointer to a string that specifies the resource name.
An optional
Optional interface reference,
Pointer to the shader entry point function where execution begins.
Pointer to a shader profile which determines the shader instruction set. See
Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See
Returns a buffer containing the created shader. This buffer contains the compiled shader code, as well as any embedded debug and symbol table information.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
Returns an
If the function succeeds, the return value is
Disassemble a shader.
\t\nPointer to a memory buffer that contains the shader data.
Enable color code to make it easier to read the disassembly.
An optional
Returns a buffer containing the disassembled shader. See
If the function succeeds, the return value is
Preprocesses a shader file without performing compilation. This resolves all #defines and #includes, providing a self-contained shader for subsequent compilation.
\t\nPointer to a string that specifies the filename of the shader.
An optional
Optional interface reference,
Returns a buffer containing a single large string that represents the resulting formatted token stream.
Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be
If the function succeeds, the return value is
Returns the size of the shader byte code, in bytes.
\t\nPointer to the function DWORD stream.
Returns the size of the shader byte code, in bytes.
Returns the shader version of the compiled shader.
\t\nPointer to the function DWORD stream.
Returns the shader version of the given shader, or zero if the shader function is
Uses a left-handed coordinate system to create a mesh containing a cylinder.
\t\nPointer to an
Radius at the negative Z end. Value should be greater than or equal to 0.0f.
Radius at the positive Z end. Value should be greater than or equal to 0.0f.
Length of the cylinder along the z-axis.
Number of slices about the main axis.
Number of stacks along the main axis.
Address of a reference to the output shape, an
Address of a reference to an
If the function succeeds, the return value is
The created cylinder is centered at the origin, and its axis is aligned with the z-axis.
This function creates a mesh with the
Uses a left-handed coordinate system to create a mesh containing a torus.
\t\nPointer to an
Inner-radius of the torus. Value should be greater than or equal to 0.0f.
Outer-radius of the torus. Value should be greater than or equal to 0.0f.
Number of sides in a cross-section. Value must be greater than or equal to 3.
Number of rings making up the torus. Value must be greater than or equal to 3.
Address of a reference to the output shape, an
Address of a reference to an
If the function succeeds, the return value is
The created torus is centered at the origin, and its axis is aligned with the z-axis. The inner radius of the torus is the radius of the cross-section (the minor radius), and the outer radius of the torus is the radius of the central hole.
This function returns a mesh that can be used later for drawing or manipulation by the application.
This function creates a mesh with the
Uses a left-handed coordinate system to create a mesh containing a sphere.
\t\nPointer to an
Radius of the sphere. This value should be greater than or equal to 0.0f.
Number of slices about the main axis.
Number of stacks along the main axis.
Address of a reference to the output shape, an
Address of a reference to an
If the function succeeds, the return value is
The created sphere is centered at the origin, and its axis is aligned with the z-axis.
This function creates a mesh with the
Uses a left-handed coordinate system to create a mesh containing a teapot.
\t\nPointer to an
Address of a reference to the output shape, an
Address of a reference to an
If the function succeeds, the return value is
This function creates a mesh with the
Uses a left-handed coordinate system to create a mesh containing an axis-aligned box.
\t\nPointer to an
Width of the box, along the x-axis.
Height of the box, along the y-axis.
Depth of the box, along the z-axis.
Address of a reference to the output shape, an
Address of a reference to an
If the function succeeds, the return value is
The created box is centered at the origin.
This function creates a mesh with the
Uses a left-handed coordinate system to create a mesh containing an \t\n n-sided polygon.
\t\nPointer to an
Length of each side.
Number of sides for the polygon. Value must be greater than or equal to 3.
Address of a reference to the output shape, an
Address of a reference to an
If the function succeeds, the return value is
The created polygon is centered at the origin.
This function creates a mesh with the
Creates a mesh containing the specified text, using the font associated with the device context.
\t\nPointer to the device that created the mesh.
Device context, containing the font for output. The font selected by the device context must be a TrueType font.
Pointer to a string that specifies the text to generate. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Maximum chordal deviation from TrueType font outlines.
Amount to extrude text in the negative z-direction.
Pointer to the returned mesh.
Pointer to a buffer containing adjacency information. May be
Pointer to an array of GLYPHMETRICSFLOAT structures that contain the glyph metric data. Each element contains information about the position and orientation of the corresponding glyph in the string. The number of elements in the array should be equal to the number of characters in the string. Note that the origin in each structure is not relative to the entire string, but rather is relative to that character cell. To compute the entire bounding box, add the increment for each glyph while traversing the string. If you are not concerned with the glyph sizes, set this parameter to
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function creates a mesh with the
Retrieves information about a given image file in memory.
\t\nVOID reference to the source file in memory.
Size of file in memory, in bytes. .
Pointer to a
Uses a compiled high-level shader language (HLSL) function to fill each texel of each mipmap level of a texture.
\t\nPointer to an
Pointer to a
If the function succeeds, the return value is
The texture target must be an HLSL function that takes contains the following semantics:
The input parameters can be in any order. For an example, see
Creates an empty cube texture, adjusting the calling parameters as needed.
\t\nPointer to an
Width and height of the cube texture, in pixels. For example, if the cube texture is an 8-pixel by 8-pixel cube, the value for this parameter should be 8.
Number of mip levels requested. If this value is zero or D3DX_DEFAULT, a complete mipmap chain is created.
0,
Member of the
Member of the
Address of a reference to an
If the function succeeds, the return value is
Cube textures differ from other surfaces in that they are collections of surfaces.
Internally,
Creates a volume texture from a file. This is a more advanced function than
If the function succeeds, the return value is
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
When skipping mipmap levels while loading a .dds file, use the D3DX_SKIP_DDS_MIP_LEVELS macro to generate the MipFilter value. This macro takes the number of levels to skip and the filter type and returns the filter value, which would then be passed into the MipFilter parameter.
\t\nUses a compiled high-level shader language (HLSL) function to fill each texel of each mipmap level of a texture.
\t\nPointer to an
Pointer to a
If the function succeeds, the return value is
The texture target must be an HLSL function that takes contains the following semantics:
The following is an example of such an HLSL function:
float4 TextureGradientFill( float2 vTexCoord : POSITION, float2 vTexelSize : PSIZE) : COLOR { float r,g, b, xSq,ySq, a; xSq = 2.f*vTexCoord.x-1.f; xSq *= xSq; ySq = 2.f*vTexCoord.y-1.f; ySq *= ySq; a = sqrt(xSq+ySq); if (a > 1.0f) { a = 1.0f-(a-1.0f); } else if (a < 0.2f) { a = 0.2f; } r = 1-vTexCoord.x; g = 1-vTexCoord.y; b = vTexCoord.x; return float4(r, g, b, a); };\t\n Note that the input parameters can be in any order, but both input semantics must be represented.
\t\nChecks cube-texture-creation parameters.
\t\nPointer to an
Pointer to the requested width and height in pixels, or
Pointer to the number of requested mipmap levels, or
0 or
Pointer to a member of the
Member of the
If the function succeeds, the return value is
If parameters to this function are invalid, this function returns corrected parameters.
Cube textures differ from other surfaces in that they are collections of surfaces. To call SetRenderTarget with a cube texture, you must select an individual face using GetCubeMapSurface and pass the resulting surface to SetRenderTarget.
\t\nCreates a texture from a file.
\t\nPointer to an
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Address of a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
The function is equivalent to
Mipmapped textures automatically have each level filled with the loaded texture.
When loading images into mipmapped textures, some devices are unable to go to a 1x1 image and this function will fail. If this happens, the images need to be loaded manually.
Note that a resource created with this function will be placed in the memory class denoted by
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
For the best performance when using
Loads a surface from a file.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Pointer to a
Combination of one or more
Pointer to a
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function handles conversion to and from compressed texture formats and supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Writing to a non-level-zero surface will not cause the dirty rectangle to be updated. If
Creates an empty volume texture, adjusting the calling parameters as needed.
\t\nPointer to an
Width in pixels. This value must be nonzero. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent in
Height in pixels. This value must be nonzero. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent in
Depth in pixels. This value must be nonzero. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent in
Number of mip levels requested. If this value is zero or D3DX_DEFAULT, a complete mipmap chain is created.
0 or
Member of the
Member of the
Address of a reference to an
If the function succeeds, the return value is
Internally,
Loads a volume from a file.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Pointer to a
Combination of one or more
Pointer to a
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function handles conversion to and from compressed texture formats and supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Writing to a non-level-zero surface of the volume texture will not cause the dirty rectangle to be updated. If
Retrieves information about a given image file.
\t\nFile name of image to retrieve information about. If UNICODE or _UNICODE are defined, this parameter type is LPCWSTR, otherwise, the type is LPCSTR.
Pointer to a
This function supports both Unicode and ANSI strings.
\t\nConverts a height map into a normal map. The (x,y,z) components of each normal are mapped to the (r,g,b) channels of the output texture.
\t\nPointer to an
Pointer to an
Pointer to a
One or more
One
Constant value multiplier that increases (or decreases) the values in the normal map. Higher values usually make bumps more visible, lower values usually make bumps less visible.
If the function succeeds, the return value is
This method computes the normal by using the central difference with a kernel size of 3x3. The central differencing denominator used is 2.0. RGB channels in the destination contain biased (x,y,z) components of the normal.
\t\nChecks volume-texture-creation parameters.
\t\nPointer to an
Pointer to the requested width in pixels, or
Pointer to the requested height in pixels, or
Pointer to the requested depth in pixels, or
Pointer to the number of requested mipmap levels, or
Currently not used, set to 0.
Pointer to a member of the
Member of the
If the function succeeds, the return value is
If parameters to this function are invalid, this function returns corrected parameters.
\t\nCreates a texture from a file in memory.
\t\nPointer to an
Pointer to the file in memory from which to create the texture.
Size in bytes of the file in memory.
Address of a reference to an
If the function succeeds, the return value is
The function is equivalent to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Note that a resource created with this function when called from a
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Creates a volume texture from a file in memory.
\t\nPointer to an
Pointer to the file in memory from which to create the volume texture.
Size of the file in memory, in bytes.
Address of a reference to an
If the function succeeds, the return value is
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
The function is equivalent to
Note that a resource created with this function when called from a
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Loads a volume from another volume.
\t\nPointer to an
Pointer to a
Pointer to a
A Pointer to an
Pointer to a
Pointer to a
A combination of one or more
If the function succeeds, the return value is
Writing to a non-level-zero surface of the volume texture will not cause the dirty rectangle to be updated. If
Saves a texture to a file.
\t\nPointer to a string that specifies the file name of the destination image. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Pointer to
Pointer to a
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function handles conversion to and from compressed texture formats.
If the volume is nondynamic (because of a usage parameter set to 0 at the creation) and located in video memory (the memory pool set to
Creates a cube texture from a file.
\t\nPointer to an
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Address of a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
The function is equivalent to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Note that a resource created with this function when called from a
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Creates a cube texture from a file in memory. This is a more advanced function than
If the function succeeds, the return value is
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Cube textures differ from other surfaces in that they are collections of surfaces. To call SetRenderTarget with a cube texture, you must select an individual face using GetCubeMapSurface and pass the resulting surface to SetRenderTarget .
This method is designed to be used for loading image files stored as RT_RCDATA, which is an application-defined resource (raw data). Otherwise this method will fail.
For details on
When skipping mipmap levels while loading a .dds file, use the D3DX_SKIP_DDS_MIP_LEVELS macro to generate the MipFilter value. This macro takes the number of levels to skip and the filter type and returns the filter value, which would then be passed into the MipFilter parameter.
\t\nCreates a texture from a resource. This is a more advanced function than
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
The resource being loaded must be of type RT_BITMAP or RT_RCDATA. Resource type RT_RCDATA is used to load formats other than bitmaps (such as .tga, .jpg, and .dds).
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Uses a user-provided function to fill each texel of each mip level of a given cube texture.
\t\nPointer to an
Pointer to a user-provided evaluator function, which will be used to compute the value of each texel. The function follows the prototype of LPD3DXFILL3D.
Pointer to an arbitrary block of user-defined data. This reference will be passed to the function provided in pFunction.
If the function succeeds, the return value is
Here is an example that creates a function called ColorCubeFill, which relies on
// Define a function that matches the prototype of LPD3DXFILL3D\t\n VOID WINAPI ColorCubeFill (* pOut, const * pTexCoord, \t\n const * pTexelSize, LPVOID pData)\t\n { *pOut = (pTexCoord->x, pTexCoord->y, pTexCoord->z, 0.0f);\t\n } // Fill the texture using \t\n if (FAILED (hr = (m_pTexture, ColorCubeFill, null )))\t\n { return hr;\t\n }\t\n Saves a texture to an image file.
\t\n
Pointer to
Pointer to a
Address of a reference to an
This function handles conversion to and from compressed texture formats.
\t\nSaves a volume to a file on disk.
\t\nPointer to a string that specifies the file name of the destination image. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Pointer to
Pointer to a
Pointer to a
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function handles conversion to and from compressed texture formats.
If the volume is nondynamic (because of a usage parameter set to 0 at the creation) and located in video memory (the memory pool set to
Loads a volume from a resource.
\t\nPointer to an
Pointer to a
Pointer to a
Handle to the module where the resource is located, or
Pointer to a string that specifies the file name of the source image. If UNICODE or _UNICODE are defined, this parameter type is LPCWSTR, otherwise, the type is LPCSTR.
Pointer to a
Combination of one or more
Pointer to a
If the function succeeds, the return value is
The resource being loaded must be a bitmap resource(RT_BITMAP).
This function handles conversion to and from compressed texture formats.
Writing to a non-level-zero surface of the volume texture will not cause the dirty rectangle to be updated. If
This function supports both Unicode and ANSI strings.
\t\nCreates a volume texture from a resource specified by a string. This is a more advanced function than
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
The resource being loaded must be an application-defined resource (RT_RCDATA).
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Creates a cube texture from a resource.
\t\nPointer to an
Handle to the module where the resource is located, or
Pointer to a string that specifies the resource name. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Address of a reference to an
If the function succeeds, the return value is
The compiler setting determines the function version. If Unicode is defined, the function call resolves to
The function is equivalent to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Note that a resource created with this function when called from a
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Saves a surface to a file.
\t\nPointer to a string that specifies the file name of the destination image. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Pointer to
Pointer to a
Pointer to a
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function handles conversion to and from compressed texture formats.
\t\nCreates a cube texture from a file. This is a more advanced function than
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Cube textures differ from other surfaces in that they are collections of surfaces. To call SetRenderTarget with a cube texture, you must select an individual face using GetCubeMapSurface and pass the resulting surface to SetRenderTarget.
When skipping mipmap levels while loading a .dds file, use the D3DX_SKIP_DDS_MIP_LEVELS macro to generate the MipFilter value. This macro takes the number of levels to skip and the filter type and returns the filter value, which would then be passed into the MipFilter parameter.
\t\nRetrieves information about a given image in a resource.
\t\nModule where the resource is loaded. Set this parameter to
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Pointer to a
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Uses a compiled high-level shader language (HLSL) function to fill each texel of each mipmap level of a texture.
\t\nPointer to an
Pointer to a
If the function succeeds, the return value is
The texture target must be an HLSL function that takes contains the following semantics:
The input parameters can be in any order. For an example, see
Uses a user-provided function to fill each texel of each mip level of a given texture.
\t\nPointer to an
Pointer to a user-provided evaluator function, which will be used to compute the value of each texel. The function follows the prototype of LPD3DXFILL2D.
Pointer to an arbitrary block of user-defined data. This reference will be passed to the function provided in pFunction.
If the function succeeds, the return value is
Here is an example that creates a function called ColorFill, which relies on
// Define a function that matches the prototype of LPD3DXFILL3D\t\n VOID WINAPI ColorFill (* pOut, const * pTexCoord, \t\n const * pTexelSize, LPVOID pData)\t\n { *pOut = (pTexCoord->x, pTexCoord->y, 0.0f, 0.0f);\t\n } // Fill the texture using \t\n if (FAILED (hr = (m_pTexture, ColorFill, null )))\t\n { return hr;\t\n }\t\n Saves a surface to an image file.
\t\nAddress of a reference to an
Pointer to
Pointer to a
Pointer to a
If the function succeeds, the return value is
This function handles conversion to and from compressed texture formats.
\t\nCreates a cube texture from a resource specified by a string. This is a more advanced function than
If the function succeeds, the return value is
The compiler setting determines the function version. If Unicode is defined, the function call resolves to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Cube textures differ from other surfaces in that they are collections of surfaces. To call SetRenderTarget with a cube texture, you must select an individual face using GetCubeMapSurface and pass the resulting surface to SetRenderTarget.
Creates a volume texture from a file.
\t\nPointer to an
Pointer to a string that specifies the file name. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Address of a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
The function is equivalent to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Mipmapped textures automatically have each level filled with the loaded texture.
When loading images into mipmapped textures, some devices are unable to go to a 1x1 image and this function will fail. If this happens, then the images need to be loaded manually.
Note that a resource created with this function when called from a
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Creates a texture from a resource.
\t\nPointer to an
Handle to the module where the resource is located, or
Pointer to a string that specifies the resource name. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Address of a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
The function is equivalent to
The resource being loaded must be of type RT_BITMAP or RT_RCDATA. Resource type RT_RCDATA is used to load formats other than bitmaps (such as .tga, .jpg, and .dds).
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Note that a resource created with this function when called from a
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Loads a volume from memory.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to the top-left corner of the source volume in memory.
Member of the
Pitch of source image, in bytes. For DXT formats (compressed texture formats), this number should represent the size of one row of cells, in bytes.
Pitch of source image, in bytes. For DXT formats (compressed texture formats), this number should represent the size of one slice of cells, in bytes.
Pointer to a
Pointer to a
A combination of one or more
If the function succeeds, the return value is
Writing to a non-level-zero surface of the volume texture will not cause the dirty rectangle to be updated. If
Creates a volume texture from a file.
\t\nPointer to an
Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Width in pixels. If this value is zero or D3DX_DEFAULT, the dimensions are taken from the file. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent in
Height, in pixels. If this value is zero or D3DX_DEFAULT, the dimensions are taken from the file. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent in
Depth, in pixels. If this value is zero or D3DX_DEFAULT, the dimensions are taken from the file. The maximum dimension that a driver supports (for width, height, and depth) can be found in MaxVolumeExtent in
Number of mip levels requested. If this value is zero or D3DX_DEFAULT, a complete mipmap chain is created.
0,
Member of the
Member of the
A combination of one or more
A combination of one or more
Pointer to a
Pointer to a
Address of a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Mipmapped textures automatically have each level filled with the loaded volume texture. When loading images into mipmapped textures, some devices are unable to go to a 1x1 image and this function will fail. If this happens, then the images need to be loaded manually.
When skipping mipmap levels while loading a .dds file, use the D3DX_SKIP_DDS_MIP_LEVELS macro to generate the MipFilter value. This macro takes the number of levels to skip and the filter type and returns the filter value, which would then be passed into the MipFilter parameter.
\t\nCreates a texture from a file in memory. This is a more advanced function than
If the function succeeds, the return value is
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
For details about
When skipping mipmap levels while loading a .dds file, use the D3DX_SKIP_DDS_MIP_LEVELS macro to generate the MipFilter value. This macro takes the number of levels to skip and the filter type and returns the filter value, which would then be passed into the MipFilter parameter.
\t\nSaves a volume to a buffer. The method creates an
If the function succeeds, the return value is
Creates a volume texture from a resource.
\t\nPointer to an
Handle to the module where the resource is located, or
Pointer to a string that specifies the resource name. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.
Address of a reference to an
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
The function is equivalent to
The resource being loaded must be an application-defined resource (RT_RCDATA).
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Note that a resource created with this function when called from a
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Creates a cube texture from a file in memory.
\t\nPointer to an
Pointer to the file in memory from which to create the cubemap. See Remarks.
Size of the file in memory, in bytes.
Address of a reference to an
If the function succeeds, the return value is
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
The function is equivalent to
Note that a resource created with this function when called from a
This method is designed to be used for loading image files stored as RT_RCDATA, which is an application-defined resource (raw data). Otherwise this method will fail.
Filtering is automatically applied to a texture created using this method. The filtering is equivalent to
Creates an empty texture, adjusting the calling parameters as needed.
\t\nPointer to an
Width in pixels. If this value is 0, a value of 1 is used. See Remarks.
Height in pixels. If this value is 0, a value of 1 is used. See Remarks.
Number of mip levels requested. If this value is zero or D3DX_DEFAULT, a complete mipmap chain is created.
0,
Member of the
Member of the
Address of a reference to an
If the function succeeds, the return value is
Internally,
If both Height and Width are set to D3DX_DEFAULT, a value of 256 is used for both parameters. If either Height or Width is set to D3DX_DEFAULT And the other parameter is set to a numeric value, the texture will be square with both the height and width equal to the numeric value.
\t\nUses a user-provided function to fill each texel of each mip level of a given volume texture.
\t\nPointer to an
Pointer to a user-provided evaluator function, which will be used to compute the value of each texel. The function follows the prototype of LPD3DXFILL3D.
Pointer to an arbitrary block of user-defined data. This reference will be passed to the function provided in pFunction.
If the function succeeds, the return value is
If the volume is non-dynamic (because usage is set to 0 when it is created), and located in video memory (the memory pool set to
This example creates a function called ColorVolumeFill, which relies on
// Define a function that matches the prototype of LPD3DXFILL3D\t\n VOID WINAPI ColorVolumeFill (* pOut, const * pTexCoord, \t\n const * pTexelSize, LPVOID pData)\t\n { *pOut = (pTexCoord->x, pTexCoord->y, pTexCoord->z, 0.0f);\t\n } // Fill volume texture\t\n if (FAILED (hr = (m_pTexture, ColorVolumeFill, null )))\t\n { return hr;\t\n }\t\n Loads a surface from memory.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to the upper left corner of the source image in memory.
Member of the
Pitch of source image, in bytes. For DXT formats, this number should represent the width of one row of cells, in bytes.
Pointer to a
Pointer to a
Combination of one or more
If the function succeeds, the return value is
This function handles conversion to and from compressed texture formats.
Writing to a non-level-zero surface will not cause the dirty rectangle to be updated. If
Loads a surface from another surface with color conversion.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to an
Pointer to a
Pointer to a
A combination of one or more
If the function succeeds, the return value is
This function handles conversion to and from compressed texture formats.
Writing to a non-level-zero surface will not cause the dirty rectangle to be updated. If
Loads a volume from a file in memory.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to the file in memory from which to load the volume.
Size in bytes of the file in memory.
Pointer to a
Combination of one or more
Pointer to a
If the function succeeds, the return value is
This function handles conversion to and from compressed texture formats and supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Writing to a non-level-zero surface of the volume texture will not cause the dirty rectangle to be updated. If
Creates a texture from a file. This is a more advanced function than
If the function succeeds, the return value is
The compiler setting also determines the function version. If Unicode is defined, the function call resolves to
Use
This function supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. See
Mipmapped textures automatically have each level filled with the loaded texture. When loading images into mipmapped textures, some devices are unable to go to a 1x1 image and this function will fail. If this happens, then the images need to be loaded manually.
For the best performance when using
When skipping mipmap levels while loading a .dds file, use the D3DX_SKIP_DDS_MIP_LEVELS macro to generate the MipFilter value. This macro takes the number of levels to skip and the filter type and returns the filter value, which would then be passed into the MipFilter parameter.
\t\nCreates an instance of an
If the function succeeds, the return value is
After using this function, use RegisterTemplates or RegisterEnumTemplates to register templates, CreateEnumObject to create an enumerator object, or CreateSaveObject to create a save object.
\t\nAn application implements this interface to handle callbacks in animation sets generated by calls to
The LPD3DXANIMATIONCALLBACKHANDLER type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXANIMATIONCALLBACKHANDLER;\t\n The application implements this method. This method is called when a callback occurs for an animation set in one of the tracks during a call to
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
This interface is used to control animation functionality, connecting animation sets with the transformation frames that are being animated. The interface has methods to mix multiple animations and to modify blending parameters over time to enable smooth transitions and other effects.
\t\nCreate an animation controller object with
The LPD3DXANIMATIONCONTROLLER type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DXANIMATIONCONTROLLER;\t\n The D3DXEVENTHANDLE type is defined as an event handle to animation controller events.
typedef DWORD D3DXEVENTHANDLE;\t\n The LPD3DXEVENTHANDLE type is defined as a reference to an event handle to animation controller events.
typedef D3DXEVENTHANDLE *LPD3DXEVENTHANDLE;\t\n Get the maximum number of animation outputs the animation controller can support.
\t\nThe maximum number of animation outputs the controller can manage.
Gets the maximum number of animation sets the animation controller can support.
\t\nThe maximum number of animation sets the controller can manage.
Gets the maximum number of tracks in the animation controller.
\t\nNumber of tracks.
The maximum number of tracks the controller can manage.
\t\nGets the maximum number of events the animation controller can support.
\t\nThe maximum number of events the controller can manage.
Adds an animation output to the animation controller and registers references for scale, rotate, and translate (SRT) transformations.
\t\nName of the animation output.
Pointer to a
Pointer to a
Pointer to a
Pointer to a
If the method succeeds, the return value is
If the animation output is already registered, pMatrix will be filled with the input transformation data.
Animation sets created with
Adds an animation set to the animation controller.
\t\nPointer to the
If the method succeeds, the return value is
Removes an animation set from the animation controller.
\t\nPointer to the
If the method succeeds, the return value is
Returns the number of animation sets currently registered in the animation controller.
\t\nNumber of animation sets.
The controller contains any number of animations sets and tracks. Animation sets can be registered with RegisterAnimationOutput. An animation controller created by a call to
Gets an animation set.
\t\nIndex of the animation set.
Pointer to the
If the method succeeds, the return value is
The animation controller contains an array of animation sets. This method returns one of them at the given index.
\t\nGets an animation set, given its name.
\t\nString containing the name of the animation set.
Pointer to the
If the method succeeds, the return value is
The animation controller contains an array of animation sets. This method returns an animation set that has the given name.
\t\nAnimates the mesh and advances the global animation time by a specified amount.
\t\nAmount, in seconds, by which to advance the global animation time. TimeDelta value must be non-negative or zero.
Pointer to a user-defined animation callback handler interface,
If the method succeeds, the return value is
Resets the global animation time to zero. Any pending events will retain their original schedules, but in the new timeframe.
\t\nIf the method succeeds, the return value is
This method is typically used when the global animation time value is nearing the maximum precision of DOUBLE storage, or 264 - 1.
\t\nGets the global animation time.
\t\nReturns the global animation time.
Animations are designed using a local animation time and mixed into global time with AdvanceTime.
\t\nApplies the animation set to the specified track.
\t\nIdentifier of the track to which the animation set is applied.
Pointer to the
If the method succeeds, the return value is
This method sets the animation set to the specified track for mixing. The animation set for each track is blended according to the track weight and speed when AdvanceTime is called.
\t\nGets the animation set for the given track.
\t\nTrack identifier.
Pointer to the
If the method succeeds, the return value is
Sets the priority blending weight for the specified animation track.
\t\nTrack identifier.
Track priority. This parameter should be set to one of the constants from
If the method succeeds, the return value is
Sets the track speed. The track speed is similar to a multiplier that is used to speed up or slow down the playback of the track.
\t\nIdentifier of the track to set the speed on.
New speed.
If the method succeeds, the return value is
Sets the track weight. The weight is used to determine how to blend multiple tracks together.
\t\nIdentifier of the track to set the weight on.
Weight value.
If the method succeeds, the return value is
Sets the track to the specified local animation time.
\t\nTrack identifier.
Local animation time value to assign to the track.
If the method succeeds, the return value is
Enables or disables a track in the animation controller.
\t\nIdentifier of the track to be mixed.
Enable value. Set to TRUE to enable this track in the controller, or to
If the method succeeds, the return value is
To mix a track with other tracks, the Enable flag must be set to TRUE. Conversely, setting the flag to
Sets the track description.
\t\nIdentifier of the track to modify.
Description of the track.
If the method succeeds, the return value is
Gets the track description.
\t\nTrack identifier.
Pointer to the track description. See
If the method succeeds, the return value is
Sets the priority blending weight used by the animation controller.
\t\nPriority blending weight used by the animation controller.
If the method succeeds, the return value is
The blend weight is used to blend high and low priority tracks together.
\t\nGets the current priority blending weight used by the animation controller.
\t\nReturns the current priority blending weight.
The priority blending weight is used to blend high and low priority tracks together.
\t\nSets an event key that changes the rate of play of an animation track.
\t\nIdentifier of the track to modify.
New speed of the animation track.
Global time key. Specifies the global time when the change will take place.
Transition time, which specifies how long the smooth transition will take to complete.
Specifies the transition type used for transitioning between speeds. See
Event handle to the priority blend event.
Sets an event key that changes the weight of an animation track. The weight is used as a multiplier when combining multiple tracks together.
\t\nIdentifier of the track to modify.
New weight of the track.
Global time key. Specifies the global time when the change will take place.
Transition time, which specifies how long the smooth transition will take to complete.
Specifies the transition type used for transitioning between weights. See
Event handle to the priority blend event.
The weight is used like a multiplier to determine how much of this track to blend together with other tracks.
\t\nSets an event key that changes the local time of an animation track.
\t\nIdentifier of the track to modify.
New local time of the animation track.
Global time key. Specifies the global time when the change will take place.
Event handle to the priority blend event.
Sets an event key that enables or disables an animation track.
\t\nIdentifier of the animation track to modify.
Enable flag. Set this to TRUE to enable the animation track, or to
Global time key. Specifies the global time when the change will take place.
Event handle to the priority blend event.
Sets blending event keys for the specified animation track.
\t\nNumber between 0 and 1 that is used to blend tracks together.
Global time to start the blend.
Global time duration of the blend.
Specifies the transition type used for the duration of the blend. See
Event handle to the priority blend event.
The animation controller blends in three phases: low priority tracks are blended first, high priority tracks are blended second, and then the results of both are blended.
\t\nRemoves a specified event from an animation track, preventing the execution of the event.
\t\nEvent handle to the event to be removed from the animation track.
If the method succeeds, the return value is
Removes all events from a specified animation track.
\t\nIdentifier of the track on which all events should be removed.
If the method succeeds, the return value is
This method prevents the execution of all events previously scheduled on the track, and discards all data associated with those events.
\t\nRemoves all scheduled priority blend events from the animation controller.
\t\nIf the method succeeds, the return value is
Returns an event handle to the event currently running on the specified animation track.
\t\nTrack identifier.
Type of event to query.
Event handle to the event currently running on the specified track.
Returns an event handle to a priority blend event that is currently running.
\t\nEvent handle to the currently running priority blend event.
Returns an event handle to the next event scheduled to occur after a specified event on an animation track.
\t\nTrack identifier.
Event handle to a specified event after which to search for a following event. If set to
Event handle to the next event scheduled to run on the specified track.
This method can be used iteratively to locate a desired event by repeatedly passing in
Note??Do not iterate further after the method has returned
Returns an event handle to the next priority blend event scheduled to occur after a specified event.
\t\nEvent handle to a specified event after which to search for a following priority blend event. If set to
Event handle to the next scheduled priority blend event.
This method can be used iteratively to locate a desired priority blend event by repeatedly passing in
Note??Do not iterate further after the method has returned
Checks whether a specified event handle is valid and the animation event has not yet completed.
\t\nEvent handle to an animation event.
Returns
Returns E_FAIL if the event handle is invalid and/or the event has completed.
The method will indicate that an event handle is valid even if the event is running but has not yet completed.
\t\nGets a description of a specified animation event.
\t\nEvent handle to an animation event to describe.
Pointer to a
If the method succeeds, the return value is
Clones, or copies, an animation controller.
\t\nMaximum number of animation outputs the controller can support.
Maximum number of animation sets the controller can support.
Maximum number of tracks the controller can support.
Maximum number of events the controller can support.
Address of a reference to the cloned
If the method succeeds, the return value is
Get the maximum number of animation outputs the animation controller can support.
\t\nGets the maximum number of animation sets the animation controller can support.
\t\nGets the maximum number of tracks in the animation controller.
\t\nThe maximum number of tracks the controller can manage.
\t\nGets the maximum number of events the animation controller can support.
\t\nReturns the number of animation sets currently registered in the animation controller.
\t\nThe controller contains any number of animations sets and tracks. Animation sets can be registered with RegisterAnimationOutput. An animation controller created by a call to
Gets the global animation time.
\t\nAnimations are designed using a local animation time and mixed into global time with AdvanceTime.
\t\nGets or sets the current priority blending weight used by the animation controller.
\t\nThe priority blending weight is used to blend high and low priority tracks together.
\t\nReturns an event handle to a priority blend event that is currently running.
\t\nThis interface encapsulates the minimum functionality required of an animation set by an animation controller. Advanced users might want to implement this interface themselves to suit their specialized needs; for most users, however, the derived
An animation set consists of animations for many nodes for the same animation.
The LPD3DXANIMATIONSET type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXANIMATIONSET;\t\n Gets the animation set name.
\t\nName of the animation set.
Gets the period of the animation set.
\t\nPeriod of the animation set.
The period is the range of time that the animation key frames are valid. For looping animations, this is the period of the loop. The time units that the key frames are specified in (for example, seconds) is determined by the application.
\t\nReturns time position in the local timeframe of an animation set.
\t\nLocal time of the animation set.
Time position as measured in the timeframe of the animation set. This value will be bounded by the period of the animation set.
The time position returned by this method can be used as the PeriodicPosition parameter of
Gets the number of animations in the animation set.
\t\nNumber of animations in the animation set.
Gets the name of an animation, given its index.
\t\nIndex of the animation.
Address of a reference to a string that receives the animation name.
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
Gets the index of an animation, given its name.
\t\nName of the animation.
Pointer to the animation index.
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
Gets the scale, rotation, and translation values of the animation set.
\t\nPosition of the animation set. The position can be obtained by calling
Animation index.
Pointer to the
Pointer to the
Pointer to the
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
Gets information about a specific callback in the animation set.
\t\nPosition from which to find callbacks.
Callback search flags. This parameter can be set to a combination of one or more flags from
Pointer to the position of the callback.
Address of the callback data reference.
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
Gets the animation set name.
\t\nGets the period of the animation set.
\t\nThe period is the range of time that the animation key frames are valid. For looping animations, this is the period of the loop. The time units that the key frames are specified in (for example, seconds) is determined by the application.
\t\nGets the number of animations in the animation set.
\t\nApplications use the methods of the
A mesh is an object made up of a set of polygonal faces. A mesh defines a set of vertices and a set of faces (the faces are defined in terms of the vertices and normals of the mesh).
The LPD3DXBASEMESH type is defined as a reference to the
typedef struct *LPD3DXBASEMESH;\t\n Draws a subset of a mesh.
\t\nDWORD that specifies which subset of the mesh to draw. This value is used to differentiate faces in a mesh as belonging to one or more attribute groups.
If the method succeeds, the return value is
The subset that is specified by AttribId will be rendered by the
An attribute table is used to identify areas of the mesh that need to be drawn with different textures, render states, materials, and so on. In addition, the application can use the attribute table to hide portions of a mesh by not drawing a given attribute identifier (AttribId) when drawing the frame.
\t\nRetrieves the number of faces in the mesh.
\t\nReturns the number of faces in the mesh.
Retrieves the number of vertices in the mesh.
\t\nReturns the number of vertices in the mesh.
Gets the fixed function vertex value.
\t\nReturns the flexible vertex format (FVF) codes.
This method can return 0 if the vertex format cannot be mapped directly to an FVF code. This will occur for a mesh created from a vertex declaration that doesn't have the same order and elements supported by the FVF codes.
\t\nRetrieves a declaration describing the vertices in the mesh.
\t\nArray of
If the method succeeds, the return value is
The array of elements includes the D3DDECL_END macro, which ends the declaration.
\t\nGets the number of bytes per vertex.
\t\nReturns the number of bytes per vertex.
Retrieves the mesh options enabled for this mesh at creation time.
\t\nReturns a combination of one or more of the following flags, indicating the options enabled for this mesh at creation time.
| Value | Description |
|---|---|
| Use 32-bit indices. | |
| Use the | |
| Equivalent to specifying both | |
| Use the | |
| Specifying this flag causes the vertex and index buffer of the mesh to be created with | |
| Equivalent to specifying both | |
| Use the | |
| Use the | |
| Use the | |
| Use the | |
| Use the | |
| Equivalent to specifying both | |
| Use the | |
| Use the | |
| Use the | |
| Use the | |
| Equivalent to specifying both |
?
Retrieves the device associated with the mesh.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Calling this method will increase the internal reference count on the
Clones a mesh using a flexible vertex format (FVF) code.
\t\nA combination of one or more D3DXMESH flags specifying creation options for the mesh.
Combination of FVF codes, which specifies the vertex format for the vertices in the output mesh. For the values of the codes, see
Pointer to an
Address of a reference to an
If the method succeeds, the return value is
Clones a mesh using a declarator.
\t\nA combination of one or more D3DXMESH flags specifying creation options for the mesh.
An array of
Pointer to an
Address of a reference to an
If the method succeeds, the return value is
Retrieves the vertex buffer associated with the mesh.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Retrieves the data in an index buffer.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Locks a vertex buffer and obtains a reference to the vertex buffer memory.
\t\nCombination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
VOID* reference to a buffer containing the vertex data.
If the method succeeds, the return value is
When working with vertex buffers, you are allowed to make multiple lock calls; however, you must ensure that the number of lock calls match the number of unlock calls. DrawPrimitive calls will not succeed with any outstanding lock count on any currently set vertex buffer.
\t\nUnlocks a vertex buffer.
\t\nIf the method succeeds, the return value is
Locks an index buffer and obtains a reference to the index buffer memory.
\t\nCombination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
VOID* reference to a buffer containing the index data. The count of indices in this buffer will be equal to
If the method succeeds, the return value is
When working with index buffers, you are allowed to make multiple lock calls. However, you must ensure that the number of lock calls match the number of unlock calls. DrawPrimitive calls will not succeed with any outstanding lock count on any currently set index buffer.
\t\nUnlocks an index buffer.
\t\nIf the method succeeds, the return value is
Retrieves either an attribute table for a mesh, or the number of entries stored in an attribute table for a mesh.
\t\nPointer to an array of
Pointer to either the number of entries stored in pAttribTable or a value to be filled in with the number of entries stored in the attribute table for the mesh.
If the method succeeds, the return value is
An attribute table is created by
An attribute table is used to identify areas of the mesh that need to be drawn with different textures, render states, materials, and so on. In addition, the application can use the attribute table to hide portions of a mesh by not drawing a given attribute identifier when drawing the frame.
\t\nConverts point representative data to mesh adjacency information.
\t\nPointer to an array of one DWORD per vertex of the mesh that contains point representative data. This parameter is optional. Supplying a
Pointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh. The number of bytes in this array must be at least 3 *
If the method succeeds, the return value is
Converts mesh adjacency information to an array of point representatives.
\t\nPointer to an array of three DWORDs per face that specify the three neighbors for each face in the mesh. The number of bytes in this array must be at least 3 *
Pointer to an array of one DWORD per vertex of the mesh that will be filled with point representative data.
If the method succeeds, the return value is
Generate a list of mesh edges, as well as a list of faces that share each edge.
\t\nSpecifies that vertices that differ in position by less than epsilon should be treated as coincident.
Pointer to an array of three DWORDs per face to be filled with the indices of adjacent faces. The number of bytes in this array must be at least 3 *
If the method succeeds, the return value is
After an application generates adjacency information for a mesh, the mesh data can be optimized for better drawing performance.
The order of the entries in the adjacency buffer is determined by the order of the vertex indices in the index buffer. The adjacent triangle 0 always corresponds to the edge between the indices of the corners 0 and 1. The adjacent triangle 1 always corresponds to the edge between the indices of the corners 1 and 2 while the adjacent triangle 2 corresponds to the edge between the indices of the corners 2 and 0.
\t\nThis method allows the user to change the mesh declaration without changing the data layout of the vertex buffer. The call is valid only if the old and new declaration formats have the same vertex size.
\t\nAn array of
If the method succeeds, the return value is
Gets the fixed function vertex value.
\t\nThis method can return 0 if the vertex format cannot be mapped directly to an FVF code. This will occur for a mesh created from a vertex declaration that doesn't have the same order and elements supported by the FVF codes.
\t\nGets the number of bytes per vertex.
\t\nRetrieves the mesh options enabled for this mesh at creation time.
\t\nRetrieves the device associated with the mesh.
\t\nCalling this method will increase the internal reference count on the
Retrieves the vertex buffer associated with the mesh.
\t\nRetrieves the data in an index buffer.
\t\nAn application uses the methods of this interface to implement a key frame animation set stored in a compressed data format.
\t\nCreate a compressed-format key frame animation set with
The LPD3DXCOMPRESSEDANIMATIONSET type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXCOMPRESSEDANIMATIONSET;\t\n Gets the type of the animation set playback loop.
\t\nType of the animation set playback loop. See
Gets the number of animation key frame ticks that occur per second.
\t\nNumber of animation key frame ticks that occur per second.
Gets the data buffer that stores compressed key frame animation data.
\t\nAddress of a reference to the
If the method succeeds, the return value is
Gets the number of callback keys in the animation set.
\t\nNumber of callback keys in the animation set.
Fills an array with callback key data used for key frame animation.
\t\nPointer to a user-allocated array of
If the method succeeds, the return value is
Gets the type of the animation set playback loop.
\t\nGets the number of animation key frame ticks that occur per second.
\t\nGets the data buffer that stores compressed key frame animation data.
\t\nGets the number of callback keys in the animation set.
\t\nThis is a user-implemented interface that allows a user to set the device state from an effect. Each of the methods in this interface must be implemented by the user and will then be used as callbacks to the application when either of the following occur:
When an application uses the state manager to implement custom callbacks, an effect no longer automatically saves and restores state when calling
A user creates an
The LPD3DXEFFECTSTATEMANAGER type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXEFFECTSTATEMANAGER;\t\n A callback function that must be implemented by a user to set a transform.
\t\nThe type of transform to apply the matrix to. See
A transformation matrix. See
The user-implemented method should return
A callback function that must be implemented by a user to set material state.
\t\nA reference to the material state. See
The user-implemented method should return
A callback function that must be implemented by a user to set a light.
\t\nThe zero-based index of the light. This is the same index in
The light object. See
The user-implemented method should return
A callback function that must be implemented by a user to enable/disable a light.
\t\nThe zero-based index of the light. This is the same index in
True to enable the light, false otherwise.
The user-implemented method should return
A callback function that must be implemented by a user to set render state.
\t\nThe render state to set.
The render state value. See Effect States (Direct3D 9).
The user-implemented method should return
A callback function that must be implemented by a user to set a texture.
\t\nThe stage to which the texture is assigned. This is the index value in
A reference to the texture object. This can be any of the Direct3D texture types (cube, volume, etc.). See
The user-implemented method should return
A callback function that must be implemented by a user to set the texture stage state.
\t\nThe stage that the texture is assigned to. This is the index value in
Defines the type of operation that a texture stage will perform. See
Can be either an operation (
The user-implemented method should return
A callback function that must be implemented by a user to set a sampler.
\t\nThe zero-based sampler number.
Identifies sampler state, which can specify the filtering, addressing, or the border color. See
A value from one of the sampler state types in Type.
The user-implemented method should return
A callback function that must be implemented by a user to set the number of subdivision segments for N-patches.
\t\nBreak the surface into this number of subdivisions. This is the same as the number used by
The user-implemented method should return
A callback function that must be implemented by a user to set a FVF code.
\t\nThe FVF constant, that determines how to interpret vertex data. See
The user-implemented method should return
A callback function that must be implemented by a user to set a vertex shader.
\t\nA reference to a vertex shader object. See
The user-implemented method should return
A callback function that must be implemented by a user to set an array of vertex shader floating-point constants.
\t\nThe zero-based index of the first constant register.
An array of floating-point constants.
The number of registers in pConstantData.
The user-implemented method should return
A callback function that must be implemented by a user to set an array of vertex shader integer constants.
\t\nThe zero-based index of the first constant register.
An array of integer constants.
The number of registers in pConstantData.
The user-implemented method should return
A callback function that must be implemented by a user to set an array of vertex shader Boolean constants.
\t\nThe zero-based index of the first constant register.
An array of Boolean constants.
The number of registers in pConstantData.
The user-implemented method should return
A callback function that must be implemented by a user to set a pixel shader.
\t\nA reference to a pixel shader object. See
The user-implemented method should return
A callback function that must be implemented by a user to set an array of vertex shader floating-point constants.
\t\nThe zero-based index of the first constant register.
An array of floating-point constants.
The number of registers in pConstantData.
The user-implemented method should return
A callback function that must be implemented by a user to set an array of vertex shader integer constants.
\t\nThe zero-based index of the first constant register.
An array of integer constants.
The number of registers in pConstantData.
The user-implemented method should return
A callback function that must be implemented by a user to set an array of vertex shader Boolean constants.
\t\nThe zero-based index of the first constant register.
An array of Boolean constants.
The number of registers in pConstantData.
The user-implemented method should return
A callback function that must be implemented by a user to set material state.
\t\nA callback function that must be implemented by a user to set the number of subdivision segments for N-patches.
\t\nA callback function that must be implemented by a user to set a FVF code.
\t\nA callback function that must be implemented by a user to set a vertex shader.
\t\nA callback function that must be implemented by a user to set a pixel shader.
\t\nThis interface is implemented by the application to allocate or free frame and mesh container objects. Methods on this are called during loading and destroying frame hierarchies.
\t\nThe LPD3DXALLOCATEHIERARCHY type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXALLOCATEHIERARCHY;\t\n Requests allocation of a frame object.
\t\nName of the frame to be created.
Returns the created frame object.
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
Requests allocation of a mesh container object.
\t\nName of the mesh.
Pointer to the mesh data structure. See
Array of materials used in the mesh.
Array of effect instances used in the mesh. See
Number of materials in the materials array.
Adjacency array for the mesh.
Pointer to the skin mesh object if skin data is found. See
Returns the created mesh container. See
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
Requests deallocation of a frame object.
\t\nPointer to the frame to be deallocated.
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
Requests deallocation of a mesh container object.
\t\nPointer to the mesh container object to be deallocated.
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
This interface is implemented by the application to save any additional user data embedded in .x files. An instance of this interface is passed to
The LPD3DXLOADUSERDATA type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXLOADUSERDATA;\t\n Load top level data from a .x file.
\t\nPointer to a .x file data structure. This is defined in Dxfile.h.
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
Load frame child data from a .x file.
\t\nPointer to a mesh container. See
Pointer to a .x file data structure. This is defined in Dxfile.h.
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
Load mesh child data from a .x file.
\t\nPointer to a mesh container. See
Pointer to a .x file data structure. This is defined in Dxfile.h.
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
A user creates an
The LPD3DXINCLUDE type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXINCLUDE;\t\n Applications use the methods of the
The
This interface inherits additional functionality from the
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DINDEXBUFFER9 and PDIRECT3DINDEXBUFFER9 types are defined as references to the
typedef struct *LPDIRECT3DINDEXBUFFER9, *PDIRECT3DINDEXBUFFER9;\t\n Locks a range of index data and obtains a reference to the index buffer memory.
\t\nOffset into the index data to lock, in bytes. Lock the entire index buffer by specifying 0 for both parameters, SizeToLock and OffsetToLock.
Size of the index data to lock, in bytes. Lock the entire index buffer by specifying 0 for both parameters, SizeToLock and OffsetToLock.
VOID* reference to a memory buffer containing the returned index data.
Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
If the method succeeds, the return value is
As a general rule, do not hold a lock across more than one frame. When working with index buffers, you are allowed to make multiple lock calls. However, you must ensure that the number of lock calls match the number of unlock calls.
The
See Programming Tips (Direct3D 9) for information about using
Unlocks index data.
\t\nIf the method succeeds, the return value is
Retrieves a description of the index buffer resource.
\t\nPointer to a
If the method succeeds, the return value is
Retrieves a description of the index buffer resource.
\t\nThis interface is implemented by the application to save any additional user data embedded in .x files. An instance of this interface is passed to
The LPD3DXSAVEUSERDATA type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXSAVEUSERDATA;\t\n Add child data to the frame.
\t\nPointer to a mesh container. See
Pointer to a .x file save object. Use the reference to call
Pointer to a .x file data node. Use the reference to call
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
Add child data to the mesh.
\t\nPointer to a mesh container. See
Pointer to a .x file save object. Use the reference to call
Pointer to a .x file data node. Use the reference to call
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
Add a top level object before the frame hierarchy.
\t\nPointer to a .x file save object. Use this reference to call IDirectXFileSaveObject::CreateDataObject to create the data object to be saved. Then call IDirectXFileSaveObject::SaveData to save the data.
The return values of this method are implemented by an application programmer. In general, if no error occurs, program the method to return
Add a top level object after the frame hierarchy.
\t\nPointer to a .x file save object. Use this reference to call IDirectXFileSaveObject::CreateDataObject to create the data object to be saved. Then call IDirectXFileSaveObject::SaveData to save the data.
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
A callback for the user to register a .x file template.
\t\nUse this reference to register user-defined .x file templates. See
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
A callback for the user to save a .x file template.
\t\nPointer to a .x file save object. Do not use this parameter to add data objects. See
The return values of this method are implemented by an application programmer.In general, if no error occurs, program the method to return
An application uses the methods of this interface to implement a key frame animation set.
\t\nCreate a keyframed animation set with
The LPD3DXKEYFRAMEDANIMATIONSET type is defined as a reference to this interface.
typedef interface ;\t\n typedef interface *LPD3DXKEYFRAMEDANIMATIONSET;\t\n Gets the type of the animation set playback loop.
\t\nType of the animation set playback loop. See
Gets the number of animation key frame ticks that occur per second.
\t\nNumber of animation key frame ticks that occur per second.
Gets the number of scale keys in the specified key frame animation.
\t\nAnimation index.
Number of scale keys in the specified key frame animation.
Fills an array with scale key data used for key frame animation.
\t\nAnimation index.
Pointer to a user-allocated array of
If the method succeeds, the return value is
Get scale information for a specific key frame in the animation set.
\t\nAnimation index.
Key frame.
Pointer to the scale data. See
If the method succeeds, the return value is
Set scale information for a specific key frame in the animation set.
\t\nAnimation index.
Key frame.
Pointer to the scale data. See
If the method succeeds, the return value is
Gets the number of rotation keys in the specified key frame animation.
\t\nAnimation index.
Number of rotation keys in the specified key frame animation.
Fills an array with rotational key data used for key frame animation.
\t\nAnimation index.
Pointer to a user-allocated array of
If the method succeeds, the return value is
Get rotation information for a specific key frame in the animation set.
\t\nAnimation index.
Key frame.
Pointer to the rotation data. See
If the method succeeds, the return value is
Set rotation information for a specific key frame in the animation set.
\t\nAnimation index.
Key frame.
Pointer to the rotation data. See
If the method succeeds, the return value is
Gets the number of translation keys in the specified key frame animation.
\t\nAnimation index.
Number of translation keys in the specified key frame animation.
Fills an array with translational key data used for key frame animation.
\t\nAnimation index.
Pointer to a user-allocated array of
If the method succeeds, the return value is
Get translation information for a specific key frame in the animation set.
\t\nAnimation index.
Key Frame.
Pointer to the rotation information. See
If the method succeeds, the return value is
Set translation information for a specific key frame in the animation set.
\t\nAnimation index.
Key Frame.
Pointer to the translation data. See
If the method succeeds, the return value is
Gets the number of callback keys in the animation set.
\t\nNumber of callback keys in the animation set.
Fills an array with callback key data used for key frame animation.
\t\nPointer to a user-allocated array of
If the method succeeds, the return value is
Gets information about a specific callback in the animation set.
\t\nAnimation index.
Pointer to the callback function.
If the method succeeds, the return value is
Sets information about a specific callback in the animation set.
\t\nAnimation index.
Pointer to the callback function.
If the method succeeds, the return value is
Removes the scale data at the specified key frame.
\t\nAnimation identifier.
Key frame.
If the method succeeds, the return value is
This method is slow and should not be used after an animation has begun to play.
\t\nRemoves the rotation data at the specified key frame.
\t\nAnimation identifier.
Key frame.
If the method succeeds, the return value is
This method is slow and should not be used after an animation has begun to play.
\t\nRemoves the translation data at the specified key frame.
\t\nAnimation identifier.
Key frame.
If the method succeeds, the return value is
This method is slow and should not be used after an animation has begun to play.
\t\nRegister the scale, rotate, and translate (SRT) key frame data for an animation.
\t\nPointer to the animation name.
Number of scale keys.
Number of rotation keys.
Number of translation keys.
Address of a reference to a user-allocated array of
Address of a reference to a user-allocated array of
Address of a reference to a user-allocated array of
Returns the animation index.
If the method succeeds, the return value is
Transforms animations in an animation set into a compressed format and returns a reference to the buffer that stores the compressed data.
\t\nOne of the
Desired compression loss ratio, in the range from 0 to 1.
Pointer to a
Address of a reference to the
If the method succeeds, the return value is
Remove the animation data from the animation set.
\t\nThe animation index.
If the method succeeds, the return value is
Gets the type of the animation set playback loop.
\t\nGets the number of animation key frame ticks that occur per second.
\t\nGets the number of callback keys in the animation set.
\t\nThe
Create a line drawing object with
The LPD3DXLINE type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DXLINE;\t\n Retrieves the Direct3D device associated with the line object.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Prepares a device for drawing lines.
\t\nIf the method succeeds, the return value is
Calling
This method must be called from inside an
Draws a line strip in screen space. Input is in the form of an array that defines points (of
If the method succeeds, the return value is
Draws a line strip in screen space with a specified input transformation matrix.
\t\nArray of vertices that make up the line. See
Number of vertices in the vertex list.
A scale, rotate, and translate (SRT) matrix for transforming the points. See
Color of the line. See
If the method succeeds, the return value is
Applies a stipple pattern to the line.
\t\nDescribes the stipple pattern: 1 is opaque, 0 is transparent.
If the method succeeds, the return value is
Gets the line stipple pattern.
\t\nReturns the line stipple pattern: 1 is opaque, 0 is transparent.
Stretches the stipple pattern along the line direction.
\t\nStipple pattern scaling value. 1.0f is the default value and represents no scaling. A value less than 1.0f shrinks the pattern, and a value greater than 1.0 stretches the pattern.
If the method succeeds, the return value is
Gets the stipple-pattern scale value.
\t\nReturns the value used to scale the stipple-pattern. 1.0f is the default value and represents no scaling. A value less than 1.0f shrinks the pattern, and a value greater than 1.0 stretches the pattern.
Specifies the thickness of the line.
\t\nDescribes the line width.
If the method succeeds, the return value is
Gets the thickness of the line.
\t\nThe line thickness.
Toggles line antialiasing.
\t\nToggles antialiasing on and off. TRUE turns antialiasing on, and
If the method succeeds, the return value is
Gets the line antialiasing state.
\t\nReturns the antialiasing switch value. TRUE means antialiasing is on, and
Toggles the mode to draw OpenGL-style lines.
\t\nToggles OpenGL-style line drawing. TRUE enables OpenGL-style lines, and
If the method succeeds, the return value is
Gets the OpenGL-style line-drawing mode.
\t\nReturns TRUE if OpenGL-style lines are enabled, and
Restores the device state to how it was when
If the method succeeds, the return value is
Use this method to release all references to video memory resources and delete all stateblocks. This method should be called whenever a device is lost, or before resetting a device.
\t\nIf the method succeeds, the return value is
This method should be called whenever the device is lost or before the user calls
Use this method to re-acquire resources and save initial state.
\t\nIf the method succeeds, the return value is
Retrieves the Direct3D device associated with the line object.
\t\nGets or sets the line stipple pattern.
\t\nGets or sets the stipple-pattern scale value.
\t\nGets or sets the thickness of the line.
\t\nGets or sets the line antialiasing state.
\t\nGets or sets the OpenGL-style line-drawing mode.
\t\nApplications use the methods of the
To obtain the
This interface inherits additional functionality from the
The LPD3DXMESH type is defined as a reference to the
typedef struct *LPD3DXMESH;\t\n Locks the mesh buffer that contains the mesh attribute data, and returns a reference to it.
\t\nCombination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
Address of a reference to a buffer containing a DWORD for each face in the mesh.
If the method succeeds, the return value is
If
Unlocks an attribute buffer.
\t\nIf the method succeeds, the return value is
Generates a new mesh with reordered faces and vertices to optimize drawing performance.
\t\nSpecifies the type of optimization to perform. This parameter can be set to a combination of one or more flags from D3DXMESHOPT and D3DXMESH (except
Pointer to an array of three DWORDs per face that specifies the three neighbors for each face in the source mesh. If the edge has no adjacent faces, the value is 0xffffffff. See Remarks.
Pointer to an array of three DWORDs per face that specifies the three neighbors for each face in the optimized mesh. If the edge has no adjacent faces, the value is 0xffffffff.
An array of DWORDs, one per face, that identifies the original mesh face that corresponds to each face in the optimized mesh. If the value supplied for this argument is
Address of a reference to an
Address of a reference to an
If the method succeeds, the return value is
This method generates a new mesh. Before running Optimize, an application must generate an adjacency buffer by calling
This method is very similar to the
Generates a mesh with reordered faces and vertices to optimize drawing performance. This method reorders the existing mesh.
\t\nCombination of one or more D3DXMESHOPT flags, specifying the type of optimization to perform.
Pointer to an array of three DWORDs per face that specifies the three neighbors for each face in the source mesh. If the edge has no adjacent faces, the value is 0xffffffff.
Pointer to an array of three DWORDs per face that specifies the three neighbors for each face in the optimized mesh. If the edge has no adjacent faces, the value is 0xffffffff. If the value supplied for this argument is
An array of DWORDs, one per face, that identifies the original mesh face that corresponds to each face in the optimized mesh. If the value supplied for this argument is
Address of a reference to an
If the method succeeds, the return value is
Before running
Note??This method will fail if the mesh is sharing its vertex buffer with another mesh, unless the
Sets the attribute table for a mesh and the number of entries stored in the table.
\t\nPointer to an array of
Number of attributes in the mesh attribute table.
If the method succeeds, the return value is
If an application keeps track of the information in an attribute table, and rearranges the table as a result of changes to attributes or faces, this method allows the application to update the attribute tables instead of calling
This interface encapsulates patch mesh functionality.
\t\nA patch mesh is a mesh that consists of a series of patches.
To obtain the
The LPD3DXPATCHMESH type is defined as a reference to the
typedef struct *LPD3DXPATCHMESH;\t\n Gets the number of patches in the mesh.
\t\nThe number of patches.
Gets the number of vertices in the mesh.
\t\nThe number of vertices.
Gets the vertex declaration.
\t\nArray of
If the method succeeds, the return value is
The array of elements includes the D3DDECL_END macro, which ends the declaration.
\t\nGets the number of control vertices per patch.
\t\nThe number of control vertices per patch.
Gets the type of patch.
\t\nThe patch type.
For more information about patch types, see
Gets the device that created the mesh.
\t\nPointer to the device.
If the method succeeds, the return value is
Gets the attributes of the patch.
\t\nPointer to the structures containing the patch attributes. For more information about patch attributes, see
If the method succeeds, the return value is
Gets the mesh vertex buffer.
\t\nPointer to the vertex buffer.
If the method succeeds, the return value is
This method assumes uniform tessellation.
\t\nGets the mesh index buffer.
\t\nPointer to the index buffer.
If the method succeeds, the return value is
The index buffer contains the vertex ordering in the vertex buffer. The index buffer is used to access the vertex buffer when the mesh is rendered.
\t\nLock the vertex buffer.
\t\nCombination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
VOID* reference to a memory buffer containing the returned vertex data.
If the method succeeds, the return value is
The vertex buffer is usually locked, written to, and then unlocked for reading.
Patch meshes use 16-bit index buffers.
\t\nUnlock the vertex buffer.
\t\nIf the method succeeds, the return value is
The vertex buffer is usually locked, written to, and then unlocked for reading.
\t\nLock the index buffer.
\t\nCombination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
VOID* reference to a memory buffer containing the returned index data.
If the method succeeds, the return value is
The index buffer is usually locked, written to, and then unlocked for reading. Patch mesh index buffers are 16-bit buffers.
\t\nUnlock the index buffer.
\t\nIf the method succeeds, the return value is
The index buffer is usually locked, written to, and then unlocked for reading.
\t\nLocks the attribute buffer.
\t\nCombination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
Address of a reference to a buffer containing a DWORD for each face in the mesh.
If the method succeeds, the return value is
The attribute buffer is usually locked, written to, and then unlocked for reading.
\t\nUnlock the attribute buffer.
\t\nIf the method succeeds, the return value is
The attribute buffer is usually locked, written to, and then unlocked for reading.
\t\nGets the size of the tessellated mesh, given a tessellation level.
\t\nTessellation level.
Adaptive tessellation. For adaptive tessellation, set this value to TRUE and set fTessLevel to the maximum tessellation value. This will result in the maximum mesh size necessary for adaptive tessellation.
Pointer to the number of triangles generated by the tessellated mesh.
Pointer to the number of vertices generated by the tessellated mesh.
If the method succeeds, the return value is
This method assumes uniform tessellation.
\t\nGenerate a list of mesh edges and the patches that share each edge.
\t\nSpecifies that vertices that differ in position by less than the tolerance should be treated as coincident.
If the method succeeds, the return value is
After an application generates adjacency information for a mesh, the mesh data can be optimized for better drawing performance. This method determines which patches are adjacent (within the provided tolerance). This information is used internally to optimize tessellation.
\t\nCreates a new patch mesh with the specified vertex declaration.
\t\nCombination of one or more D3DXMESH flags that specify creation options for the mesh.
Array of
Address of a reference to an
If the method succeeds, the return value is
CloneMesh converts the vertex buffer to the new vertex declaration. Entries in the vertex declaration that are new to the original mesh are set to 0. If the current mesh has adjacency, the new mesh will also have adjacency.
\t\nOptimizes the patch mesh for efficient tessellation.
\t\nCurrently unused.
If the method succeeds, the return value is
After an application generates adjacency information for a mesh, the mesh data can be optimized (reordered) for better drawing performance. This method determines which patches are adjacent (within the provided tolerance).
Adjacency information is also used to optimize tessellation. Generate adjacency information once and tessellate repeatedly by calling
Sets mesh geometry displacement parameters.
\t\nTexture containing the displacement data.
Minification level. For more information, see
Magnification level. For more information, see
Mip filter level. For more information, see
Texture address wrap mode. For more information, see
Level of detail bias value.
If the method succeeds, the return value is
Displacement maps can only be 2D textures. Mipmapping is ignored for nonadaptive tessellation.
\t\nGets mesh geometry displacement parameters.
\t\nTexture containing the displacement data.
Minification level. For more information, see
Magnification level. For more information, see
Mip filter level. For more information, see
Texture address wrap mode. For more information, see
Level of detail bias value.
If the method succeeds, the return value is
Displacement maps can only be 2D textures. Mipmapping is ignored for nonadaptive tessellation.
\t\nPerforms uniform tessellation based on the tessellation level.
\t\nTessellation level. This is the number of vertices introduced between existing vertices. The range of this float parameter is 0 < fTessLevel <= 32.
Resulting tessellated mesh. See
If the method succeeds, the return value is
This function will perform more efficiently if the patch mesh has been optimized using
Performs adaptive tessellation based on the z-based adaptive tessellation criterion.
\t\nSpecifies a 4D vector that is dotted with the vertices to get the per-vertex adaptive tessellation amount. Each edge is tessellated to the average value of the tessellation levels for the two vertices it connects.
Maximum limit for adaptive tessellation. This is the number of vertices introduced between existing vertices. This integer value can range from 1 to 32, inclusive.
Minimum limit for adaptive tessellation. This is the number of vertices introduced between existing vertices. This integer value can range from 1 to 32, inclusive.
Resulting tessellated mesh. See
If the method succeeds, the return value is
This function will perform more efficiently if the patch mesh has been optimized using
Gets the number of patches in the mesh.
\t\nGets the number of vertices in the mesh.
\t\nGets the number of control vertices per patch.
\t\nGets the type of patch.
\t\nFor more information about patch types, see
Gets the device that created the mesh.
\t\nGets the mesh vertex buffer.
\t\nThis method assumes uniform tessellation.
\t\nGets the mesh index buffer.
\t\nThe index buffer contains the vertex ordering in the vertex buffer. The index buffer is used to access the vertex buffer when the mesh is rendered.
\t\nApplications use the methods of the
The LPDIRECT3DPIXELSHADER9 and PDIRECT3DPIXELSHADER9 types are defined as references to the
typedef struct *LPDIRECT3DPIXELSHADER9, *PDIRECT3DPIXELSHADER9; Gets the device.
\t\nPointer to the
If the method succeeds, the return value is
Gets a reference to the shader data.
\t\nPointer to a buffer that contains the shader data. The application needs to allocate enough room for this.
Size of the data, in bytes. To get the buffer size that is needed to retrieve the data, set pData =
If the method succeeds, the return value is
Gets the device.
\t\nApplications use the methods of the
The LPDIRECT3DQUERY9 and PDIRECT3DQUERY9 types are defined as references to the
typedef struct *LPDIRECT3DQUERY9, *PDIRECT3DQUERY9; Gets the device that is being queried.
\t\nPointer to the device being queried. See
If the method succeeds, the return value is
Gets the query type.
\t\nReturns the query type. See
Gets the number of bytes in the query data.
\t\nReturns the number of bytes of query data.
Issue a query.
\t\nQuery flags specify the type of state change for the query. See
If the method succeeds, the return value is
A signaled query means the query has completed, the data is available, and
Polls a queried resource to get the query state or a query result. For more information about queries, see Queries (Direct3D 9).
\t\nThe return type identifies the query state (see Queries (Direct3D 9)). The method returns
It is possible to lose the device while polling for query status. When D3DGETDATA_FLUSH is specified, this method will return
An application must never write code that only invokes GetData ( ... , 0 ), expecting that GetData will eventually return
// Enables an infinite loop:\t\n while( pQuery->GetData( ... , 0 ) == S_FALSE ) ; // Still enables an infinite loop:\t\n pQuery->GetData( ... , D3DGETDATA_FLUSH );\t\n while( pQuery->GetData( ... , 0 ) == S_FALSE ) ; // Does not enable an infinite loop because eventually the command\t\n // buffer will fill up and that will cause a flush to occur.\t\n while( pQuery->GetData( ..., 0 ) == S_FALSE ) { pDevice->SetTexture(...); pDevice->Draw(...);\t\n }\t\n Gets the device that is being queried.
\t\nGets the number of bytes in the query data.
\t\nThe
An environment map is used to texture-map scene geometry to provide a more sophisticated scene without using complex geometry. This interface supports creating surfaces for the following kinds of geometry: cube, half sphere or hemispheric, parabolic, or sphere.
The
The LPD3DXRenderToEnvMap type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DXRenderToEnvMap;\t\n Retrieves the Direct3D device associated with the environment map.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Retrieves the description of the render surface.
\t\nPointer to a
If the method succeeds, the return value is
Initiate the rendering of a cubic environment map.
\t\nPointer to an
If the method succeeds, the return value is
See
Initiate the rendering of a spherical environment map.
\t\nPointer to an
If the method succeeds, the return value is
See
Initiate the rendering of a hemispheric environment map.
\t\nPointer to an
Pointer to an
If the method succeeds, the return value is
See
Initiate the rendering of a parabolic environment map.
\t\nPointer to an
Pointer to an
If the function succeeds, the return value is
See
Initiate the drawing of each face of an environment map.
\t\nThe first face of the environmental cube map. See
A valid combination of one or more
If the method succeeds, the return value is
This method must be called once for each type of environment map. The only exception is a cubic environment map which requires this method to be called six times, once for each face in
Restore all render targets and, if needed, compose all the rendered faces into the environment map surface.
\t\nA valid combination of one or more
If the method succeeds, the return value is
Use this method to release all references to video memory resources and delete all stateblocks. This method should be called whenever a device is lost, or before resetting a device.
\t\nIf the method succeeds, the return value is
This method should be called whenever the device is lost or before the user calls
Use this method to re-acquire resources and save initial state.
\t\nIf the method succeeds, the return value is
Retrieves the Direct3D device associated with the environment map.
\t\nRetrieves the description of the render surface.
\t\nThe
Surfaces can be used in a variety of ways including render targets, off-screen rendering, or rendering to textures.
A surface can be configured using a separate viewport using the
The
The LPD3DXRENDERTOSURFACE type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DXRENDERTOSURFACE;\t\n Retrieves the Direct3D device associated with the render surface.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Retrieves the parameters of the render surface.
\t\nPointer to a
If the method succeeds, the return value is
Begins a scene.
\t\nPointer to an
Pointer to a
If the method succeeds, the return value is
Ends a scene.
\t\nFilter options, enumerated in
If the method succeeds, the return value is
Use this method to release all references to video memory resources and delete all stateblocks. This method should be called whenever a device is lost or before resetting a device.
\t\nIf the method succeeds, the return value is
This method should be called whenever the device is lost or before the user calls
Use this method to re-acquire resources and save initial state.
\t\nIf the method succeeds, the return value is
Pointer to an
Width of the render surface, in pixels.
Height of the render surface, in pixels.
Member of the
If TRUE, the render surface supports a depth-stencil surface. Otherwise, this member is set to
If DepthStencil is set to TRUE, this parameter is a member of the
Retrieves the Direct3D device associated with the render surface.
\t\nRetrieves the parameters of the render surface.
\t\nApplications use the methods of the
Create a
The LPD3DXSKININFO type is defined as a reference to the
typedef struct *LPD3DXSKININFO;\t\n Sets the influence value for a bone.
\t\nBone number.
Number of influences.
The array of vertices influenced by a bone.
The array of weights influenced by a bone.
If the method succeeds, the return value is
Sets an influence value of a bone on a single vertex.
\t\nIndex of the bone. Must be between 0 and the number of bones.
Index of the influence array of the specified bone.
Blend factor of the specified bone influence.
If the method succeeds, the return value is
Gets the number of influences for a bone.
\t\nBone number.
Returns the number of influences for a bone.
Gets the vertices and weights that a bone influences.
\t\nBone number.
Get the array of vertices influenced by a bone.
Get the array of weights influenced by a bone.
If the method succeeds, the return value is
Use
Retrieves the blend factor and vertex affected by a specified bone influence.
\t\nIndex of the bone. Must be between 0 and the number of bones.
Index of the influence array of the specified bone.
Pointer to the blend factor influenced by influenceNum.
Pointer to the vertex influenced by influenceNum.
If the method succeeds, the return value is
Gets the maximum number of influences for any vertex in the mesh.
\t\nPointer to the maximum vertex influence.
If the method succeeds, the return value is
Gets the number of bones.
\t\nReturns the number of bones.
Retrieves the index of the bone influence affecting a single vertex.
\t\nIndex of the bone. Must be between 0 and the number of bones.
Index of the vertex for which the bone influence is to be found. Must be between 0 and the number of vertices in the mesh.
Pointer to the index of the bone influence that affects vertexNum.
If the method succeeds, the return value is
Gets the maximum face influences in a triangle mesh with the specified index buffer.
\t\nPointer to the index buffer that contains the mesh index data.
Number of faces in the mesh.
Pointer to the maximum face influences.
If the method succeeds, the return value is
Sets the minimum bone influence. Influence values smaller than this are ignored.
\t\nMinimum influence value. Influence values smaller than this are ignored.
If the method succeeds, the return value is
Gets the minimum bone influence. Influence values smaller than this are ignored.
\t\nReturns the minimum bone influence value.
Sets the bone name.
\t\nBone number
Bone name
If the method succeeds, the return value is
Bone names are returned by
Gets the bone name, from the bone index.
\t\nBone number.
Returns the bone name. Do not free this string.
Sets the bone offset matrix.
\t\nBone number.
Pointer to the bone offset matrix.
If the method succeeds, the return value is
Bone names are returned by
Gets the bone offset matrix.
\t\nBone number.
Returns a reference to the bone offset matrix. Do not free this reference.
Clones a skin info object.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Updates bone influence information to match vertices after they are reordered. This method should be called if the target vertex buffer has been reordered externally.
\t\nNumber of vertices to remap.
Array of DWORDS whose length is specified by NumVertices.
If the method succeeds, the return value is
Each element in pVertexRemap specifies the previous vertex index for that position. For example, if a vertex was in position 3 but has been remapped to position 5, then the fifth element of pVertexRemap should contain 3. The vertex remap array returned by
Sets the flexible vertex format (FVF) type.
\t\nFlexible vertex format. See
If the method succeeds, the return value is
Sets the vertex declaration.
\t\nPointer to an array of
If the method succeeds, the return value is
Gets the fixed function vertex value.
\t\nReturns the flexible vertex format (FVF) codes.
This method can return 0 if the vertex format cannot be mapped directly to an FVF code. This will occur for a mesh created from a vertex declaration that doesn't have the same order and elements supported by the FVF codes.
\t\nGets the vertex declaration.
\t\nArray of
If the method succeeds, the return value is
The array of elements includes the D3DDECL_END macro, which ends the declaration.
\t\nApplies software skinning to the target vertices based on the current matrices.
\t\nBone transform matrix.
Inverse transpose of the bone transform matrix.
Pointer to the buffer containing the source vertices.
Pointer to the buffer containing the destination vertices.
If the method succeeds, the return value is
When used to skin vertices with two position elements, this method skins the second position element with the inverse of the bone instead of the bone itself.
\t\nTakes a mesh and returns a new mesh with per-vertex blend weights and a bone combination table. The table describes which bones affect which subsets of the mesh.
\t\nInput mesh. See
Currently unused.
Input mesh adjacency information.
Output mesh adjacency information.
An array of DWORDs, one per face, that identifies the original mesh face that corresponds to each face in the blended mesh. If the value supplied for this argument is
Address of a reference to an
Pointer to a DWORD that will contain the maximum number of bone influences required per vertex for this skinning method.
Pointer to the number of bones in the bone combination table.
Pointer to the bone combination table. The data is organized in a
Pointer to the new mesh.
If the method succeeds, the return value is
Each element in the remap array specifies the previous index for that position. For example, if a vertex was in position 3 but has been remapped to position 5, then the fifth element of pVertexRemap will contain 3.
This method does not run on hardware that does not support fixed-function vertex blending.
\t\nTakes a mesh and returns a new mesh with per-vertex blend weights, indices, and a bone combination table. The table describes which bone palettes affect which subsets of the mesh.
\t\nThe input mesh. See
Currently unused.
Number of bone matrices available for matrix palette skinning.
Input mesh adjacency information.
Output mesh adjacency information.
An array of DWORDs, one per face, that identifies the original mesh face that corresponds to each face in the blended mesh. If the value supplied for this argument is
Address of a reference to an
Pointer to a DWORD that will contain the maximum number of bone influences required per vertex for this skinning method.
Pointer to the number of bones in the bone combination table.
Pointer to the bone combination table. The data is organized in a
Pointer to the new mesh.
If the method succeeds, the return value is
Each element in the remap arrays specifies the previous index for that position. For example, if a vertex was in position 3 but has been remapped to position 5, then the fifth element of pVertexRemap will contain 3.
This method does not run on hardware that does not support fixed-function vertex blending.
\t\nGets the maximum number of influences for any vertex in the mesh.
\t\nGets the number of bones.
\t\nGets or sets the minimum bone influence. Influence values smaller than this are ignored.
\t\nGets or sets the fixed function vertex value.
\t\nThis method can return 0 if the vertex format cannot be mapped directly to an FVF code. This will occur for a mesh created from a vertex declaration that doesn't have the same order and elements supported by the FVF codes.
\t\nThe
The
The application typically first calls
The LPD3DXSPRITE type is defined as a reference to the
typedef interface ;\t\n typedef interface *LPD3DXSPRITE;\t\n Retrieves the device associated with the sprite object.
\t\nAddress of a reference to an
If the method succeeds, the return value is
Calling this method will increase the internal reference count on the
Gets the sprite transform.
\t\nPointer to a
If the method succeeds, the return value is
Sets the sprite transform.
\t\nPointer to a
If the method succeeds, the return value is
Sets the right-handed world-view transform for a sprite. A call to this method is required before billboarding or sorting sprites.
\t\nPointer to a
Pointer to a
If the method succeeds, the return value is
A call to this method (or to
Sets the left-handed world-view transform for a sprite. A call to this method is required before billboarding or sorting sprites.
\t\nPointer to a
Pointer to a
If the method succeeds, the return value is
A call to this method (or to
Prepares a device for drawing sprites.
\t\nCombination of zero or more flags that describe sprite rendering options. For this method, the valid flags are:
For a description of the flags and for information on how to control device state capture and device view transforms, see
If the method succeeds, the return value is
This method must be called from inside a
This method will set the following states on the device.
Render States:
| Type ( | Value |
|---|---|
| TRUE | |
| 0x00 | |
| AlphaCmpCaps | |
| TRUE | |
| 0 |
?
Texture Stage States:
| Stage Identifier | Type ( | Value |
|---|---|---|
| 0 | ||
| 0 | ||
| 0 | ||
| 0 | ||
| 0 | ||
| 0 | ||
| 0 | 0 | |
| 0 | ||
| 1 | ||
| 1 |
?
Sampler States:
| Sampler Stage Index | Type ( | Value |
|---|---|---|
| 0 | ||
| 0 | ||
| 0 | ||
| 0 | 0 | |
| 0 | MaxAnisotropy | |
| 0 | ||
| 0 | ||
| 0 | 0 | |
| 0 | 0 |
?
Note??This method disables N-patches.
\t\nAdds a sprite to the list of batched sprites.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to a
If the method succeeds, the return value is
To scale, rotate, or translate a sprite, call
Forces all batched sprites to be submitted to the device. Device states remain as they were after the last call to
If the method succeeds, the return value is
Calls
If the method succeeds, the return value is
Use this method to release all references to video memory resources and delete all stateblocks. This method should be called whenever a device is lost or before resetting a device.
\t\nIf the method succeeds, the return value is
This method should be called whenever the device is lost or before the user calls
Use this method to re-acquire resources and save initial state.
\t\nIf the method succeeds, the return value is
Adds a sprite to the list of batched sprites.
\t\nPointer to an
If the method succeeds, the return value is
To scale, rotate, or translate a sprite, call
Adds a sprite to the list of batched sprites.
\t\nPointer to an
Pointer to a
Pointer to a
Pointer to a
If the method succeeds, the return value is
To scale, rotate, or translate a sprite, call
Retrieves the device associated with the sprite object.
\t\nCalling this method will increase the internal reference count on the
Gets or sets the sprite transform.
\t\nApplications use the methods of the
This interface can be used to save and restore pipeline state. It can also be used to capture the current state.
The LPDIRECT3DSTATEBLOCK9 and PDIRECT3DSTATEBLOCK9 types are defined as references to the
typedef struct *LPDIRECT3DSTATEBLOCK9, *PDIRECT3DSTATEBLOCK9; Gets the device.
\t\nPointer to the
If the method succeeds, the return value is
Capture the current value of states that are included in a stateblock.
\t\nIf the method succeeds, the return value is
The Capture method captures current values for states within an existing state block. It does not capture the entire state of the device. For example:
* pStateBlock = null ; pd3dDevice->BeginStateBlock();\t\n // Add the ZENABLE state to the stateblock \t\n pd3dDevice->SetRenderState ( , );\t\n pd3dDevice->EndStateBlock ( &pStateBlock ); // Change the current value that is stored in the state block\t\n pd3dDevice->SetRenderState ( , );\t\n pStateBlock->Capture();\t\t\t pStateBlock->Release();\t\n Creating an empty stateblock and calling the Capture method does nothing if no states have been set.
The Capture method will not capture information for lights that are explicitly or implicitly created after the stateblock is created.
\t\nApply the state block to the current device state.
\t\nIf the method succeeds, the return value is
Gets the device.
\t\nApplications use the methods of the
The LPDIRECT3DSURFACE9 and PDIRECT3DSURFACE9 types are defined as references to the
typedef struct *LPDIRECT3DSURFACE9, *PDIRECT3DSURFACE9;\t\n Provides access to the parent cube texture or texture (mipmap) object, if this surface is a child level of a cube texture or a mipmap. This method can also provide access to the parent swap chain if the surface is a back-buffer child.
\t\nReference identifier of the container being requested.
Address of a reference to fill with the container reference if the query succeeds. See Remarks.
If the method succeeds, the return value is
If the surface is created using CreateRenderTarget or CreateOffscreenPlainSurface or CreateDepthStencilSurface, the surface is considered stand alone. In this case, GetContainer will return the Direct3D device used to create the surface.
If the call succeeds, the reference count of the container is increased by one.
Here's an example getting the parent texture of a mip surface.
// Assumes pSurface is a valid reference\t\n void *pContainer = null ;\t\n *pTexture = null ;\t\n hr = pSurface->GetContainer(IID_IDirect3DTexture9, &pContainer);\t\n if (SUCCEEDED(hr) && pContainer)\t\n { pTexture = ( *)pContainer;\t\n }\t\n Retrieves a description of the surface.
\t\nPointer to a
If the method succeeds, the return value is
Locks a rectangle on a surface.
\t\nPointer to a
Pointer to a rectangle to lock. Specified by a reference to a
Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
You may not specify a subrect when using
If the method succeeds, the return value is
If the method fails, the return value can be
If the
The only lockable format for a depth-stencil surface is
For performance reasons, dirty regions are recorded only for level zero of a texture. Dirty regions are automatically recorded when
A multisample back buffer cannot be locked.
This method cannot retrieve data from a surface that is is contained by a texture resource created with
Unlocks a rectangle on a surface.
\t\nIf the method succeeds, the return value is
Retrieves a device context.
\t\nPointer to the device context for the surface.
The following restrictions apply.
When a device context is outstanding on a surface, the application may not call these methods:
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| |
?
* (on a swap chain that contains the surface)
It is valid to call
The hdc provides access to Win32 and GDI functionality.
\t\nRelease a device context handle.
\t\nHandle to a device context.
If the method succeeds, the return value is
An hdc is a Windows resource. It must be released after use so Windows can return it to the pool of available resources.
This method will release only the device context returned by
Retrieves a description of the surface.
\t\nApplications use the methods of the
There is always at least one swap chain for each device, known as the implicit swap chain. However, an additional swap chain for rendering multiple views from the same device can be created by calling the
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DSWAPCHAIN9 and PDIRECT3DSWAPCHAIN9 types are defined as references to the
typedef struct *LPDIRECT3DSWAPCHAIN9, *PDIRECT3DSWAPCHAIN9;\t\n Note the application should ensure that its associated device window is visible when its swapchain(s) is in fullscreen mode. Invisible windows cannot receive user mode events and invisible fullscreen windows will interfere with other windowed mode applications' presentation.
\t\nPresents the contents of the next buffer in the sequence of back buffers owned by the swap chain.
\t\nPointer to the source rectangle (see
Pointer to the destination rectangle in client coordinates (see
Destination window whose client area is taken as the target for this presentation. If this value is
This value must be
Allows the application to request that the method return immediately when the driver reports that it cannot schedule a presentation. Valid values are 0, or any combination of
If the method succeeds, the return value is
The Present method is a shortcut to Present. Present has been updated to take a flag allowing the application to request that the method return immediately when the driver reports that it cannot schedule a presentation.
If necessary, a stretch operation is applied to transfer the pixels within the source rectangle to the destination rectangle in the client area of the target window.
Present will fail if called between BeginScene and EndScene pairs unless the render target is not the current render target (such as the back buffer you get from creating an additional swap chain). This is a new behavior for Direct3D 9.
\t\nGenerates a copy of the swapchain's front buffer and places that copy in a system memory buffer provided by the application.
\t\nPointer to an
If the method succeeds, the return value is
Calling this method will increase the internal reference count on the
Retrieves a back buffer from the swap chain of the device.
\t\nIndex of the back buffer object to return. Back buffers are numbered from 0 to the total number of back buffers - 1. A value of 0 returns the first back buffer, not the front buffer. The front buffer is not accessible through this method. Use
Stereo view is not supported in Direct3D 9, so the only valid value for this parameter is
Address of a reference to an
Calling this method will increase the internal reference count on the
Returns information describing the raster of the monitor on which the swap chain is presented.
\t\nPointer to a
If the method succeeds, the return value is
Retrieves the display mode's spatial resolution, color resolution, and refresh frequency.
\t\nPointer to a
If the method succeeds, the return value is
Retrieves the device associated with the swap chain.
\t\nAddress of a reference to an
If the method succeeds, the return value is
This method allows navigation to the owning device object.
Calling this method will increase the internal reference count on the
Retrieves the presentation parameters associated with a swap chain.
\t\nPointer to the presentation parameters. See
If the method succeeds, the return value is
This method can be used to see the presentation parameters of the parent swap chain of a surface (a back buffer, for instance). The parent swap chain can be retrieved with
Returns information describing the raster of the monitor on which the swap chain is presented.
\t\nRetrieves the display mode's spatial resolution, color resolution, and refresh frequency.
\t\nRetrieves the device associated with the swap chain.
\t\nThis method allows navigation to the owning device object.
Calling this method will increase the internal reference count on the
Retrieves the presentation parameters associated with a swap chain.
\t\nThis method can be used to see the presentation parameters of the parent swap chain of a surface (a back buffer, for instance). The parent swap chain can be retrieved with
Applications use the methods of the
There is always at least one swap chain for each device, known as the implicit swap chain. However, an additional swap chain for rendering multiple views from the same device can be created by calling the CreateAdditionalSwapChain method.
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DSWAPCHAIN9 and PDIRECT3DSWAPCHAIN9 types are defined as references to the
Returns the number of times the swapchain has been processed.
\t\nPointer to a UINT to be filled with the number of times the
Retrieves the display mode's spatial resolution, color resolution, refresh frequency, and rotation settings.
\t\nPointer to a
Pointer to a
If the method succeeds, the return value is
Returns the number of times the swapchain has been processed.
\t\nApplications use the methods of the
The
This interface inherits additional functionality from the
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DTEXTURE9 and PDIRECT3DTEXTURE9 types are defined as references to the
typedef struct *LPDIRECT3DTEXTURE9, *PDIRECT3DTEXTURE9;\t\n Retrieves a level description of a texture resource.
\t\nIdentifies a level of the texture resource. This method returns a surface description for the level specified by this parameter.
Pointer to a
Retrieves the specified texture surface level.
\t\nIdentifies a level of the texture resource. This method returns a surface for the level specified by this parameter. The top-level surface is denoted by 0.
Address of a reference to an
Calling this method will increase the internal reference count on the
Locks a rectangle on a texture resource.
\t\nSpecifies the level of the texture resource to lock.
Pointer to a
Pointer to a rectangle to lock. Specified by a reference to a
Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
You may not specify a subrect when using
If the method succeeds, the return value is
Textures created with
For performance reasons, dirty regions are recorded only for level zero of a texture. Dirty regions are automatically recorded when
The only lockable format for a depth-stencil texture is D3DLOCK_D16_LOCKABLE.
Video memory textures cannot be locked, but must be modified by calling
This method cannot retrieve data from a texture resource created with
Unlocks a rectangle on a texture resource.
\t\nSpecifies the level of the texture resource to unlock.
If the method succeeds, the return value is
Adds a dirty region to a texture resource.
\t\nPointer to a
If the method succeeds, the return value is
For performance reasons, dirty regions are only recorded for level zero of a texture. For sublevels, it is assumed that the corresponding (scaled) rectangle or box is also dirty. Dirty regions are automatically recorded when
Using
The
The
The
The LPD3DXTEXTURESHADER type is defined as a reference to the
typedef interface *LPD3DXTEXTURESHADER;\t\n Gets a reference to the function DWORD stream.
\t\nA reference to the function DWORD stream. See
If the method succeeds, the return value is
Get a reference to the constant table.
\t\nPointer to an
If the method succeeds, the return value is
Gets a description of the constant table.
\t\nThe attributes of the constant table. See
If the method succeeds, the return value is
Gets a reference to the array of constants in the constant table.
\t\nUnique identifier to a constant. See
Returns a reference to an array of descriptions. See
The input supplied must be the maximum size of the array. The output is the number of elements that are filled in the array when the function returns.
If the method succeeds, the return value is
Samplers can appear more than once in a constant table, therefore, this method can return an array of descriptions each with a different register index.
\t\nGets a constant by looking up its index.
\t\nA handle to the parent data structure. If the constant is a top-level parameter (there is no parent data structure), use
Zero-based index of the constant.
Returns a unique identifier to the constant.
To get a constant from an array of constants, use
Gets a constant by looking up its name.
\t\nA handle to the parent data structure. If the constant is a top-level parameter (there is no parent data structure), use
A string containing the name of the constant.
Returns a unique identifier to the constant.
Get a constant from the constant table.
\t\nA handle to the array of constants. This value may not be
Zero-based index of the element in the constant table.
Returns a unique identifier to the constant.
To get a constant that is not part of an array, use
Sets the constants to the default values declared in the shader.
\t\nIf the method succeeds, the return value is
Sets the constant table with the data in the buffer.
\t\nUnique identifier to a constant. See
A reference to a buffer containing the constant data.
Size of the buffer, in bytes.
If the method succeeds, the return value is
Sets a
Unique identifier to the constant. See
If the method succeeds, the return value is
Sets an array of
Unique identifier to the array of constants. See
Array of
Number of
If the method succeeds, the return value is
Sets an integer value.
\t\nUnique identifier to the constant. See
Integer value.
If the method succeeds, the return value is
Sets an array of integers.
\t\nUnique identifier to the array of constants. See
Array of integers.
Number of integers in the array.
If the method succeeds, the return value is
Sets a floating-point number.
\t\nUnique identifier to the constant. See
Floating-point number.
If the method succeeds, the return value is
Sets an array of floating-point numbers.
\t\nUnique identifier to the array of constants. See
Array of floating-point numbers.
Number of floating-point values in the array.
If the method succeeds, the return value is
Sets a 4D vector.
\t\nUnique identifier to the vector constant. See
Pointer to a 4D vector. See
If the method succeeds, the return value is
Sets an array of 4D vectors.
\t\nUnique identifier to the array of vector constants. See
Array of 4D vectors. See
Number of vectors in the array.
If the method succeeds, the return value is
Sets a non-transposed matrix.
\t\nUnique identifier to the matrix of constants. See
Pointer to a non-transposed matrix. See
If the method succeeds, the return value is
A non-transposed matrix contains row-major data; that is, each vector is contained in a row.
\t\nSets an array of non-transposed matrices.
\t\nUnique identifier to the array of constant matrices. See
Array of non-transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A non-transposed matrix contains row-major data; that is, each vector is contained in a row.
\t\nSets an array of references to non-transposed matrices.
\t\nUnique identifier to an array of constant matrices. See
Array of references to non-transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A non-transposed matrix contains row-major data; that is, each vector is contained in a row.
\t\nSets a transposed matrix.
\t\nUnique identifier to the matrix of constants. See
Pointer to a transposed matrix. See
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
\t\nSets an array of transposed matrices.
\t\nUnique identifier to the array of matrix constants. See
Array of transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
\t\nSets an array of references to transposed matrices.
\t\nUnique identifier to the array of matrix constants. See
Array of references to transposed matrices. See
Number of matrices in the array.
If the method succeeds, the return value is
A transposed matrix contains column-major data; that is, each vector is contained in a column.
\t\nGets a reference to the function DWORD stream.
\t\nGet a reference to the constant table.
\t\nGets a description of the constant table.
\t\nApplications use the methods of the
The
This interface inherits additional functionality from the
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DVERTEXBUFFER9 and PDIRECT3DVERTEXBUFFER9 types are defined as references to the
typedef struct *LPDIRECT3DVERTEXBUFFER9, *PDIRECT3DVERTEXBUFFER9;\t\n Locks a range of vertex data and obtains a reference to the vertex buffer memory.
\t\nOffset into the vertex data to lock, in bytes. To lock the entire vertex buffer, specify 0 for both parameters, SizeToLock and OffsetToLock.
Size of the vertex data to lock, in bytes. To lock the entire vertex buffer, specify 0 for both parameters, SizeToLock and OffsetToLock.
VOID* reference to a memory buffer containing the returned vertex data.
Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
If the method succeeds, the return value is
As a general rule, do not hold a lock across more than one frame. When working with vertex buffers, you are allowed to make multiple lock calls; however, you must ensure that the number of lock calls match the number of unlock calls. DrawPrimitive calls will not succeed with any outstanding lock count on any currently set vertex buffer.
The
For information about using
Unlocks vertex data.
\t\nIf the method succeeds, the return value is
Retrieves a description of the vertex buffer resource.
\t\nPointer to a
If the method succeeds, the return value is
Retrieves a description of the vertex buffer resource.
\t\nApplications use the methods of the
A vertex shader declaration is made up of an array of vertex elements.
The LPDIRECT3DVERTEXDECLARATION9 and PDIRECT3DVERTEXDECLARATION9 types are defined as references to the
typedef struct *LPDIRECT3DVERTEXDECLARATION9, *PDIRECT3DVERTEXDECLARATION9; Gets the current device.
\t\nPointer to the
If the method succeeds, the return value is
Gets the vertex shader declaration.
\t\nArray of vertex elements (see
Number of elements in the array. The application needs to allocate enough room for this.
If the method succeeds, the return value is
The number of elements, pNumElements, includes the D3DDECL_END macro, which ends the declaration. So the element count is actually one higher than the number of valid vertex elements.
Here's an example that will return the vertex declaration array of up to 256 elements:
decl[MAXD3DDECLLENGTH];\t\n UINT numElements;\t\n hr = m_pVertexDeclaration->GetDeclaration( decl, &numElements);\t\n Specify
Gets the current device.
\t\nApplications use the methods of the
The LPDIRECT3DVERTEXSHADER9 and PDIRECT3DVERTEXSHADER9 types are defined as references to the
typedef struct *LPDIRECT3DVERTEXSHADER9, *PDIRECT3DVERTEXSHADER9; Gets the device.
\t\nPointer to the
If the method succeeds, the return value is
Gets a reference to the shader data.
\t\nPointer to a buffer that contains the shader data. The application needs to allocate enough room for this.
Size of the data, in bytes. To get the buffer size that is needed to retrieve the data, set pData =
If the method succeeds, the return value is
Gets the device.
\t\nApplications use the methods of the
The
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DVOLUME9 and PDIRECT3DVOLUME9 types are defined as references to the
typedef struct *LPDIRECT3DVOLUME9, *PDIRECT3DVOLUME9;\t\n Retrieves the device associated with a volume.
\t\nAddress of a reference to an
If the method succeeds, the return value is
This method allows navigation to the owning device object.
Calling this method will increase the internal reference count on the
Associates data with the volume that is intended for use by the application, not by Direct3D.
\t\nReference to the globally unique identifier that identifies the private data to set.
Pointer to a buffer that contains the data to associate with the volume.
Size of the buffer at pData in bytes.
Value that describes the type of data being passed, or indicates to the application that the data should be invalidated when the resource changes.
| Item | Description |
|---|---|
| (none) | If no flags are specified, Direct3D allocates memory to hold the data within the buffer and copies the data into the new buffer. The buffer allocated by Direct3D is automatically freed, as appropriate. |
| D3DSPD_IUNKNOWN | The data at pData is a reference to an |
?
If the method succeeds, the return value is
Direct3D does not manage the memory at pData. If this buffer was dynamically allocated, it is the calling application's responsibility to free the memory.
Data is passed by value, and multiple sets of data can be associated with a single volume.
\t\nCopies the private data associated with the volume to a provided buffer.
\t\nReference to (C++) or address of (C) the globally unique identifier that identifies the private data to retrieve.
Pointer to a previously allocated buffer to fill with the requested private data if the call succeeds. The application calling this method is responsible for allocating and releasing this buffer. If this parameter is
Pointer to the size of the buffer at pData, in bytes. If this value is less than the actual size of the private data, such as 0, the method sets this parameter to the required buffer size, and the method returns
If the method succeeds, the return value is
Frees the specified private data associated with this volume.
\t\nReference to the globally unique identifier that identifies the private data to free.
If the method succeeds, the return value is
Direct3D calls this method automatically when a volume is released.
\t\nProvides access to the parent volume texture object, if this surface is a child level of a volume texture.
\t\nReference identifier of the volume being requested.
Address of a reference to fill with the container reference, if the query succeeds.
If the method succeeds, the return value is
If the call succeeds, the reference count of the container is increased by one.
Here's an example getting the parent volume texture of a volume texture.
// Assumes pSurface is a valid reference\t\n void *pContainer = null ;\t\n *pVolumeTexture = null ;\t\n hr = pVolume->GetContainer(IID_IDirect3DVolumeTexture9, &pContainer);\t\n if (SUCCEEDED(hr) && pContainer)\t\n { pVolumeTexture = ( *)pContainer;\t\n Retrieves a description of the volume.
\t\nPointer to a
If the method succeeds, the return value is
Locks a box on a volume resource.
\t\nPointer to a
Pointer to a box to lock. Specified by a reference to a
Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
If the method succeeds, the return value is
For performance reasons, dirty regions are only recorded for level zero of a texture. Dirty regions are automatically recorded when
Unlocks a box on a volume resource.
\t\nIf the method succeeds, the return value is
Retrieves the device associated with a volume.
\t\nThis method allows navigation to the owning device object.
Calling this method will increase the internal reference count on the
Retrieves a description of the volume.
\t\nApplications use the methods of the
The
This interface inherits additional functionality from the
This interface, like all COM interfaces, inherits from the
The LPDIRECT3DVOLUMETEXTURE9 and PDIRECT3DVOLUMETEXTURE9 types are defined as references to the
typedef struct *LPDIRECT3DVOLUMETEXTURE9, *PDIRECT3DVOLUMETEXTURE9;\t\n Retrieves a level description of a volume texture resource.
\t\nIdentifies a level of the volume texture resource. This method returns a volume description for the level specified by this parameter.
Pointer to a
Retrieves the specified volume texture level.
\t\nIdentifies a level of the volume texture resource. This method returns a volume for the level specified by this parameter.
Address of a reference to an
Calling this method will increase the internal reference count on the
Locks a box on a volume texture resource.
\t\nSpecifies the level of the volume texture resource to lock.
Pointer to a
Pointer to the volume to lock. This parameter is specified by a reference to a
Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:
For a description of the flags, see
If the method succeeds, the return value is
For performance reasons, dirty regions are only recorded for level zero of a texture. Dirty regions are automatically recorded when LockBox is called without
Unlocks a box on a volume texture resource.
\t\nSpecifies the level of the volume texture resource to unlock.
If the method succeeds, the return value is
Adds a dirty region to a volume texture resource.
\t\nPointer to a
If the method succeeds, the return value is
For performance reasons, dirty regions are only recorded for level zero of a texture. For sublevels, it is assumed that the corresponding (scaled) box is also dirty. Dirty regions are automatically recorded when LockBox is called without
Using
Applications use the methods of the
An
The
The globally unique identifier (
The LPD3DXFILE type is defined as a reference to the
typedef interface *LPD3DXFILE;\t\n Creates an enumerator object that will read a .x file.
\t\nThe data source. Either:
Depending on the value of loadflags.
Value that specifies the source of the data. This value can be one of the D3DXF_FILELOADOPTIONS flags.
Address of a reference to an
If the method succeeds, the return value is
After using this method, use one of the
Creates a save object that will be used to save data to a .x file.
\t\nPointer to the name of the file to use for saving data.
Value that specifies the name of the file to which data is to be saved. This value can be one of the File Save Options flags.
Indicates the format to use when saving the .x file. This value can be one of the File Formats flags. For more information, see Remarks.
Address of a reference to an
If the method succeeds, the return value is
After using this method, use methods of the
For the saved file format dwFileFormat, one of the binary, legacy binary, or text flags in File Formats must be specified. The file can be compressed by using the optional
The file format values can be combined in a logical OR to create compressed text or compressed binary files. If you indicate that the file format should be text and compressed, the file will be written out first as text and then compressed. However, compressed text files are not as efficient as binary text files; in most cases, therefore, you will want to indicate binary and compressed.
\t\nRegisters custom templates.
\t\nPointer to a buffer consisting of a .x file in text or binary format that contains templates.
Size of the buffer pointed to by pvData, in bytes.
If the method succeeds, the return value is
The following code fragment provides an example call to RegisterTemplates And example contents for the buffer to which pvData points.
#define XSKINEXP_TEMPLATES \\ \"xof 0303txt 0032\\ template XSkinMeshHeader \\ { \\ <3CF169CE-FF7C-44ab-93C0-F78F62D172E2> \\ WORD nMaxSkinWeightsPerVertex; \\ WORD nMaxSkinWeightsPerFace; \\ WORD nBones; \\ } \\ template VertexDuplicationIndices \\ { \\ <B8D65549-D7C9-4995-89CF-53A9A8B031E3> \\ DWORD nIndices; \\ DWORD nOriginalVertices; \\ array DWORD indices[nIndices]; \\ } \\ template SkinWeights \\ { \\ <6F0D123B-BAD2-4167-A0D0-80224F25FABB> \\ STRING transformNodeName;\\ DWORD nWeights; \\ array DWORD vertexIndices[nWeights]; \\ array float weights[nWeights]; \\ Matrix4x4 matrixOffset; \\ }\"\t\n .\t\n .\t\n . LPD3DXFILE pD3DXFile = null ; if ( FAILED (hr = pD3DXFile->RegisterTemplates( (LPVOID)XSKINEXP_TEMPLATES, sizeof( XSKINEXP_TEMPLATES ) - 1 ) ) )\t\n goto End;\t\n All templates must specify a name and a UUID.
This method calls the RegisterEnumTemplates method, obtaining an
Registers custom templates, given an
If the method succeeds, the return value is
If the method fails, the following value will be returned: D3DXFERR_BADVALUE.
When this method is called, it copies templates stored with the
If an
Applications use the methods of the
Data types allowed by the template are called optional members. The optional members are not required, but an object might miss important information without them. These optional members are saved as children of the data object. A child can be another data object or a reference to an earlier data object.
The
The LPD3DXFILEDATA type is defined as a reference to this interface.
typedef interface *LPD3DXFILEDATA;\t\n Retrieves the enumeration object in this file data object.
\t\nAddress of a reference to receive the enumeration object in this file data object.
If the method succeeds, the return value is
Retrieves the name of this file data object.
\t\nAddress of a reference to receive the name of this file data object. If this parameter is
Pointer to the size of the string that represents the name of this file data object. This parameter can be
If the method succeeds, the return value is
For this method to succeed, either szName or puiSize must be non-
Retrieves the
Pointer to a
If the method succeeds, the return value is
Accesses the .x file data.
\t\nPointer to the size of the .x file data.
Address of a reference to receive the
If the method succeeds, the return value is
The ppData reference is only valid during a
Because file data is not guaranteed to be aligned properly with byte boundaries, you should access ppData with UNALIGNED references.
Returned parameter values are not guaranteed to be valid due to possible file corruption; therefore, your code should verify the returned parameter values.
\t\nEnds the lifespan of the ppData reference returned by
The return value is
You must ensure that the number of
Retrieves the template ID in this file data object.
\t\nPointer to the
If the method succeeds, the return value is
Indicates whether this file data object is a reference object that points to another child data object.
\t\nReturns TRUE if the file data object is a reference object; returns
Retrieves the number of children in this file data object.
\t\nAddress of a reference to receive the number of children in this file data object.
If the method succeeds, the return value is
Retrieves a child object in this file data object.
\t\nID of the child object to retrieve.
Address of a reference to receive the child object's interface reference.
If the method succeeds, the return value is
Retrieves the enumeration object in this file data object.
\t\nRetrieves the template ID in this file data object.
\t\nIndicates whether this file data object is a reference object that points to another child data object.
\t\nRetrieves the number of children in this file data object.
\t\nApplications use the methods of the
The
The LPD3DXFILEENUMOBJECT type is defined as a reference to this interface.
typedef interface *LPD3DXFILEENUMOBJECT;\t\n Retrieves the
If the method succeeds, the return value is
Retrieves the number of child objects in this file data object.
\t\nAddress of a reference to receive the number of child objects in this file data object.
If the method succeeds, the return value is
Retrieves a child object in this file data object.
\t\nID of the child object to retrieve.
Address of a reference to receive the child object's interface reference.
If the method succeeds, the return value is
Retrieves the data object that has the specified
Reference to the requested
Address of a reference to an
If the method succeeds, the return value is
Obtain the
Retrieves the data object that has the specified name.
\t\nPointer to the requested name.
Address of a reference to an
If the method succeeds, the return value is
Obtain the name szName of the current file data object with the
Retrieves the
Retrieves the number of child objects in this file data object.
\t\nApplications use the methods of the
The
The LPD3DXFileSaveData type is defined as a reference to this interface.
typedef interface *LPD3DXFILESAVEDATA;\t\n Retrieves a reference to this
If the method succeeds, the return value is
Retrieves the name of this
If the method succeeds, the return value is
For this method to succeed, either szName or puiSize must be non-
Retrieves the
If the method succeeds, the return value is
Retrieves the template ID of this file data node.
\t\nPointer to the
If the method succeeds, the return value is
Adds a data object as a child of the
If the method succeeds, the return value is
Adds a data reference as a child of this
If the method succeeds, the return value is
The file data object being referenced must have either a name or a
Retrieves a reference to this
Retrieves the template ID of this file data node.
\t\nApplications use the methods of the
Templates are not required in every file. For example, you could put all templates into a single .x file rather than duplicating them in every .x file.
The
The globally unique identifier (
The LPD3DXFILESAVEOBJECT type is defined as a reference to this interface.
typedef interface *LPD3DXFILESAVEOBJECT;\t\n Gets the
If the method succeeds, the return value is
Adds a data object as a child of the
If the method succeeds, the return value is
If a data reference object will reference the data object, either the szName or pId parameter must be non-
Save the created data to disk by using the
Saves a data object and its children to a .x file on disk.
\t\nIf the method succeeds, the return value is
After this method succeeds,
Gets the
Stores an attribute table entry.
\t\nAn attribute table is used to identify areas of the mesh that need to be drawn with different textures, render states, materials, and so on. In addition, the application can use the attribute table to hide portions of a mesh by not drawing a given attribute identifier (AttribId) when drawing the frame.
The LPD3DXATTRIBUTERANGE type is defined as a reference to the
typedef * LPD3DXATTRIBUTERANGE;\t\n Attribute table identifier.
Starting face.
Face count.
Starting vertex.
Vertex count.
Specifies mesh weight attributes.
\t\nThis structure describes how a simplification operation will consider vertex data when calculating relative costs between collapsing edges. For example, if the Normal field is 0.0, the simplification operation will ignore the vertex normal component when calculating the error for the collapse. However, if the Normal field is 1.0, the simplification operation will use the vertex normal component. If the Normal field is 2.0, double the amount of errors; if the Normal field is 4.0, then quadruple the number of errors, and so on.
The LPD3DXATTRIBUTEWEIGHTS type is defined as a reference to the
typedef * LPD3DXATTRIBUTEWEIGHTS;\t\n Position.
Blend weight.
Normal.
Diffuse lighting value.
Specular lighting value.
Tangent.
Binormal.
Eight texture coordinates.
Throughput metrics for help in understanding the performance of an application.
\t\nThe bandwidth or maximum data transfer rate from the host CPU to the GPU. This is typically the bandwidth of the PCI or AGP bus which connects the CPU and the GPU.
Memory utilized percentage when uploading data from the host CPU to the GPU.
Vertex throughput percentage. This is the number of vertices processed compared to the theoretical maximum vertex processing rate.
Triangle set-up throughput percentage. This is the number of triangles that are set up for rasterization compared to the theoretical maximum triangle set-up rate.
Pixel fill throughput percentage. This is the number of pixels that are filled compared to the theoretical pixel fill.
Defines a volume.
\t\nThe restrictions on side ordering observed for
Position of the left side of the box on the x-axis.
Position of the top of the box on the y-axis.
Position of the right side of the box on the x-axis.
Position of the bottom of the box on the y-axis.
Position of the front of the box on the z-axis.
Position of the back of the box on the z-axis.
Measure the cache hit rate performance for textures and indexed vertices.
\t\nAn efficient cache is typically closer to a 90 percent hit rate, and an inefficient cache is typically closer to a 10 percent hit rate (although a low percentage is not necessarily a problem).
\t\nThe hit rate for finding a texture in the texture cache. This assumes there is a texture cache. Increasing the level-of-detail bias to use the most detailed texture, using many large textures, or producing a near random texture access pattern on large textures with custom shader code can dramatically affect the texture cache hit rate.
The hit rate for finding transformed vertices in the vertex cache. The GPU is designed to transform indexed vertices and may store them in a vertex cache. If you are using meshes,
Describes a callback key for use in key frame animation.
\t\nKey frame time stamp.
Pointer to user callback data.
Describes the current clip status.
\t\nWhen clipping is enabled during vertex processing (by ProcessVertices, DrawPrimitive, or other drawing functions), Direct3D computes a clip code for every vertex. The clip code is a combination of D3DCS_* bits. When a vertex is outside a particular clipping plane, the corresponding bit is set in the clipping code. Direct3D maintains the clip status using
Clip status is not updated by DrawRectPatch and DrawTriPatch because there is no software emulation for them.
\t\nClip union flags that describe the current clip status. This member can be one or more of the following flags:
| Value | Meaning |
|---|---|
| Combination of all clip flags. | |
| All vertices are clipped by the left plane of the viewing frustum. | |
| All vertices are clipped by the right plane of the viewing frustum. | |
| All vertices are clipped by the top plane of the viewing frustum. | |
| All vertices are clipped by the bottom plane of the viewing frustum. | |
| All vertices are clipped by the front plane of the viewing frustum. | |
| All vertices are clipped by the back plane of the viewing frustum. | |
| Application-defined clipping planes. | |
| Application-defined clipping planes. | |
| Application-defined clipping planes. | |
| Application-defined clipping planes. | |
| Application-defined clipping planes. | |
| Application-defined clipping planes. |
?
Clip intersection flags that describe the current clip status. This member can take the same flags as ClipUnion.
A description of a constant in a constant table.
\t\nName of the constant.
Constant data type. See
Zero-based index of the constant in the table.
Number of registers that contain data.
Parameter class. See
Parameter type. See
Number of rows.
Number of columns.
Number of elements in the array.
Number of structure member sub-parameters.
Data size in number of bytes.
Pointer to the default value.
A description of the constant table.
\t\nName of the constant table creator.
Shader version.
Number of constants in the constant table.
Describes the creation parameters for a device.
\t\nOrdinal number that denotes the display adapter. D3DADAPTER_DEFAULT is always the primary display adapter. Use this ordinal as the Adapter parameter for any of the
Member of the
Window handle to which focus belongs for this Direct3D device. The value of this parameter mirrors the value passed to the CreateDevice call that created this device.
A combination of one or more
Specifies types of display modes to filter out.
\t\nThe size of this structure. This should always be set to sizeof(
The display mode format to filter out. See
Whether the scanline ordering is interlaced or progressive. See
Describes an animation event.
\t\nEvent type, as defined in
Event track identifier.
Start time of the event in global time.
Duration of the event in global time.
Transition style of the event, as defined in
Track weight for the event.
Track speed for the event.
Track position for the event.
Enable flag.
Returns material information saved in Direct3D (.x) files.
\t\nThe
The LPD3DXMATERIAL type is defined as a reference to the
typedef struct * LPD3DXMATERIAL;\t\n
Pointer to a string that specifies the file name of the texture.
Defines the attributes of a font.
\t\nThe compiler setting also determines the structure type. If Unicode is defined, the
Possible values of the above members are given in the GDI
Height, in logical units, of the font's character cell or character.
Width, in logical units, of characters in the font.
Weight of the font in the range from 0 through 1000.
Number of mip levels requested. If this value is zero or D3DX_DEFAULT, a complete mipmap chain is created. If the value is 1, the texture space is mapped identically to the screen space.
Set to TRUE for an Italic font.
Character set.
Output precision. The output precision defines how closely the output must match the requested font height, width, character orientation, escapement, pitch, and font type.
Output quality.
Pitch and family of the font.
A null-terminated string or characters that specifies the typeface name of the font. The length of the string must not exceed 32 characters, including the terminating null character. If FaceName is an empty string, the first font that matches the other specified attributes will be used. If the compiler settings require Unicode, the data type TCHAR resolves to WCHAR; otherwise, the data type resolves to CHAR. See Remarks.
Encapsulates a transform frame in a transformation frame hierarchy.
\t\nAn application can derive from this structure to add other data.
\t\nName of the frame.
Transformation matrix.
Pointer to the mesh container.
Pointer to a sibling frame.
Pointer to a child frame.
Describes a function used by an effect.
\t\nFunction name.
Unused. This member will always be set to zero by GetFunctionDesc.
Returns a description of the original contents of an image file.
\t\nWidth of original image in pixels.
Height of original image in pixels.
Depth of original image in pixels.
Number of mip levels in original image.
A value from the
Represents the type of the texture stored in the file. It is either
Represents the format of the image file.
Percent of time processing data in the driver. These statistics may help identify cases when the driver is waiting for other resources.
\t\nThese metrics help identify when a driver is waiting and what it is waiting for. High percentages are not necessarily a problem.
These system-global metrics may or may not be implemented. Depending on the specific hardware, these metrics may not support multiple queries simultaneously.
\t\nPercentage of time the driver spent waiting for the GPU to finish using a locked resource (and
Percentage of time the driver spent waiting for the GPU to finish processing some commands before the driver could send more. This indicates the driver has run out of room to send commands to the GPU.
Percentage of time the driver spent waiting for the GPU latency to reduce to less than three rendering frames.
If an application is GPU-limited, the driver must stall the CPU until the GPU gets within three frames. This prevents an application from queuing up many seconds' worth of rendering calls which may dramatically increase the latency between when the user inputs new data and when the user sees the results of that input. In general, the driver can track the number of times Present is called to prevent queuing up more than three frames of rendering work.
Percentage of time the driver spent waiting for a resource that cannot be pipelined (that is operated in parallel). An application may want to avoid using a non-pipelined resource for performance reasons.
Percentage of time the driver spent waiting for other GPU processing.
Defines a set of lighting properties.
\t\nType of the light source. This value is one of the members of the
Diffuse color emitted by the light. This member is a
Specular color emitted by the light. This member is a
Ambient color emitted by the light. This member is a
Position of the light in world space, specified by a
Direction that the light is pointing in world space, specified by a
Distance beyond which the light has no effect. The maximum allowable value for this member is the square root of FLT_MAX. This member does not affect directional lights.
Decrease in illumination between a spotlight's inner cone (the angle specified by Theta) and the outer edge of the outer cone (the angle specified by Phi).
The effect of falloff on the lighting is subtle. Furthermore, a small performance penalty is incurred by shaping the falloff curve. For these reasons, most developers set this value to 1.0.
Value specifying how the light intensity changes over distance. Attenuation values are ignored for directional lights. This member represents an attenuation constant. For information about attenuation, see Light Properties (Direct3D 9). Valid values for this member range from 0.0 to infinity. For non-directional lights, all three attenuation values should not be set to 0.0 at the same time.
Value specifying how the light intensity changes over distance. Attenuation values are ignored for directional lights. This member represents an attenuation constant. For information about attenuation, see Light Properties (Direct3D 9). Valid values for this member range from 0.0 to infinity. For non-directional lights, all three attenuation values should not be set to 0.0 at the same time.
Value specifying how the light intensity changes over distance. Attenuation values are ignored for directional lights. This member represents an attenuation constant. For information about attenuation, see Light Properties (Direct3D 9). Valid values for this member range from 0.0 to infinity. For non-directional lights, all three attenuation values should not be set to 0.0 at the same time.
Angle, in radians, of a spotlight's inner cone - that is, the fully illuminated spotlight cone. This value must be in the range from 0 through the value specified by Phi.
Angle, in radians, defining the outer edge of the spotlight's outer cone. Points outside this cone are not lit by the spotlight. This value must be between 0 and pi.
Describes a locked rectangular region.
\t\nThe pitch for DXTn formats is different from what was returned in DirectX 7. It now refers to the number of bytes in a row of blocks. For example, if you have a width of 16, then you will have a pitch of 4 blocks (4*8 for DXT1, 4*16 for DXT2-5.)
\t\nNumber of bytes in one row of the surface.
Pointer to the locked bits. If a
Describes preprocessor definitions used by an effect object.
\t\nTo use
sample=\t\n macro.Name = \"DO_CODE_BLOCK\";\t\n macro.Definition = \"/* here is a block of code */\\\\\\n\" \"{ do something ... }\\\\\\n\";\t\n Notice the 3 backslash characters at the end of the line. The first two are required to output a single '\\', followed by the newline character \"\\n\". Optionally, you may also want to terminate your lines using \"\\\\\\r\\n\".
\t\nPreprocessor name.
Definition name.
Specifies material properties.
\t\nTo turn off specular highlights, set
For more information about using the lighting engine to calculate specular lighting, see Specular Lighting (Direct3D 9).
\t\nValue specifying the diffuse color of the material. See
Value specifying the ambient color of the material. See
Value specifying the specular color of the material. See
Value specifying the emissive color of the material. See
Floating-point value specifying the sharpness of specular highlights. The higher the value, the sharper the highlight.
Mesh data structure.
\t\nDefines the mesh data type. See
Pointer to a mesh. See
Pointer to a patch mesh. See
Describes a parameter used for an effect object.
\t\nName of the parameter.
Semantic meaning, also called the usage.
Parameter class. Set this to one of the values in
Parameter type. Set this to one of the values in
Number of rows in the array.
Number of columns in the array.
Number of elements in the array.
Number of annotations.
Number of structure members.
Parameter attributes. See Effect Constants.
The size of the parameter, in bytes.
Describes a pass for an effect object.
\t\nString value used for the pass.
Annotations are user-specific data that can be attached to any technique, pass, or parameter. See Add Information to Effect Parameters with_Annotations.
Pointer to the vertex shader function. If an effect is created with
Pointer to the pixel shader function. If an effect is created with
Structure that contains the attributes of a patch mesh.
\t\nA mesh is a set of faces, each of which is described by a simple polygon. Objects can be created by connecting several meshes together. A patch mesh is constructed from patches. A patch is a four-sided piece of geometry constructed from curves. The type of curve used and the order of the curve can be varied so that the patch surface will fit almost any surface shape.
The following types of patch combinations are supported:
| Patch Type | Basis | Degree |
|---|---|---|
| Rectangle | Bezier | 2,3,5 |
| Rectangle | B-Spline | 2,3,5 |
| Rectangle | Catmull-Rom | 3 |
| Triangle | Bezier | 2,3,5 |
| N-patch | N/A | 3 |
?
\t\nThe patch type. For information about patch types, see
Degree of the curves used to construct the patch. For information about the degrees supported, see
Type of curve used to construct the patch. For information about the basis types supported, see
Percent of time processing data in the pipeline.
\t\nFor best performance, a balanced load is recommended.
\t\nPercent of time spent running vertex shaders.
Percent of time spent running pixel shaders.
Percent of time spent doing other processing.
Percent of time not processing anything.
Describes swapchain statistics relating to PresentEx calls.
\t\nWhen a 9Ex application adopts Flip Mode present (
Applications can determine whether a frame has been dropped by sampling any two instances of PresentCount and GetPresentStats (by calling GetPresentStats API at any two points in time). For example, a media application that is presenting at the same rate as the monitor refresh rate (for example, monitor refresh rate is 60Hz, the application presents a frame every 1/60 seconds) wants to present frames A, B, C, D, E, each corresponding to Present IDs (PresentCount) 1, 2, 3, 7, 8.
The application code looks like the following sequence.
Note that GetPresentStatistics will be processed after it is called, regardless of the state of FLIPEX mode PresentEx calls.
Windows?Vista:??The Present calls will be queued and then processed before GetPresentStats call will be processed.When an application detects that the presentation of certain frames are behind, it can skip those frames and correct the presentation to re-synchronize with the vblank. To do this, an application can simply not render the late frames and start rendering with the next correct frame in the queue. However, if an application has already started the rendering of late frames, it can use a new Present parameter in D3D9Ex called
Applications can synchronize video and audio streams in the same manner because the behavior of GetPresentStatistics does not change in that scenario.
D3D9Ex Flip Mode provides frame statistics information to windowed applications and full screen 9Ex applications.
Windows?Vista:??Use the DWM APIs for retrieving present statistics.When Desktop Window Manager is turned off, windowed mode 9Ex applications using flip mode will receive present statistics information of limited accuracy.
Windows?Vista:??If an application is not fast enough to keep up with the monitor's refresh rate, possibly due to slow hardware or lack of system resources, then it can experience a graphics glitch. A glitch is a so-called visual hiccup. If a monitor is set to refresh at 60 Hz, and the application can only manage 30 fps, then half of the frames will have glitches.
Applications can detect a glitch by keeping track of SynchRefreshCount. For example, an application might perform the following sequence of actions.
Describes the presentation parameters.
\t\nWidth of the new swap chain's back buffers, in pixels. If Windowed is
Height of the new swap chain's back buffers, in pixels. If Windowed is
The back buffer format. For more information about formats, see
In fact,
For windowed applications, the back buffer format no longer needs to match the display-mode format because color conversion can now be done by the hardware (if the hardware supports color conversion). The set of possible back buffer formats is constrained, but the runtime will allow any valid back buffer format to be presented to any desktop format. (There is the additional requirement that the device be operable in the desktop mode; devices typically do not operate in 8 bits per pixel modes.)
Full-screen applications cannot do color conversion.
This value can be between 0 and
The method fails if one back buffer cannot be created. The value of BackBufferCount influences what set of swap effects are allowed. Specifically, any
Member of the
Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by CheckDeviceMultiSampleType. Passing a larger value returns the error
Member of the
| Differences between Direct3D9 and Direct3D9Ex In Direct3D9Ex, |
?
The device window determines the location and size of the back buffer on screen. This is used by Direct3D when the back buffer contents are copied to the front buffer during Present.
For a full-screen application, this is a handle to the top window (which is the focus window).
For applications that use multiple full-screen devices (such as a multimonitor system), exactly one device can use the focus window as the device window. All other devices must have unique device windows.
Note that no attempt is made by the runtime to reflect user changes in window size. The back buffer is not implicitly reset when this window is reset. However, the Present method does automatically track window position changes.
TRUE if the application runs windowed;
If this value is TRUE, Direct3D will manage depth buffers for the application. The device will create a depth-stencil buffer when it is created. The depth-stencil buffer will be automatically set as the render target of the device. When the device is reset, the depth-stencil buffer will be automatically destroyed and recreated in the new size.
If EnableAutoDepthStencil is TRUE, then AutoDepthStencilFormat must be a valid depth-stencil format.
Member of the
One of the
The rate at which the display adapter refreshes the screen. The value depends on the mode in which the application is running:
The maximum rate at which the swap chain's back buffers can be presented to the front buffer. For a detailed explanation of the modes and the intervals that are supported, see
Describes the raster status.
\t\nTRUE if the raster is in the vertical blank period.
If InVBlank is
If InVBlank is TRUE, then this value is set to zero and can be ignored.
Describes a rectangular high-order patch.
\t\nThe following diagram identifies the parameters that specify a rectangle patch.
Each of the vertices in the vertex buffer is shown as a black dot. In this case, the vertex buffer has 20 vertices in it, 16 of which are in the rectangle patch. The stride is the number of vertices in the width of the vertex buffer, in this case five. The x offset to the first vertex is called the StartIndexVertexWidth and is in this case 1. The y offset to the first patch vertex is called the StartIndexVertexHeight and is in this case 0.
To render a stream of individual rectangular patches (non-mosaic), you should interpret your geometry as a long narrow (1 x N) rectangular patch. The
RectInfo; RectInfo.Width = 4;\t\n RectInfo.Height = 4;\t\n RectInfo.Stride = 4;\t\n RectInfo.Basis = ;\t\n RectInfo.Order = D3DORDER_CUBIC;\t\n RectInfo.StartVertexOffsetWidth = 0;\t\n RectInfo.StartVertexOffsetHeight = 4*i; // The variable i is the index of the \t\n // patch you want to render.\t\n Starting vertex offset width, in number of vertices.
Starting vertex offset height, in number of vertices.
Width of each vertex, in number of vertices.
Height of each vertex, in number of vertices.
Width of the imaginary two-dimensional vertex array, which occupies the same space as the vertex buffer. For an example, see the diagram below.
Member of the
| Value | Order supported | Width and height |
|---|---|---|
| Linear, cubic, and quintic | Width = height = (DWORD)order + 1 | |
| Linear, cubic, and quintic | Width = height > (DWORD)order | |
| D3DBASIS_INTERPOLATE | Cubic | Width = height > (DWORD)order |
?
Member of the
Describes an off-screen render target used by an instance of
This method is used to return the creation parameters used when creating an
Describes a render surface.
\t\nWidth of the render surface, in pixels.
Height of the render surface, in pixels.
Member of the
If TRUE, the render surface supports a depth-stencil surface; otherwise this member is set to
If DepthStencil is set to TRUE, this parameter is a member of the
Resource statistics gathered by the D3DDEVINFO_ResourceManager when using the asynchronous query mechanism.
\t\nDescribes a quaternion key for use in key frame animation. A quaternion key is a quaternion value at a given time.
\t\nTime value.
Describes a vector key for use in key frame animation. It specifies a vector at a given time. This is used for scale and translation keys.
\t\nKey frame time stamp.
Offset from the beginning of this structure, in bytes, to the string that contains the constant information.
Register set. See
The register index.
Number of registers.
Reserved.
Offset from the beginning of this structure, in bytes, to the string that contains the D3DXSHADER_TYPEINFO information.
Offset from the beginning of this structure, in bytes, to the string that contains the default value.
Helper structure for managing a shader constant table. This can also be done using
Shader constant information is included in a tab-delimited table of comments. All offsets are measured in bytes from the beginning of the structure. Entries in the constant table are sorted by Creator in ascending order.
A shader constant table can be managed with the
This size member is often initialized using the following:
constantTable;\t\n constantTable.Size = sizeof()\t\n Semantics map a parameter to vertex or pixel shader registers. They can also be optional descriptive strings attached to non-register parameters.
\t\nSemantics are required for vertex and pixel shader, input and output registers.
\t\nOptions that identify how resources are used. See
Options that modify how the usage is interpreted. The usage and usage index make up a vertex declaration. See Vertex Declaration (Direct3D 9).
Percent of time processing shader data.
\t\nFor best performance, a balanced load is recommended.
\t\nPercent of time in shader spent on memory accesses.
Percent of time processing (moving data around in registers or doing mathematical operations).
Describes a surface.
\t\nMember of the
Member of the
Either the
Member of the
Member of the
Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by CheckDeviceMultiSampleType. Passing a larger value returns the error,
Width of the surface, in pixels.
Height of the surface, in pixels.
Describes a technique used by an effect.
\t\nSome video cards can render two textures in a single pass. However, if a card does not have this capability, it is often possible to render the same effect in two passes, using one texture for each pass.
\t\nString that contains the technique name.
Number of rendering passes the technique requires. See Remarks.
The number of annotations. See Add Information to Effect Parameters with_Annotations.
Describes an animation track and specifies blending weight, speed, and position for the track at a given time.
\t\nTracks with the same priority are blended together, and the two resulting values are then blended using the priority blend factor. A track must have an animation set (stored separately) associated with it.
\t\nPriority type, as defined in
Weight value. The weight determines the proportion of this track to blend with other tracks.
Speed value. This is used similarly to a multiplier to scale the period of the track.
Time position of the track, in the local timeframe of its current animation set.
Track enable/disable. To enable, set to TRUE. To disable, set to
Describes a triangular high-order patch.
\t\nFor example, the following diagram identifies the vertex order and segment numbers for a cubic B?zier triangle patch. The vertex order determines the segment numbers used by DrawTriPatch. The offset is the number of bytes to the first triangle patch vertex in the vertex buffer.
\t\nStarting vertex offset, in number of vertices.
Number of vertices.
Member of the
Member of the
| Value | Number of vertices |
|---|---|
| 10 | |
| 3 | |
| N/A | |
| 21 |
?
N/A - Not available. Not supported.
DirectX 8.1 and later versions only.
The
DirectX 8.1 versions only.The Direct3D runtime calls a driver's D3dGetDriverState function to obtain vertex-cache information from the driver. In this D3dGetDriverState call, the runtime specifies the D3DDEVINFOID_VCACHE flag in the dwFlags member of the DD_GETDRIVERSTATEDATA structure that the runtime passes. The driver specifies vertex-cache information in a
DirectX 9.0 and later versions only.The Direct3D runtime specifies D3DDP2OP_CREATEQUERY and D3DDP2OP_ISSUEQUERY commands in calls to the driver's D3dDrawPrimitives2 callback to create driver-side resources for the query and then to asynchronously query the driver for vertex-cache information. In the call with the D3DDP2OP_CREATEQUERY command, the runtime specifies the
When the driver completes a vertex-cache query, the driver sets the total size of the response buffer in the dwErrorOffset member of the D3DHAL_DRAWPRIMITIVES2DATA structure and sets the ddrval member of D3DHAL_DRAWPRIMITIVES2DATA to
Specifies the bit pattern. The driver must specify the bit pattern as the CACH four-character code (FOURCC) value. The driver can use the MAKEFOURCC macro as follows to specify the FOURCC value as CACH:
MAKEFOURCC('C', 'A', 'C', 'H');Specifies the method of mesh optimization. The driver can use one of the following values to specify the mesh optimization that it uses:
| Value | Meaning |
|---|---|
| | Longest strips optimization |
| D3DXMESHOPT_VCACHE (1) | Vertex-cache based optimization |
?
Specifies the effective size, in entries, for which the driver optimizes the vertex cache. The actual cache size is not required to be the size specified in CacheSize because in most cases the actual cache size turns out to be larger. The driver only specifies an optimized size in CacheSize if it also specifies D3DXMESHOPT_VCACHE in the OptMethod member.
Specifies the number that should be used as part of a trial-and-error procedure when determining when to restart the strips list. This number can be set from 1 to the value in the CacheSize member. Typically, the best values are near CacheSize/2.
Defines the vertex data layout. Each vertex can contain one or more data types, and each data type is described by a vertex element.
\t\nVertex data is defined using an array of
Stream number.
Offset from the beginning of the vertex data to the data associated with the particular data type.
The data type, specified as a
The method specifies the tessellator processing, which determines how the tessellator interprets (or operates on) the vertex data. For more information, see
Defines what the data will be used for; that is, the interoperability between vertex data layouts and vertex shaders. Each usage acts to bind a vertex declaration to a vertex shader. In some cases, they have a special interpretation. For example, an element that specifies
Modifies the usage data to allow the user to specify multiple usage types.
Vertex shader caps.
\t\nInstruction predication is supported if this value is nonzero. See setp_comp - vs.
Either 0 or 24, which represents the depth of the dynamic flow control instruction nesting. See
The number of temporary registers supported. See
The depth of nesting of the loop - vs/rep - vs and call - vs/callnz bool - vs instructions. See
Reports the number of triangles that have been processed and clipped by the runtime's software vertex processing.
\t\nUse the debug runtime and software vertex processing to get the number of non-clipped and clipped primitives for a particular scene. Primitives will typically be clipped based on a guard band (if one is present). The clipping guard band is set with parameters such as GuardBandLeft in
Total number of triangles that are not clipped in this frame.
Number of new triangles generated by clipping.
Describes a volume.
\t\nMember of the
Member of the
Currently not used. Always returned as 0.
Member of the
Width of the volume, in pixels.
Height of the volume, in pixels.
Depth of the volume, in pixels.
Specifies tolerance values for each vertex component when comparing vertices to determine if they are similar enough to be welded together.
\t\nThe LPD3DXWELDEPSILONS type is defined as a reference to the
typedef *LPD3DXWELDEPSILONS;\t\n Position
Blend weight
Normal
Point size value
Specular lighting value
Diffuse lighting value
Tangent
Binormal
Tessellation factor
Eight texture coordinates
Identifies compressed key frame animation data.
\t\nTotal size, in bytes, of the compressed data in the compressed key frame animation data buffer.
Number of animation key frame ticks that occur per second.
Type of the animation set playback loop. See
Minimum buffer size, in bytes, required to hold compressed key frame animation data. Value is equal to ( ( CompressedBlockSize + 3 ) / 4 ).
The semantics of version numbers are left to the manufacturer of the device. The only guarantee is that newer versions have larger numbers.
\t\nIf the method succeeds, the return value is
For compatibility with DirectX 3, it is also valid to pass a DIDEVCAPS_DX3 structure with the dwSize member initialized to sizeof(DIDEVCAPS_DX3).
The number of objects returned in the
If the method succeeds, the return value is
The
Applications should not rely on this method to determine whether certain keyboard keys or indicator lights are present, as these objects might be enumerated even though they are not present. Although the basic set of available objects can be determined from the device subtype, there is no reliable way of determining whether extra objects such as the menu key are available.
\t\nPredefined property that allows the application to access the information that DirectInput uses to manipulate axes that require calibration. This property exists primarily for applications of the control panel type. Normal applications should not need to deal with calibration information.
You can access the calibration mode property for a particular axis by setting the dwHow member of the
Control panel applications that set new calibration data must also invoke the IDirectInputJoyConfig::SendNotify method to notify other applications of the change in calibration. For more information about IDirectInputJoyConfig::SendNotify, see the DirectInput Driver Development Kit (DDK).
If the method succeeds, the return value is
If rguidProp is set to
S_FALSE is always returned when
The scan codes reported in Microsoft DirectX 8.1 are different from the ones reported in DirectX 8.0. In DirectX 8.0, the property actually reported the single byte
The following C example shows how to obtain the value of the
dipdw; // contains a structure. \t\n hr; \t\n dipdw.diph.dwSize = sizeof( ); \t\n dipdw.diph.dwHeaderSize = sizeof( ); \t\n dipdw.diph.dwObj = 0; // device property \t\n dipdw.diph.dwHow = ; hr = idirectinputdevice9_GetProperty(pdid, , &dipdw.diph); \t\n if (SUCCEEDED(hr)) { // The dipdw.dwData member contains the buffer size. \t\n } \t\n
The following example shows how to extract the two WORD values from the dwData member of the
wVendorID = LOWORD(\t\n.dwData);\t\n wProductID = HIWORD( .dwData);\t\n
Specifies whether device objects are self centering. This setting applies to the entire device, rather than to any particular object, so the dwHow member of the associated
The dwData member can be one of the following values.
DIPROPAUTOCENTER_OFF: The device should not automatically center when the user releases the device. An application that uses force feedback should disable autocentering before playing effects.
DIPROPAUTOCENTER_ON: The device should automatically center when the user releases the device.
Not all devices support the autocenter property.
Predefined property that allows the application to access the information that DirectInput uses to manipulate axes that require calibration. This property exists primarily for applications of the control panel type. Normal applications should not need to deal with calibration information.
You can access the calibration mode property for an axis by setting the dwHow member of the
Control panel applications that set new calibration data must also invoke the IDirectInputJoyConfig::SendNotify method to notify other applications of the change in calibration. For more information about IDirectInputJoyConfig::SendNotify, see the DirectX Driver Development Kit (DDK).
Enables the application to specify whether DirectInput should retrieve calibrated or uncalibrated data from an axis. By default, DirectInput retrieves calibrated data.
Setting the calibration mode for the entire device is equivalent to setting it for each axis individually.
The dwData member of the
DIPROPCALIBRATIONMODE_COOKED: DirectInput should return data after applying calibration information. This is the default mode.
DIPROPCALIBRATIONMODE_RAW: DirectInput should return raw, uncalibrated data. This mode is typically used only by applications of the control panel type. Note that raw data might include negative values.
Setting a device into raw mode causes the dead zone, saturation, and range settings to be ignored.
The dwData member contains a gain value that is applied to all effects created on the device. The value is an integer in the range from 0 through 10,000, specifying the amount by which effect magnitudes should be scaled for the device. For example, a value of 10,000 indicates that all effect magnitudes are to be taken at face value. A value of 9,000 indicates that all effect magnitudes are to be reduced to 90 percent of their nominal magnitudes.
DirectInput always checks the gain value before setting the gain property. If the gain is outside of the range (less than zero or greater than 10,000),
Setting a gain value is useful when an application wants to scale down the strength of all force-feedback effects uniformly, based on user preferences.
Unlike other properties, the gain can be set when the device is in an acquired state.
This property exists for advanced applications that want to change the friendly instance name of a device (as returned in the tszInstanceName member of the
This setting applies to the entire device, so the dwHow member of the associated
The pdiph parameter must be a reference to the diph member of a
This property exists for advanced applications that want to change the friendly product name of a device (as returned in the tszProductName member of the
This setting applies to the entire device, so the dwHow member of the associated
The pdiph parameter must be a reference to the diph member of a
Setting the product name is only useful for changing the user-defined name of an analog joystick on Microsoft Windows 98, Windows 2000, and Windows Millennium Edition (Windows Me) computers. In other cases, attempting to set this property will still return
For some devices, this is a read-only property.
You cannot set a reverse range; lmax must be greater than lmin.
If the method succeeds, the return value is
The buffer size determines the amount of data that the buffer can hold between calls to the
If the method succeeds, the return value is
Before a device can be acquired, a data format must be set by using the
Devices must be acquired before calling the
Device acquisition does not use a reference count. Therefore, if an application calls the
If
The return value is
c_dfDIKeyboard
c_dfDIMouse
c_dfDIMouse2
c_dfDIJoystick
c_dfDIJoystick2
If the method succeeds, the return value is
The data format must be set before the device can be acquired by using the
If the application is using action mapping, the data format is set instead by the call to
The application can create the handle as either a manual-reset or autoreset event by using the Win32 CreateEvent function. If the event is created as an autoreset event, the operating system automatically resets the event when a wait has been satisfied. If the event is created as a manual-reset event, it is the application's responsibility to call the Win32 ResetEvent function to reset it. DirectInput does not call the Win32 ResetEvent function for event notification handles. Most applications create the event as an automatic-reset event.
If the method succeeds, the return value is
A device state change is defined as any of the following:
A change in the position of an axis
A change in the state (pressed or released) of a button
A change in the direction of a POV control
Loss of acquisition
Do not call the Win32 CloseHandle function on the event while it has been selected into a DirectInputDevice object. You must call this method with the hEvent parameter set to
The event notification handle cannot be changed while the device is acquired. If the function is successful, the application can use the event handle like any other Win32 event handle.
ExamplesThe following code example checks whether the handle is currently set without blocking:
dwResult = WaitForSingleObject(hEvent, 0); \t\n if (dwResult == WAIT_OBJECT_0) { // Event is set. If the event was created as // autoreset, it has also been reset. \t\n } \t\n The following code example illustrates blocking indefinitely until the event is set. This behavior is strongly discouraged because the thread does not respond to the system until the wait is satisfied. In particular, the thread does not respond to Microsoft Windows messages.
dwResult = WaitForSingleObject(hEvent, INFINITE); \t\n if (dwResult == WAIT_OBJECT_0) { // Event has been set. If the event was created // as autoreset, it has also been reset. \t\n }\t\n The following code example illustrates a typical application loop for a non-message-based application that uses two events:
HANDLE ah[2] = { hEvent1, hEvent2 }; while (TRUE) { dwResult = MsgWaitForMultipleObjects(2, ah, , INFINITE, QS_ALLINPUT); switch (dwResult) { case WAIT_OBJECT_0: // Event 1 has been set. If the event was created as // autoreset, it has also been reset. ProcessInputEvent1(); break; case WAIT_OBJECT_0 + 1: // Event 2 has been set. If the event was created as // autoreset, it has also been reset. ProcessInputEvent2(); break; case WAIT_OBJECT_0 + 2: // A Windows message has arrived. Process // messages until there aren't any more. while(PeekMessage(&msg, null , 0, 0, PM_REMOVE)){ if (msg.message == WM_QUIT) { goto exitapp; } TranslateMessage(&msg); DispatchMessage(&msg); } break; default: // Unexpected error. Panic(); break; } \t\n } \t\n The following code example illustrates a typical message loop for a message-based application that uses two events:
HANDLE ah[2] = { hEvent1, hEvent2 }; \t\n DWORD dwWait = 0; while (TRUE) { dwResult = MsgWaitForMultipleObjects(2, ah, , dwWait, QS_ALLINPUT); dwWait = 0; switch (dwResult) { case WAIT_OBJECT_0: // Event 1 has been set. If the event was // created as autoreset, it has also // been reset. ProcessInputEvent1(); break; case WAIT_OBJECT_0 + 1: // Event 2 has been set. If the event was // created as autoreset, it has also // been reset. ProcessInputEvent2(); break; case WAIT_OBJECT_0 + 2: // A Windows message has arrived. Process // messages until there aren't any more. while(PeekMessage(&msg, null , 0, 0, PM_REMOVE)){ if (msg.message == WM_QUIT) { goto exitapp; } TranslateMessage(&msg); DispatchMessage(&msg); } break; default: // No input or messages waiting. // Do a frame of the game. // If the game is idle, tell the next wait // to wait indefinitely for input or a message. if (!DoGame()) { dwWait = INFINITE; } break; } \t\n } \t\n \t\n For compatibility with DirectX 3, it is also valid to pass a DIDEVICEOBJECTINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEOBJECTINSTANCE_DX3).
\t\nIf the method succeeds, the return value is
For compatibility with DirectX 3, it is also valid to pass a DIDEVICEINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEINSTANCE_DX3).
\t\nIf the method succeeds, the return value is
If the method succeeds, the return value is
If this method fails, the underlying object should be considered to be in an indeterminate state and must be reinitialized before use.
\t\nIf the method succeeds, the return value is
If the return value is
If the method succeeds, the return value is
If the callback stops the enumeration prematurely, the enumeration is considered to have succeeded.
An application can use the dwEffType member of the DIEffectInfo structure to obtain general information about the effect, such as its type and which envelope and condition parameters are supported by the effect.
To exploit an effect to its fullest, contact the device manufacturer to obtain information about the semantics of the effect and its effect-specific parameters.
\t\n| Note |
|---|
| If this method is called on an non-Force Feedback device, E_POINTER will be returned. |
The value is a combination of the following constants.
Applications should ignore any flags that are not currently defined.
The device must be acquired at the exclusive cooperative level for this method to succeed.
The
| Note |
|---|
| When calling |
While the device is paused, new effects cannot be started, and existing ones cannot be modified. Doing so can cause the subsequent
To abandon a pause and stop all effects, use the
If the method succeeds, the return value is
The device must be acquired at the exclusive cooperative level for this method to succeed.
| Note |
|---|
| When calling |
If the method succeeds, the return value is
The results are unpredictable if you create or destroy an effect while an enumeration is in progress. However, the callback function can safely release the effect passed to it.
\t\nIf the method succeeds, the return value is
Other device-specific error codes are also possible. Ask the hardware manufacturer for details.
Because each driver implements different escapes, it is the application's responsibility to ensure that it is sending the escape to the correct driver by comparing the value of the guidFFDriver member of the
If the method succeeds, the return value is
Before a device data can be polled, the data format must be set by using the
| Note |
|---|
| There are no devices that accept output from |
If the method succeeds, the return value is
Applications should not use
If the method succeeds, the return value is
If the callback stops the enumeration prematurely, the enumeration is considered to have succeeded.
\t\nIf the method succeeds, it returns
If the method succeeds, the return value is
The method returns
If
If DIEFF_MAPFILEFAIL is returned, an error has occurred either reading the vendor supplied file for the device or reading or writing the user configuration file for the device.
If
If the method succeeds, the return value can be one of the following error values:
This method provides the mechanism to change action-to-control mapping from the device defaults. An application must use this method to map its in-game actions to virtual controls.
The user name passed to this method binds a set of action mappings for a device to a specific user. Settings are automatically saved to disk when they differ from the currently applied map. Applications that accept input from multiple users should be very careful when applying action maps to the system mouse or keyboard, as the action maps for each user may conflict.
The method can be called only when the device is not acquired.
If
If the method succeeds, the return value is
For compatibility with DirectX 3, it is also valid to pass a DIDEVCAPS_DX3 structure with the dwSize member initialized to sizeof(DIDEVCAPS_DX3).
The number of objects returned in the
The data format must be set before the device can be acquired by using the
If the application is using action mapping, the data format is set instead by the call to
A device state change is defined as any of the following:
A change in the position of an axis
A change in the state (pressed or released) of a button
A change in the direction of a POV control
Loss of acquisition
Do not call the Win32 CloseHandle function on the event while it has been selected into a DirectInputDevice object. You must call this method with the hEvent parameter set to
The event notification handle cannot be changed while the device is acquired. If the function is successful, the application can use the event handle like any other Win32 event handle.
ExamplesThe following code example checks whether the handle is currently set without blocking:
dwResult = WaitForSingleObject(hEvent, 0); \t\n if (dwResult == WAIT_OBJECT_0) { // Event is set. If the event was created as // autoreset, it has also been reset. \t\n } \t\n The following code example illustrates blocking indefinitely until the event is set. This behavior is strongly discouraged because the thread does not respond to the system until the wait is satisfied. In particular, the thread does not respond to Microsoft Windows messages.
dwResult = WaitForSingleObject(hEvent, INFINITE); \t\n if (dwResult == WAIT_OBJECT_0) { // Event has been set. If the event was created // as autoreset, it has also been reset. \t\n }\t\n The following code example illustrates a typical application loop for a non-message-based application that uses two events:
HANDLE ah[2] = { hEvent1, hEvent2 }; while (TRUE) { dwResult = MsgWaitForMultipleObjects(2, ah, , INFINITE, QS_ALLINPUT); switch (dwResult) { case WAIT_OBJECT_0: // Event 1 has been set. If the event was created as // autoreset, it has also been reset. ProcessInputEvent1(); break; case WAIT_OBJECT_0 + 1: // Event 2 has been set. If the event was created as // autoreset, it has also been reset. ProcessInputEvent2(); break; case WAIT_OBJECT_0 + 2: // A Windows message has arrived. Process // messages until there aren't any more. while(PeekMessage(&msg, null , 0, 0, PM_REMOVE)){ if (msg.message == WM_QUIT) { goto exitapp; } TranslateMessage(&msg); DispatchMessage(&msg); } break; default: // Unexpected error. Panic(); break; } \t\n } \t\n The following code example illustrates a typical message loop for a message-based application that uses two events:
HANDLE ah[2] = { hEvent1, hEvent2 }; \t\n DWORD dwWait = 0; while (TRUE) { dwResult = MsgWaitForMultipleObjects(2, ah, , dwWait, QS_ALLINPUT); dwWait = 0; switch (dwResult) { case WAIT_OBJECT_0: // Event 1 has been set. If the event was // created as autoreset, it has also // been reset. ProcessInputEvent1(); break; case WAIT_OBJECT_0 + 1: // Event 2 has been set. If the event was // created as autoreset, it has also // been reset. ProcessInputEvent2(); break; case WAIT_OBJECT_0 + 2: // A Windows message has arrived. Process // messages until there aren't any more. while(PeekMessage(&msg, null , 0, 0, PM_REMOVE)){ if (msg.message == WM_QUIT) { goto exitapp; } TranslateMessage(&msg); DispatchMessage(&msg); } break; default: // No input or messages waiting. // Do a frame of the game. // If the game is idle, tell the next wait // to wait indefinitely for input or a message. if (!DoGame()) { dwWait = INFINITE; } break; } \t\n } \t\n \t\n For compatibility with DirectX 3, it is also valid to pass a DIDEVICEINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEINSTANCE_DX3).
\t\nApplications do not typically need to create a
Applications that need to create a
The following code example sets a data format for a device that has an X-axis and a Y-axis:
// Suppose an application uses the following \t\n // structure to read device data. typedef struct MYDATA { LONG lX; // X-axis goes here. LONG lY; // Y-axis goes here. BYTE bButtonA; // One button goes here. BYTE bButtonB; // Another button goes here. BYTE bPadding[2]; // Must be DWORD multiple in size. \t\n } MYDATA; // Then, it can use the following data format. DIOBJECTDATAFORMAT rgodf[ ] = { { &, FIELD_OFFSET(MYDATA, lX), | , 0, }, { &, FIELD_OFFSET(MYDATA, lY), | , 0, }, { &, FIELD_OFFSET(MYDATA, bButtonA), | , 0, }, { &, FIELD_OFFSET(MYDATA, bButtonB), | , 0, }, \t\n }; \t\n #define numObjects (sizeof(rgodf) / sizeof(rgodf[0])) df = { sizeof(), // Size of this structure sizeof(DIOBJECTDATAFORMAT), // Size of object data format , // Absolute axis coordinates sizeof(MYDATA), // Size of device data numObjects, // Number of objects rgodf, // And here they are \t\n }; \t\n The buffer at lprgImageInfoArray must be large enough to hold all required image information structures. Applications can query for the required size by calling the
The following device types and subtypes are defined for use in the dwDevType member.
First-person action game device. The following subtypes are defined.
Device that does not provide the minimum number of device objects for action mapping.
Device designed for first-person shooter games.
Device with six degrees of freedom; that is, three lateral axes and three rotational axes.
Unknown subtype.
Device that does not fall into another category.
Input device used to control another type of device from within the context of the application. The following subtypes are defined.
Control used to make communications selections.
Device that must use its default configuration and cannot be remapped.
Unknown subtype.
Device for steering. The following subtypes are defined.
Steering device that reports acceleration and brake pedal values from a single axis.
Steering device that reports acceleration and brake pedal values from separate axes.
Hand-held steering device.
Steering device that does not provide the minimum number of device objects for action mapping.
Steering device that reports acceleration, brake, and clutch pedal values from separate axes.
Controller for flight simulation. The following subtypes are defined.
Flight controller that does not provide the minimum number of device objects for action mapping.
Flight device based on a remote control for model aircraft.
Joystick.
Yoke.
Gamepad. The following subtypes are defined.
Gamepad that does not provide the minimum number of device objects for action mapping.
Standard gamepad that provides the minimum number of device objects for action mapping.
Gamepad that can report x-axis and y-axis data based on the attitude of the controller.
Joystick. The following subtypes are defined.
Joystick that does not provide the minimum number of device objects for action mapping.
Standard joystick that provides the minimum number of device objects for action mapping.
Keyboard or keyboard-like device. The following subtypes are defined.
Subtype could not be determined.
IBM PC/XT 83-key keyboard.
Olivetti 102-key keyboard.
IBM PC/AT 84-key keyboard.
IBM PC Enhanced 101/102-key or Microsoft Natural keyboard.
Nokia 1050 keyboard.
Nokia 9140 keyboard.
Japanese NEC PC98 keyboard.
Japanese NEC PC98 laptop keyboard.
Japanese NEC PC98 106-key keyboard.
Japanese 106-key keyboard.
Japanese AX keyboard.
Japanese J3100 keyboard.
A mouse or mouse-like device (such as a trackball). The following subtypes are defined.
Mouse that returns absolute axis data.
Fingerstick.
Touchpad.
Trackball.
Traditional mouse.
Subtype could not be determined.
Remote-control device. The following subtype is defined.
Subtype could not be determined.
Screen reference. The following subtypes are defined.
Unknown subtype.
Light gun.
Light pen.
Touch screen.
Specialized device with functionality unsuitable for the main control of an application, such as pedals used with a wheel. The following subtypes are defined.
Secondary handheld controller.
Device whose primary function is to report acceleration and brake pedal values from a single axis.
Device whose primary function is to report acceleration and brake pedal values from separate axes.
Device that tracks hand movement.
Device that tracks head movement.
Device with rudder pedals.
Device that reports gear selection from an axis.
Device that reports gear selection from button states.
Device whose primary function is to report at least two throttle values. It may have other controls.
Device whose primary function is to report acceleration, brake, and clutch pedal values from separate axes.
Device whose primary function is to report a single throttle value. It may have other controls.
Unknown subtype.
Versions of DirectInput earlier than DirectX 8.0 have a somewhat different scheme of device types and subtypes. See the DIDEVTYPExxx defines in Dinput.h.
\t\n| Note |
|---|
| The value in dwOfs is the offset within the raw data returned by the device, regardless of whether the data format has been set for the device. |
Applications can use the wUsagePage and wUsage members to obtain additional information about how the object was designed to be used. For example, if wUsagePage has the value 0x02 (vehicle controls) and wUsage has the value 0xB9 (elevator trim), the object was designed to be the elevator trim control on a flight stick. A flight simulator application can use this information to provide more reasonable defaults for objects on the device. HID usage codes are determined by the USB standards committee.
\t\nIf the method succeeds, the return value is
Calling this method with pUnkOuter =
Calling this method with pUnkOuter !=
To restrict the enumeration to a particular type of device, set this parameter to a DI8DEVTYPE_* value. See
To enumerate a class of devices, use one of the following values.
If the method succeeds, the return value is
All installed devices can be enumerated, even if they are not present. For example, a flight stick might be installed on the system but not currently plugged into the computer. Set the dwFlags parameter to indicate whether only attached or all installed devices should be enumerated. If the
A preferred device type can be passed as a dwDevType filter so that only the devices of that type are enumerated.
On Microsoft Windows XP, DirectInput enumerates only one mouse and one keyboard device, referred to as the system mouse and the system keyboard. These devices represent the combined output of all mice and keyboards respectively on a system. For information about how to read from multiple mice or keyboards individually on Windows XP, see the WM_INPUT documentation.
| Note |
|---|
| The order in which devices are enumerated by DirectInput is not guaranteed. |
If the method succeeds, the return value is
If the method succeeds, the return value is
If the method succeeds, the return value is
If the method succeeds, the return value is
The keyboard and mouse are enumerated last.
| Note |
|---|
| The order in which devices are enumerated by DirectInput is not guaranteed. |
| Note |
|---|
| The rglDirection array must contain cAxes entries, even if polar or spherical coordinates are given. In these cases, the last element in the rglDirection array is reserved and must be 0. |
| Note |
|---|
| The rglDirection array must contain cAxes entries, even if polar or spherical coordinates are given. In these cases, the last element in the rglDirection array is reserved and must be 0. |
If the function succeeds, the return value is
The DirectInput object created by this function is implemented in Dinput8.dll. Versions of interfaces earlier than DirectX 8.0 cannot be obtained in this implementation.
To create a DirectX 8.x interface with the latest DirectX SDK without using CoCreateInstance:
Set \"#define
Call DirectInput8Create instead of DirectInputCreateEx.
Link to the Dinput8.lib library instead of Dinput.lib.
To create a DirectX 8.x interface with the DirectX 8.x SDK without using CoCreateInstance:
Call DirectInput8Create instead of DirectInputCreateEx.
Link to the Dinput8.lib library instead of Dinput.lib.
To create a DirectX 7.0 interface from the DirectX 8.x or latest DirectX SDK without using CoCreateInstance:
Set \"#define
Call DirectInputCreateEx instead of DirectInput8Create.
Link to the Dinput.lib library instead of Dinput8.lib.
To create a DirectX 7.0 interface from the DirectX 8.x or latest DirectX SDK using CoCreateInstance:
Call CoInitializeEx.
Call CoCreateInstance using CLISID_DirectInput.
Use IDirectInput7::Initialize to initialize the DirectInput object.
To create a DirectX 8.x or DirectX 9.0 interface from the DirectX 8.x or latest DirectX SDK using CoCreateInstance:
Call CoInitializeEx.
Call CoCreateInstance using CLISID_DirectInput8.
Use
Calling the function with pUnkOuter =
Calling the function with pUnkOuter !=
The ftTimeStamp member can contain special values that apply to new and unused devices. New devices have never been enumerated for this application and have never had an action map applied to them. Unused devices have been enumerated for the application before but have never had an action map applied. New devices always have DIAFTS_NEWDEVICELOW and DIAFTS_NEWDEVICEHIGH in the low and high DWORDs respectively of the
Applications should not use ftTimeStamp to check for new devices. Instead, they should look for the DIEDBS_RECENTDEVICE and DIEDBS_NEWDEVICE flags in the enumeration callback. For more information, see DIEnumDevicesBySemanticsCallback.
\t\nA reference to an array of
Different types of conditions interpret the parameters differently, but the basic idea is that force resulting from a condition is equal to A(q - q0) where A is a scaling coefficient, q is some metric, and q0 is the neutral value for that metric.
The preceding simplified formula must be adjusted if a nonzero deadband is provided. If the metric is less than lOffset - lDeadBand, the resulting force is given by the following formula:
force = lNegativeCoefficient * ( q - ( lOffset - lDeadBand))
Similarly, if the metric is greater than lOffset + lDeadBand, the resulting force is given by the following formula:
force = lPositiveCoefficient * ( q - ( lOffset + lDeadBand))
A spring condition uses axis position as the metric.
A damper condition uses axis velocity as the metric.
An inertia condition uses axis acceleration as the metric.
If the number of
If there is a single
Because each driver implements different escapes, it is the application's responsibility to ensure that it is talking to the correct driver by comparing the guidFFDriver member in the
The system time returned in dwTimeStamp comes from the same clock used by the Microsoft Win32 GetTickCount or timeGetTime functions, but it produces potentially more precise values. For example, on Microsoft Windows 95, the GetTickCount timer is updated only every 55 milliseconds, but the dwTimeStamp value is accurate to within 1 millisecond. Therefore, if you call GetTickCount and it returns n, and you then receive an event with a timestamp of n + n1, you cannot assume that the event took place exactly n1 milliseconds after the call to GetTickCount.
\t\nThe diph member must be initialized as follows:
| Member \t\n | Value \t\n |
|---|---|
| dwSize \t\n | sizeof( |
| dwHeaderSize \t\n | sizeof( |
| dwObj \t\n | For this structure, this member must be set to 0.\t\n |
| dwHow \t\n | Specifies how the dwObj member should be interpreted. For this structure, dwHow should be |
The
The application calls the
The diph member must be initialized as follows:
| Member \t\n | Value \t\n |
|---|---|
| dwSize \t\n | sizeof( |
| dwHeaderSize \t\n | sizeof( |
| dwObj \t\n | If the dwHow member is If the dwHow member is If the dwHow member is If the dwHow member is |
| dwHow \t\n | Specifies how the dwObj member should be interpreted. See the preceding description of the dwObj member for details.\t\n |
The diph member must be initialized as follows:
| Member \t\n | Value \t\n |
|---|---|
| dwSize \t\n | sizeof( |
| dwHeaderSize \t\n | sizeof( |
| dwObj \t\n | If the dwHow member is If the dwHow member is If the dwHow member is If the dwHow member is |
| dwHow \t\n | Specifies how the dwObj member should be interpreted. See the preceding description of the dwObj member for details. \t\n |
The diph member must be initialized as follows:
| Member\t\n | Value\t\n |
|---|---|
| dwSize \t\n | sizeof( |
| dwHeaderSize \t\n | sizeof( |
| dwObj \t\n | If the dwHow member is If the dwHow member is If the dwHow member is If the dwHow member is |
| dwHow \t\n | Specifies how the dwObj member should be interpreted. See the preceding description of the dwObj member for details.\t\n |
The range values for devices whose ranges are unrestricted wraparound.
\t\nThe diph member must be initialized as follows:
| Member\t\n | Value\t\n |
|---|---|
| dwSize \t\n | sizeof( |
| dwHeaderSize \t\n | sizeof( |
| dwObj \t\n | If the dwHow member is If the dwHow member is If the dwHow member is If the dwHow member is |
| dwHow \t\n | Specifies how the dwObj member should be interpreted. See the preceding description of the dwObj member for details. \t\n |
The
The structure describes a constant force effect.
A reference to a single
The structure describes a custom or user-defined force.
A reference to a
The structure describes a periodic effect.
A reference to a single
A device driver cannot provide support for all values in the dwPhase member. In this case, the value is rounded off to the nearest supported value.
\t\nA reference to a single
The dwDuration for a ramp force effect cannot be INFINITE.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_UNSUPPORTED |
| DSERR_OUTOFMEMORY |
| Value | Description |
| The buffer is capturing audio data. | |
| The buffer is looping. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
| Value | Description |
| DSCBLOCK_ENTIREBUFFER | Ignore dwBytes and lock the entire capture buffer. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values:
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_INVALIDCALL |
This method accepts an offset and a byte count, and returns two read references and their associated sizes. If the locked portion does not extend to the end of the buffer and wrap to the beginning, the second reference, ppvAudioBytes2, receives
If the application passes
The application should read data from the references returned by this method and then immediately call Unlock. The sound buffer should not remain locked while it is running; if it does, the capture cursor will reach the locked bytes and audio problems may result.
\t\n| Value | Description |
| DSCBSTART_LOOPING | After the end of the buffer is reached, capture restarts at the beginning and continues until explicitly stopped. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_NODRIVER |
| DSERR_OUTOFMEMORY |
If the buffer is already capturing, a call to this method using a different value in dwFlags might not change the value returned by GetStatus.
If the application is multithreaded, the thread that starts the buffer must continue to exist as long as the buffer is capturing. Buffers created on WDM drivers stop capturing when the thread is terminated.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_CONTROLUNAVAIL |
| DSERR_INVALIDPARAM |
| DSERR_OBJECTNOTFOUND |
The value in dwIndex is the index of the object within the array of effects in the
| Value | Description |
| DSCFXR_LOCHARDWARE | Effect is instantiated in hardware. |
| DSCFXR_LOCSOFTWARE | Effect is instantiated in software. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
| Value\t\n | Description\t\n |
|---|---|
| Effect specified by guidDSCFXInstance must be in hardware.\t\n | |
| Effect specified by guidDSCFXInstance must be in software.\t\n |
On return, this member can contain one of the values shown in the following table.
| Value\t\n | Description\t\n |
|---|---|
| Effect was created in hardware.\t\n | |
| Effect was created in software.\t\n |
| Value\t\n | Description\t\n |
|---|---|
| Acoustic echo cancellation.\t\n | |
| Noise suppression.\t\n |
| Value\t\n | Description\t\n |
|---|---|
| Microsoft acoustic echo cancellation. Available in software only.\t\n | |
| Microsoft noise suppression. Available in software only.\t\n | |
| System default acoustic echo cancellation.\t\n | |
| System default noise suppression.\t\n |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
If the method succeeds, the return value is DS_OK, or DS_NO_VIRTUALIZATION if a requested 3D algorithm was not available and stereo panning was substituted. See the description of the guid3DAlgorithm member of
| Return code |
| DSERR_ALLOCATED |
| DSERR_BADFORMAT |
| DSERR_BUFFERTOOSMALL |
| DSERR_CONTROLUNAVAIL |
| DSERR_DS8_REQUIRED |
| DSERR_INVALIDCALL |
| DSERR_INVALIDPARAM |
| DSERR_NOAGGREGATION |
| DSERR_OUTOFMEMORY |
| DSERR_UNINITIALIZED |
| DSERR_UNSUPPORTED |
DirectSound does not initialize the contents of the buffer, and the application cannot assume that it contains silence.
If an attempt is made to create a buffer with the
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the error values shown in the following table.
| Return code |
| DSERR_GENERIC |
| DSERR_INVALIDPARAM |
| DSERR_UNINITIALIZED |
Information retrieved in the
Because of resource-sharing requirements, the maximum capabilities in one area might be available only at the cost of another area.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the error values shown in the following table.
| Return code |
|---|
| DSERR_INVALIDPARAM |
| DSERR_UNINITIALIZED |
The value returned at pdwSpeakerConfig can be a packed DWORD containing both configuration and geometry information. Use the DSSPEAKER_CONFIG and DSSPEAKER_GEOMETRY macros to unpack the DWORD, as in the following example:
if (DSSPEAKER_CONFIG(dwSpeakerConfig) ==) { if (DSSPEAKER_GEOMETRY(dwSpeakerConfig) == ) { // Configuration is wide stereo. ...} }
To use #defines implemented in Windows Vista, set the DIRECTSOUND_VERSION to 0x1000 before including dsound.h.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the error values shown in the following table.
| Return code |
|---|
| DSERR_INVALIDPARAM |
| DSERR_UNINITIALIZED |
In Windows Vista and later versions of Windows, SetSpeakerConfig is a NOP. For Windows Vista and later versions, the speaker configuration is a system setting that should not be modified by an application. End users can set the speaker configuration through control panels.
Speaker ConfigurationsThese tables contain the possible speaker configurations.
| Value\t\n | Description\t\n |
|---|---|
| The audio is played through a speaker arrangement of five surround speakers with a subwoofer. ( | |
| The audio is played through a home theater speaker arrangement of five surround speakers with a subwoofer. This value applies to Windows Vista or later.\t\n | |
| The audio is passed through directly, without being configured for speakers.\t\n | |
| The audio is played through headphones.\t\n | |
| The audio is played through a single speaker.\t\n | |
| The audio is played through quadraphonic speakers.\t\n | |
| The audio is played through stereo speakers (default value).\t\n | |
| The audio is played through surround speakers.\t\n | |
| The audio is played through a wide speaker arrangement of seven surround speakers with a subwoofer. ( | |
| The audio is played through a home theater speaker arrangement of seven surround speakers with a subwoofer. This value applies to Windows XP SP2 or later.\t\n |
| Value\t\n | Description\t\n |
|---|---|
| The speakers are directed over an arc of 20 degrees.\t\n | |
| The speakers are directed over an arc of 10 degrees.\t\n | |
| The speakers are directed over an arc of 5 degrees.\t\n | |
| The speakers are directed over an arc of 180 degrees.\t\n |
If a geometry value is to be used, it must be packed in a DWORD along with the
lpds->SetSpeakerConfig(DSSPEAKER_COMBINED(, ));
To use #defines implemented in Windows Vista, set the DIRECTSOUND_VERSION to 0x1000 before including dsound.h.
\t\nInformation retrieved in the
Because of resource-sharing requirements, the maximum capabilities in one area might be available only at the cost of another area.
\t\n| Value | Description |
| DS_CERTIFIED | Driver is certified for DirectSound. |
| DS_UNCERTIFIED | Driver is not certified for DirectSound. |
If the function succeeds, the return value is DS_OK.
If the function fails, the return value may be one of the error values shown in the following table.
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_UNSUPPORTED |
This method may attempt to retrieve certification information from the Internet.
On emulated devices, the method returns DSERR_UNSUPPORTED. Emulated devices are identified by the
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values.
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_BADFORMAT |
| DSERR_GENERIC |
| DSERR_NODRIVER |
| DSERR_OUTOFMEMORY |
| DSERR_UNINITIALIZED |
On Microsoft Windows98 and Windows2000, each capture device supports a single buffer.
The
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_UNSUPPORTED |
| DSERR_NODRIVER |
| DSERR_OUTOFMEMORY |
| DSERR_UNINITIALIZED |
If the method succeeds, the return value is DS_OK or S_FALSE. See the Remarks for
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
If the method succeeds, the return value is DS_OK.
If the method fails, the return value may be DSERR_INVALIDPARAM.
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The minimum, maximum, and default cone angles are defined in Dsound.h as DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, and DS3D_DEFAULTCONEANGLE.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The values returned are not necessarily the same as those set by using the SetConeOrientation method. DirectSound normalizes orientation vectors so that all axes have a magnitude of less than or equal to 1.0.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
Volume levels are expressed as attenuation, in hundredths of a decibel. Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). The default value is DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation). These values are defined in Dsound.h. DirectSound does not support amplification.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The default maximum distance, defined as DS3D_DEFAULTMAXDISTANCE, is effectively infinite.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
By default, the minimum distance value is DS3D_DEFAULTMINDISTANCE, defined as 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 meters per unit).
\t\n| Value | Description |
| Processing of 3D sound is disabled. The sound seems to originate from the center of the listener's head. | |
| Sound parameters (position, velocity, and orientation) are relative to the listener's parameters. In this mode, the absolute parameters of the sound are updated automatically as the listener's parameters change, so that the relative parameters remain constant. | |
| Normal processing. This is the default mode. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
Velocity is used for Doppler effects only. It does not actually move the buffer. For more information, see Doppler Effect.
The default unit of measurement is meters per second, but this can be changed by using the SetDistanceFactor method.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The minimum, maximum, and default cone angles are defined in Dsound.h as DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, and DS3D_DEFAULTCONEANGLE. Each angle must be in the range of 0 degrees (no cone) to 360 degrees (the full sphere). The default value is 360.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
This method has no effect unless the cone angle and cone outside volume have also been set to values other than the default.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
Volume levels are represented by attenuation. Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). The default value is DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation). These values are defined in Dsound.h. DirectSound does not support amplification.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The default maximum distance, defined as DS3D_DEFAULTMAXDISTANCE, is effectively infinite.
The default unit of measurement is meters, but this can be changed by using the SetDistanceFactor method.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
By default, the minimum distance value is DS3D_DEFAULTMINDISTANCE, defined as 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 meters per unit).
The default unit of measurement is meters, but this can be changed by using the SetDistanceFactor method.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The default unit of measurement is meters, but this can be changed by using the SetDistanceFactor method.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
Velocity is used only for calculating Doppler effect. It does not change the position of the buffer. For more information, see Doppler Effect.
The default unit of measurement is meters per second, but this can be changed by using the SetDistanceFactor method.
\t\nCustom effects can be implemented as DMOs. Effect DMOs must implement the
If dwFlags is zero, the effect is placed in hardware if possible. If the hardware does not support the effect (always the case since DirectX 9.0), software is used. If the effect is not available at all, the call to SetFX fails.
\t\n| Value\t\n | Description\t\n |
|---|---|
| DSFX_LOCHARDWARE\t\n | Effect must be in hardware. If the effect is not available in hardware, |
| DSFX_LOCSOFTWARE\t\n | Effect must be in software, even if the hardware supports acceleration of guidDSFXClass. If the effect is not available in software, SetFX raises an error. Since DirectX 9.0, all effects are in software regardless of whether this flag is set.\t\n |
| Value\t\n | Description\t\n |
|---|---|
| Chorus\t\n | |
| Compressor\t\n | |
| Distortion\t\n | |
| Echo\t\n | |
| Flanger\t\n | |
| Gargle\t\n | |
| Interactive 3D Level 2 reverb\t\n | |
| Parametric equalizer\t\n | |
| Waves reverb\t\n |
| Value | Description |
|---|---|
| DSDEVID_DefaultPlayback | System-wide default audio playback device. |
| DSDEVID_DefaultCapture | System-wide default audio capture device. |
| DSDEVID_DefaultVoicePlayback | Default voice playback device. |
| DSDEVID_DefaultVoiceCapture | Default voice capture device. |
If the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.
If pGuidSrc points to a valid device identifier, the same value is returned in pGuidDest. If pGuidSrc is one of the listed constants, pGuidDest returns the address of the corresponding device
If the function succeeds, it returns DS_OK. If it fails, the return value may be one of the following values.
| Return Code |
|---|
| DSERR_ALLOCATED |
| DSERR_INVALIDPARAM |
| DSERR_NOAGGREGATION |
| DSERR_OUTOFMEMORY |
On sound cards that do not support full duplex, this method will fail and return DSERR_ALLOCATED.
\t\nThe DirectSoundFullDuplexCreate function is documented under a different name. For complete documentation of this function, see DirectSoundFullDuplexCreate8.
\t\nIf this function succeeds, it returns
If the function succeeds, it returns DS_OK. If it fails, the return value may be one of the following.
| Return Code |
|---|
| DSERR_ALLOCATED |
| DSERR_INVALIDPARAM |
| DSERR_NOAGGREGATION |
| DSERR_NODRIVER |
| DSERR_OUTOFMEMORY |
The application must call the IDirectSound8::SetCooperativeLevel method immediately after creating a device object.
\t\nIf the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.
If the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.
| Constant | Value |
| 0x0 | |
| 0x1 | |
| 0x2 | |
| 0x8 |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values.
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_OUTOFMEMORY |
| Windows |
|---|
Important Note for Windows Vista Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio. To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK. |
The three least significant bits in *pdwStatus describe the convergence history; that is, the success of the effect in canceling the echo. The convergence history can be used by the application to determine if the algorithm has converged and remained in the converged state since it started processing data.
Initially, the AEC algorithm sets the three lower bits to 0 for the uninitialized state (
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_OUTOFMEMORY.
| Windows |
|---|
Important Note for Windows Vista Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio. To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK. |
Applications should not reset an effect except when necessary because it has entered an incorrect state. This might be done in response to user input. An effect must not be reset arbitrarily at startup, because another application might be using the same effect.
\t\n| Windows |
|---|
Important Note for Windows Vista Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio. To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK. |
The three least significant bits in *pdwStatus describe the convergence history; that is, the success of the effect in canceling the echo. The convergence history can be used by the application to determine if the algorithm has converged and remained in the converged state since it started processing data.
Initially, the AEC algorithm sets the three lower bits to 0 for the uninitialized state (
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_OUTOFMEMORY.
| Windows |
|---|
Important Note for Windows Vista Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio. To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK. |
Applications should not reset an effect except when necessary because it has entered an incorrect state. This might be done in response to user input. An effect must not be reset arbitrarily at startup, because another application might be using the same effect.
\t\nIf the method succeeds, the return value is DS_OK or S_FALSE. See the Remarks for
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_PRIOLEVELNEEDED |
The write cursor is the point in the buffer ahead of which it is safe to write data to the buffer. Data should not be written to the part of the buffer after the play cursor and before the write cursor.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The format structure can have a variable length that depends on the format. Before retrieving the format description, the application should query the buffer object for the size of the format by calling this method and specifying
| Value | Description |
| The buffer is lost and must be restored before it can be played or locked. | |
| The buffer is being looped. If this value is not set, the buffer will stop when it reaches the end of the sound data. This value is returned only in combination with | |
| The buffer is playing. If this value is not set, the buffer is stopped. | |
| The buffer is playing in software. Set only for buffers created with the | |
| The buffer is playing in hardware. Set only for buffers created with the | |
| The buffer was prematurely terminated by the voice manager and is not playing. Set only for buffers created with the |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_BADFORMAT |
| DSERR_INVALIDCALL |
| DSERR_INVALIDPARAM |
| DSERR_OUTOFMEMORY |
| DSERR_PRIOLEVELNEEDED |
| DSERR_UNSUPPORTED |
The format of the primary buffer should be set before secondary buffers are created.
The method fails if the application has the
If the application is using DirectSound at the
If the cooperative level is
This method is not available for secondary sound buffers. If a new format is required, the application must create a new DirectSoundBuffer object.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_CONTROLUNAVAIL |
| DSERR_GENERIC |
| DSERR_INVALIDPARAM |
| DSERR_PRIOLEVELNEEDED |
Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). These values are defined in Dsound.h as 0 and ?10,000 respectively. The value DSBVOLUME_MAX represents the original, unadjusted volume of the stream. The value DSBVOLUME_MIN indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. DirectSound does not support amplification.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_CONTROLUNAVAIL |
| DSERR_GENERIC |
| DSERR_INVALIDPARAM |
| DSERR_PRIOLEVELNEEDED |
Increasing or decreasing the frequency changes the perceived pitch of the audio data. This method does not affect the format of the buffer.
Before setting the frequency, you should ascertain whether the frequency is supported by checking the dwMinSecondarySampleRate and dwMaxSecondarySampleRate members of the
This method is not valid for the primary buffer.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_INVALIDCALL |
| DSERR_INVALIDPARAM |
| DSERR_PRIOLEVELNEEDED |
An application must pass both references, pvAudioPtr1 and pvAudioPtr2, returned by the IDirectSoundBuffer8::Lock method to ensure the correct pairing of IDirectSoundBuffer8::Lock and IDirectSoundBuffer8::Unlock. The second reference is needed even if nothing was written to the second reference.
The values in dwAudioBytes1 and dwAudioBytes2 must specify the number of bytes actually written to each part of the buffer, which might be less than the size of the lock. DirectSound uses these values to determine how much data to commit to the device.
\t\nFor this method to succeed, CoInitialize must have been called. Additionally, the buffer must not be playing or locked.
\t\n| Note |
|---|
| This parameter must be |
| Value | Description |
|---|---|
| Effect is instantiated in hardware. | |
| Effect is instantiated in software. | |
| Effect has not yet been assigned to hardware or software. This value is returned if the buffer was created with the | |
| No effect was created because resources weren't available. | |
| Effect is available but was not created because one of the other effects requested could not be created. If any of the effects requested cannot be created, none of them are, and the call fails. | |
| Effect is not registered on the system, and the method failed as a result. |
If the method succeeds, the return value is DS_OK or DS_INCOMPLETE. If the method fails, the return value may be one of the error values shown in the following table.
| Return code |
|---|
| CO_E_NOTINITIALIZED |
| DSERR_CONTROLUNAVAIL |
| DSERR_GENERIC |
| DSERR_INVALIDPARAM |
| DSERR_INVALIDCALL |
| DSERR_NOINTERFACE |
| DSERR_PRIOLEVELNEEDED |
In addition, the method can return an error value from DMO methods, including
If the method fails, the value for each effect in pdwResultCodes is either DSFXF_PRESENT or
For the method to succeed, the buffer must have been created with the
If the method returns DSERR_NOINTERFACE or another COM error, check the result code array for
An effect must be set on a buffer before the effect interface can be obtained. To obtain the effect interface, use GetObjectInPath.
\t\nIf the method succeeds, the return value is DS_OK or DS_INCOMPLETE. If the method fails, the return value may be one of the error values shown in the following table.
| Return code |
|---|
| DSERR_CONTROLUNAVAIL |
| DSERR_INVALIDCALL |
| DSERR_INVALIDPARAM |
Normally, buffers created with
A buffer with acquired resources that is not yet playing is not a candidate for premature termination by the voice management flags passed to the Play method.
Resources that have been acquired by AcquireResources are released when playback is stopped.
If the method is called on a buffer on which it has already been called, the status of the effects is returned but no additional resources are allocated.
The dwEffectsCount parameter to this function must be the same as the one passed in the call to SetFX.
If an attempt is made to acquire resources for a buffer with the
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_CONTROLUNAVAIL |
| DSERR_INVALIDPARAM |
| DSERR_OBJECTNOTFOUND |
Any DMO that has been set on a buffer by using SetFX can be retrieved, even it has not been allocated resources.
The following interfaces can be retrieved for the various DMOs supplied with DirectX.
| rguidInterface\t\n | *ppObject\t\n |
| IID_IDirectSoundFXGargle8\t\n | IDirectSoundFXGargle8 |
| IID_IDirectSoundFXChorus8\t\n | IDirectSoundFXChorus8 |
| IID_IDirectSoundFXFlanger8\t\n | IDirectSoundFXFlanger8 |
| IID_IDirectSoundFXEcho8\t\n | IDirectSoundFXEcho8 |
| IID_IDirectSoundFXDistortion8\t\n | IDirectSoundFXDistortion8 |
| IID_IDirectSoundFXCompressor8\t\n | IDirectSoundFXCompressor8 |
| IID_IDirectSoundFXParamEq8\t\n | IDirectSoundFXParamEq8 |
| IID_IDirectSoundFXWavesReverb8\t\n | IDirectSoundFXWavesReverb8 |
| IID_IDirectSoundFXI3DL2Reverb8\t\n | IDirectSoundFXI3DL2Reverb8 |
In addition, the following interfaces are available for any of the standard DMOs. For information on these interfaces, see the Help for DirectX Media Objects.
| rguidInterface\t\n | *ppObject\t\n |
| IID_IMediaObject\t\n | |
| IID_IMediaObjectInPlace\t\n | |
| IID_IMediaParams\t\n | IMediaParams\t\n |
NoteWhen the DirectSound API is used to play buffers, parameter curves (envelopes) set by using the IMediaParams interface do not work, because DirectSound does not timestamp the DMO buffers.
The value in dwIndex is the index of the object within the array of effects passed to SetFX. This is not necessarily the actual position of the object in the effects chain, because some effects might not have been created.
An object is returned solely on the basis of whether it matches rguidObject and dwIndex. It is up to the application to ensure that rguidInterface specifies an interface that can be expected to be found on the object.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The Doppler factor has a range of DS3D_MINDOPPLERFACTOR (no Doppler effects) to DS3D_MAXDOPPLERFACTOR (defined as 10 times the Doppler effects found in the real world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The rolloff factor has a range of DS3D_MINROLLOFFFACTOR (no rolloff) to DS3D_MAXROLLOFFFACTOR (defined as 10 times the rolloff found in the real world). The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0). For more information, see Rolloff Factor.
\t\nIf the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
Velocity is used only for calculating Doppler effect. It does not change the listener's position. To move the listener, use the SetPosition method.
The default velocity is (0,0,0).
By default, measurement units are meters per second, but this can be changed by calling the SetDistanceFactor method.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The distance factor has a range of DS3D_MINDISTANCEFACTOR to DS3D_MAXDISTANCEFACTOR, defined in Dsound.h as FLT_MIN and FLT_MAX respectively. The default value is DS3D_DEFAULTDISTANCEFACTOR, or 1.0.
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The Doppler factor has a range of DS3D_MINDOPPLERFACTOR (no Doppler effects) to DS3D_MAXDOPPLERFACTOR (defined as 10 times the Doppler effects found in the real world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).
\t\n| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers. |
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.
The rolloff factor has a range of DS3D_MINROLLOFFFACTOR (no rolloff) to DS3D_MAXROLLOFFFACTOR (defined as 10 times the rolloff found in the real world). The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0). For more information, see Rolloff Factor.
\t\nIf the method succeeds, the return value is DS_OK.
The dwMode member is ignored when this structure is passed to IDirectSoundCaptureFXAec8::SetAllParameters.
| Windows |
|---|
Important Note for Windows Vista Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio. To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK. |
| Value\t\n | Description\t\n |
|---|---|
| The effect is passing capture and render data through without modifying it.\t\n | |
| The effect is running in half duplex mode. Not presently supported.\t\n | |
| The effect is running in full duplex mode.\t\n |
The values in fPostEQBandwidth, fPostEQCenterFrequency, and fPreLowpassCutoff cannot exceed one-third of the frequency of the buffer. If an attempt is made to set a value greater than this, but within the range of accepted values, the parameter is set to the nearest supported value and S_FALSE is returned by IDirectSoundFXDistortion8::SetAllParameters.
\t\n| Value\t\n | Description\t\n |
|---|---|
| DSFXFLANGER_WAVE_TRIANGLE\t\n | Triangle.\t\n |
| DSFXFLANGER_WAVE_SIN\t\n | Sine.\t\n |
| Value\t\n |
|---|
| DSFXFLANGER_PHASE_NEG_180\t\n |
| DSFXFLANGER_PHASE_NEG_90\t\n |
| DSFXFLANGER_PHASE_ZERO\t\n |
| DSFXFLANGER_PHASE_90\t\n |
| DSFXFLANGER_PHASE_180\t\n |
The default value is DSFXFLANGER_PHASE_ZERO.
| Value\t\n | Description\t\n |
|---|---|
| DSFXGARGLE_WAVE_TRIANGLE\t\n | Triangular waveform.\t\n |
| DSFXGARGLE_WAVE_SQUARE\t\n | Square waveform.\t\n |
The default value is DSFXGARGLE_WAVE_TRIANGLE.
| Value\t\n |
|---|
| DSFXCHORUS_PHASE_NEG_180\t\n |
| DSFXCHORUS_PHASE_NEG_90\t\n |
| DSFXCHORUS_PHASE_ZERO\t\n |
| DSFXCHORUS_PHASE_90\t\n |
| DSFXCHORUS_PHASE_180\t\n |
The default value is DSFXCHORUS_PHASE_90.
| Windows |
|---|
Important Note for Windows Vista Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio. To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK. |
The value in fCenter cannot exceed one-third of the sampling frequency of the buffer. If an attempt is made to set a value greater than this, but within the range of accepted values, the parameter is set to the nearest supported value and S_FALSE is returned by IDirectSoundFXParamEq8::SetAllParameters.
\t\nAn earlier version of this structure, DSBUFFERDESC1, is maintained in Dsound.h for compatibility with DirectX 7 and earlier.
\t\nWhen creating a primary buffer, applications must set the dwBufferBytes member to zero. DirectSound will determine the best buffer size for the particular sound device in use. To determine the size of a created primary buffer, call IDirectSoundBuffer8::GetCaps.
The DSBCAPS_CTRLDEFAULT flag is no longer supported. This flag was defined as
On VXD drivers, a sound buffer created with
The
The 3D algorithms represent selection of the software emulation layer only: that is, the software algorithm that is used when no hardware is present for acceleration. In order to maximize hardware utilization,
If a free hardware 3D voice is available, that 3D hardware voice is used.
If no free hardware 3D voices are available and a 2D hardware voice is available, that 2D hardware voice will be used. This is possible because the
If no free 2D or 3D hardware voices are available, the voice will be played in software using the
If a speaker configuration other than
If a buffer is created using one of the HRTF algorithms, and the HRTF algorithm is not available on the system (for example, a non-WDM system), a success code, DS_NO_VIRTUALIZATION, is returned. The sound buffer created will use
Applies to: desktop apps | Metro style apps
Represents a byte stream from some data source, which might be a local file, a network file, or some other source. The
The following functions return
A byte stream for a media souce can be opened with read access. A byte stream for an archive media sink should be opened with both read and write access. (Read access may be required, because the archive sink might need to read portions of the file as it writes.)
Some implementations of this interface also expose one or more of the following interfaces:
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents a byte stream from some data source, which might be a local file, a network file, or some other source. The
The following functions return
A byte stream for a media souce can be opened with read access. A byte stream for an archive media sink should be opened with both read and write access. (Read access may be required, because the archive sink might need to read portions of the file as it writes.)
Some implementations of this interface also expose one or more of the following interfaces:
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Reads data from the stream.
\t\nPointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
This method reads at most cb bytes from the current position in the stream and copies them into the buffer provided by the caller. The number of bytes that were read is returned in the pcbRead parameter. The method does not return an error code on reaching the end of the file, so the application should check the value in pcbRead after the method returns.
This method is synchronous. It blocks until the read operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous read operation from the stream.
\t\nPointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been read into the buffer, the callback object's
Do not read from, write to, free, or reallocate the buffer while an asynchronous read is pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous read operation.
\t\n Pointer to the
Call this method after the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Writes data to the stream.
\t\nPointer to a buffer that contains the data to write.
Size of the buffer in bytes.
Receives the number of bytes that are written.
If this method succeeds, it returns
This method writes the contents of the pb buffer to the stream, starting at the current stream position. The number of bytes that were written is returned in the pcbWritten parameter.
This method is synchronous. It blocks until the write operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous write operation to the stream.
\t\nPointer to a buffer containing the data to write.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been written to the stream, the callback object's
Do not reallocate, free, or write to the buffer while an asynchronous write is still pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous write operation.
\t\nPointer to the
Call this method when the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Moves the current position in the stream by a specified offset.
\t\n Specifies the origin of the seek as a member of the
Specifies the new position, as a byte offset from the seek origin.
Specifies zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| All pending I/O requests are canceled after the seek request completes successfully. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Clears any internal buffers used by the stream. If you are writing to the stream, the buffered data is written to the underlying file or device.
\t\nIf this method succeeds, it returns
If the byte stream is read-only, this method has no effect.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Closes the stream and releases any resources associated with the stream, such as sockets or file handles. This method also cancels any pending asynchronous I/O requests.
\t\nIf this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the byte stream.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the stream.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current read or write position in the stream.
\t\nThe methods that update the current position are Read, BeginRead, Write, BeginWrite, SetCurrentPosition, and Seek.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the current position has reached the end of the stream.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Reads data from the stream.
\t\nPointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
This method reads at most cb bytes from the current position in the stream and copies them into the buffer provided by the caller. The number of bytes that were read is returned in the pcbRead parameter. The method does not return an error code on reaching the end of the file, so the application should check the value in pcbRead after the method returns.
This method is synchronous. It blocks until the read operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous read operation from the stream.
\t\nPointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been read into the buffer, the callback object's
Do not read from, write to, free, or reallocate the buffer while an asynchronous read is pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous read operation.
\t\n Pointer to the
Call this method after the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Writes data to the stream.
\t\nPointer to a buffer that contains the data to write.
Size of the buffer in bytes.
This method writes the contents of the pb buffer to the stream, starting at the current stream position. The number of bytes that were written is returned in the pcbWritten parameter.
This method is synchronous. It blocks until the write operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous write operation to the stream.
\t\nPointer to a buffer containing the data to write.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been written to the stream, the callback object's
Do not reallocate, free, or write to the buffer while an asynchronous write is still pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous write operation.
\t\nPointer to the
Call this method when the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Moves the current position in the stream by a specified offset.
\t\n Specifies the origin of the seek as a member of the
Specifies the new position, as a byte offset from the seek origin.
Specifies zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| All pending I/O requests are canceled after the seek request completes successfully. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Clears any internal buffers used by the stream. If you are writing to the stream, the buffered data is written to the underlying file or device.
\t\nIf this method succeeds, it returns
If the byte stream is read-only, this method has no effect.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Closes the stream and releases any resources associated with the stream, such as sockets or file handles. This method also cancels any pending asynchronous I/O requests.
\t\nIf this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the byte stream.
\t\nReceives a bitwise OR of zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| The byte stream can be read. |
| The byte stream can be written to. |
| The byte stream can be seeked. |
| The byte stream is from a remote source, such as a network. |
| The byte stream represents a file directory. |
| Seeking within this stream might be slow. For example, the byte stream might download from a network. |
| The byte stream is currently downloading data to a local cache. Read operations on the byte stream might take longer until the data is completely downloaded. This flag is cleared after all of the data has been downloaded. If the MFBYTESTREAM_HAS_SLOW_SEEK flag is also set, it means the byte stream must download the entire file sequentially. Otherwise, the byte stream can respond to seek requests by restarting the download from a new point in the stream. |
| Another thread or process can open this byte stream for writing. If this flag is present, the length of thebyte stream could change while it is being read. This flag can affect the behavior of byte-stream handlers. For more information, see Note??Requires Windows?7 or later. |
?
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the stream.
\t\nReceives the length of the stream, in bytes. If the length is unknown, this value is -1.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the length of the stream.
\t\nLength of the stream in bytes.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current read or write position in the stream.
\t\nReceives the current position, in bytes.
If this method succeeds, it returns
The methods that update the current position are Read, BeginRead, Write, BeginWrite, SetCurrentPosition, and Seek.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the current read or write position.
\t\nNew position in the stream, as a byte offset from the start of the stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
?
If the new position is larger than the length of the stream, the method returns E_INVALIDARG.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the current position has reached the end of the stream.
\t\n Receives the value TRUE if the end of the stream has been reached, or
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Reads data from the stream.
\t\nPointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Receives the number of bytes that are copied into the buffer. This parameter cannot be
If this method succeeds, it returns
This method reads at most cb bytes from the current position in the stream and copies them into the buffer provided by the caller. The number of bytes that were read is returned in the pcbRead parameter. The method does not return an error code on reaching the end of the file, so the application should check the value in pcbRead after the method returns.
This method is synchronous. It blocks until the read operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous read operation from the stream.
\t\nPointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been read into the buffer, the callback object's
Do not read from, write to, free, or reallocate the buffer while an asynchronous read is pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous read operation.
\t\n Pointer to the
Receives the number of bytes that were read.
If this method succeeds, it returns
Call this method after the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Writes data to the stream.
\t\nPointer to a buffer that contains the data to write.
Size of the buffer in bytes.
Receives the number of bytes that are written.
If this method succeeds, it returns
This method writes the contents of the pb buffer to the stream, starting at the current stream position. The number of bytes that were written is returned in the pcbWritten parameter.
This method is synchronous. It blocks until the write operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous write operation to the stream.
\t\nPointer to a buffer containing the data to write.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been written to the stream, the callback object's
Do not reallocate, free, or write to the buffer while an asynchronous write is still pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous write operation.
\t\nPointer to the
Receives the number of bytes that were written.
If this method succeeds, it returns
Call this method when the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Moves the current position in the stream by a specified offset.
\t\n Specifies the origin of the seek as a member of the
Specifies the new position, as a byte offset from the seek origin.
Specifies zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| All pending I/O requests are canceled after the seek request completes successfully. |
?
Receives the new position after the seek.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Clears any internal buffers used by the stream. If you are writing to the stream, the buffered data is written to the underlying file or device.
\t\nIf this method succeeds, it returns
If the byte stream is read-only, this method has no effect.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Closes the stream and releases any resources associated with the stream, such as sockets or file handles. This method also cancels any pending asynchronous I/O requests.
\t\nIf this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the byte stream.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the stream.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current read or write position in the stream.
\t\nThe methods that update the current position are Read, BeginRead, Write, BeginWrite, SetCurrentPosition, and Seek.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the current position has reached the end of the stream.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Specifies how the output alpha values are calculated for Microsoft DirectX Video Acceleration High Definition (DXVA-HD) blit operations.
\t\nThe Mode member of the
To find out which modes the device supports, call the
Alpha values inside the target rectangle are set to opaque.
Alpha values inside the target rectangle are set to the alpha value specified in the background color. See
Existing alpha values remain unchanged in the output surface.
Alpha values from the input stream are scaled and copied to the corresponding destination rectangle for that stream. If the input stream does not have alpha data, the DXVA-HD device sets the alpha values in the target rectangle to an opaque value. If the input stream is disabled or the source rectangle is empty, the alpha values in the target rectangle are not modified.
Applies to: desktop apps only
Specifies whether the output is downsampled in a blit operation, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nIf the Enable member is TRUE, the device downsamples the composed target rectangle to the size given in the Size member, and then scales it back to the size of the target rectangle.
The width and height of Size must be greater than zero. If the size is larger than the target rectangle, downsampling does not occur.
To use this state, the device must support downsampling, indicated by the
If the device does not support downsampling, the
Downsampling is sometimes used to reduce the quality of premium content when other forms of content protection are not available.
\t\nIf TRUE, downsampling is enabled. Otherwise, downsampling is disabled and the Size member is ignored. The default state value is
The sampling size. The default value is (1,1).
Applies to: desktop apps only
Defines video processing capabilities for a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe device can blend video content in linear color space. Most video content is gamma corrected, resulting in nonlinear values. If the DXVA-HD device sets this flag, it means the device converts colors to linear space before blending, which produces better results.\t\n
The device supports the xvYCC color space for YCbCr data.
The device can perform range conversion when the input and output are both RGB but use different color ranges (0-255 or 16-235, for 8-bit RGB).
The device can apply a matrix conversion to YCbCr values when the input and output are both YCbCr. For example, the driver can convert colors from BT.601 to BT.709.
Applies to: desktop apps only
Specifies the type of Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nHardware device. Video processing is performed in the GPU by the driver.
Software device. Video processing is performed in the CPU by a software plug-in.
Reference device. Video processing is performed in the CPU by a software plug-in.
Other. The device is neither a hardware device nor a software plug-in.
Applies to: desktop apps only
Specifies the intended use for a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe graphics driver uses one of these enumeration constants as a hint when it creates the DXVA-HD device.
\t\nNormal video playback. The graphics driver should expose a set of capabilities that are appropriate for real-time video playback.
Optimal speed. The graphics driver should expose a minimal set of capabilities that are optimized for performance.
Use this setting if you want better performance and can accept some reduction in video quality. For example, you might use this setting in power-saving mode or to play video thumbnails.
Optimal quality. The grahics driver should expose its maximum set of capabilities.
Specify this setting to get the best video quality possible. It is appropriate for tasks such as video editing, when quality is more important than speed. It is not appropriate for real-time playback.
Applies to: desktop apps only
Defines features that a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device can support.
\t\nThe device can set the alpha values on the video output. See
The device can downsample the video output. See
The device can perform luma keying. See
The device can apply alpha values from color palette entries. See
Applies to: desktop apps only
Defines the range of supported values for an image filter.
\t\nThe multiplier enables the filter range to have a fractional step value.
For example, a hue filter might have an actual range of [-180.0 ... +180.0] with a step size of 0.25. The device would report the following range and multiplier:
In this case, a filter value of 2 would be interpreted by the device as 0.50 (or 2 ? 0.25).
The device should use a multiplier that can be represented exactly as a base-2 fraction.
\t\nThe minimum value of the filter.
The maximum value of the filter.
The default value of the filter.
A multiplier. Use the following formula to translate the filter setting into the actual filter value: Actual Value = Set Value???Multiplier.
Applies to: desktop apps only
Defines capabilities related to image adjustment and filtering for a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe device can adjust the brightness level.
The device can adjust the contrast level.
The device can adjust hue.
The device can adjust the saturation level.
The device can perform noise reduction.
The device can perform edge enhancement.
The device can perform anamorphic scaling. Anamorphic scaling can be used to stretch 4:3 content to a widescreen 16:9 aspect ratio.
Applies to: desktop apps only
Describes how a video stream is interlaced.
\t\nFrames are progressive.
Frames are interlaced. The top field of each frame is displayed first.
Frame are interlaced. The bottom field of each frame is displayed first.
Applies to: desktop apps only
Defines capabilities related to input formats for a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThese flags define video processing capabilities that are usually not needed, and therefore are not required for DXVA-HD devices to support.
The first three flags relate to RGB support for functions that are normally applied to YCbCr video: deinterlacing, color adjustment, and luma keying. A DXVA-HD device that supports these functions for YCbCr is not required to support them for RGB input. Supporting RGB input for these functions is an additional capability, reflected by these constants. The driver might convert the input to another color space, perform the indicated function, and then convert the result back to RGB.
Similarly, a device that supports de-interlacing is not required to support deinterlacing of palettized formats. This capability is indicated by the
The device can deinterlace an input stream that contains interlaced RGB video.
The device can perform color adjustment on RGB video.
The device can perform luma keying on RGB video.
The device can deinterlace input streams with palettized color formats.
Applies to: desktop apps only
Specifies the inverse telecine (IVTC) capabilities of a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processor.
\t\nThe video processor can reverse 3:2 pulldown.
The video processor can reverse 2:2 pulldown.
The video processor can reverse 2:2:2:4 pulldown.
The video processor can reverse 2:3:3:2 pulldown.
The video processor can reverse 3:2:3:2:2 pulldown.
The video processor can reverse 5:5 pulldown.
The video processor can reverse 6:4 pulldown.
The video processor can reverse 8:7 pulldown.
The video processor can reverse 2:2:2:2:2:2:2:2:2:2:2:3 pulldown.
The video processor can reverse other telecine modes not listed here.
Applies to: desktop apps only
Describes how to map color data to a normalized [0...1] range.
These flags are used in the
For YUV colors, these flags specify how to convert between Y'CbCr and Y'PbPr. The Y'PbPr color space has a range of [0..1] for Y' (luma) and [-0.5...0.5] for Pb/Pr (chroma).
| Value | Description |
|---|---|
| Should not be used for YUV data. | |
| For 8-bit Y'CbCr components:
For samples with n bits of precision, the general equations are:
The inverse equations to convert from Y'CbCr to Y'PbPr are:
| |
| For 8-bit Y'CbCr values, Y' range of [0..1] maps to [48...208]. |
?
For RGB colors, the flags differentiate various RGB spaces.
| Value | Description |
|---|---|
| sRGB | |
| Studio RGB; ITU-R BT.709 | |
| ITU-R BT.1361 RGB |
?
Video data might contain values above or below the nominal range.
Note??The values named
This enumeration is equivalent to the DXVA_NominalRange enumeration used in DXVA 1.0, although it defines additional values.
If you are using the
Applies to: desktop apps only
Specifies the output frame rates for an input stream, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
This enumeration type is used in the
Applies to: desktop apps only
Specifies the processing capabilities of a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processor.
\t\nThe video processor can perform blend deinterlacing.
In blend deinterlacing, the two fields from an interlaced frame are blended into a single progressive frame. A video processor uses blend deinterlacing when it deinterlaces at half rate, as when converting 60i to 30p. Blend deinterlacing does not require reference frames.
The video processor can perform bob deinterlacing.
In bob deinterlacing, missing field lines are interpolated from the lines above and below. Bob deinterlacing does not require reference frames.
The video processor can perform adaptive deinterlacing.
Adaptive deinterlacing uses spatial or temporal interpolation, and switches between the two on a field-by-field basis, depending on the amount of motion. If the video processor does not receive enough reference frames to perform adaptive deinterlacing, it falls back to bob deinterlacing.
The video processor can perform motion-compensated deinterlacing.
Motion-compensated deinterlacing uses motion vectors to recreate missing lines. If the video processor does not receive enough reference frames to perform motion-compensated deinterlacing, it falls back to bob deinterlacing.
The video processor can perform inverse telecine (IVTC).
If the video processor supports this capability, the ITelecineCaps member of the
The video processor can convert the frame rate by interpolating frames.
Applies to: desktop apps only
Describes the content of a video sample. These flags are used in the
This enumeration is equivalent to the DXVA_SampleFormat enumeration used in DXVA 1.0.
The following table shows the mapping from
| No exact match. Use |
?
With the exception of
The value
Applies to: desktop apps only
Specifies the luma key for an input stream, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nTo use this state, the device must support luma keying, indicated by the
If the device does not support luma keying, the
If the input format is RGB, the device must also support the
The values of Lower and Upper give the lower and upper bounds of the luma key, using a nominal range of [0...1]. Given a format with n bits per channel, these values are converted to luma values as follows:
val = f * ((1 << n)-1)
Any pixel whose luma value falls within the upper and lower bounds (inclusive) is treated as transparent.
For example, if the pixel format uses 8-bit luma, the upper bound is calculated as follows:
BYTE Y = BYTE(max(min(1.0, Upper), 0.0) * 255.0)
Note that the value is clamped to the range [0...1] before multiplying by 255.
\t\n If TRUE, luma keying is enabled. Otherwise, luma keying is disabled. The default value is
The lower bound for the luma key. The range is [0?1]. The default state value is 0.0.
The upper bound for the luma key. The range is [0?1]. The default state value is 0.0.
Applies to: desktop apps only
Describes a DirectX surface type for DirectX Video Acceleration (DXVA).
\t\nThe surface is a decoder render target.
The surface is a video processor render target.
The surface is a Direct3D texture render target.
Applies to: desktop apps only
Specifies the type of video surface created by a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nIf the DXVA-HD device is a software plug-in and the surface type is
A surface for an input stream. This surface type is equivalent to an off-screen plain surface in Microsoft Direct3D. The application can use the surface in Direct3D calls.
A private surface for an input stream. This surface type is equivalent to an off-screen plain surface, except that the application cannot use the surface in Direct3D calls.
A surface for an output stream. This surface type is equivalent to an off-screen plain surface in Direct3D. The application can use the surface in Direct3D calls.
This surface type is recommended for video processing applications that need to lock the surface and access the surface memory. For video playback with optimal performance, a render-target surface or swap chain is recommended instead.
Applies to: desktop apps only
Contains flags that define the chroma encoding scheme for Y'Cb'Cr' data.
\t\nThese flags are used with the
For more information about these values, see the remarks for the
Unknown encoding scheme.
Chroma should be reconstructed as if the underlying video was progressive content, rather than skipping fields or applying chroma filtering to minimize artifacts from reconstructing 4:2:0 interlaced chroma.
Chroma samples are aligned horizontally with the luma samples, or with multiples of the luma samples. If this flag is not set, chroma samples are located 1/2 pixel to the right of the corresponding luma sample.
Chroma samples are aligned vertically with the luma samples, or with multiples of the luma samples. If this flag is not set, chroma samples are located 1/2 pixel down from the corresponding luma sample.
The U and V planes are aligned vertically. If this flag is not set, the chroma planes are assumed to be out of phase by 1/2 chroma sample, alternating between a line of U followed by a line of V.
Specifies the chroma encoding scheme for MPEG-2 video. Chroma samples are aligned horizontally with the luma samples, but are not aligned vertically. The U and V planes are aligned vertically.
Specifies the chroma encoding scheme for MPEG-1 video.
Specifies the chroma encoding scheme for PAL DV video.
Chroma samples are aligned vertically and horizontally with the luma samples. YUV formats such as 4:4:4, 4:2:2, and 4:1:1 are always cosited in both directions and should use this flag.
Reserved.
Applies to: desktop apps only
Describes the intended lighting conditions for viewing video content. These flags are used in the
This enumeration is equivalent to the DXVA_VideoLighting enumeration used in DXVA 1.0.
If you are using the
Applies to: desktop apps only
Specifies the color primaries of a video source. These flags are used in the
Color primaries define how to convert RGB colors into the CIE XYZ color space, and can be used to translate colors between different RGB color spaces. An RGB color space is defined by the chromaticity coordinates (x,y) of the RGB primaries plus the white point, as listed in the following table.
| Color space | (Rx, Ry) | (Gx, Gy) | (Bx, By) | White point (Wx, Wy) |
|---|---|---|---|---|
| BT.709 | (0.64, 0.33) | (0.30, 0.60) | (0.15, 0.06) | D65 (0.3127, 0.3290) |
| BT.470-2 System M; EBU 3212 | (0.64, 0.33) | (0.29, 0.60) | (0.15, 0.06) | D65 (0.3127, 0.3290) |
| BT.470-4 System B,G | (0.67, 0.33) | (0.21, 0.71) | (0.14, 0.08) | CIE III.C (0.310, 0.316) |
| SMPTE 170M; SMPTE 240M; SMPTE C | (0.63, 0.34) | (0.31, 0.595) | (0.155, 0.07) | D65 (0.3127, 0.3291) |
?
The z coordinates can be derived from x and y as follows: z = 1 - x - y. To convert between RGB colors to CIE XYZ tristimulus values, compute a matrix T as follows:
Given T, you can use the following formulas to convert between an RGB color value and a CIE XYZ tristimulus value. These formulas assume that the RGB components are linear (not gamma corrected) and are normalized to the range [0...1].
To convert colors directly from one RGB color space to another, use the following formula, where T1 is the matrix for color space RGB1, and T2 is the matrix for color space RGB2.
For a derivation of these formulas, refer to Charles Poynton, Digital Video and HDTV Algorithms and Interfaces (Morgan Kaufmann, 2003).
This enumeration is equivalent to the DXVA_VideoPrimaries enumeration used in DXVA 1.0.
If you are using the
Applies to: desktop apps only
Specifies the conversion function from linear RGB to non-linear RGB (R'G'B'). These flags are used in the
The following table shows the formulas for the most common transfer functions. In these formulas, L is the linear value and L' is the non-linear (gamma corrected) value. These values are relative to a normalized range [0...1].
| Color space | Transfer function |
|---|---|
| sRGB (8-bit) | L' = 12.92L, for L < 0.031308 L' = 1.055L^1/2.4? 0.055, for L >= 0.031308 |
| BT.470-2 System B, G | L' = L^0.36 |
| BT.470-2 System M | L' = L^0.45 |
| BT.709 | L' = 4.50L, for L < 0.018 L' = 1.099L^0.45? 0.099, for L >= 0.018 |
| scRGB | L' = L |
| SMPTE 240M | L' = 4.0L, for L < 0.0228 L' = 1.1115L^0.45? 0.01115, for L >= 0.0228 |
?
The following table shows the inverse formulas to obtain the original gamma-corrected values:
| Color space | Transfer function |
|---|---|
| sRGB (8-bit) | L = 1/12.92L', for L' < 0.03928 L = ((L' + 0.055)/1055)^2.4, for L' >= 0.03928 |
| BT.470-2 System B, G | L = L'^1/0.36 |
| BT.470-2 System M | L = L'^1/0.45 |
| BT.709 | L = L'/4.50, for L' < 0.081 L = ((L' + 0.099) / 1.099)^1/0.45, for L' >= 0.081 |
| scRGB | L = L' |
| SMPTE 240M | L = L'/4.0, for L' < 0.0913 L= ((L' + 0.1115)/1.1115)^1/0.45, for L' >= 0.0913 |
?
This enumeration is equivalent to the DXVA_VideoTransferFunction enumeration used in DXVA 1.0.
If you are using the
Bitmask to validate flag values. This value is not a valid flag.
Unknown. Treat as
Linear RGB (gamma = 1.0).
True 1.8 gamma, L' = L^1/1.8.
True 2.0 gamma, L' = L^1/2.0.
True 2.2 gamma, L' = L^1/2.2. This transfer function is used in ITU-R BT.470-2 System M (NTSC).
ITU-R BT.709 transfer function. Gamma 2.2 curve with a linear segment in the lower range. This transfer function is used in BT.709, BT.601, SMPTE 296M, SMPTE 170M, BT.470, and SMPTE 274M. In addition BT-1361 uses this function within the range [0...1].
SMPTE 240M transfer function. Gamma 2.2 curve with a linear segment in the lower range.
sRGB transfer function. Gamma 2.4 curve with a linear segment in the lower range.
True 2.8 gamma. L' = L^1/2.8. This transfer function is used in ITU-R BT.470-2 System B, G (PAL).
Applies to: desktop apps only
Describes the conversion matrices between Y'PbPr (component video) and studio R'G'B'. These flags are used in the
The transfer matrices are defined as follows.
BT.709 transfer matrices:
Y' 0.212600 0.715200 0.072200 R' \t\n Pb = -0.114572 -0.385428 0.500000 x G' \t\n Pr 0.500000 -0.454153 -0.045847 B' R' 1.000000 0.000000 1.574800 Y' \t\n G' = 1.000000 -0.187324 -0.468124 x Pb \t\n B' 1.000000 1.855600 0.000000 Pr \t\n BT.601 transfer matrices:
Y' 0.299000 0.587000 0.114000 R' \t\n Pb = -0.168736 -0.331264 0.500000 x G' \t\n Pr 0.500000 -0.418688 -0.081312 B' R' 1.000000 0.000000 1.402000 Y' \t\n G' = 1.000000 -0.344136 -0.714136 x Pb \t\n B' 1.000000 1.772000 0.000000 Pr \t\n SMPTE 240M (SMPTE RP 145) transfer matrices:
Y' 0.212000 0.701000 0.087000 R' \t\n Pb = -0.116000 -0.384000 0.500000 x G' \t\n Pr 0.500000 -0.445000 -0.055000 B' R' 1.000000 -0.000000 1.576000 Y' \t\n G' = 1.000000 -0.227000 -0.477000 x Pb \t\n B' 1.000000 1.826000 0.000000 Pr \t\n This enumeration is equivalent to the DXVA_VideoTransferMatrix enumeration used in DXVA 1.0.
If you are using the
Applies to: desktop apps only
Creates an instance of the Direct3D Device Manager.
\t\nIf this function succeeds, it returns
Applies to: desktop apps only
Creates a DirectX Video Acceleration (DXVA) services object. Call this function if your application uses DXVA directly, without using DirectShow or Media Foundation.
\t\n A reference to the
The interface identifier (IID) of the requested interface. Any of the following interfaces might be supported by the Direct3D device:
Receives a reference to the interface. The caller must release the interface.
If this function succeeds, it returns
Applies to: desktop apps only
Creates a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nA reference to the
A reference to a
A member of the
A reference to an initialization function for a software device. Set this reference if you are using a software plug-in device. Otherwise, set this parameter to
The function reference type is PDXVAHDSW_Plugin.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Direct3D device does not support DXVA-HD. |
?
Use the
Applies to: desktop apps only
Gets the range of values for an image filter that the Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device supports.
\t\nTo find out which image filters the device supports, check the FilterCaps member of the
Applies to: desktop apps only
Creates one or more Microsoft Direct3D video surfaces.
\t\nThe width of each surface, in pixels.
The height of each surface, in pixels.
The pixel format, specified as a
The memory pool in which the surface is created. This parameter must equal the InputPool member of the
Reserved. Set to 0.
The type of surface to create, specified as a member of the
The number of surfaces to create.
A reference to an array of
Reserved. Set to
If this method succeeds, it returns
Applies to: desktop apps only
Gets the capabilities of the Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nA reference to a
If this method succeeds, it returns
Applies to: desktop apps only
Gets a list of the output formats supported by the Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe number of formats to retrieve. This parameter must equal the OutputFormatCount member of the
A reference to an array of
If this method succeeds, it returns
The list of formats can include both
Applies to: desktop apps only
Gets the capabilities of one or more Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processors.
\t\nThe number of elements in the pCaps array. This parameter must equal the VideoProcessorCount member of the
A reference to an array of
If this method succeeds, it returns
Applies to: desktop apps only
Gets a list of custom rates that a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processor supports. Custom rates are used for frame-rate conversion and inverse telecine (IVTC).
\t\nA
The number of rates to retrieve. This parameter must equal the CustomRateCount member of the
A reference to an array of
If this method succeeds, it returns
Applies to: desktop apps only
Gets the range of values for an image filter that the Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device supports.
\t\nThe type of image filter, specified as a member of the
A reference to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Filter parameter is invalid or the device does not support the specified filter. |
?
To find out which image filters the device supports, check the FilterCaps member of the
Applies to: desktop apps only
Creates a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processor.
\t\nA
Receives a reference to the
If this method succeeds, it returns
Applies to: desktop apps only
Gets the capabilities of the Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nApplies to: desktop apps only
Represents a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processor.
To get a reference to this interface, call the
Applies to: desktop apps only
Sets a state parameter for a blit operation by a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe state parameter to set, specified as a member of the
The size, in bytes, of the buffer pointed to by pData.
A reference to a buffer that contains the state data. The meaning of the data depends on the State parameter. Each state has a corresponding data structure; for more information, see
If this method succeeds, it returns
Applies to: desktop apps only
Gets the value of a state parameter for blit operations performed by a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe state parameter to query, specified as a member of the
The size, in bytes, of the buffer pointed to by pData.
A reference to a buffer allocated by the caller. The method copies the state data into the buffer. The buffer must be large enough to hold the data structure that corresponds to the state parameter. For more information, see
If this method succeeds, it returns
Applies to: desktop apps only
Sets a state parameter for an input stream on a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe zero-based index of the input stream. To get the maximum number of streams, call
The state parameter to set, specified as a member of the
The size, in bytes, of the buffer pointed to by pData.
A reference to a buffer that contains the state data. The meaning of the data depends on the State parameter. Each state has a corresponding data structure; for more information, see
If this method succeeds, it returns
Call this method to set state parameters that apply to individual input streams.
\t\nApplies to: desktop apps only
Gets the value of a state parameter for an input stream on a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nThe zero-based index of the input stream. To get the maximum number of streams, call
The state parameter to query, specified as a member of the
The size, in bytes, of the buffer pointed to by pData.
A reference to a buffer allocated by the caller. The method copies the state data into the buffer. The buffer must be large enough to hold the data structure that corresponds to the state parameter. For more information, see
If this method succeeds, it returns
Applies to: desktop apps only
Performs a video processing blit on one or more input samples and writes the result to a Microsoft Direct3D surface.
\t\nA reference to the
Frame number of the output video frame, indexed from zero.
Number of input streams to process.
Pointer to an array of
If this method succeeds, it returns
The maximum value of StreamCount is given in the MaxStreamStates member of the
Applies to: desktop apps only
Enables two threads to share the same Direct3D 9 device, and provides access to the DirectX Video Acceleration (DXVA) features of the device.
\t\nThis interface is exposed by the Direct3D Device Manager. To create the Direct3D device manager, call
To get this interface from the Enhanced Video Renderer (EVR), call
The Direct3D Device Manager supports Direct3D 9 devices only. It does not support DXGI devices.
\t\nApplies to: desktop apps only
Sets the Direct3D device or notifies the device manager that the Direct3D device was reset.
\t\nPointer to the
Token received in the pResetToken parameter of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid token |
| | Direct3D device error. |
?
When you first create the Direct3D device manager, call this method with a reference to the Direct3D device. The device manager does not create the device; the caller must provide the device reference initially.
Also call this method if the Direct3D device becomes lost and you need to reset the device or create a new device. This occurs if
The resetToken parameter ensures that only the component which originally created the device manager can invalidate the current device.
If this method succeeds, all open device handles become invalid.
\t\nApplies to: desktop apps only
Gets a handle to the Direct3D device.
\t\nReceives the device handle.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Direct3D device manager was not initialized. The owner of the device must call |
?
To get the Direct3D device's
To test whether a device handle is still valid, call
Applies to: desktop apps only
Closes a Direct3D device handle. Call this method to release a device handle retrieved by the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid handle. |
?
Applies to: desktop apps only
Tests whether a Direct3D device handle is valid.
\t\nHandle to a Direct3D device. To get a device handle, call
The method returns an
| Return code | Description |
|---|---|
| | The device handle is valid. |
| The specified handle is not a Direct3D device handle. |
| The device handle is invalid. |
?
If the method returns DXVA2_E_NEW_VIDEO_DEVICE, call
Applies to: desktop apps only
Gives the caller exclusive access to the Direct3D device.
\t\nA handle to the Direct3D device. To get the device handle, call
Receives a reference to the device's
Specifies whether to wait for the device lock. If the device is already locked and this parameter is TRUE, the method blocks until the device is unlocked. Otherwise, if the device is locked and this parmater is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The device handle is invalid. |
| The Direct3D device manager was not initialized. The owner of the device must call |
| The device is locked and fBlock is |
| The specified handle is not a Direct3D device handle. |
?
When you are done using the Direct3D device, call
If the method returns DXVA2_E_NEW_VIDEO_DEVICE, call
If fBlock is TRUE, this method can potentially deadlock. For example, it will deadlock if a thread calls LockDevice and then waits on another thread that calls LockDevice. It will also deadlock if a thread calls LockDevice twice without calling UnlockDevice in between.
\t\nApplies to: desktop apps only
Unlocks the Direct3D device. Call this method to release the device after calling
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The specified device handle is not locked, or is not a valid handle. |
?
Applies to: desktop apps only
Gets a DirectX Video Acceleration (DXVA) service interface.
\t\n A handle to a Direct3D device. To get a device handle, call
The interface identifier (IID) of the requested interface. The Direct3D device might support the following DXVA service interfaces:
Receives a reference to the requested interface. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The device handle is invalid. |
| The Direct3D device does not support video acceleration. |
| The Direct3D device manager was not initialized. The owner of the device must call |
| The specified handle is not a Direct3D device handle. |
?
If the method returns DXVA2_E_NEW_VIDEO_DEVICE, call
Applies to: desktop apps only
Provides DirectX Video Acceleration (DXVA) services from a Direct3D device. To get a reference to this interface, call
This is the base interface for DXVA services. The Direct3D device can support any of the following DXVA services, which derive from
Applies to: desktop apps only
Creates a DirectX Video Acceleration (DXVA) video processor or DXVA decoder render target.
\t\nThe width of the surface, in pixels.
The height of the surface, in pixels.
The number of back buffers. The method creates BackBuffers + 1 surfaces.
The pixel format, specified as a
The memory pool in which to create the surface, specified as a
Reserved. Set this value to zero.
The type of surface to create. Use one of the following values.
| Value | Meaning |
|---|---|
| Video decoder render target. | |
| Video processor render target. Used for | |
| Software render target. This surface type is for use with software DXVA devices. |
?
The address of an array of
A reference to a handle that is used to share the surfaces between Direct3D devices. Set this parameter to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid parameter |
| The DirectX Video Acceleration Manager is not initialized. |
| |
?
If the method returns E_FAIL, try calling
Applies to: desktop apps only
Represents a DirectX Video Acceleration (DXVA) video decoder device.
To get a reference to this interface, call
The
Applies to: desktop apps only
Retrieves the DirectX Video Acceleration (DXVA) decoder service that created this decoder device.
\t\nReceives a reference to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the parameters that were used to create this device.
\t\nReceives the device
Pointer to a
Pointer to a
Receives an array of
Receives the number of elements in the pppDecoderRenderTargets array. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. At least one parameter must be non- |
?
You can set any parameter to
If you specify a non-
Applies to: desktop apps only
Retrieves a reference to a DirectX Video Acceleration (DXVA) decoder buffer.
\t\nType of buffer to retrieve. Use one of the following values.
| Value | Meaning |
|---|---|
| Picture decoding parameter buffer. | |
| Macroblock control command buffer. | |
| Residual difference block data buffer. | |
| Deblocking filter control command buffer. | |
| Inverse quantization matrix buffer. | |
| Slice-control buffer. | |
| Bitstream data buffer. | |
| Motion vector buffer. | |
| Film grain synthesis data buffer. |
?
Receives a reference to the start of the memory buffer.
Receives the size of the buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The method locks the Direct3D surface that contains the buffer. When you are done using the buffer, call
This method might block if too many operations have been queued on the GPU. The method unblocks when a free buffer becomes available.
\t\nApplies to: desktop apps only
Releases a buffer that was obtained by calling
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Starts the decoding operation.
\t\nPointer to the
Reserved; set to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid surface type. See Remarks. |
?
After this method is called, call
Each call to BeginFrame must have a matching call to EndFrame, and BeginFrame calls cannot be nested.
DXVA 1.0 migration note: Unlike the IAMVideoAccelerator::BeginFrame method, which specifies the buffer as an index, this method takes a reference directly to the uncompressed buffer.
The surface pointed to by pRenderTarget must be created by calling
Applies to: desktop apps only
Signals the end of the decoding operation.
\t\nReserved.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Executes a decoding operation on the current frame.
\t\nPointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
You must call
Applies to: desktop apps only
Retrieves the DirectX Video Acceleration (DXVA) decoder service that created this decoder device.
\t\nApplies to: desktop apps only
Provides access to DirectX Video Acceleration (DXVA) decoder services. Use this interface to query which hardware-accelerated decoding operations are available and to create DXVA video decoder devices.
To get a reference to this interface, call
Applies to: desktop apps only
Retrieves an array of GUIDs that identifies the decoder devices supported by the graphics hardware.
\t\nReceives the number of GUIDs.
Receives an array of GUIDs. The size of the array is retrieved in the Count parameter. The method allocates the memory for the array. The caller must free the memory by calling CoTaskMemFree.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Error from the Direct3D device. |
?
The following decoder GUIDs are defined. Some of these GUIDs have alternate names, shown in parentheses.
| Description | |
|---|---|
| DXVA2_ModeH264_A (DXVA2_ModeH264_MoComp_NoFGT) | H.264 motion compensation (MoComp), no film grain technology (FGT). |
| DXVA2_ModeH264_B (DXVA2_ModeH264_MoComp_FGT) | H.264 MoComp, FGT. |
| DXVA2_ModeH264_C (DXVA2_ModeH264_IDCT_NoFGT) | H.264 inverse discrete cosine transform (IDCT), no FGT. |
| DXVA2_ModeH264_D (DXVA2_ModeH264_IDCT_FGT) | H.264 IDCT, FGT. |
| DXVA2_ModeH264_E (DXVA2_ModeH264_VLD_NoFGT) | H.264 VLD, no FGT. |
| DXVA2_ModeH264_F (DXVA2_ModeH264_VLD_FGT) | H.264 variable-length decoder (VLD), FGT. |
| DXVA2_ModeMPEG2_IDCT | MPEG-2 IDCT. |
| DXVA2_ModeMPEG2_MoComp | MPEG-2 MoComp. |
| DXVA2_ModeMPEG2_VLD | MPEG-2 VLD. |
| DXVA2_ModeVC1_A (DXVA2_ModeVC1_PostProc) | VC-1 post processing. |
| DXVA2_ModeVC1_B (DXVA2_ModeVC1_MoComp) | VC-1 MoComp. |
| DXVA2_ModeVC1_C (DXVA2_ModeVC1_IDCT) | VC-1 IDCT. |
| DXVA2_ModeVC1_D (DXVA2_ModeVC1_VLD) | VC-1 VLD. |
| DXVA2_ModeWMV8_A (DXVA2_ModeWMV8_PostProc) | Windows Media Video 8 post processing. |
| DXVA2_ModeWMV8_B (DXVA2_ModeWMV8_MoComp) | Windows Media Video 8 MoComp. |
| DXVA2_ModeWMV9_A (DXVA2_ModeWMV9_PostProc) | Windows Media Video 9 post processing. |
| DXVA2_ModeWMV9_B (DXVA2_ModeWMV9_MoComp) | Windows Media Video 9 MoComp. |
| DXVA2_ModeWMV9_C (DXVA2_ModeWMV9_IDCT) | Windows Media Video 9 IDCT. |
?
\t\nApplies to: desktop apps only
Retrieves the supported render targets for a specified decoder device.
\t\nReceives the number of formats.
Receives an array of formats, specified as
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Gets the configurations that are available for a decoder device.
\t\nA
A reference to a
Reserved. Set to
Receives the number of configurations.
Receives an array of
If this method succeeds, it returns
Applies to: desktop apps only
Creates a video decoder device.
\t\nPointer to a
Pointer to a
Pointer to an array of
Size of the ppDecoderRenderTargets array. This value cannot be zero.
Receives a reference to the decoder's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Creates a video decoder device.
\t\nPointer to a
Pointer to a
Pointer to an array of
Size of the ppDecoderRenderTargets array. This value cannot be zero.
Receives a reference to the decoder's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets the type of video memory for uncompressed video surfaces. This interface is used by video decoders and transforms.
The DirectShow enhanced video renderer (EVR) filter exposes this interface as a service on the filter's input pins. To obtain a reference to this interface, call
A video decoder can use this interface to enumerate the EVR filter's preferred surface types and then select the surface type. The decoder should then create surfaces of that type to hold the results of the decoding operation.
This interface does not define a way to clear the surface type. In the case of DirectShow, disconnecting two filters invalidates the surface type.
\t\nApplies to: desktop apps only
Retrieves a supported video surface type.
\t\nZero-based index of the surface type to retrieve. Surface types are indexed in order of preference, starting with the most preferred type.
Receives a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The index was out of range. |
?
Applies to: desktop apps only
Sets the video surface type that a decoder will use for DirectX Video Acceleration (DVXA) 2.0.
\t\nMember of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The renderer does not support the specified surface type. |
?
By calling this method, the caller agrees to create surfaces of the type specified in the dwType parameter.
In DirectShow, during pin connection, a video decoder that supports DVXA 2.0 should call SetSurface with the value
The only way to undo the setting is to break the pin connection.
\t\nApplies to: desktop apps only
Sets the video surface type that a decoder will use for DirectX Video Acceleration (DVXA) 2.0.
\t\nBy calling this method, the caller agrees to create surfaces of the type specified in the dwType parameter.
In DirectShow, during pin connection, a video decoder that supports DVXA 2.0 should call SetSurface with the value
The only way to undo the setting is to break the pin connection.
\t\nApplies to: desktop apps only
Retrieves the parameters that were used to create this device.
\t\nYou can set any parameter to
Applies to: desktop apps only
Retrieves the DirectX Video Acceleration (DXVA) video processor service that created this video processor device.
\t\nReceives a reference to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the parameters that were used to create this device.
\t\nReceives the device
Pointer to a
Receives the render target format, specified as a
Receives the maximum number of streams supported by the device. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. At least one parameter must be non- |
?
You can set any parameter to
Applies to: desktop apps only
Retrieves the capabilities of the video processor device.
\t\nPointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the range of values for a video processor (ProcAmp) setting on this video processor device.
\t\nThe ProcAmp setting to query. See ProcAmp Settings.
Pointer to a
If this method succeeds, it returns
Applies to: desktop apps only
Retrieves the range of values for an image filter supported by this device.
\t\nFilter setting to query. For more information, see DXVA Image Filter Settings.
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Performs a video process operation on one or more input samples and writes the result to a Direct3D9 surface.
\t\n A reference to the
A reference to a
A reference to an array of
The maximum number of input samples is given by the constant MAX_DEINTERLACE_SURFACES, defined in the header file dxva2api.h.
The number of elements in the pSamples array.
Reserved; set to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Internal driver error. |
| Invalid arguments. |
?
When the method returns, the operation might not be complete.
If the method returns E_INVALIDARG, check for the following:
Applies to: desktop apps only
Retrieves the DirectX Video Acceleration (DXVA) video processor service that created this video processor device.
\t\nApplies to: desktop apps only
Retrieves the capabilities of the video processor device.
\t\nApplies to: desktop apps only
Provides access to DirectX Video Acceleration (DXVA) video processing services.
Use this interface to query which hardware-accelerated video processing operations are available and to create DXVA video processor devices. To obtain a reference to this interface, call
Applies to: desktop apps only
Registers a software video processing device.
\t\nPointer to an initialization function.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Gets an array of GUIDs which identify the video processors supported by the graphics hardware.
\t\n Pointer to a
Receives the number of GUIDs.
Receives an array of GUIDs. The size of the array is retrieved in the pCount parameter. The method allocates the memory for the array. The caller must free the memory by calling CoTaskMemFree.
If this method succeeds, it returns
The following video processor GUIDs are predefined.
| Description | |
|---|---|
| DXVA2_VideoProcBobDevice | Bob deinterlace device. This device uses a \"bob\" algorithm to deinterlace the video. Bob algorithms create missing field lines by interpolating the lines in a single field. |
| DXVA2_VideoProcProgressiveDevice | Progressive video device. This device is available for progressive video, which does not require a deinterlace algorithm. |
| DXVA2_VideoProcSoftwareDevice | Reference (software) device. |
?
The graphics device may define additional vendor-specific GUIDs. The driver provides the list of GUIDs in descending quality order. The mode with the highest quality is first in the list. To get the capabilities of each mode, call
Applies to: desktop apps only
Gets the render target formats that a video processor device supports. The list may include RGB and YUV formats.
\t\n A
A reference to a
Receives the number of formats.
Receives an array of formats, specified as
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Gets a list of substream formats supported by a specified video processor device.
\t\n A
A reference to a
The format of the render target surface, specified as a
Receives the number of elements returned in the ppFormats array.
Receives an array of
If this method succeeds, it returns
Applies to: desktop apps only
Gets the capabilities of a specified video processor device.
\t\n A
A reference to a
The format of the render target surface, specified as a
A reference to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Gets the range of values for a video processor (ProcAmp) setting.
\t\nA
A reference to a
The format of the render target surface, specified as a
The ProcAmp setting to query. See ProcAmp Settings.
A reference to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the range of values for an image filter supported by a video processor device.
\t\n A
A reference to a
The format of the render target surface, specified as a
The filter setting to query. See DXVA Image Filter Settings.
A reference to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Creates a video processor device.
\t\nA
A reference to a
The format of the render target surface, specified as a
The maximum number of substreams that will be used with this device.
Receives a reference to the video processor's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Contains an initialization vector (IV) for 128-bit Advanced Encryption Standard CTR mode (AES-CTR) block cipher encryption.
\t\nFor AES-CTR encyption, the pvPVPState member of the
The D3DAES_CTR_IV structure and the
If the IDirect3DDevice9Video::GetContentProtectionCaps method returns the D3DCPCAPS_SEQUENTIAL_CTR_IV flag, the caller should keep IV unchanged when submitting multiple buffers for the same video frame, and Count should be in sequential order of the previous submission for the frame.
Example: Suppose the software decoder submits three buffers for a single frame, and that each buffer contains three 128-bit blocks. For the first buffer, IV can be any value. For the next two buffers, the same value of IV must be used. The value of Count starts at 1. For the second buffer, Count equals 4 (1 + 3 blocks from the first submission). For the third buffer, Count equals 7 (4 + 3 blocks from the second submission).
When the D3DCPCAPS_SEQUENTIAL_CTR_IV capability is present, it is recommended to submit data in 128-bit blocks.
\t\nThe IV, in big-endian format.
The block count, in big-endian format.
Applies to: desktop apps only
Contains parameters for the
Applies to: desktop apps only
Specifies an input sample for the
Applies to: desktop apps only
Specifies the planar alpha value for an input stream, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nFor each pixel, the destination color value is computed as follows:
Cd = Cs * (As * Ap * Ae) + Cd * (1.0 - As * Ap * Ae)
where
Cd = Color value of the destination pixel.Cs = Color value of source pixel.As = Per-pixel source alpha.Ap = Planar alpha value.Ae = Palette-entry alpha value, or 1.0 (see Note).Note??Palette-entry alpha values apply only to palettized color formats, and only when the device supports the
The destination alpha value is computed according to the
To get the device capabilities, call
If TRUE, alpha blending is enabled. Otherwise, alpha blending is disabled. The default state value is
Specifies the planar alpha value as a floating-point number from 0.0 (transparent) to 1.0 (opaque).
If the Enable member is
Applies to: desktop apps only
Contains the response to a D3DAUTHENTICATEDQUERY_OUTPUTIDCOUNT query.
To send this query, call IDirect3DAuthenticatedChannel9::Query.
\t\nApplies to: desktop apps only
Specifies whether the output is downsampled in a blit operation, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nIf the Enable member is TRUE, the device downsamples the composed target rectangle to the size given in the Size member, and then scales it back to the size of the target rectangle.
The width and height of Size must be greater than zero. If the size is larger than the target rectangle, downsampling does not occur.
To use this state, the device must support downsampling, indicated by the
If the device does not support downsampling, the
Downsampling is sometimes used to reduce the quality of premium content when other forms of content protection are not available.
\t\nIf TRUE, downsampling is enabled. Otherwise, downsampling is disabled and the Size member is ignored. The default state value is
The sampling size. The default value is (1,1).
Applies to: desktop apps only
Specifies the output color space for blit operations, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nThe RGB_Range member applies to RGB output, while the YCbCr_Matrix and YCbCr_xvYCC members apply to YCbCr (YUV) output. If the device performs color-space conversion on the background color, it uses the values that apply to both color spaces.
Extended YCbCr can be used with either transfer matrix. Extended YCbCr does not change the black point or white point?the black point is still 16 and the white point is still 235. However, extended YCbCr explicitly allows blacker-than-black values in the range 1?15, and whiter-than-white values in the range 236?254. When extended YCbCr is used, the driver should not clip the luma values to the nominal 16?235 range.
If the device supports extended YCbCr, it sets the
If the output format is a wide-gamut RGB format, output might fall outside the nominal [0...1] range of sRGB. This is particularly true if one or more input streams use extended YCbCr.
\t\nSpecifies whether the output is intended for playback or video processing (such as editing or authoring). The device can optimize the processing based on the type. The default state value is 0 (playback).
| Value | Meaning |
|---|---|
| Playback. |
| Video processing. |
?
Specifies the RGB color range. The default state value is 0 (full range).
| Value | Meaning |
|---|---|
| Full range (0-255). |
| Limited range (16-235). |
?
Specifies the YCbCr transfer matrix. The default state value is 0 (BT.601).
| Value | Meaning |
|---|---|
| ITU-R BT.601. |
| ITU-R BT.709. |
?
Specifies whether the output uses conventional YCbCr or extended YCbCr (xvYCC). The default state value is zero (conventional YCbCr).
| Value | Meaning |
|---|---|
| Conventional YCbCr. |
| Extended YCbCr (xvYCC). |
?
Applies to: desktop apps only
Contains the response to a D3DAUTHENTICATEDQUERY_OUTPUTIDCOUNT query.
To send this query, call IDirect3DAuthenticatedChannel9::Query.
\t\nApplies to: desktop apps only
Specifies the target rectangle for blitting, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nSpecifies whether to use the target rectangle. The default state value is
| Value | Meaning |
|---|---|
| Use the target rectangle specified by the TargetRect member. |
| Use the entire destination surface as the target rectangle. Ignore the TargetRect member. |
?
Specifies the target rectangle. The target rectangle is the area within the destination surface where the output will be drawn. The target rectangle is given in pixel coordinates, relative to the destination surface. The default state value is an empty rectangle, (0, 0, 0, 0).
If the Enable member is
Applies to: desktop apps only
Specifies a YCbCr color value.
\t\nValues have a nominal range of [0...1]. Given a format with n bits per channel, the value of each color component is calculated as follows:
val = f * ((1 << n)-1)
For example, for 8-bit YUV formats, val = BYTE(f * 255.0).
Reference black is (0.0625, 0.5, 0.5), which corresponds to (16, 128, 128) in an 8-bit representation.
\t\nThe Y (luma) value.
The Cb chroma value.
Applies to: desktop apps only
Specifies an RGB color value.
\t\nThe RGB values have a nominal range of [0...1]. For an RGB format with n bits per channel, the value of each color component is calculated as follows:
val = f * ((1 << n)-1)
For example, for RGB-32 (8 bits per channel), val = BYTE(f * 255.0).
For full-range RGB, reference black is (0.0, 0.0, 0.0), which corresponds to (0, 0, 0) in an 8-bit representation. For limited-range RGB, reference black is (0.0625, 0.0625, 0.0625), which corresponds to (16, 16, 16) in an 8-bit representation. For wide-gamut formats, the values might fall outside of the [0...1] range.
\t\nThe red value.
The green value.
The blue value.
The alpha value. Values range from 0 (transparent) to 1 (opaque).
Applies to: desktop apps only
Describes the configuration of a DXVA decoder device.
\t\nDefines the encryption protocol type for bit-stream data buffers. If no encryption is applied, the value is DXVA_NoEncrypt. If ConfigBitstreamRaw is 0, the value must be DXVA_NoEncrypt.
Defines the encryption protocol type for macroblock control data buffers. If no encryption is applied, the value is DXVA_NoEncrypt. If ConfigBitstreamRaw is 1, the value must be DXVA_NoEncrypt.
Defines the encryption protocol type for residual difference decoding data buffers (buffers containing spatial-domain data or sets of transform-domain coefficients for accelerator-based IDCT). If no encryption is applied, the value is DXVA_NoEncrypt. If ConfigBitstreamRaw is 1, the value must be DXVA_NoEncrypt.
Indicates whether the host-decoder sends raw bit-stream data. If the value is 1, the data for the pictures will be sent in bit-stream buffers as raw bit-stream content. If the value is 0, picture data will be sent using macroblock control command buffers. If either ConfigResidDiffHost or ConfigResidDiffAccelerator is 1, the value must be 0.
Specifies whether macroblock control commands are in raster scan order or in arbitrary order. If the value is 1, the macroblock control commands within each macroblock control command buffer are in raster-scan order. If the value is 0, the order is arbitrary. For some types of bit streams, forcing raster order either greatly increases the number of required macroblock control buffers that must be processed, or requires host reordering of the control information. Therefore, supporting arbitrary order can be more efficient.
Contains the host residual difference configuration. If the value is 1, some residual difference decoding data may be sent as blocks in the spatial domain from the host. If the value is 0, spatial domain data will not be sent.
Indicates the word size used to represent residual difference spatial-domain blocks for predicted (non-intra) pictures when using host-based residual difference decoding.
If ConfigResidDiffHost is 1 and ConfigSpatialResid8 is 1, the host will send residual difference spatial-domain blocks for non-intra macroblocks using 8-bit signed samples and for intra macroblocks in predicted (non-intra) pictures in a format that depends on the value of ConfigIntraResidUnsigned:
If ConfigResidDiffHost is 1 and ConfigSpatialResid8 is 0, the host will send residual difference spatial-domain blocks of data for non-intra macroblocks using 16- bit signed samples and for intra macroblocks in predicted (non-intra) pictures in a format that depends on the value of ConfigIntraResidUnsigned:
If ConfigResidDiffHost is 0, ConfigSpatialResid8 must be 0.
For intra pictures, spatial-domain blocks must be sent using 8-bit samples if bits-per-pixel (BPP) is 8, and using 16-bit samples if BPP > 8. If ConfigIntraResidUnsigned is 0, these samples are sent as signed integer values relative to a constant reference value of 2^(BPP?1), and if ConfigIntraResidUnsigned is 1, these samples are sent as unsigned integer values relative to a constant reference value of 0.
If the value is 1, 8-bit difference overflow blocks are subtracted rather than added. The value must be 0 unless ConfigSpatialResid8 is 1.
The ability to subtract differences rather than add them enables 8-bit difference decoding to be fully compliant with the full ?255 range of values required in video decoder specifications, because +255 cannot be represented as the addition of two signed 8-bit numbers, but any number in the range ?255 can be represented as the difference between two signed 8-bit numbers (+255 = +127 minus ?128).
If the value is 1, spatial-domain blocks for intra macroblocks must be clipped to an 8-bit range on the host and spatial-domain blocks for non-intra macroblocks must be clipped to a 9-bit range on the host. If the value is 0, no such clipping is necessary by the host.
The value must be 0 unless ConfigSpatialResid8 is 0 and ConfigResidDiffHost is 1.
If the value is 1, any spatial-domain residual difference data must be sent in a chrominance-interleaved form matching the YUV format chrominance interleaving pattern. The value must be 0 unless ConfigResidDiffHost is 1 and the YUV format is NV12 or NV21.
Indicates the method of representation of spatial-domain blocks of residual difference data for intra blocks when using host-based difference decoding.
If ConfigResidDiffHost is 1 and ConfigIntraResidUnsigned is 0, spatial-domain residual difference data blocks for intra macroblocks must be sent as follows:
If ConfigResidDiffHost is 1 and ConfigIntraResidUnsigned is 1, spatial-domain residual difference data blocks for intra macroblocks must be sent as follows:
The value of the member must be 0 unless ConfigResidDiffHost is 1.
If the value is 1, transform-domain blocks of coefficient data may be sent from the host for accelerator-based IDCT. If the value is 0, accelerator-based IDCT will not be used. If both ConfigResidDiffHost and ConfigResidDiffAccelerator are 1, this indicates that some residual difference decoding will be done on the host and some on the accelerator, as indicated by macroblock-level control commands.
The value must be 0 if ConfigBitstreamRaw is 1.
If the value is 1, the inverse scan for transform-domain block processing will be performed on the host, and absolute indices will be sent instead for any transform coefficients. If the value is 0, the inverse scan will be performed on the accelerator.
The value must be 0 if ConfigResidDiffAccelerator is 0 or if Config4GroupedCoefs is 1.
If the value is 1, the IDCT specified in Annex W of ITU-T Recommendation H.263 is used. If the value is 0, any compliant IDCT can be used for off-host IDCT.
The H.263 annex does not comply with the IDCT requirements of MPEG-2 corrigendum 2, so the value must not be 1 for use with MPEG-2 video.
The value must be 0 if ConfigResidDiffAccelerator is 0, indicating purely host-based residual difference decoding.
If the value is 1, transform coefficients for off-host IDCT will be sent using the DXVA_TCoef4Group structure. If the value is 0, the DXVA_TCoefSingle structure is used. The value must be 0 if ConfigResidDiffAccelerator is 0 or if ConfigHostInverseScan is 1.
Specifies how many frames the decoder device processes at any one time.
Contains decoder-specific configuration information.
Applies to: desktop apps only
Describes a video stream for a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processor.
The display driver can use the information in this structure to optimize the capabilities of the video processor. For example, some capabilities might not be exposed for high-definition (HD) content, for performance reasons.
\t\nFrame rates are expressed as ratios. For example, 30 frames per second (fps) is expressed as 30:1, and 29.97 fps is expressed as 30000/1001. For interlaced content, a frame consists of two fields, so that the frame rate is half the field rate.
If the application will composite two or more input streams, use the largest stream for the values of InputWidth and InputHeight.
\t\nA member of the
The frame rate of the input video stream, specified as a
The width of the input frames, in pixels.
The height of the input frames, in pixels.
The frame rate of the output video stream, specified as a
The width of the output frames, in pixels.
The height of the output frames, in pixels.
Applies to: desktop apps only
Contains the response to a D3DAUTHENTICATEDQUERY_OUTPUTIDCOUNT query.
To send this query, call IDirect3DAuthenticatedChannel9::Query.
\t\nApplies to: desktop apps only
Contains an initialization vector (IV) for 128-bit Advanced Encryption Standard CTR mode (AES-CTR) block cipher encryption.
\t\nFor AES-CTR encyption, the pvPVPState member of the
The D3DAES_CTR_IV structure and the
If the IDirect3DDevice9Video::GetContentProtectionCaps method returns the D3DCPCAPS_SEQUENTIAL_CTR_IV flag, the caller should keep IV unchanged when submitting multiple buffers for the same video frame, and Count should be in sequential order of the previous submission for the frame.
Example: Suppose the software decoder submits three buffers for a single frame, and that each buffer contains three 128-bit blocks. For the first buffer, IV can be any value. For the next two buffers, the same value of IV must be used. The value of Count starts at 1. For the second buffer, Count equals 4 (1 + 3 blocks from the first submission). For the third buffer, Count equals 7 (4 + 3 blocks from the second submission).
When the D3DCPCAPS_SEQUENTIAL_CTR_IV capability is present, it is recommended to submit data in 128-bit blocks.
\t\nThe IV, in big-endian format.
The block count, in big-endian format.
Applies to: desktop apps only
Executes a decoding operation on the current frame.
\t\nYou must call
Pointer to a
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Describes the format of a video stream.
\t\nMost of the values in this structure can be translated directly to and from
Use this member to access all of the bits in the union.
Describes the interlacing of the video frames. Contains a value from the
Describes the chroma siting. Contains a value from the
Describes the nominal range of the Y'CbCr or RGB color data. Contains a value from the
Describes the transform from Y'PbPr (component video) to studio R'G'B'. Contains a value from the
Describes the intended viewing conditions. Contains a value from the
Describes the color primaries. Contains a value from the
Describes the gamma correction transfer function. Contains a value from the
Applies to: desktop apps only
Defines the range of supported values for an image filter.
\t\nThe multiplier enables the filter range to have a fractional step value.
For example, a hue filter might have an actual range of [-180.0 ... +180.0] with a step size of 0.25. The device would report the following range and multiplier:
In this case, a filter value of 2 would be interpreted by the device as 0.50 (or 2 ? 0.25).
The device should use a multiplier that can be represented exactly as a base-2 fraction.
\t\nThe minimum value of the filter.
The maximum value of the filter.
The default value of the filter.
A multiplier. Use the following formula to translate the filter setting into the actual filter value: Actual Value = Set Value???Multiplier.
Applies to: desktop apps only
Contains parameters for the
Applies to: desktop apps only
Returns a
You can use this function for DirectX Video Acceleration (DXVA) operations that require alpha values expressed as fixed-point numbers.
\t\nApplies to: desktop apps only
Defines a video frequency.
\t\nThe value 0/0 indicates an unknown frequency. Values of the form n/0, where n is not zero, are invalid. Values of the form 0/n, where n is not zero, indicate a frequency of zero.
\t\nNumerator of the frequency.
Denominator of the frequency.
Applies to: desktop apps only
Sets one or more color adjustment (ProcAmp) settings.
\t\nBefore calling this method, set the video processor mode. To select a video processor mode, call
To find out which ProcAmp settings the driver supports, call
Bitwise OR of one or more flags, specifying which ProcAmp values to set. For a list of flags, see ProcAmp Settings.
Pointer to a
Applies to: desktop apps only
Specifies the pixel aspect ratio (PAR) for the source and destination rectangles.
\t\nPixel aspect ratios of the form 0/n and n/0 are not valid.
If the Enable member is
If TRUE, the SourceAspectRatio and DestinationAspectRatio members contain valid values. Otherwise, the pixel aspect ratios are unspecified.
A
Applies to: desktop apps only
Contains per-stream data for the
The Direct3D surfaces must be allocated in the memory pool specified by the InputPool member of the
The past and future reference frames must be placed in the arrays in temporal order, from oldest to newest. For example, if T is the current input frame, the arrays would be ordered as follows:
The
The OutputIndex and InputFrameOrField members are used to correlate input frames or fields with output frames. The value of the OutputIndex member is cyclic and resets to zero after each cycle.
Here are some example patterns:
Applies to: desktop apps only
Specifies the planar alpha value for an input stream, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nFor each pixel, the destination color value is computed as follows:
Cd = Cs * (As * Ap * Ae) + Cd * (1.0 - As * Ap * Ae)
where
Cd = Color value of the destination pixel.Cs = Color value of source pixel.As = Per-pixel source alpha.Ap = Planar alpha value.Ae = Palette-entry alpha value, or 1.0 (see Note).Note??Palette-entry alpha values apply only to palettized color formats, and only when the device supports the
The destination alpha value is computed according to the
To get the device capabilities, call
If TRUE, alpha blending is enabled. Otherwise, alpha blending is disabled. The default state value is
Specifies the planar alpha value as a floating-point number from 0.0 (transparent) to 1.0 (opaque).
If the Enable member is
Applies to: desktop apps only
Specifies the pixel aspect ratio (PAR) for the source and destination rectangles.
\t\nPixel aspect ratios of the form 0/n and n/0 are not valid.
If the Enable member is
If TRUE, the SourceAspectRatio and DestinationAspectRatio members contain valid values. Otherwise, the pixel aspect ratios are unspecified.
A
A
Applies to: desktop apps only
Specifies the format for an input stream, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nThe surface format, specified as a
The default state value is
Applies to: desktop apps only
Specifies the destination rectangle for an input stream, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nSpecifies whether to use the destination rectangle, or use the entire output surface. The default state value is
| Value | Meaning |
|---|---|
| Use the destination rectangle given in the DestinationRect member. |
| Use the entire output surface as the destination rectangle. |
?
The destination rectangle, which defines the portion of the output surface where the source rectangle is blitted. The destination rectangle is given in pixel coordinates, relative to the output surface. The default value is an empty rectangle, (0, 0, 0, 0).
If the Enable member is
Applies to: desktop apps only
Specifies the level for a filtering operation on a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) input stream.
\t\nFor a list of image filters that are defined for DXVA-HD, see
If TRUE, the filter is enabled. Otherwise, the filter is disabled.
The level for the filter. The meaning of this value depends on the implementation. To get the range and default value of a particular filter, call the
If the Enable member is
Applies to: desktop apps only
Specifies the target rectangle for blitting, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nSpecifies whether to use the target rectangle. The default state value is
| Value | Meaning |
|---|---|
| Use the target rectangle specified by the TargetRect member. |
| Use the entire destination surface as the target rectangle. Ignore the TargetRect member. |
?
Applies to: desktop apps only
Specifies the color space for a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) input stream.
\t\nThe RGB_Range member applies to RGB input, while the YCbCr_Matrix and YCbCr_xvYCC members apply to YCbCr (YUV) input.
In some situations, the device might perform an intermediate color conversion on the input stream. If so, it uses the flags that apply to both color spaces. For example, suppose the device converts from RGB to YCbCr. If the RGB_Range member is 0 and the YCbCr_Matrix member is 1, the device will convert from full-range RGB to BT.709 YCbCr.
If the device supports xvYCC, it returns the
Specifies whether the input stream contains video or graphics. The device can optimize the processing based on the type. The default state value is 0 (video).
| Value | Meaning |
|---|---|
| Video. |
| Graphics. |
?
Specifies the RGB color range. The default state value is 0 (full range).
| Value | Meaning |
|---|---|
| Full range (0-255). |
| Limited range (16-235). |
?
Specifies the YCbCr transfer matrix. The default state value is 0 (BT.601).
| Value | Meaning |
|---|---|
| ITU-R BT.601. |
| ITU-R BT.709. |
?
Specifies whether the input stream uses conventional YCbCr or extended YCbCr (xvYCC). The default state value is 0 (conventional YCbCr).
| Value | Meaning |
|---|---|
| Conventional YCbCr. |
| Extended YCbCr (xvYCC). |
?
Applies to: desktop apps only
Specifies the luma key for an input stream, when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nTo use this state, the device must support luma keying, indicated by the
If the device does not support luma keying, the
If the input format is RGB, the device must also support the
The values of Lower and Upper give the lower and upper bounds of the luma key, using a nominal range of [0...1]. Given a format with n bits per channel, these values are converted to luma values as follows:
val = f * ((1 << n)-1)
Any pixel whose luma value falls within the upper and lower bounds (inclusive) is treated as transparent.
For example, if the pixel format uses 8-bit luma, the upper bound is calculated as follows:
BYTE Y = BYTE(max(min(1.0, Upper), 0.0) * 255.0)
Note that the value is clamped to the range [0...1] before multiplying by 255.
\t\n If TRUE, luma keying is enabled. Otherwise, luma keying is disabled. The default value is
The lower bound for the luma key. The range is [0?1]. The default state value is 0.0.
The upper bound for the luma key. The range is [0?1]. The default state value is 0.0.
Applies to: desktop apps only
Specifies the output frame rate for an input stream when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD).
\t\nThe output rate might require the device to convert the frame rate of the input stream. If so, the value of RepeatFrame controls whether the device creates interpolated frames or simply repeats input frames.
\t\nSpecifies how the device performs frame-rate conversion, if required. The default state value is
| Value | Meaning |
|---|---|
| The device repeats frames. |
| The device interpolates frames. |
?
Specifies the output rate, as a member of the
Specifies a custom output rate, as a
To get the list of custom rates supported by the video processor, call
Applies to: desktop apps only
Contains the response to a D3DAUTHENTICATEDQUERY_OUTPUTIDCOUNT query.
To send this query, call IDirect3DAuthenticatedChannel9::Query.
\t\nApplies to: desktop apps only
Contains the response to a D3DAUTHENTICATEDQUERY_OUTPUTIDCOUNT query.
To send this query, call IDirect3DAuthenticatedChannel9::Query.
\t\nApplies to: desktop apps only
Contains the response to a D3DAUTHENTICATEDQUERY_OUTPUTIDCOUNT query.
To send this query, call IDirect3DAuthenticatedChannel9::Query.
\t\nApplies to: desktop apps only
Specifies the source rectangle for an input stream when using Microsoft DirectX Video Acceleration High Definition (DXVA-HD)
\t\nSpecifies whether to blit the entire input surface or just the source rectangle. The default state value is
| Value | Meaning |
|---|---|
| Use the source rectangle specified in the SourceRect member. |
| Blit the entire input surface. Ignore the SourceRect member. |
?
The source rectangle, which defines the portion of the input sample that is blitted to the destination surface. The source rectangle is given in pixel coordinates, relative to the input surface. The default state value is an empty rectangle, (0, 0, 0, 0).
If the Enable member is
Applies to: desktop apps only
Contains the response to a D3DAUTHENTICATEDQUERY_OUTPUTIDCOUNT query.
To send this query, call IDirect3DAuthenticatedChannel9::Query.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Describes a video stream for a DXVA decoder device or video processor device.
\t\nThe InputSampleFreq member gives the frame rate of the decoded video stream, as received by the video renderer. The OutputFrameFreq member gives the frame rate of the video that is displayed after deinterlacing. If the input video is interlaced and the samples contain interleaved fields, the output frame rate is twice the input frame rate. If the input video is progressive or contains single fields, the output frame rate is the same as the input frame rate.
Decoders should set the values of InputSampleFreq and OutputFrameFreq if the frame rate is known. Otherwise, set these members to 0/0 to indicate an unknown frame rate.
\t\nWidth of the video frame, in pixels.
Height of the video frame, in pixels.
Additional details about the video format, specified as a
Surface format, specified as a
Frame rate of the input video stream, specified as a
Frame rate of the output video, specified as a
Level of data protection required when the user accessible bus (UAB) is present. If TRUE, the video must be protected when a UAB is present. If
Reserved. Must be zero.
Applies to: desktop apps only
Contains parameters for the
Applies to: desktop apps only
Describes the capabilities of a DirectX Video Acceleration (DVXA) video processor mode.
\t\nIdentifies the type of device. The following values are defined.
| Value | Meaning |
|---|---|
| DXVA 2.0 video processing is emulated by using DXVA 1.0. An emulated device may be missing significant processing capabilities and have lower image quality and performance. | |
| Hardware device. | |
| Software device. |
?
The Direct3D memory pool used by the device.
Number of forward reference samples the device needs to perform deinterlacing. For the bob, progressive scan, and software devices, the value is zero.
Number of backward reference samples the device needs to perform deinterlacing. For the bob, progressive scan, and software devices, the value is zero.
Reserved. Must be zero.
Identifies the deinteracing technique used by the device. This value is a bitwise OR of one or more of the following flags.
| Value | Meaning |
|---|---|
| The algorithm is unknown or proprietary. | |
| The algorithm creates missing lines by repeating the line either above or below the missing line. This algorithm produces a jagged image and is not recommended. | |
| The algorithm creates missing lines by averaging two lines. Slight vertical adjustments are made so that the resulting image does not bob up and down. | |
| The algorithm creates missing lines by applying a [?1, 9, 9, ?1]/16 filter across four lines. Slight vertical adjustments are made so that the resulting image does not bob up and down. | |
| The algorithm uses median filtering to recreate the pixels in the missing lines. | |
| The algorithm uses an edge filter to create the missing lines. In this process, spatial directional filters are applied to determine the orientation of edges in the picture content. Missing pixels are created by filtering along (rather than across) the detected edges. | |
| The algorithm uses spatial or temporal interpolation, switching between the two on a field-by-field basis, depending on the amount of motion. | |
| The algorithm uses spatial or temporal interpolation, switching between the two on a pixel-by-pixel basis, depending on the amount of motion. | |
| The algorithm identifies objects within a sequence of video fields. Before it recreates the missing pixels, it aligns the movement axes of the individual objects in the scene to make them parallel with the time axis. | |
| The device can undo the 3:2 pulldown process used in telecine. |
?
Specifies the available video processor (ProcAmp) operations. The value is a bitwise OR of ProcAmp Settings constants.
Specifies operations that the device can perform concurrently with the
| Value | Meaning |
|---|---|
| The device can convert the video from YUV color space to RGB color space, with at least 8 bits of precision for each RGB component. | |
| The device can stretch or shrink the video horizontally. If this capability is present, aspect ratio correction can be performed at the same time as deinterlacing. | |
| The device can stretch or shrink the video vertically. If this capability is present, image resizing and aspect ratio correction can be performed at the same time. | |
| The device can alpha blend the video. | |
| The device can operate on a subrectangle of the video frame. If this capability is present, source images can be cropped before further processing occurs. | |
| The device can accept substreams in addition to the primary video stream, and can composite them. | |
| The device can perform color adjustments on the primary video stream and substreams, at the same time that it deinterlaces the video and composites the substreams. The destination color space is defined in the DestFormat member of the | |
| The device can convert the video from YUV to RGB color space when it writes the deinterlaced and composited pixels to the destination surface. An RGB destination surface could be an off-screen surface, texture, Direct3D render target, or combined texture/render target surface. An RGB destination surface must use at least 8 bits for each color channel. | |
| The device can perform an alpha blend operation with the destination surface when it writes the deinterlaced and composited pixels to the destination surface. | |
| The device can downsample the output frame, as specified by the ConstrictionSize member of the | |
| The device can perform noise filtering. | |
| The device can perform detail filtering. | |
| The device can perform a constant alpha blend to the entire video stream when it composites the video stream and substreams. | |
| The device can perform accurate linear RGB scaling, rather than performing them in nonlinear gamma space. | |
| The device can correct the image to compensate for artifacts introduced when performing scaling in nonlinear gamma space. | |
| The deinterlacing algorithm preserves the original field lines from the interlaced field picture, unless scaling is also applied. For example, in deinterlacing algorithms such as bob and median filtering, the device copies the original field into every other scan line and then applies a filter to reconstruct the missing scan lines. As a result, the original field can be recovered by discarding the scan lines that were interpolated. If the image is scaled vertically, however, the original field lines cannot be recovered. If the image is scaled horizontally (but not vertically), the resulting field lines will be equivalent to scaling the original field picture. (In other words, discarding the interpolated scan lines will yield the same result as stretching the original picture without deinterlacing.) |
?
Specifies the supported noise filters. The value is a bitwise OR of the following flags.
| Value | Meaning |
|---|---|
| Noise filtering is not supported. | |
| Unknown or proprietary filter. | |
| Median filter. | |
| Temporal filter. | |
| Block noise filter. | |
| Mosquito noise filter. |
?
Specifies the supported detail filters. The value is a bitwise OR of the following flags.
| Value | Meaning |
|---|---|
| Detail filtering is not supported. | |
| Unknown or proprietary filter. | |
| Edge filter. | |
| Sharpen filter. |
?
Applies to: desktop apps only
Specifies an input sample for the
Applies to: desktop apps only
Gets the capabilities of one or more Microsoft DirectX Video Acceleration High Definition (DXVA-HD) video processors.
\t\nThe number of elements in the pCaps array. This parameter must equal the VideoProcessorCount member of the
A reference to an array of
Applies to: desktop apps only
Specifies the capabilities of a Microsoft DirectX Video Acceleration High Definition (DXVA-HD) device.
\t\nIn DXVA-HD, the device stores state information for each input stream. These states persist between blits. With each blit, the application selects which streams to enable or disable. Disabling a stream does not affect the state information for that stream.
The MaxStreamStates member gives the maximum number of stream states that can be set by the application. The MaxInputStreams member gives the maximum number of streams that can be enabled during a blit. These two values can differ.
To set the state data for a stream, call
Specifies the device type, as a member of the
A bitwise OR of zero or more flags from the
A bitwise OR of zero or more flags from the
A bitwise OR of zero or more flags from the
A bitwise OR of zero or more flags from the
The memory pool that is required for the input video surfaces.
The number of supported output formats. To get the list of output formats, call the
The number of supported input formats. To get the list of input formats, call the
The number of video processors. Each video processor represents a distinct set of processing capabilities. To get the capabilities of each video processor, call the
The maximum number of input streams that can be enabled at the same time.
The maximum number of input streams for which the device can store state data.
Applies to: desktop apps only
Defines the ASF indexer options.
\t\nThe indexer creates a new index object.
The indexer returns values for reverse playback.
The indexer creates an index object for a live ASF stream.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Applies to: desktop apps | Metro style apps
Describes the current status of a call to the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies a type of capture device.
\t\nAn audio capture device, such as a microphone.
A video capture device, such as a webcam.
Applies to: desktop apps only
Defines the ASF stream selector options.
\t\nThe stream selector will not set thinning. Thinning is the process of removing samples from a stream to reduce the bit rate.
The stream selector will use the average bit rate of streams when selecting streams.
Applies to: desktop apps only
Creates a new work queue. This function extends the capabilities of the
When you are done using the work queue, call
The
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps only
Defines flags for serializing and deserializing attribute stores.
\t\nIf this flag is set,
Applies to: desktop apps | Metro style apps
Specifies how to compare the attributes on two objects.
\t\nCheck whether all the attributes in pThis exist in pTheirs and have the same data, where pThis is the object whose Compare method is being called and pTheirs is the object given in the pTheirs parameter.
Check whether all the attributes in pTheirs exist in pThis and have the same data, where pThis is the object whose Compare method is being called and pTheirs is the object given in the pTheirs parameter.
Check whether both objects have identical attributes with the same data.
Check whether the attributes that exist in both objects have the same data.
Find the object with the fewest number of attributes, and check if those attributes exist in the other object and have the same data.
Applies to: desktop apps | Metro style apps
Defines the data type for a key/value pair.
\t\nUnsigned 32-bit integer.
Unsigned 64-bit integer.
Floating-point number.
Byte array.
Applies to: desktop apps | Metro style apps
Specifies the origin for a seek request.
\t\nThe seek position is specified relative to the start of the stream.
The seek position is specified relative to the current read/write position in the stream.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the topology loader connects a topology node. This enumeration is used with the
Media Foundation transforms (MFTs) are an evolution of the transform model first introduced with DirectX Media Objects (DMOs). This topic summarizes the main ways in which MFTs differ from DMOs. Read this topic if you are already familiar with the DMO interfaces, or if you want to convert an existing DMO into an MFT.
This topic contains the following sections:
Applies to: desktop apps only
Contains flags that are used to configure the Microsoft DirectShow enhanced video renderer (EVR) filter.
\t\nEnables dynamic adjustments to video quality during playback.
Applies to: desktop apps only
Specifies the requested access mode for opening a file.
\t\nRead mode.
Write mode.
Read and write mode.
Applies to: desktop apps only
Specifies the behavior when opening a file.
\t\nUse the default behavior.
Open the file with no system caching.
Subsequent open operations can have write access to the file.
Note??Requires Windows?7 or later.
Applies to: desktop apps only
Creates a byte stream that is backed by a temporary local file.
\t\n This function creates a file in the system temporary folder, and then returns a byte stream object for that file. The full path name of the file is storted in the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
The requested access mode, specified as a member of the
The behavior of the function if the file already exists or does not exist, specified as a member of the
Bitwise OR of values from the
Receives a reference to the
Applies to: desktop apps only
Defines the characteristics of a media source. These flags are retrieved by the
To skip forward or backward in a playlist, call
Applies to: desktop apps only
Contains flags that define the behavior of the
Applies to: desktop apps only
Contains flags that define the behavior of the
Applies to: desktop apps only
Defines the characteristics of a media source. These flags are retrieved by the
To skip forward or backward in a playlist, call
Applies to: desktop apps only
Defines messages for an enhanced video renderer (EVR) presenter. This enumeration is used with the
Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.\t\n if (Buffer.dwStatus == )\t\n { ...\t\n } // Incorrect.\t\n if ((Buffer.dwStatus & ) != 0)\t\n { ...\t\n }\t\n \t\n Applies to: desktop apps | Metro style apps
Describes the current status of a call to the
Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.\t\n if (Buffer.dwStatus == )\t\n { ...\t\n } // Incorrect.\t\n if ((Buffer.dwStatus & ) != 0)\t\n { ...\t\n }\t\n \t\n Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.\t\n if (Buffer.dwStatus == )\t\n { ...\t\n } // Incorrect.\t\n if ((Buffer.dwStatus & ) != 0)\t\n { ...\t\n }\t\n \t\n Applies to: desktop apps only
Indicates whether a Media Foundation transform (MFT) can produce output data.
\t\nThere is a sample available for at least one output stream. To retrieve the available output samples, call
Applies to: desktop apps only
Describes an output stream on a Media Foundation transform (MFT).
\t\nBefore the client sets the media types on the MFT, the only flag guaranteed to be accurate is the
The
MFT_OUTPUT_STREAM_DISCARDABLE: The MFT discards output data only if the client calls ProcessOutput with the
MFT_OUTPUT_STREAM_LAZY_READ: If the client continues to call ProcessInput without collecting the output from this stream, the MFT eventually discards the output. If all output streams have the
If neither of these flags is set, the MFT never discards output data.
\t\nEach media sample (
For uncompressed audio formats, this flag is always implied. (It is valid to set the flag, but not required.) An uncompressed audio frame should never span more than one media sample.
Each output sample contains exactly one unit of data, as defined for the
If this flag is present, the
An MFT that outputs uncompressed audio should not set this flag. For efficiency, it should output more than one audio frame at a time.
All output samples are the same size.
The MFT can discard the output data from this output stream, if requested by the client. To discard the output, set the
This output stream is optional. The client can deselect the stream by not setting a media type or by setting a
The MFT provides the output samples for this stream, either by allocating them internally or by operating directly on the input samples. The MFT cannot use output samples provided by the client for this stream.
If this flag is not set, the MFT must set cbSize to a nonzero value in the
The MFT can either provide output samples for this stream or it can use samples that the client allocates. This flag cannot be combined with the
If the MFT does not set this flag or the
The MFT does not require the client to process the output for this stream. If the client continues to send input data without getting the output from this stream, the MFT simply discards the previous input.
The MFT might remove this output stream during streaming. This flag typically applies to demultiplexers, where the input data contains multiple streams that can start and stop during streaming. For more information, see
Applies to: desktop apps only
Defines flags for the setting or testing the media type on a Media Foundation transform (MFT).
\t\nTest the proposed media type, but do not set it.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Media Foundation provides a default implementation of the
To create the default credential cache object, call the
hr = ;\t\n *pCredentialCache = null ;\t\n hr = (&pCredentialCache);\t\n After the credential cache is created, the application can use the following methods to get a credential object, set user credentials, and specify the caching options.
To get the credential object for a URL, call
hr = pCredentialCache-> GetCredential( pszUrl, pszRealm, dwAuthenticationFlags, &pCredential, &dwRequirementsFlags);\t\n If the credentials for the specified URL do not exist in the credential cache, GetCredential creates a new credential object with empty user name and password values.
To set the caching options on the credential object, call
hr = pCredentialCache-> SetUserOptions( pCredentialCache, );\t\n The dwOptionsFlags parameter values are defined in the
By default, user credentials sent over the network are encrypted. To change this to clear text, set the
To remove information from the registry, call GetCredential to get the credential object, and then call SetUserOption and set dwOptionsFlags to
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
This topic describes the configuration settings for the default proxy locator. For information about creating the proxy locator with custom configuration settings, see How to Configure the Proxy Locator.
The proxy locator can be configured to operate in three modes: manual mode, auto-detect mode, and browser mode. The values are defined in
Caution??A proxy server is a security barrier between your intranet and the Internet. Not using a proxy server can expose the network to security threats.
Manual Mode. The application sets this mode by setting the MFNETSOURCE_PROXYSETTING property to
Whether to use a proxy server for local addresses: MFNETSOURCE_PROXYBYPASSFORLOCAL property. This setting is optional. If this is not specified, then the proxy locator uses a default value of
Note??By bypassing the proxy server, the application might be able to connect to media servers on the intranet faster.
Auto-Detect Mode. The application sets this mode by setting the MFNETSOURCE_PROXYSETTING property to
The proxy locator caches the connection information in the registry. In subsequent proxy detection calls, the proxy locator reads proxy information from the registry cache to reduce the overhead involved in auto detection. However, the application can force auto proxy redetection by setting the MFNETSOURCE_PROXYRERUNAUTODETECTION property.
Applies to: desktop apps only
Defines the status of the cache for a media file or entry.
\t\nThe cache for a file or entry does not exist.
The cache for a file or entry is growing.
The cache for a file or entry is completed.
Applies to: desktop apps only
Retrieves a supported protocol by index
\t\nZero-based index of the protocol to retrieve. To get the number of supported protocols, call
Receives a member of the
Applies to: desktop apps only
Defines statistics collected by the network source. The values in this enumeration define property identifiers (PIDs) for the MFNETSOURCE_STATISTICS property.
To retrieve statistics from the network source, call
In the descriptions that follow, the data type and value-type tag for the
Applies to: desktop apps only
Defines statistics collected by the network source. The values in this enumeration define property identifiers (PIDs) for the MFNETSOURCE_STATISTICS property.
To retrieve statistics from the network source, call
In the descriptions that follow, the data type and value-type tag for the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps | Metro style apps
Defines the object types that are created by the source resolver.
\t\nMedia source. You can query the object for the
Byte stream. You can query the object for the
Invalid type.
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Defines event types for the
For each event type, the
In your implementation of OnMediaPlayerEvent, you must cast the pEventHeader parameter to the correct structure type. A set of macros is defined for this purpose. These macros check the value of the event type and return
| Event type | Event structure | Pointer cast macro |
|---|---|---|
| | MFP_GET_PLAY_EVENT | |
| | MFP_GET_PAUSE_EVENT | |
| | MFP_GET_STOP_EVENT | |
| | MFP_GET_POSITION_SET_EVENT | |
| | MFP_GET_RATE_SET_EVENT | |
| | MFP_GET_MEDIAITEM_CREATED_EVENT | |
| | MFP_GET_MEDIAITEM_SET_EVENT | |
| | MFP_GET_FRAME_STEP_EVENT | |
| | MFP_GET_MEDIAITEM_CLEARED_EVENT | |
| | MFP_GET_MF_EVENT | |
| | MFP_GET_ERROR_EVENT | |
| | MFP_GET_PLAYBACK_ENDED_EVENT | |
| | MFP_GET_ACQUIRE_USER_CREDENTIAL_EVENT |
?
\t\nApplies to: desktop apps only
Adds a class identifier (CLSID) to the preferred list or removes a CLSID from the list.
\t\nThe preferred list is global to the caller's process. Calling this method does not affect the list in other process.
\t\nMember of the
The key name for the CLSID. For more information about the format of key names, see the Remarks section of
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Specifies the current playback state.
\t\nApplies to: desktop apps only
Contains flags that define the behavior of the
Applies to: desktop apps | Metro style apps
Defines actions that can be performed on a stream.
\t\nNo action.
Play the stream.
Copy the stream.
Export the stream to another format.
Extract the data from the stream and pass it to the application. For example, acoustic echo cancellation requires this action.
Reserved.
Reserved.
Reserved.
Last member of the enumeration.
Applies to: desktop apps only
Contains flags for the
If the decoder sets the
Applies to: desktop apps | Metro style apps
Specifies how aggressively a pipeline component should drop samples.
\t\nIn drop mode, a component drops samples, more or less aggressively depending on the level of the drop mode. The specific algorithm used depends on the component. Mode 1 is the least aggressive mode, and mode 5 is the most aggressive. A component is not required to implement all five levels.
For example, suppose an encoded video stream has three B-frames between each pair of P-frames. A decoder might implement the following drop modes:
Mode 1: Drop one out of every three B frames.
Mode 2: Drop one out of every two B frames.
Mode 3: Drop all delta frames.
Modes 4 and 5: Unsupported.
The enhanced video renderer (EVR) can drop video frames before sending them to the EVR mixer.
\t\nNormal processing of samples. Drop mode is disabled.
First drop mode (least aggressive).
Second drop mode.
Third drop mode.
Fourth drop mode.
Fifth drop mode (most aggressive, if it is supported; see Remarks).
Maximum number of drop modes. This value is not a valid flag.
Applies to: desktop apps | Metro style apps
Specifies the quality level for a pipeline component. The quality level determines how the component consumes or produces samples.
\t\nEach successive quality level decreases the amount of processing that is needed, while also reducing the resulting quality of the audio or video. The specific algorithm used to reduce quality depends on the component. Mode 1 is the least aggressive mode, and mode 5 is the most aggressive. A component is not required to implement all five levels. Also, the same quality level might not be comparable between two different components.
Video decoders can often reduce quality by leaving out certain post-processing steps. The enhanced video renderer (EVR) can sometimes reduce quality by switching to a different deinterlacing mode.
\t\nNormal quality.
One level below normal quality.
Two levels below normal quality.
Three levels below normal quality.
Four levels below normal quality.
Five levels below normal quality.
Maximum number of quality levels. This value is not a valid flag.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps | Metro style apps
Retrieves the sample protection certificate.
\t\nFor certain version numbers of sample protection, the downstream component must provide a certificate. Components that do not support these version numbers can return E_NOTIMPL.
\t\nSpecifies the version number of the sample protection scheme for which to receive a certificate. The version number is specified as a
Receives a reference to a buffer containing the certificate. The caller must free the memory for the buffer by calling CoTaskMemFree.
Receives the size of the ppCert buffer, in bytes.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Retrieves an interface from the enhanced video renderer (EVR), or from the video mixer or video presenter.
Type
[in] Specifies the scope of the search. Currently this parameter is ignored. Use the value
dwIndex
[in] Reserved, must be zero.
guidService
[in] Service
riid
[in] Interface identifier of the requested interface.
ppvObjects
[out] Array of interface references. If the method succeeds, each member of the array is initialized to the requested interface. The caller must release the interface references when the EVR calls
pnObjects
[in, out] On input, a reference to a value that specifies the size of the ppvObjects array. The value must be at least 1. On output, receives the number of valid references copied into the ppvObjects array. In the current implementation, there is no particular reason to specify an array size larger than one element.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| E_INVALIDARG | Invalid argument. |
| E_NOINTERFACE | The requested interface is not available. |
| | The method was not called from inside the InitServicePointers method. See Remarks. |
| | The object does not support the specified service |
This method can be called only from inside the
The presenter can use this method to query the EVR and the mixer. The mixer can use it to query the EVR and the presenter. Which objects are queried depends on the caller and the service
| Caller | Service | Objects queried |
|---|---|---|
| Presenter | MR_VIDEO_RENDER_SERVICE | EVR |
| Presenter | MR_VIDEO_MIXER_SERVICE | Mixer |
| Mixer | MR_VIDEO_RENDER_SERVICE | Presenter and EVR |
The following interfaces are available from the EVR:
IMediaEventSink Interface
The IMediaEventSink interface is documented in the DirectShow SDK documentation.
The following interfaces are available from the mixer:
Client: Requires Windows Vista.
Header: Include evr.h.
Library: Use strmiids.lib.
ReferenceIMFTopologyServiceLookup InterfaceConceptsHow to Write an EVR Presenter\t\nApplies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Applies to: desktop apps only
Defines the behavior of the
These flags are optional, and are not mutually exclusive. If no flags are set, the Media Session resolves the topology and then adds it to the queue of pending presentations.
\t\nApplies to: desktop apps | Metro style apps
Describes the current status of a call to the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Contains flags for the
Applies to: desktop apps only
Contains flags that indicate the status of the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps | Metro style apps
Places a marker in the stream.
\t\nThis method causes the stream sink to send an
Specifies the marker type, as a member of the
Optional reference to a
Optional reference to a
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Applies to: desktop apps | Metro style apps
Sends a message to the Media Foundation transform (MFT).
\t\nBefore calling this method, set the media types on all input and output streams.
The MFT might ignore certain message types. If so, the method returns
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessMessage. See Creating Hybrid DMO/MFT Objects.
\t\n The message to send, specified as a member of the
Message parameter. The meaning of this parameter depends on the message type.
Applies to: desktop apps only
Specifies whether the topology loader enables Microsoft DirectX Video Acceleration (DXVA) in the topology.
\t\nThis enumeration is used with the
If an MFT supports DXVA, the MFT must return TRUE for the
Previous versions of Microsoft Media Foundation supported DXVA only for decoders.
\t\nThe topology loader enables DXVA\t\n on the decoder if possible, and drops optional Media Foundation transforms (MFTs) that do not support DXVA.
The topology loader disables all video acceleration. This setting forces software processing, even when the decoder supports DXVA.
The topology loader enables DXVA on every MFT that supports it.
Applies to: desktop apps only
Specifies whether the topology loader will insert hardware-based Media Foundation transforms (MFTs) into the topology.
\t\n This enumeration is used with the
Use only software MFTs. Do not use hardware-based MFTs. This mode is the default, for backward compatibility with existing applications.
Use hardware-based MFTs when possible, and software MFTs otherwise. This mode is the recommended one.
Applies to: desktop apps only
Defines status flags for the
Applies to: desktop apps only
Defines the type of a topology node.
\t\nOutput node. Represents a media sink in the topology.
Source node. Represents a media stream in the topology.
Transform node. Represents a Media Foundation Transform (MFT) in the topology.
Tee node. A tee node does not hold a reference to an object. Instead, it represents a fork in the stream. A tee node has one input and multiple outputs, and samples from the upstream node are delivered to all of the downstream nodes.
Reserved.
Applies to: desktop apps only
Defines at what times a transform in a topology is drained.
\t\nThe transform is drained when the end of a stream is reached. It is not drained when markout is reached at the end of a segment.
The transform is drained whenever a topology ends.
The transform is never drained.
Applies to: desktop apps only
Defines when a transform in a topology is flushed.
\t\nThe transform is flushed whenever the stream changes, including seeks and new segments.
The transform is flushed when seeking is performed on the stream.
The transform is never flushed during streaming. It is flushed only when the object is released.
Applies to: desktop apps only
Specifies the status of a topology during playback.
\t\n This enumeration is used with the
For a single topology, the Media Session sends these status flags in numerical order, starting with
This value is not used.
The topology is ready to start. After this status flag is received, you can use the Media Session's
The Media Session has started to read data from the media sources in the topology.
The Media Session modified the topology, because the format of a stream changed.
The media sinks have switched from the previous topology to this topology. This status value is not sent for the first topology that is played. For the first topology, the
Playback of this topology is complete. The Media Session might still use the topology internally. The Media Session does not completely release the topology until it sends the next
Applies to: desktop apps only
Defines the profile flags that are set in the
These flags are checked by
For more information about the stream settings that an application can specify, see Using the Transcode API.
\t\nIf the
The
For the video stream, the required attributes are as follows:
If these attributes are not set,
Use the
For example, assume that your input source is an MP3 file. You set the container to be MFTranscodeContainerType_ASF, you do not set any stream attributes, and you set the
Applies to: desktop apps only
Defines flags for the
Applies to: desktop apps only
Contains flags for registering and enumeration Media Foundation transforms (MFTs).
These flags are used in the following functions:
For registration, these flags describe the MFT that is being registered. Some flags do not apply in that context. For enumeration, these flags control which MFTs are selected in the enumeration. For more details about the precise meaning of these flags, see the reference topics for
For registration, the
Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.\t\n if (Buffer.dwStatus == )\t\n { ...\t\n } // Incorrect.\t\n if ((Buffer.dwStatus & ) != 0)\t\n { ...\t\n }\t\n \t\n Applies to: desktop apps only
Indicates the status of a call to
If the MFT sets this flag, the ProcessOutput method returns
Call
Call
Call
Until these steps are completed, all further calls to ProcessOutput return
Applies to: desktop apps | Metro style apps
Retrieves a URL for performing a manual content enabling action.
\t\nIf the enabling action can be performed by navigating to a URL, this method returns the URL. If no such URL exists, the method returns a failure code.
The purpose of the URL depends on the content enabler type, which is obtained by calling
| Enable type | Purpose of URL |
|---|---|
| Individualization | Not applicable. |
| License acquisition | URL to obtain the license. Call |
| Revocation | URL to a webpage where the user can download and install an updated component. |
?
\t\nReceives a reference to a buffer that contains the URL. The caller must release the memory for the buffer by calling CoTaskMemFree.
Receives the number of characters returned in ppwszURL, including the terminating
Receives a member of the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies the aspect-ratio mode.
\t\nDo not maintain the aspect ratio of the video. Stretch the video to fit the output rectangle.
Preserve the aspect ratio of the video by letterboxing or within the output rectangle.
Note??Currently the EVR ignores this flag.
Correct the aspect ratio if the physical size of the display device does not match the display resolution. For example, if the native resolution of the monitor is 1600 by 1200 (4:3) but the display resolution is 1280 by 1024 (5:4), the monitor will display non-square pixels.
If this flag is set, you must also set the
Apply a non-linear horizontal stretch if the aspect ratio of the destination rectangle does not match the aspect ratio of the source rectangle.
The non-linear stretch algorithm preserves the aspect ratio in the middle of the picture and stretches (or shrinks) the image progressively more toward the left and right. This mode is useful when viewing 4:3 content full-screen on a 16:9 display, instead of pillar-boxing. Non-linear vertical stretch is not supported, because the visual results are generally poor.
This mode may cause performance degradation.
If this flag is set, you must also set the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Creates a video media type from a
Applies to: desktop apps only
Contains flags that define the chroma encoding scheme for Y'Cb'Cr' data.
\t\nThese flags are used with the
For more information about these values, see the remarks for the
Unknown encoding scheme.
Chroma should be reconstructed as if the underlying video was progressive content, rather than skipping fields or applying chroma filtering to minimize artifacts from reconstructing 4:2:0 interlaced chroma.
Chroma samples are aligned horizontally with the luma samples, or with multiples of the luma samples. If this flag is not set, chroma samples are located 1/2 pixel to the right of the corresponding luma sample.
Chroma samples are aligned vertically with the luma samples, or with multiples of the luma samples. If this flag is not set, chroma samples are located 1/2 pixel down from the corresponding luma sample.
The U and V planes are aligned vertically. If this flag is not set, the chroma planes are assumed to be out of phase by 1/2 chroma sample, alternating between a line of U followed by a line of V.
Specifies the chroma encoding scheme for MPEG-2 video. Chroma samples are aligned horizontally with the luma samples, but are not aligned vertically. The U and V planes are aligned vertically.
Specifies the chroma encoding scheme for MPEG-1 video.
Specifies the chroma encoding scheme for PAL DV video.
Chroma samples are aligned vertically and horizontally with the luma samples. YUV formats such as 4:4:4, 4:2:2, and 4:1:1 are always cosited in both directions and should use this flag.
Reserved.
Reserved. This member forces the enumeration type to compile as a DWORD value.
Applies to: desktop apps only
Specifies how a video stream is interlaced.
In the descriptions that follow, upper field refers to the field that contains the leading half scan line. Lower field refers to the field that contains the first full scan line.
\t\nScan lines in the lower field are 0.5 scan line lower than those in the upper field. In NTSC television, a frame consists of a lower field followed by an upper field. In PAL television, a frame consists of an upper field followed by a lower field.
The upper field is also called the even field, the top field, or field 2. The lower field is also called the odd field, the bottom field, or field 1.
If the interlace mode is
The type of interlacing is not known.
Progressive frames.
Interlaced frames. Each frame contains two fields. The field lines are interleaved, with the upper field appearing on the first line.
Interlaced frames. Each frame contains two fields. The field lines are interleaved, with the lower field appearing on the first line.
Interlaced frames. Each frame contains one field, with the upper field appearing first.
Interlaced frames. Each frame contains one field, with the lower field appearing first.
The stream contains a mix of interlaced and progressive modes.
Reserved.
Reserved. This member forces the enumeration type to compile as a DWORD value.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Contains flags that are used to configure how the enhanced video renderer (EVR) performs deinterlacing.
\t\nTo set these flags, call the
These flags control some trade-offs between video quality and rendering speed. The constants named \"MFVideoMixPrefs_Allow...\" enable lower-quality settings, but only when the quality manager requests a drop in quality. The constants named \"MFVideoMixPrefs_Force...\" force the EVR to use lower-quality settings regardless of what the quality manager requests. (For more information about the quality manager, see
Currently two lower-quality modes are supported, as described in the following table. Either is preferable to dropping an entire frame.
| Mode | Description |
|---|---|
| Half interface | The EVR's video mixer skips the second field (relative to temporal order) of each interlaced frame. The video mixer still deinterlaces the first field, and this operation typically interpolates data from the second field. The overall frame rate is unaffected. |
| Bob deinterlacing | The video mixer uses bob deinterlacing, even if the driver supports a higher-quality deinterlacing algorithm. |
?
\t\nForce the EVR to skip the second field (in temporal order) of every interlaced frame.
If the EVR is falling behind, allow it to skip the second field (in temporal order) of every interlaced frame.
If the EVR is falling behind, allow it to use bob deinterlacing, even if the driver supports a higher-quality deinterlacing mode.
Force the EVR to use bob deinterlacing, even if the driver supports a higher-quality mode.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Contains flags that define how the enhanced video renderer (EVR) displays the video.
\t\nTo set these flags, call
The flags named \"MFVideoRenderPrefs_Allow...\" cause the EVR to use lower-quality settings only when requested by the quality manager. (For more information, see
If this flag is set, the EVR does not draw the border color. By default, the EVR draws a border on areas of the destination rectangle that have no video. See
If this flag is set, the EVR does not clip the video when the video window straddles two monitors. By default, if the video window straddles two monitors, the EVR clips the video to the monitor that contains the largest area of video.
Note??Requires Windows?7 or later.
Allow the EVR to limit its output to match GPU bandwidth.
Note??Requires Windows?7 or later.
Force the EVR to limit its output to match GPU bandwidth.
Note??Requires Windows?7 or later.
Force the EVR to batch Direct3D Present calls. This optimization enables the system to enter to idle states more frequently, which can reduce power consumption.
Note??Requires Windows?7 or later.
Allow the EVR to batch Direct3D Present calls.
Note??Requires Windows?7 or later.
Force the EVR to mix the video inside a rectangle that is smaller than the output rectangle. The EVR will then scale the result to the correct output size. The effective resolution will be lower if this setting is applied.
Note??Requires Windows?7 or later.
Allow the EVR to mix the video inside a rectangle that is smaller than the output rectangle.
Note??Requires Windows?7 or later.
Prevent the EVR from repainting the video window after a stop command. By default, the EVR repaints the video window black after a stop command.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Defines messages for an enhanced video renderer (EVR) presenter. This enumeration is used with the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
\t\nThe application implements the credential manager, which must expose the
The credential cache object sets the
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Creates a media sample that manages a Direct3D surface.
\t\n A reference to the
Receives a reference to the sample's
If this function succeeds, it returns
The media sample created by this function exposes the following interfaces in addition to
If pUnkSurface is non-
Alternatively, you can set pUnkSurface to
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates an instance of the enhanced video renderer (EVR) media sink.
\t\nInterface identifier (IID) of the requested interface on the EVR.
Receives a reference to the requested interface. The caller must release the interface.
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This function creates the Media Foundation version of the EVR. To create the DirectShow EVR filter, call CoCreateInstance with the class identifier CLSID_EnhancedVideoRenderer.
\t\nApplies to: desktop apps only
Creates the default video mixer and video presenter for the enhanced video renderer (EVR).
\t\nPointer to the owner of the video mixer. If the mixer is aggregated, pass a reference to the aggregating object's
Pointer to the owner of the video presenter. If the presenter is aggregated, pass a reference to the aggregating object's
Interface identifier (IID) of the requested interface on the video mixer. The video mixer exposes the
Receives a reference to the requested interface on the video mixer. The caller must release the interface.
IID of the requested interface on the video presenter. The video presenter exposes the
Receives a reference to the requested interface on the video presenter. The caller must release the interface.
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Creates a new instance of the MFPlay player object.
\t\nIf this function succeeds, it returns
Before calling this function, call CoIntialize(Ex) from the same thread to initialize the COM library.
Internally,
Note??If you use other Media Foundation APIs outside the life time of the player object, then your application should call
Applies to: desktop apps | Metro style apps
Creates the sink writer from a URL or byte stream.
\t\nA null-terminated string that contains the URL of the output file. This parameter can be
Pointer to the
If this parameter is a valid reference, the sink writer writes to the provided byte stream. (The byte stream must be writable.) Otherwise, if pByteStream is
Pointer to the
Receives a reference to the
This function can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| | The specified URL was not found. |
?
Call CoInitialize(Ex) and
The first three parameters to this function can be
| Description | pwszOutputURL | pByteStream | pAttributes |
|---|---|---|---|
| Specify a byte stream, with no URL. | non- | Required (must not be | |
| Specify a URL, with no byte stream. | not | Optional (may be | |
| Specify both a URL and a byte stream. | non- | non- | Optional (may be |
?
The pAttributes parameter is required in the first case and optional in the others.
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Creates the source reader from a URL.
\t\nThe URL of a media file to open.
Pointer to the
Receives a reference to the
If this function succeeds, it returns
Call CoInitialize(Ex) and
Internally, the source reader calls the
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Creates the source reader from a media source.
\t\nA reference to the
Pointer to the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The source contains protected content. |
?
Call CoInitialize(Ex) and
By default, when the application releases the source reader, the source reader shuts down the media source by calling
To change this default behavior, set the
When using the Source Reader, do not call any of the following methods on the media source:
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Creates the sink writer from a media sink.
\t\nPointer to the
Pointer to the
Receives a reference to the
If this function succeeds, it returns
Call CoInitialize(Ex) and
When you are done using the media sink, call the media sink's
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Creates the source reader from a byte stream.
\t\nA reference to the
Pointer to the
Receives a reference to the
If this function succeeds, it returns
Call CoInitialize(Ex) and
Internally, the source reader calls the
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps only
Manages an Advanced Systems Format (ASF) profile. A profile is a collection of information that describes the configuration of streams that will be included in an ASF file. Information about the relationships between streams is also included in the profile.
An
Applies to: desktop apps only
Creates an activation object for the ASF streaming sink.
The ASF streaming sink enables an application to write streaming Advanced Systems Format (ASF) packets to an HTTP byte stream. The activation object can be used to create the ASF streaming sink in another process.
\t\nA reference to the
A reference to an ASF ContentInfo Object that contains the properties that describe the ASF content. These settings can contain stream settings, encoding properties, and metadata. For more information about these properties, see Setting Properties in the ContentInfo Object.
Receives a reference to the
If this function succeeds, it returns
Starting in Windows?7, Media Foundation provides an ASF streaming sink that writes the content in a live streaming scenario. This function should be used in secure transcode scenarios where this media sink needs to be created and configured in the remote\t\n process. Like the ASF file sink, the new media sink performs ASF related tasks such as writing the ASF header, generating data packets (muxing). The content is written to a caller-implemented byte stream such as an HTTP byte stream.\t\n The caller must also provide an activation object that media sink can use to create the byte stream remotely.
In addition, it performs transcryption for streaming protected content. It hosts the Windows Media Digital Rights Management (DRM) for Network Devices Output Trust Authority (OTA) that handles the license request and response. For more information, see
The new media sink does not perform any time adjustments. If the clock seeks, the timestamps are not changed.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates an activation object for the ASF streaming sink.
The ASF streaming sink enables an application to write streaming Advanced Systems Format (ASF) packets to an HTTP byte stream.
\t\nA reference to a byte stream object in which the ASF media sink writes the streamed content.
Receives a reference to the
If this function succeeds, it returns
To create the ASF streaming sink in another process, call
An application can get a reference to the ASF ContentInfo Object by calling IUnknown::QueryInterface on the media sink object received in the ppIMediaSink parameter. The ContentInfo object is used to set the encoder configuration settings, provide stream properties supplied by an ASF profile, and add metadata information. These configuration settings populate the various ASF header objects of the encoded ASF file. For more information, see \t\n Setting Properties in the ContentInfo Object.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates an activation object for the ASF streaming sink.
The ASF streaming sink enables an application to write streaming Advanced Systems Format (ASF) packets to an HTTP byte stream.
\t\nA reference to a byte stream object in which the ASF media sink writes the streamed content.
Receives a reference to the
If this function succeeds, it returns
To create the ASF streaming sink in another process, call
An application can get a reference to the ASF ContentInfo Object by calling IUnknown::QueryInterface on the media sink object received in the ppIMediaSink parameter. The ContentInfo object is used to set the encoder configuration settings, provide stream properties supplied by an ASF profile, and add metadata information. These configuration settings populate the various ASF header objects of the encoded ASF file. For more information, see \t\n Setting Properties in the ContentInfo Object.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates an activation object that can be used to create a Windows Media Audio (WMA) encoder.
\t\n A reference to the
A reference to the
Receives a reference to the
If this function succeeds, it returns
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates the ASF media sink.
\t\nPointer to a byte stream that will be used to write the ASF stream.
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[This API is not supported and may be altered or unavailable in the future.]
Applies to: desktop apps only
Creates an audio media type from a
Pointer to a
Receives a reference to the
If this function succeeds, it returns
The
Alternatively, you can call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Cancels a callback function that was set by the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
The callback is dispatched on another thread, and this function does not attempt to synchronize with the callback thread. Therefore, it is possible for the callback to be invoked after this function returns.
\t\nApplies to: desktop apps only
Converts a video frame rate into a frame duration.
\t\nThe numerator of the frame rate.
The denominator of the frame rate.
Receives the average duration of a video frame, in 100-nanosecond units.
If this function succeeds, it returns
This function is useful for calculating time stamps on a sample, given the frame rate.
Also, average time per frame is used in the older
For certain common frame rates, the function gets the frame duration from a look-up table:
| Frames per second (floating point) | Frames per second (fractional) | Average time per frame |
|---|---|---|
| 59.94 | 60000/1001 | 166833 |
| 29.97 | 30000/1001 | 333667 |
| 23.976 | 24000/1001 | 417188 |
| 60 | 60/1 | 166667 |
| 30 | 30/1 | 333333 |
| 50 | 50/1 | 200000 |
| 25 | 25/1 | 400000 |
| 24 | 24/1 | 416667 |
?
Most video content uses one of the frame rates listed here. For other frame rates, the function calculates the duration.
\t\nApplies to: desktop apps only
This function is not implemented.
\t\nReserved.
Reserved.
Reserved.
Reserved.
Reserved.
Reserved.
Reserved.
Reserved.
Reserved.
Returns E_FAIL.
Note??Prior to Windows?7, this function was exported from evr.dll. Starting in Windows?7, this function is exported from mfplat.dll, and evr.dll exports a stub function that calls into mfplat.dll. For more information, see Library Changes in Windows?7.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Converts a Media Foundation audio media type to a
Pointer to the
Receives a reference to the
Receives the size of the
Contains a flag from the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
If the wFormatTag member of the returned structure is
[This API is not supported and may be altered or unavailable in the future. Applications should avoid using the
Applies to: desktop apps only
Returns the FOURCC or
Returns a FOURCC or
Note??Prior to Windows?7, this function was exported from evr.dll. Starting in Windows?7, this function is exported from mfplat.dll, and evr.dll exports a stub function that calls into mfplat.dll. For more information, see Library Changes in Windows?7.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Registers a Media Foundation transform (MFT) in the caller's process.
\t\nThe class identifier (CLSID) of the MFT.
A
A wide-character null-terminated string that contains the friendly name of the MFT.
A bitwise OR of zero or more flags from the _MFT_ENUM_FLAG enumeration.
The number of elements in the pInputTypes array.
A reference to an array of
The number of elements in the pOutputTypes array.
A reference to an array of
If this function succeeds, it returns
The primary purpose of this function is to make an MFT available for automatic topology resolution without making the MFT available to other processes or applications.
After you call this function, the MFT can be enumerated by calling the
To unregister the MFT from the current process, call
If you need to register an MFT in the Protected Media Path (PMP) process, use the
Applies to: desktop apps only
Enumerates Media Foundation transforms (MFTs) in the registry.
Starting in Windows?7, applications should use the
If this function succeeds, it returns
This function returns a list of all the MFTs in the specified category that match the search criteria given by the pInputType, pOutputType, and pAttributes parameters. Any of those parameters can be
If no MFTs match the criteria, the method succeeds but returns the value zero in pcMFTs.
\t\nApplies to: desktop apps only
Puts an asynchronous operation on a work queue.
\t\nThe identifier for the work queue. This value can specify one of the standard Media Foundation work queues, or a work queue created by the application. For list of standard Media Foundation work queues, see Work Queue Identifiers. To create a new work queue, call
A reference to the
Returns an
| Return code | Description |
|---|---|
| | Success. |
| | Invalid work queue identifier. For more information, see |
| | The |
?
To invoke the work-item, this function passes pResult to the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates a media buffer that wraps an existing media buffer. The new media buffer points to the same memory as the original media buffer, or to an offset from the start of the memory.
\t\nA reference to the
The start of the new buffer, as an offset in bytes from the start of the original buffer.
The size of the new buffer. The value of cbOffset + dwLength must be less than or equal to the size of valid data the original buffer. (The size of the valid data is returned by the
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| The requested offset or the requested length is not valid. |
?
The maximum size of the wrapper buffer is limited to the size of the valid data in the original buffer. This might be less than the allocated size of the original buffer. To set the size of the valid data, call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates a media type that wraps another media type.
\t\n A reference to the
A
If this function succeeds, it returns
The original media type (pOrig) is stored in the new media type under the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the size of the buffer needed for the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Use this function to find the size of the array that is needed for the
Applies to: desktop apps | Metro style apps
Copies an image or image plane from one buffer to another.
\t\nPointer to the start of the first row of pixels in the destination buffer.
Stride of the destination buffer, in bytes.
Pointer to the start of the first row of pixels in the source image.
Stride of the source image, in bytes.
Width of the image, in bytes.
Number of rows of pixels to copy.
If this function succeeds, it returns
This function copies a single plane of the image. For planar YUV formats, you must call the function once for each plane. In this case, pDest and pSrc must point to the start of each plane.
This function is optimized if the MMX, SSE, or SSE2 instruction sets are available on the processor. The function performs a non-temporal store (the data is written to memory directly without polluting the cache).
Note??Prior to Windows?7, this function was exported from evr.dll. Starting in Windows?7, this function is exported from mfplat.dll, and evr.dll exports a stub function that calls into mfplat.dll. For more information, see Library Changes in Windows?7.
\t\n[This API is not supported and may be altered or unavailable in the future. Applications should avoid using the
Applies to: desktop apps only
Creates a video media type from an
If this function succeeds, it returns
Instead of using the
Note??Prior to Windows?7, this function was exported from evr.dll. Starting in Windows?7, this function is exported from mfplat.dll, and evr.dll exports a stub function that calls into mfplat.dll. For more information, see Library Changes in Windows?7.
\t\nApplies to: desktop apps only
Gets information from the registry about a Media Foundation transform (MFT).
\t\nThe CLSID of the MFT.
Receives a reference to a wide-character string containing the friendly name of the MFT. The caller must free the string by calling CoTaskMemFree. This parameter can be
Receives a reference to an array of
Receives the number of elements in the ppInputTypes array. If ppInputTypes is
Receives a reference to an array of
Receives the number of elements in the ppOutputType array. If ppOutputTypes is
Receives a reference to the
This parameter can be
If this function succeeds, it returns
Applies to: desktop apps only
Begins an asynchronous request to create a byte stream from a file.
\t\nThe requested access mode, specified as a member of the
The behavior of the function if the file already exists or does not exist, specified as a member of the
Bitwise OR of values from the
Pointer to a null-terminated string containing the file name.
Pointer to the
Pointer to the
Receives an
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
When the request is completed, the callback object's
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Locks a work queue.
\t\nThe identifier for the work queue. The identifier is returned by the
If this function succeeds, it returns
This function prevents the
Call
Note??The
Applies to: desktop apps only
Begins an asynchronous request to create a byte stream from a file.
\t\nThe requested access mode, specified as a member of the
The behavior of the function if the file already exists or does not exist, specified as a member of the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
When the request is completed, the callback object's
Applies to: desktop apps only
Unregisters a Media Foundation transform (MFT) from the caller's process.
\t\nThe class identifier (CLSID) of the MFT.
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT specified by the clsidMFT parameter was not registered in this process. |
?
Use this function to unregister a local MFT that was previously registered through the
Applies to: desktop apps only
Creates a video media type from a
If the function succeeds, it returns
Applies to: desktop apps | Metro style apps
Initializes a media type from a
Pointer to the
Pointer to a
Size of the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates a byte stream that is backed by a temporary local file.
\t\n The requested access mode, specified as a member of the
The behavior of the function if the file already exists or does not exist, specified as a member of the
Bitwise OR of values from the
Receives a reference to the
If this function succeeds, it returns
This function creates a file in the system temporary folder, and then returns a byte stream object for that file. The full path name of the file is storted in the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Attempts to cancel an asynchronous operation that was scheduled with
If this function succeeds, it returns
Because work items are asynchronous, the work-item callback might still be invoked after
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Gets a reference to the Microsoft Media Foundation plug-in manager.
\t\nReceives a reference to the
If this function succeeds, it returns
Applies to: desktop apps only
Creates a new work queue.
\t\nReceives an identifier for the work queue.
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| The application exceeded the maximum number of work queues. |
| | The application did not call |
?
When you are done using the work queue, call
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Cancels a callback function that was set by the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
The callback is dispatched on another thread, and this function does not attempt to synchronize with the callback thread. Therefore, it is possible for the callback to be invoked after this function returns.
\t\nApplies to: desktop apps only
Puts an asynchronous operation on a work queue.
\t\n The identifier for the work queue. This value can specify one of the standard Media Foundation work queues, or a work queue created by the application. For list of standard Media Foundation work queues, see Work Queue Identifiers. To create a new work queue, call
A reference to the
A reference to the
Returns an
| Return code | Description |
|---|---|
| | Success. |
| | Invalid work queue. For more information, see |
| | The |
?
This function creates an asynchronous result object and puts the result object on the work queue. The work queue calls the
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates a media type that wraps another media type.
\t\n A reference to the
A
A
Applications can define custom subtype GUIDs.
Receives a reference to the
If this function succeeds, it returns
The original media type (pOrig) is stored in the new media type under the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Unregisters a Media Foundation transform (MFT) from the caller's process.
\t\nThe class identifier (CLSID) of the MFT.
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT specified by the clsidMFT parameter was not registered in this process. |
?
Use this function to unregister a local MFT that was previously registered through the
Applies to: desktop apps | Metro style apps
Unlocks the Media Foundation platform after it was locked by a call to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
The application must call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Retrieves the image size for a video format. Given a
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| The |
?
Before calling this function, you must set at least the following members of the
Also, if biCompression is BI_BITFIELDS, the
This function fails if the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an event queue.
\t\nReceives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
This function creates a helper object that you can use to implement the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates a media buffer object that manages a Direct3D 9 surface.
\t\nIdentifies the type of Direct3D 9 surface. Currently this value must be IID_IDirect3DSurface9.
A reference to the
If TRUE, the buffer's
For more information about top-down versus bottom-up images, see Image Stride.
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
?
This function creates a media buffer object that holds a reference to the Direct3D surface specified in punkSurface. Locking the buffer gives the caller access to the surface memory. When the buffer object is destroyed, it releases the surface. For more information about media buffers, see Media Buffers.
Note??This function does not allocate the Direct3D surface itself.
The buffer object created by this function also exposes the
This function does not support DXGI surfaces.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Unlocks a work queue.
\t\nIdentifier for the work queue to be unlocked. The identifier is returned by the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
The application must call
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an empty media sample.
\t\nReceives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Initially the sample does not contain any media buffers.
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates a Media Foundation media type from another format representation.
\t\n| Description | |
|---|---|
| AM_MEDIA_TYPE_REPRESENTATION | Convert a DirectShow |
?
Pointer to a buffer that contains the format representation to convert. The layout of the buffer depends on the value of guidRepresentation.
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| | The |
?
If the original format is a DirectShow audio media type, and the format type is not recognized, the function sets the following attributes on the converted media type.
| Attribute | Description |
|---|---|
| | Contains the format type |
| | Contains the format block. |
?
\t\nApplies to: desktop apps | Metro style apps
Creates an empty attribute store.
\t\nReceives a reference to the
The initial number of elements allocated for the attribute store. The attribute store grows as needed.
If this function succeeds, it returns
Attributes are used throughout Microsoft Media Foundation to configure objects, describe media formats, query object properties, and other purposes. For more information, see Attributes in Media Foundation.
For a complete list of all the defined attribute GUIDs in Media Foundation, see Media Foundation Attributes.
\t\nApplies to: desktop apps only
Calculates the minimum surface stride for a video format.
\t\nFOURCC code or
Width of the image, in pixels.
Receives the minimum surface stride, in pixels.
If this function succeeds, it returns
This function calculates the minimum stride needed to hold the image in memory. Use this function if you are allocating buffers in system memory. Surfaces allocated in video memory might require a larger stride, depending on the graphics card.
If you are working with a DirectX surface buffer, use the
For planar YUV formats, this function returns the stride for the Y plane. Depending on the format, the chroma planes might have a different stride.
Note??Prior to Windows?7, this function was exported from evr.dll. Starting in Windows?7, this function is exported from mfplat.dll, and evr.dll exports a stub function that calls into mfplat.dll. For more information, see Library Changes in Windows?7.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates an empty collection object.
\t\nReceives a reference to the collection object's
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Schedules an asynchronous operation to be completed after a specified interval.
\t\nPointer to the
Pointer to the
Time-out interval, in milliseconds. Set this parameter to a negative value. The callback is invoked after ?Timeout milliseconds. For example, if Timeout is ?5000, the callback is invoked after 5000 milliseconds.
Receives a key that can be used to cancel the timer. To cancel the timer, call
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
This function creates an asynchronous result object. When the timer interval elapses, the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Converts a video frame rate into a frame duration.
\t\nThe numerator of the frame rate.
The denominator of the frame rate.
Receives the average duration of a video frame, in 100-nanosecond units.
If this function succeeds, it returns
This function is useful for calculating time stamps on a sample, given the frame rate.
Also, average time per frame is used in the older
For certain common frame rates, the function gets the frame duration from a look-up table:
| Frames per second (floating point) | Frames per second (fractional) | Average time per frame |
|---|---|---|
| 59.94 | 60000/1001 | 166833 |
| 29.97 | 30000/1001 | 333667 |
| 23.976 | 24000/1001 | 417188 |
| 60 | 60/1 | 166667 |
| 30 | 30/1 | 333333 |
| 50 | 50/1 | 200000 |
| 25 | 25/1 | 400000 |
| 24 | 24/1 | 416667 |
?
Most video content uses one of the frame rates listed here. For other frame rates, the function calculates the duration.
\t\nApplies to: desktop apps only
Registers a Media Foundation transform (MFT) in the caller's process.
\t\nA reference to the
A
A wide-character null-terminated string that contains the friendly name of the MFT.
A bitwise OR of zero or more flags from the _MFT_ENUM_FLAG enumeration.
The number of elements in the pInputTypes array.
A reference to an array of
The number of elements in the pOutputTypes array.
A reference to an array of
If this function succeeds, it returns
The primary purpose of this function is to make an MFT available for automatic topology resolution without making the MFT available to other processes or applications.
After you call this function, the MFT can be enumerated by calling the
The pClassFactory parameter specifies a class factory object that creates the MFT. The class factory's IClassFactory::CreateInstance method must return an object that supports the
Note??The
To unregister the MFT from the current process, call
If you need to register an MFT in the Protected Media Path (PMP) process, use the
Applies to: desktop apps only
Creates a new work queue. This function extends the capabilities of the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| The application exceeded the maximum number of work queues. |
| Invalid argument. |
| | The application did not call |
?
When you are done using the work queue, call
The
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an asynchronous result object. Use this function if you are implementing an asynchronous method.
\t\nPointer to the object stored in the asynchronous result. This reference is returned by the
Pointer to the
Pointer to the
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
To invoke the callback specified in pCallback, call the
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Invokes a callback method to complete an asynchronous operation.
\t\nPointer to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| | Invalid work queue. For more information, see |
| | The |
?
If you are implementing an asynchronous method, use this function to invoke the caller's
The callback is invoked from a Media Foundation work queue. For more information, see Writing an Asynchronous Method.
The
Applies to: desktop apps only
Creates a byte stream from a file.
\t\n The requested access mode, specified as a member of the
The behavior of the function if the file already exists or does not exist, specified as a member of the
Bitwise OR of values from the
Pointer to a null-terminated string that contains the file name.
Receives a reference to the
If this function succeeds, it returns
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Calculates ((a * b) + d) / c, where each term is a 64-bit signed value.
\t\nA multiplier.
Another multiplier.
The divisor.
The rounding factor.
Returns the result of the calculation. If numeric overflow occurs, the function returns _I64_MAX (positive overflow) or LLONG_MIN (negative overflow). If Mfplat.dll cannot be loaded, the function returns _I64_MAX.
Note??A previous version of this topic described the parameters incorrectly. The divisor is c and the rounding factor is d.
\t\nApplies to: desktop apps | Metro style apps
Shuts down the Microsoft Media Foundation platform. Call this function once for every call to
If this function succeeds, it returns
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Allocates system memory with a specified byte alignment and creates a media buffer to manage the memory.
\t\nSize of the buffer, in bytes.
Specifies the memory alignment for the buffer. Use one of the following constants.
| Value | Meaning |
|---|---|
| Align to 1 bytes. |
| Align to 2 bytes. |
| Align to 4 bytes. |
| Align to 8 bytes. |
| Align to 16 bytes. |
| Align to 32 bytes. |
| Align to 64 bytes. |
| Align to 128 bytes. |
| Align to 256 bytes. |
| Align to 512 bytes. |
?
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
When the media buffer object is destroyed, it releases the allocated memory.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Validates the size of a buffer for a video format block.
\t\nPointer to a buffer that contains the format block.
Size of the pBlock buffer, in bytes.
The function returns an
| Return code | Description |
|---|---|
| | The buffer that contains the format block is large enough. |
| | The buffer that contains the format block is too small, or the format block is not valid. |
| | This function does not support the specified format type. |
?
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the size of the buffer needed for the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Use this function to find the size of the array that is needed for the
Applies to: desktop apps | Metro style apps
Attempts to cancel an asynchronous operation that was scheduled with
If this function succeeds, it returns
Because work items are asynchronous, the work-item callback might still be invoked after
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates a media event object.
\t\nThe event type. See
The extended type. See
The event status. See
The value associated with the event, if any. See
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates the source resolver, which is used to create a media source from a URL or byte stream.
\t\nReceives a reference to the source resolver's
If this function succeeds, it returns
Note??Prior to Windows?7, this function was exported from mf.dll. Starting in Windows?7, this function is exported from mfplat.dll, and mf.dll exports a stub function that calls into mfplat.dll. For more information, see Library Changes in Windows?7.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Blocks the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
This function prevents work queue threads from being shut down when
This function holds a lock on the Media Foundation platform. To unlock the platform, call
The
The default implementation of the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Allocates system memory and creates a media buffer to manage it.
\t\nSize of the buffer, in bytes.
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| Insufficient memory. |
?
The function allocates a buffer with a 1-byte memory alignment. To allocate a buffer that is aligned to a larger memory boundary, call
When the media buffer object is destroyed, it releases the allocated memory.
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Adds information about a Media Foundation transform (MFT) to the registry.
Applications can enumerate the MFT by calling the
If this function succeeds, it returns
The registry entries created by this function are read by the following functions:
| Function | Description |
|---|---|
| | Enumerates MFTs by media type and category. |
| | Extended version of |
| | Looks up an MFT by CLSID and retrieves the registry information. |
?
This function does not register the CLSID of the MFT for the CoCreateInstance or CoGetClassObject functions.
To remove the entries from the registry, call
The formats given in the pInputTypes and pOutputTypes parameters are intended to help applications search for MFTs by format. Applications can use the
It is recommended to specify at least one input type in pInputTypes and one output type in the pOutputTypes parameter. Otherwise, the MFT might be skipped in the enumeration.
On 64-bit Windows, the 32-bit version of this function registers the MFT in the 32-bit node of the registry. For more information, see 32-bit and 64-bit Application Data in the Registry.
\t\nApplies to: desktop apps only
Unregisters one or more Media Foundation transforms (MFTs) from the caller's process.
\t\nA reference to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT specified by the pClassFactory parameter was not registered in this process. |
?
Use this function to unregister a local MFT that was previously registered through the
If the pClassFactory parameter is
Applies to: desktop apps only
Begins an asynchronous request to create a byte stream from a file.
\t\nThe requested access mode, specified as a member of the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
When the request is completed, the callback object's
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an empty media type.
\t\n Receives a reference to the
If this function succeeds, it returns
The media type is created without any attributes.
\t\nApplies to: desktop apps only
Gets a list of Microsoft Media Foundation transforms (MFTs) that match specified search criteria. This function extends the
If this function succeeds, it returns
The Flags parameter controls which MFTs are enumerated, and the order in which they are returned. The flags for this parameter fall into several groups.
The first set of flags specifies how an MFT processes data.
| Flag | Description |
|---|---|
| | The MFT performs synchronous data processing in software. This is the original MFT processing model, and is compatible with Windows?Vista. |
| | The MFT performs asynchronous data processing in software. This processing model requires Windows?7. For more information, see Asynchronous MFTs. |
| | The MFT performs hardware-based data processing, using either the AVStream driver or a GPU-based proxy MFT. MFTs in this category always process data asynchronously. For more information, see Hardware MFTs. |
?
Every MFT falls into exactly one of these categories. To enumerate a category, set the corresponding flag in the Flags parameter. You can combine these flags to enumerate more than one category. If none of these flags is specified, the default category is synchronous MFTs (
Next, the following flags include MFTs that are otherwise excluded from the results. By default, flags that match these criteria are excluded from the results. Use any these flags to include them.
| Flag | Description |
|---|---|
| | Include MFTs that must be unlocked by the application. |
| | Include MFTs that are registered in the caller's process through either the |
| | Include MFTs that are optimized for transcoding rather than playback. |
?
The last flag is used to sort and filter the results:
| Flag | Description |
|---|---|
| | Sort and filter the results. |
?
If the
If you do not set the
Setting the Flags parameter to zero is equivalent to using the value
Setting Flags to
If no MFTs match the search criteria, the function returns
Note??There is no way to enumerate just local MFTs and nothing else. Setting Flags equal to
If at least one MFT matches the search criteria, the pppMFTActivate parameter receives an array of
Additional information about each MFT is stored as attributes on the activation objects. For a list of the possible attributes, see Transform Attributes.
To create an instance of the MFT, call
Hardware codecs are excluded from the enumeration results if the following registry keys are set to zero:
Decoders:
HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows Media Foundation\\HardwareMFT\\EnableDecoders
Encoders:
HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows Media Foundation\\HardwareMFT\\EnableEncoders
Video processors:
HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows Media Foundation\\HardwareMFT\\EnableVideoProcessors
These keys are intended for OEMs, and should not be used by applications.
For hardware codecs, the guidCategory parameter of
Hardware codecs should also be registered under an MFT_CATEGORY
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates a presentation time source that is based on the system time.
\t\nReceives a reference to the object's
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps only
Enumerates a list of audio or video capture devices.
\t\nPointer to an attribute store that contains search criteria. To create the attribute store, call
| Value | Meaning |
|---|---|
| Specifies whether to enumerate audio or video devices. (Required.) | |
| For audio capture devices, specifies the device role. (Optional.) | |
| For video capture devices, specifies the device category. (Optional.) |
?
Receives an array of
Receives the number of elements in the pppSourceActivate array. If no capture devices match the search criteria, this parameter receives the value 0.
If this function succeeds, it returns
Each returned
| Attribute | Description |
|---|---|
| | The display name of the device. |
| | The major type and subtype GUIDs that describe the device's output format. |
| | The type of capture device (audio or video). |
| | The audio endpoint ID string. (Audio devices only.) |
| | The device category. (Video devices only.) |
| | Whether a device is a hardware or software device. (Video devices only.) |
| | The symbolic link for the device driver. (Video devices only.) |
?
To create a media source from an
Applies to: desktop apps only
Creates an empty transcode profile object.
The transcode profile stores configuration settings for the output file. These configuration settings are specified by the caller, and include audio and video stream properties, encoder settings, and container settings. To set these properties, the caller must call the appropriate
The configured transcode profile is passed to the
If this function succeeds, it returns
The
For example code that uses this function, see the following topics:
Media Foundation provides a default implementation of the
To create the default credential cache object, call the
hr = ;\t\n *pCredentialCache = null ;\t\n hr = (&pCredentialCache);\t\n After the credential cache is created, the application can use the following methods to get a credential object, set user credentials, and specify the caching options.
To get the credential object for a URL, call
hr = pCredentialCache-> GetCredential( pszUrl, pszRealm, dwAuthenticationFlags, &pCredential, &dwRequirementsFlags);\t\n If the credentials for the specified URL do not exist in the credential cache, GetCredential creates a new credential object with empty user name and password values.
To set the caching options on the credential object, call
hr = pCredentialCache-> SetUserOptions( pCredentialCache, );\t\n The dwOptionsFlags parameter values are defined in the
By default, user credentials sent over the network are encrypted. To change this to clear text, set the
To remove information from the registry, call GetCredential to get the credential object, and then call SetUserOption and set dwOptionsFlags to
Applies to: desktop apps only
Creates the sequencer source.
\t\nReserved. Must be
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps only
Creates a Microsoft Media Foundation byte stream that wraps an
A reference to the
Receives a reference to the
Returns an
This function enables applications to pass an
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates an activation object for the sample grabber media sink.
\t\n Pointer to the
Pointer to the
Receives a reference to the
If this function succeeds, it returns
To create the sample grabber sink, call
Before calling ActivateObject, you can configure the sample grabber by setting any of the following attributes on the ppIActivate reference:
Applies to: desktop apps only
Creates a media sink for authoring MP4 files.
\t\nA reference to the
A reference to the
This parameter can be
A reference to the
This parameter can be
Receives a reference to the MP4 media sink's
If this function succeeds, it returns
The MP4 media sink supports a maximum of one video stream and one audio stream. The initial stream formats are given in the pVideoMediaType and pAudioMediaType parameters. To create an MP4 file with one stream, set the other stream type to
The number of streams is fixed when you create the media sink. The sink does not support the
To author 3GP files, use the
Applies to: desktop apps only
Creates the transcode sink activation object.
The transcode sink activation object can be used to create any of the following file sinks:
The transcode sink activation object exposes the
If this function succeeds, it returns
Applies to: desktop apps | Metro style apps
Queries an object for a specified service interface.
This function is a helper function that wraps the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The service requested cannot be found in the object represented by punkObject. |
?
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates a media sink for authoring 3GP files.
\t\nA reference to the
A reference to the
This parameter can be
A reference to the
This parameter can be
Receives a reference to the 3GP media sink's
If this function succeeds, it returns
The 3GP media sink supports a maximum of one video stream and one audio stream. The initial stream formats are given in the pVideoMediaType and pAudioMediaType parameters. To create an MP4 file with one stream, set the other stream type to
The number of streams is fixed when you create the media sink. The sink does not support the
To author MP4 files, use the
Applies to: desktop apps only
Creates a partial transcode topology.
The underlying topology builder creates a partial topology by connecting the required pipeline objects:\t\n source, encoder, and sink. The encoder and the sink are configured according to the settings specified by the caller in the transcode profile.
To create the transcode profile object, call the
The configured transcode profile is passed to the
The function returns an
| Return code | Description |
|---|---|
| | The function call succeeded, and ppTranscodeTopo receives a reference to the transcode topology. |
| pwszOutputFilePath contains invalid characters. |
| | No streams are selected in the media source. |
| | The profile does not contain the |
| | For one or more streams, cannot find an encoder that accepts the media type given in the profile. |
| | The profile does not specify a media type for any of the selected streams on the media source. |
?
For example code that uses this function, see the following topics:
Applies to: desktop apps only
Creates the scheme handler for the network source.
\t\nInterface identifier (IID) of the interface to retrieve.
Receives a reference to the requested interface. The caller must release the interface. The scheme handler exposes the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps only
Creates an instance of the Media Session inside a Protected Media Path (PMP) process.
\t\n The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
You can use the pConfiguration parameter to set any of the following attributes:
If this function cannot create the PMP Media Session because a trusted binary was revoked, the ppEnablerActivate parameter receives an
If the function successfully creates the PMP Media Session, the ppEnablerActivate parameter receives the value
Do not make calls to the PMP Media Session from a thread that is processing a window message sent from another thread. To test whether the current thread falls into this category, call InSendMessage.
\t\n[This API is not supported and may be altered or unavailable in the future. Instead, applications should use the PSCreateMemoryPropertyStore function to create property stores.]
Applies to: desktop apps only
Creates an empty property store object.
\t\n Receives a reference to the
If this function succeeds, it returns
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates an activation object for the Streaming Audio Renderer.
\t\nIf this function succeeds, it returns
To create the audio renderer, call
Note??To avoid a memory leak, call
To configure the audio renderer, set any of the following attributes on the
| Attribute | Description |
|---|---|
| | The audio endpoint device identifier. |
| | The audio endpoint role. |
| | Miscellaneous configuration flags. |
| | The audio policy class. |
| MF_AUDIO_RENDERER_ATTRIBUTE_STREAM_CATEGORY | The audio stream category. |
| MF_LOW_LATENCY | Enables low-latency audio streaming. |
?
\t\nApplies to: desktop apps only
Creates a media source for a hardware capture device.
\t\nPointer to the
Receives a reference to the media source's
If this function succeeds, it returns
The pAttributes parameter specifies an attribute store. To create the attribute store, call the
For audio capture devices, optionally set one of the following attributes:
| Attribute | Description |
|---|---|
| | Specifies the audio endpoint ID of the audio capture device. |
| | Specifies the device role. If this attribute is set, the function uses the default audio capture device for that device role. Do not combine this attribute with the |
?
If neither attribute is specified, the function selects the default audio capture device for the eCommunications role.
For video capture devices, you must set the following attribute:
| Attribute | Description |
|---|---|
| | Specifies the symbolic link to the device. |
?
\t\nApplies to: desktop apps | Metro style apps
Creates a presentation descriptor.
\t\nNumber of elements in the apStreamDescriptors array.
Array of
Receives a reference to an
If this function succeeds, it returns
If you are writing a custom media source, you can use this function to create the source presentation descriptor. The presentation descriptor is created with no streams selected. Generally, a media source should select at least one stream by default. To select a stream, call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Enumerates a list of audio or video capture devices.
\t\nPointer to an attribute store that contains search criteria. To create the attribute store, call
| Value | Meaning |
|---|---|
| Specifies whether to enumerate audio or video devices. (Required.) | |
| For audio capture devices, specifies the device role. (Optional.) | |
| For video capture devices, specifies the device category. (Optional.) |
?
If this function succeeds, it returns
Each returned
| Attribute | Description |
|---|---|
| | The display name of the device. |
| | The major type and subtype GUIDs that describe the device's output format. |
| | The type of capture device (audio or video). |
| | The audio endpoint ID string. (Audio devices only.) |
| | The device category. (Video devices only.) |
| | Whether a device is a hardware or software device. (Video devices only.) |
| | The symbolic link for the device driver. (Video devices only.) |
?
To create a media source from an
Applies to: desktop apps only
Gets a list of output formats from an audio encoder.
\t\nSpecifies the subtype of the output media. The encoder uses this value as a filter when it is enumerating the available output types. For information about the audio subtypes, see Audio Subtype GUIDs.
Bitwise OR of zero or more flags from the _MFT_ENUM_FLAG enumeration.
A reference to the
| Value | Meaning |
|---|---|
| Set this attribute to unlock an encoder that has field-of-use descriptions. | |
| Specifies a device conformance profile for a Windows Media encoder. | |
| Sets the tradeoff between encoding quality and encoding speed. |
?
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function call succeeded. |
| | Failed to find an encoder that matches the specified configuration settings. |
?
This function assumes the encoder will be used in its default encoding mode, which is typically constant bit-rate (CBR) encoding. Therefore, the types returned by the function might not work with other modes, such as variable bit-rate (VBR) encoding.
Internally, this function works by calling
Applies to: desktop apps only
Creates an instance of the sample copier transform.
\t\nReceives a reference to the
If this function succeeds, it returns
The sample copier is a Media Foundation transform (MFT) that copies data from input samples to output samples without modifying the data. The following data is copied from the sample:
This MFT is useful in the following situation:
The following diagram shows this situation with a media source and a media sink.
In order for the media sink to receive data from the media source, the data must be copied into the media samples owned by the media sink. The sample copier can be used for this purpose.
A specific example of such a media sink is the Enhanced Video Renderer (EVR). The EVR allocates samples that contain Direct3D surface buffers, so it cannot receive video samples directly from a media source. Starting in Windows?7, the topology loader automatically handles this case by inserting the sample copier between the media source and the EVR.
\t\nApplies to: desktop apps only
Creates a topology node.
\t\n The type of node to create, specified as a member of the
Receives a reference to the node's
If this function succeeds, it returns
Applies to: desktop apps | Metro style apps
Creates the source resolver, which is used to create a media source from a URL or byte stream.
\t\nReceives a reference to the source resolver's
If this function succeeds, it returns
Note??Prior to Windows?7, this function was exported from mf.dll. Starting in Windows?7, this function is exported from mfplat.dll, and mf.dll exports a stub function that calls into mfplat.dll. For more information, see Library Changes in Windows?7.
\t\nApplies to: desktop apps only
Creates an activation object for the enhanced video renderer (EVR) media sink.
\t\nHandle to the window where the video will be displayed.
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To create the EVR, call
To configure the EVR, set any of the following attributes on the
| Attribute | Description |
|---|---|
| | Activation object for a custom mixer. |
| | CLSID for a custom mixer. |
| | Flags for creating a custom mixer. |
| | Activation object for a custom presenter. |
| | CLSID for a custom presenter. |
| | Flags for creating a custom presenter. |
?
When
Applies to: desktop apps only
Creates a topology object.
\t\nReceives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates the remote desktop plug-in object. Use this object if the application is running in a Terminal Services client session.
\t\nReceives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| Remote desktop connections are not allowed by the current session policy. |
?
Applies to: desktop apps only
Creates a new instance of the topology loader.
\t\nReceives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps | Metro style apps
Creates a stream descriptor.
\t\nStream identifier.
Number of elements in the apMediaTypes array.
Pointer to an array of
Receives a reference to the
If this function succeeds, it returns
If you are writing a custom media source, you can use this function to create stream descriptors for the source. This function automatically creates the stream descriptor media type handler and initializes it with the list of types given in apMediaTypes. The function does not set the current media type on the handler, however. To set the type, call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the system time.
\t\nReturns the system time, in 100-nanosecond units.
Applies to: desktop apps only
Creates the MP3 media sink.
\t\nA reference to the
Receives a reference to the
If this function succeeds, it returns
The MP3 media sink takes compressed MP3\t\n audio samples as input, and writes an MP3 file with ID3 headers as output. The MP3 media sink does not perform MP3 audio encoding.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[This API is not supported and may be altered or unavailable in the future. Instead, applications should use the PSCreateMemoryPropertyStore function to create named property stores.]
Applies to: desktop apps only
Creates an empty property store to hold name/value pairs.
\t\nReceives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps only
Creates the Media Session in the application's process.
\t\nThe function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
If your application does not play protected content, you can use this function to create the Media Session in the application's process. To use the Media Session for protected content, you must call
You can use the pConfiguration parameter to specify any of the following attributes:
Applies to: desktop apps | Metro style apps
Creates a media source that aggregates a collection of media sources.
\t\nA reference to the
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The pSourceCollection collection does not contain any elements. |
?
The aggregated media source is useful for combining streams from separate media sources. For example, you can use it to combine a video capture source and an audio capture source.
\t\nApplies to: desktop apps only
Creates the protected media path (PMP) server object.
\t\nA member of the
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Queries whether a media presentation requires the Protected Media Path (PMP).
\t\nPointer to the
The function returns an
| Return code | Description |
|---|---|
| | This presentation requires a protected environment. |
| This presentation does not require a protected environment. |
?
If this function returns
If the function returns S_FALSE, you can use the unprotected pipeline. Call
Internally, this function checks whether any of the stream descriptors in the presentation have the
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Creates the Streaming Audio Renderer.
\t\nIf this function succeeds, it returns
To configure the audio renderer, set any of the following attributes on the
| Attribute | Description |
|---|---|
| | The audio endpoint device identifier. |
| | The audio endpoint role. |
| | Miscellaneous configuration flags. |
| | The audio policy class. |
| MF_AUDIO_RENDERER_ATTRIBUTE_STREAM_CATEGORY | The audio stream category. |
| MF_LOW_LATENCY | Enables low-latency audio streaming. |
?
\t\nApplies to: desktop apps | Metro style apps
Loads attributes from a stream into an attribute store.
\t\nPointer to the
Bitwise OR of zero or more flags from the
Pointer to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Use this function to deserialize an attribute store that was serialized with the
If dwOptions contains the
If the
Otherwise, the function calls CoUnmarshalInterface to deserialize a proxy for the object.
This function deletes any attributes that were previously stored in pAttr.
\t\nApplies to: desktop apps | Metro style apps
Loads attributes from a stream into an attribute store.
\t\nPointer to the
Bitwise OR of zero or more flags from the
Pointer to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Use this function to deserialize an attribute store that was serialized with the
If dwOptions contains the
If the
Otherwise, the function calls CoUnmarshalInterface to deserialize a proxy for the object.
This function deletes any attributes that were previously stored in pAttr.
\t\nApplies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\t\nVersion number. Use the value
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Version parameter requires a newer version of Media Foundation than the version that is running. |
| | The Media Foundation platform is disabled because the system was started in \"Safe Mode\" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates the object associated with this activation object.
\t\nSome Microsoft Media Foundation objects must be shut down before being released. If so, the caller is responsible for shutting down the object that is returned in ppv. To shut down the object, do one of the following:
The
After the first call to ActivateObject, subsequent calls return a reference to the same instance, until the client calls either ShutdownObject or
Applies to: desktop apps | Metro style apps
Provides a generic way to store key/value pairs on an object. The keys are
For a list of predefined attribute
To create an empty attribute store, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Compares the attributes on this object with the attributes on another object.
\t\nPointer to the
Member of the
Receives a Boolean value. The value is TRUE if the two sets of attributes match in the way specified by the MatchType parameter. Otherwise, the value is
If pThis is the object whose Compare method is called, and pTheirs is the object passed in as the pTheirs parameter, the following comparisons are defined by MatchType.
| Match type | Returns TRUE if and only if |
|---|---|
| For every attribute in pThis, an attribute with the same key and value exists in pTheirs. | |
| For every attribute in pTheirs, an attribute with the same key and value exists in pThis. | |
| The key/value pairs are identical in both objects. | |
| Take the intersection of the keys in pThis and the keys in pTheirs. The values associated with those keys are identical in both pThis and pTheirs. | |
| Take the object with the smallest number of attributes. For every attribute in that object, an attribute with the same key and value exists in the other object. |
?
The pTheirs and pbResult parameters must not be
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a UINT32 value associated with a key.
\t\nReceives a UINT32 value. If the key is found and the data type is UINT32, the method copies the value into this parameter. Otherwise, the original value of this parameter is not changed.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a UINT64 value associated with a key.
\t\nReceives a UINT64 value. If the key is found and the data type is UINT64, the method copies the value into this parameter. Otherwise, the original value of this parameter is not changed.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a double value associated with a key.
\t\nReceives a double value. If the key is found and the data type is double, the method copies the value into this parameter. Otherwise, the original value of this parameter is not changed.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a
Receives a
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of a string value associated with a key.
\t\nIf the key is found and the value is a string type, this parameter receives the number of characters in the string, not including the terminating
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a wide-character string associated with a key.
\t\nPointer to a wide-character array allocated by the caller. The array must be large enough to hold the string, including the terminating
The size of the pwszValue array, in characters. This value includes the terminating
Receives the number of characters in the string, excluding the terminating
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The length of the string is too large to fit in a UINT32 value. |
| The buffer is not large enough to hold the string. |
| | The specified key was not found. |
| | The attribute value is not a string. |
?
You can also use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets a wide-character string associated with a key. This method allocates the memory for the string.
\t\nA
If the key is found and the value is a string type, this parameter receives a copy of the string. The caller must free the memory for the string by calling CoTaskMemFree.
Receives the number of characters in the string, excluding the terminating
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The specified key was not found. |
| | The attribute value is not a string. |
?
To copy a string value into a caller-allocated buffer, use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Note??An earlier version of the documentation incorrectly stated that the pcchLength parameter can be
Applies to: desktop apps | Metro style apps
Retrieves the length of a byte array associated with a key.
\t\nIf the key is found and the value is a byte array, this parameter receives the size of the array, in bytes.
To get the byte array, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a byte array associated with a key. This method copies the array into a caller-allocated buffer.
\t\nPointer to a buffer allocated by the caller. If the key is found and the value is a byte array, the method copies the array into this buffer. To find the required size of the buffer, call
The size of the pBuf buffer, in bytes.
Receives the size of the byte array. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The buffer is not large enough to the array. |
| | The specified key was not found. |
| | The attribute value is not a byte array. |
?
You can also use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a byte array associated with a key. This method allocates the memory for the array.
\t\nIf the key is found and the value is a byte array, this parameter receives a copy of the array. The caller must free the memory for the array by calling CoTaskMemFree.
Receives the size of the array, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The specified key was not found. |
| | The attribute value is not a byte array. |
?
To copy a byte array value into a caller-allocated buffer, use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an interface reference associated with a key.
\t\nInterface identifier (IID) of the interface to retrieve.
Receives a reference to the requested interface. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The attribute value is an |
| | The specified key was not found. |
| | The attribute value is not an |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds an attribute value with a specified key.
\t\n A
A
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
| | Invalid attribute type. |
?
This method checks whether the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Removes a key/value pair from the object's attribute list.
guidKey
[in]
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
If the specified key does not exist, the method returns
Client: Requires Windows Vista.
Header: Defined in mfobjects.h; include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFAttributes Interface\t\nApplies to: desktop apps | Metro style apps
Removes all key/value pairs from the object's attribute list.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a UINT32 value with a key.
\t\nNew value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the UINT32 value, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a UINT64 value with a key.
\t\nNew value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the UINT64 value, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a double value with a key.
\t\nNew value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the double value, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a
New value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
?
To retrieve the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a wide-character string with a key.
\t\nNull-terminated wide-character string to associate with this key. The method stores a copy of the string.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the string, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Associates a byte array with a key.
guidKey
[in]
pBuf
[in] Pointer to a byte array to associate with this key. The method stores a copy of the array.
cbBufSize
[in] Size of the array, in bytes.
The method returns an
| Return code | Description |
|---|---|
| E_OUTOFMEMORY | Insufficient memory. |
| | The method succeeded. |
Client: Requires Windows Vista.
Header: Defined in mfobjects.h; include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFAttributes Interface\t\nApplies to: desktop apps | Metro style apps
Locks the attribute store so that no other thread can access it. If the attribute store is already locked by another thread, this method blocks until the other thread unlocks the object. After calling this method, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method can cause a deadlock if a thread that calls LockStore waits on a thread that calls any other
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Unlocks the attribute store after a call to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of attributes that are set on this object.
\t\nReceives the number of attributes. This parameter must not be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To enumerate all of the attributes, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an attribute at the specified index.
\t\nIndex of the attribute to retrieve. To get the number of attributes, call
Receives the
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid index. |
?
To enumerate all of an object's attributes in a thread-safe way, do the following:
Call
Call
Call GetItemByIndex to get each attribute by index.
Call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Copies all of the attributes from this object into another attribute store.
\t\n A reference to the
If this method succeeds, it returns
This method deletes all of the attributes originally stored in pDest.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Attributes are used throughout Microsoft Media Foundation to configure objects, describe media formats, query object properties, and other purposes. For more information, see Attributes in Media Foundation.
For a complete list of all the defined attribute GUIDs in Media Foundation, see Media Foundation Attributes.
\t\nApplies to: desktop apps | Metro style apps
Retrieves an attribute at the specified index.
\t\nIndex of the attribute to retrieve. To get the number of attributes, call
Receives the
To enumerate all of an object's attributes in a thread-safe way, do the following:
Call
Call
Call GetItemByIndex to get each attribute by index.
Call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds an attribute value with a specified key.
\t\n A
A
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
| Invalid attribute type. |
?
This method checks whether the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds an attribute value with a specified key.
\t\n A
A
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
| Invalid attribute type. |
?
This method checks whether the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of attributes that are set on this object.
\t\nTo enumerate all of the attributes, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates the object associated with this activation object.
\t\nInterface identifier (IID) of the requested interface.
Receives a reference to the requested interface. The caller must release the interface.
If this method succeeds, it returns
Some Microsoft Media Foundation objects must be shut down before being released. If so, the caller is responsible for shutting down the object that is returned in ppv. To shut down the object, do one of the following:
The
After the first call to ActivateObject, subsequent calls return a reference to the same instance, until the client calls either ShutdownObject or
Applies to: desktop apps | Metro style apps
Shuts down the created object.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If you create an object by calling
The component that calls ActivateObject?not the component that creates the activation object?is responsible for calling ShutdownObject. For example, in a typical playback application, the application creates activation objects for the media sinks, but the Media Session calls ActivateObject. Therefore the Media Session, not the application, calls ShutdownObject.
After ShutdownObject is called, the activation object releases all of its internal references to the created object. If you call ActivateObject again, the activation object will create a new instance of the other object.
\t\nApplies to: desktop apps | Metro style apps
Detaches the created object from the activation object.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
?
The activation object releases all of its internal references to the created object. If you call ActivateObject again, the activation object will create a new instance of the other object.
The DetachObject method does not shut down the created object. If the DetachObject method succeeds, the client must shut down the created object. This rule applies only to objects that have a shutdown method or that support the
Implementation of this method is optional. If the activation object does not support this method, the method returns E_NOTIMPL.
\t\nApplies to: desktop apps only
Provides methods to work with the header section of files conforming to the Advanced Systems Format (ASF) specification.
The ASF ContentInfo Object exposes this interface. To create the get a reference to the
Applies to: desktop apps only
Retrieves the size of the header section of an Advanced Systems Format (ASF) file.
\t\nThe
Receives the size, in bytes, of the header section of the content. The value includes the size of the ASF Header Object plus the size of the header section of the Data Object. Therefore, the resulting value is the offset to the start of the data packets in the ASF Data Object.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The buffer does not contain valid ASF data. |
| | The buffer does not contain enough valid data. |
?
The header of an ASF file or stream can be passed to the
Applies to: desktop apps only
Parses the information in an ASF header and uses that information to set values in the ContentInfo object. You can pass the entire header in a single buffer or send it in several pieces.
\t\nPointer to the
Offset, in bytes, of the first byte in the buffer relative to the beginning of the header.
The method returns an
| Return code | Description |
|---|---|
| | The header is completely parsed and validated. |
| | The input buffer does not contain valid ASF data. |
| | The input buffer is to small. |
| The method succeeded, but the header passed was incomplete. This is the successful return code for all calls but the last one when passing the header in pieces. |
?
If you pass the header in pieces, the ContentInfo object will keep references to the buffer objects until the entire header is parsed. Therefore, do not write over the buffers passed into this method.
The start of the Header object has the following layout in memory:
| Field Name | Size in bytes |
|---|---|
| Object ID | 16 |
| Object Size | 8 |
| Number of Header Objects | 4 |
| Reserved1 | 1 |
| Reserved2 | 1 |
?
The first call to ParseHeader reads everything up to and including Rerserved2, so it requires a minimum of 30 bytes. (Note that the
Applies to: desktop apps only
Encodes the data in the MFASFContentInfo object into a binary Advanced Systems Format (ASF) header.
\t\n A reference to the
Size of the encoded ASF header in bytes. If pIHeader is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The ASF Header Objects do not exist for the media that the ContentInfo object holds reference to. |
| | The ASF Header Object size exceeds 10 MB. |
| | The buffer passed in pIHeader is not large enough to hold the ASF Header Object information. |
?
The size received in the pcbHeader parameter includes the padding size. The content information shrinks or expands the padding data depending on the size of the ASF Header Objects.
During this call, the stream properties are set based on the encoding properties of the profile. These properties are available through the
Applies to: desktop apps only
Retrieves an Advanced Systems Format (ASF) profile that describes the ASF content.
\t\nReceives an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The profile is set by calling either
The ASF profile object returned by this method does not include any of the MF_PD_ASF_xxx attributes (see Presentation Descriptor Attributes). To get these attributes, do the following:
Call
(Optional.) Call
An ASF profile is a template for file encoding, and is intended mainly for creating ASF content. If you are reading an existing ASF file, it is recommended that you use the presentation descriptor to get information about the file. One exception is that the profile contains the mutual exclusion and stream prioritization objects, which are not exposed directly from the presentation descriptor.
\t\nApplies to: desktop apps only
Uses profile data from a profile object to configure settings in the ContentInfo object.
\t\nThe
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If there is already information in the ContentInfo object when this method is called, it is replaced by the information from the profile object.
\t\nApplies to: desktop apps only
Creates a presentation descriptor for ASF content.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves a property store that can be used to set encoding properties.
\t\nStream number to configure. Set to zero to configure file-level encoding properties.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves an Advanced Systems Format (ASF) profile that describes the ASF content.
\t\nThe profile is set by calling either
The ASF profile object returned by this method does not include any of the MF_PD_ASF_xxx attributes (see Presentation Descriptor Attributes). To get these attributes, do the following:
Call
(Optional.) Call
An ASF profile is a template for file encoding, and is intended mainly for creating ASF content. If you are reading an existing ASF file, it is recommended that you use the presentation descriptor to get information about the file. One exception is that the profile contains the mutual exclusion and stream prioritization objects, which are not exposed directly from the presentation descriptor.
\t\nApplies to: desktop apps only
Provides methods to work with indexes in Systems Format (ASF) files. The ASF indexer object exposes this interface. To create the ASF indexer, call
You can use the indexer object to read an existing ASF index or write a new index. The index object has two mutually exclusive modes: read mode and write mode. To set the mode, call SetFlags.
Use the following methods to configure the indexer object (both modes):
Use the following methods to read an existing index:
Use the following methods to write an index:
Applies to: desktop apps only
Sets indexer options.
\t\nBitwise OR of zero or more flags from the MFASF_INDEXER_FLAGS enumeration specifying the indexer options to use.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The indexer object was initialized before setting flags for it. For more information, see Remarks. |
?
Applies to: desktop apps only
Retrieves the flags that indicate the selected indexer options.
\t\nReceives a bitwise OR of zero or more flags from the MFASF_INDEXER_FLAGS enumeration.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| pdwFlags is |
?
You must call this method before initializing the indexer object with
Applies to: desktop apps only
Initializes the indexer object. This method reads information in a ContentInfo object about the configuration of the content and the properties of the existing index, if present. Use this method before using the indexer for either writing or reading an index. You must make this call before using any of the other methods of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid ASF data. |
| | Unexpected error. |
?
The indexer needs to examine the data in the ContentInfo object to properly write or read the index for the content. The indexer will not make changes to the content information and will not hold any references to the
In the ASF header, the maximum data-packet size must equal the minimum data-packet size. Otherwise, the method returns
Applies to: desktop apps only
Retrieves the offset of the index object from the start of the content.
\t\nPointer to the
Receives the offset of the index relative to the beginning of the content described by the ContentInfo object. This is the position relative to the beginning of the ASF file.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| pIContentInfo is |
?
The index continues from the offset retrieved by this method to the end of the file.
You must call
If the index is retrieved by using more than one call to
Applies to: desktop apps only
Adds byte streams to be indexed.
\t\nAn array of
The number of references in the ppIByteStreams array.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The indexer object has already been initialized and it has packets which have been indexed. |
?
For a reading scenario, only one byte stream should be used by the indexer object. For an index generating scenario, it depends how many index objects are needed to be generated.
\t\nApplies to: desktop apps only
Retrieves the number of byte streams that are in use by the indexer object.
\t\nReceives the number of byte streams that are in use by the indexer object.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| pcByteStreams is |
?
Applies to: desktop apps only
Retrieves the index settings for a specified stream and index type.
\t\nPointer to an
A variable that retrieves a Boolean value specifying whether the index described by pIndexIdentifier has been created.
A buffer that receives the index descriptor. The index descriptor consists of an
On input, specifies the size, in bytes, of the buffer that pbIndexDescriptor points to. The value can be zero if pbIndexDescriptor is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The buffer size specified in pcbIndexDescriptor is too small. |
?
To read an existing ASF index, call
If an index exists for the stream and the value passed into pcbIndexDescriptor is smaller than the required size of the pbIndexDescriptor buffer, the method returns
If there is no index for the specified stream, the method returns
Applies to: desktop apps only
Configures the index for a stream.
\t\nThe index descriptor to set. The index descriptor is an
The size, in bytes, of the index descriptor.
A Boolean value. Set to TRUE to have the indexer create an index of the type specified for the stream specified in the index descriptor.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | At attempt was made to change the index status in a seek-only scenario. For more information, see Remarks. |
?
You must make all calls to SetIndexStatus before making any calls to
The indexer object is configured to create temporal indexes for each stream by default. Call this method only if you want to override the default settings.
You cannot use this method in an index reading scenario. You can only use this method when writing indexes.
\t\nApplies to: desktop apps only
Given a desired seek time, gets the offset from which the client should start reading data.
\t\nThe value of the index entry for which to get the position. The format of this value varies depending on the type of index, which is specified in the index identifier. For time-based indexing, the variant type is VT_I8 and the value is the desired seek time, in 100-nanosecond units.
Pointer to an
Receives the offset within the data segment of the ASF Data Object. The offset is in bytes, and is relative to the start of packet 0. The offset gives the starting location from which the client should begin reading from the stream. This location might not correspond exactly to the requested seek time.
For reverse playback, if no key frame exists after the desired seek position, this parameter receives the value MFASFINDEXER_READ_FOR_REVERSEPLAYBACK_OUTOFDATASEGMENT. In that case, the seek position should be 1 byte pass the end of the data segment.
Receives the approximate time stamp of the data that is located at the offset returned in the pcbOffsetWithinData parameter. The accuracy of this value is equal to the indexing interval of the ASF index, typically about 1 second.
If the approximate time stamp cannot be determined, this parameter receives the value MFASFINDEXER_APPROX_SEEK_TIME_UNKNOWN.
Receives the payload number of the payload that contains the information for the specified stream. Packets can contain multiple payloads, each containing data for a different stream. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The requested seek time is out of range. |
| | No index exists of the specified type for the specified stream. |
?
Applies to: desktop apps only
Accepts an ASF packet for the file and creates index entries for them.
\t\n Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The argument passed in is |
| | The indexer is not initialized. |
?
The ASF indexer creates indexes for a file internally. You can get the completed index for all data packets sent to the indexer by committing the index with
When this method creates index entries, they are immediately available for use by
The media sample specified in pIASFPacketSample must hold a buffer that contains a single ASF packet. Get the sample from the ASF multiplexer by calling the
You cannot use this method while reading an index, only when writing an index.
\t\nApplies to: desktop apps only
Adds information about a new index to the ContentInfo object associated with ASF content. You must call this method before copying the index to the content so that the index will be readable by the indexer later.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The caller made an invalid request. For more information, see Remarks. |
?
For the index to function properly, you must call this method after all ASF packets in the file have been passed to the indexer by using the
An application must use the CommitIndex method only when writing a new index otherwise CommitIndex may return
You cannot use this method in an index reading scenario. You can only use this method when writing indexes.
\t\nApplies to: desktop apps only
Retrieves the size, in bytes, of the buffer required to store the completed index.
\t\nReceives the size of the index, in bytes
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The index has not been committed. For more information; see Remarks. |
?
Use this method to get the size of the index and then allocate a buffer big enough to hold it.
The index must be committed with a call to
Call
You cannot use this method in a reading scenario. You can only use this method when writing indexes.
\t\nApplies to: desktop apps only
Retrieves the completed index from the ASF indexer object.
\t\nPointer to the
The offset of the data to be retrieved, in bytes from the start of the index data. Set to 0 for the first call. If subsequent calls are needed (the buffer is not large enough to hold the entire index), set to the byte following the last one retrieved.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The index was not committed before attempting to get the completed index. For more information, see Remarks. |
?
This method uses as much of the buffer as possible, and updates the length of the buffer appropriately.
If pIIndexBuffer is large enough to contain the entire buffer, cbOffsetWithinIndex should be 0, and the call needs to be made only once. Otherwise, there should be no gaps between successive buffers.
The user must write this data to the content at cbOffsetFromIndexStart bytes after the end of the ASF data object. You can call
This call will not succeed unless
You cannot use this method in an index reading scenario. You can only use this method when writing indexes.
\t\nApplies to: desktop apps only
Provides methods to create Advanced Systems Format (ASF) data packets. The methods of this interface process input samples into the packets that make up an ASF data section. The ASF multiplexer exposes this interface. To create the ASF multiplexer, call
Applies to: desktop apps only
Initializes the multiplexer with the data from an ASF ContentInfo object.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This call must be made once at the beginning of encoding, with pIContentInfo pointing to the ASF ContentInfo object that describes the content to be encoded. This enables the ASF multiplexer to see, among other things, which streams will be present in the encoding session. This call typically does not affect the data in the ASF ContentInfo object.
\t\nApplies to: desktop apps only
Sets multiplexer options.
\t\nBitwise OR of zero or more members of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves flags indicating the configured multiplexer options.
\t\nReceives a bitwise OR of zero or more values from the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Delivers input samples to the multiplexer.
\t\nThe stream number of the stream to which the sample belongs.
Pointer to the
The adjustment to apply to the time stamp of the sample. This parameter is used if the caller wants to shift the sample time on pISample. This value should be positive if the time stamp should be pushed ahead and negative if the time stamp should be pushed back. This time stamp is added to sample time on pISample, and the resulting time is used by the multiplexer instead of the original sample time. If no adjustment is needed, set this value to 0.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | There are too many packets waiting to be retrieved from the multiplexer. Call |
| | The sample that was processed violates the bandwidth limitations specified for the stream in the ASF ContentInfo object. When this error is generated, the sample is dropped. |
| | The value passed in wStreamNumber is invalid. |
| | The presentation time of the input media sample is earlier than the send time. |
?
The application passes samples to ProcessSample, and the ASF multiplexer queues them internally until they are ready to be placed into ASF packets. Call
After each call to ProcessSample, call GetNextPacket in a loop to get all of the available data packets. For a code example, see Generating New ASF Data Packets.
\t\nApplies to: desktop apps only
Retrieves the next output ASF packet from the multiplexer.
\t\n Receives zero or more status flags. If more than one packet is waiting, the method sets the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The client needs to call this method, ideally after every call to
If no packets are ready, the method returns
Applies to: desktop apps only
Signals the multiplexer to process all queued output media samples. Call this method after passing the last sample to the multiplexer.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
You must call Flush after the last sample has been passed into the ASF multiplexer and before you call
Applies to: desktop apps only
Collects data from the multiplexer and updates the ASF ContentInfo object to include that information in the ASF Header Object.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | There are pending output media samples waiting in the multiplexer. Call |
?
For non-live encoding scenarios (such as encoding to a file), the user should call End to update the specified ContentInfo object, adding data that the multiplexer has collected during the packet generation process. The user should then call
During live encoding, it is usually not possible to rewrite the header, so this call is not required for live encoding. (The header in those cases will simply lack some of the information that was not available until the end of the encoding session.)
\t\nApplies to: desktop apps only
Retrieves multiplexer statistics.
\t\nThe stream number for which to obtain statistics.
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets the maximum time by which samples from various streams can be out of synchronization. The multiplexer will not accept a sample with a time stamp that is out of synchronization with the latest samples from any other stream by an amount that exceeds the synchronization tolerance.
\t\nSynchronization tolerance in milliseconds.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The synchronization tolerance is the maximum difference in presentation times at any given point between samples of different streams that the ASF multiplexer can accommodate. That is, if the synchronization tolerance is 3 seconds, no stream can be more than 3 seconds behind any other stream in the time stamps passed to the multiplexer. The multiplexer determines a default synchronization tolerance to use, but this method overrides it (usually to increase it). More tolerance means the potential for greater latency in the multiplexer. If the time stamps are synchronized among the streams, actual latency will be much lower than msSyncTolerance.
\t\nApplies to: desktop apps only
Sets the maximum time by which samples from various streams can be out of synchronization. The multiplexer will not accept a sample with a time stamp that is out of synchronization with the latest samples from any other stream by an amount that exceeds the synchronization tolerance.
\t\nThe synchronization tolerance is the maximum difference in presentation times at any given point between samples of different streams that the ASF multiplexer can accommodate. That is, if the synchronization tolerance is 3 seconds, no stream can be more than 3 seconds behind any other stream in the time stamps passed to the multiplexer. The multiplexer determines a default synchronization tolerance to use, but this method overrides it (usually to increase it). More tolerance means the potential for greater latency in the multiplexer. If the time stamps are synchronized among the streams, actual latency will be much lower than msSyncTolerance.
\t\nApplies to: desktop apps only
Adds a stream number to a record in the Advanced Systems Format mutual exclusion object.
\t\nEach record includes one or more streams. Every stream in a record is mutually exclusive of all streams in every other record.
\t\nApplies to: desktop apps only
Retrieves the type of mutual exclusion represented by the Advanced Systems Format (ASF) mutual exclusion object.
\t\nA variable that receives the type identifier. For a list of predefined mutual exclusion type constants, see ASF Mutual Exclusion Type GUIDs.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Sometimes, content must be made mutually exclusive in more than one way. For example, a video file might contain audio streams of several bit rates for each of several languages. To handle this type of complex mutual exclusion, you must configure more than one ASF mutual exclusion object. For more information, see
Applies to: desktop apps only
Sets the type of mutual exclusion that is represented by the Advanced Systems Format (ASF) mutual exclusion object.
\t\nThe type of mutual exclusion that is represented by the ASF mutual exclusion object. For a list of predefined mutual exclusion type constants, see ASF Mutual Exclusion Type GUIDs.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Sometimes, content must be made mutually exclusive in more than one way. For example, a video file might contain audio streams in several bit rates for each of several languages. To handle this type of complex mutual exclusion, you must configure more than one ASF mutual exclusion object. For more information, see
Applies to: desktop apps only
Retrieves the number of records in the Advanced Systems Format mutual exclusion object.
\t\nReceives the count of records.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Each record includes one or more streams. Every stream in a record is mutually exclusive of streams in every other record.
Use this method in conjunction with
Applies to: desktop apps only
Retrieves the stream numbers contained in a record in the Advanced Systems Format mutual exclusion object.
\t\nThe number of the record for which to retrieve the stream numbers.
An array that receives the stream numbers. Set to
On input, the number of elements in the array referenced by pwStreamNumArray. On output, the method sets this value to the count of stream numbers in the record. You can call GetStreamsForRecord with pwStreamNumArray set to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Adds a stream number to a record in the Advanced Systems Format mutual exclusion object.
\t\nThe record number to which the stream is added. A record number is set by the
The stream number to add to the record.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The specified stream number is already associated with the record. |
?
Each record includes one or more streams. Every stream in a record is mutually exclusive of all streams in every other record.
\t\nApplies to: desktop apps only
Removes a stream number from a record in the Advanced Systems Format mutual exclusion object.
\t\nThe record number from which to remove the stream number.
The stream number to remove from the record.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The stream number is not listed for the specified record. |
?
Applies to: desktop apps only
Removes a record from the Advanced Systems Format (ASF) mutual exclusion object.
\t\nThe index of the record to remove.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
When a record is removed, the ASF mutual exclusion object indexes the remaining records so that they are sequential starting with zero. You should enumerate the records to ensure that you have the correct index for each record. If the record removed is the one with the highest index, removing it has no effect on the other indexes.
\t\nApplies to: desktop apps only
Adds a record to the mutual exclusion object. A record specifies streams that are mutually exclusive with the streams in all other records.
\t\nReceives the index assigned to the new record. Record indexes are zero-based and sequential.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
A record can include one or more stream numbers. All of the streams in a record are mutually exclusive with all the streams in all other records in the ASF mutual exclusion object.
You can use records to create complex mutual exclusion scenarios by using multiple ASF mutual exclusion objects.
\t\nApplies to: desktop apps only
Creates a copy of the Advanced Systems Format mutual exclusion object.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The cloned object is a new object, completely independent of the object from which it was cloned.
\t\nApplies to: desktop apps only
Manages an Advanced Systems Format (ASF) profile. A profile is a collection of information that describes the configuration of streams that will be included in an ASF file. Information about the relationships between streams is also included in the profile.
An
Applies to: desktop apps only
Retrieves the number of streams in the profile.
\t\nReceives the number of streams in the profile.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves a stream from the profile by stream index, and/or retrieves the stream number for a stream index.
\t\nThe index of the stream to retrieve. Stream indexes are sequential and zero-based. You can get the number of streams that are in the profile by calling the
Receives the stream number of the requested stream. Stream numbers are one-based and are not necessarily sequential. This parameter can be set to
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method does not create a copy of the stream configuration object. The reference that is retrieved points to the object within the profile object. You must not make any changes to the stream configuration object using this reference, because doing so can affect the profile object in unexpected ways.
To change the configuration of the stream configuration object in the profile, you must first clone the stream configuration object by calling
Applies to: desktop apps only
Retrieves an Advanced Systems Format (ASF) stream configuration object for a stream in the profile. This method references the stream by stream number instead of stream index.
\t\nThe stream number for which to obtain the interface reference.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method does not create a copy of the stream configuration object. The reference that is retrieved points to the object within the profile object. You must not make any changes to the stream configuration object using this reference, because doing so can affect the profile object in unexpected ways.
To change the configuration of the stream configuration object in the profile, you must first clone the stream configuration object by calling
Applies to: desktop apps only
Adds a stream to the profile or reconfigures an existing stream.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the stream number in the ASF stream configuration object is already included in the profile, the information in the new object replaces the old one. If the profile does not contain a stream for the stream number, the ASF stream configuration object is added as a new stream.
\t\nApplies to: desktop apps only
Removes a stream from the Advanced Systems Format (ASF) profile object.
\t\nStream number of the stream to remove.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
After a stream is removed, the ASF profile object reassigns stream indexes so that the index values are sequential starting from zero. Any previously stored stream index numbers are no longer valid after deleting a stream.
\t\nApplies to: desktop apps only
Creates an Advanced Systems Format (ASF) stream configuration object.
\t\nPointer to the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| ppIStream is |
| stream configuration object could not be created due to insufficient memory. |
?
The ASF stream configuration object created by this method is not included in the profile. To include the stream, you must first configure the stream configuration and then call
Applies to: desktop apps only
Retrieves the number of Advanced Systems Format (ASF) mutual exclusion objects that are associated with the profile.
\t\nReceives the number of mutual exclusion objects.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Multiple mutual exclusion objects may be required for streams that are mutually exclusive in more than one way. For more information, see
Applies to: desktop apps only
Retrieves an Advanced Systems Format (ASF) mutual exclusion object from the profile.
\t\nIndex of the mutual exclusion object in the profile.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method does not create a copy of the mutual exclusion object. The returned reference refers to the mutual exclusion contained in the profile object. You must not make any changes to the mutual exclusion object using this reference, because doing so can affect the profile object in unexpected ways.
To change the configuration of the mutual exclusion object in the profile, you must first clone the mutual exclusion object by calling
Applies to: desktop apps only
Adds a configured Advanced Systems Format (ASF) mutual exclusion object to the profile.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
You can create a mutual exclusion object by calling the
Applies to: desktop apps only
Removes an Advanced Systems Format (ASF) mutual exclusion object from the profile.
\t\nThe index of the mutual exclusion object to remove from the profile.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
When a mutual exclusion object is removed from the profile, the ASF profile object reassigns the mutual exclusion indexes so that they are sequential starting with zero. Any previously stored indexes are no longer valid after calling this method.
\t\nApplies to: desktop apps only
Creates a new Advanced Systems Format (ASF) mutual exclusion object. Mutual exclusion objects can be added to a profile by calling the AddMutualExclusion method.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The ASF mutual exclusion object created by this method is not associated with the profile. Call
Applies to: desktop apps only
Note??This method is not supported.
\t\nReserved.
If this method succeeds, it returns
Applies to: desktop apps only
Note??This method is not supported.
\t\nReserved.
If this method succeeds, it returns
Applies to: desktop apps only
Note??This method is not supported.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Note??This method is not implemented.
\t\nReserved.
Returns E_NOTIMPL.
Applies to: desktop apps only
Creates a copy of the Advanced Systems Format profile object.
\t\nReceives a reference to the
If this method succeeds, it returns
The cloned object is completely independent of the original.
\t\nApplies to: desktop apps only
Adds a stream to the profile or reconfigures an existing stream.
\t\nIf the stream number in the ASF stream configuration object is already included in the profile, the information in the new object replaces the old one. If the profile does not contain a stream for the stream number, the ASF stream configuration object is added as a new stream.
\t\nApplies to: desktop apps only
Note??This method is not supported.
\t\nApplies to: desktop apps only
Retrieves a sample from the Advanced Systems Format (ASF) splitter after the data has been parsed.
\t\nBefore calling this method, call
The ASF splitter skips samples for unselected streams. To select streams, call
Applies to: desktop apps only
Resets the Advanced Systems Format (ASF) splitter and configures it to parse data from an ASF data section.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The pIContentInfo parameter is |
?
Applies to: desktop apps only
Sets option flags on the Advanced Systems Format (ASF) splitter.
\t\nA bitwise combination of zero or more members of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The splitter is not initialized. |
| The dwFlags parameter does not contain a valid flag. |
| | The |
?
This method can only be called after the splitter is initialized.
\t\nApplies to: desktop apps only
Retrieves the option flags that are set on the ASF splitter.
\t\nReceives the option flags. This value is a bitwise OR of zero or more members of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| pdwFlags is |
?
Applies to: desktop apps only
Sets the streams to be parsed by the Advanced Systems Format (ASF) splitter.
\t\nAn array of variables containing the list of stream numbers to select.
The number of valid elements in the stream number array.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| pwStreamNumbers is |
| | Invalid stream number was passed in the array. |
?
Calling this method supersedes any previous stream selections; only the streams specified in the pwStreamNumbers array will be selected.
By default, no streams are selected by the splitter.
You can obtain a list of the currently selected streams by calling the
Applies to: desktop apps only
Gets a list of currently selected streams.
\t\n The address of an array of WORDs. This array receives the stream numbers of the selected streams. This parameter can be
On input, points to a variable that contains the number of elements in the pwStreamNumbers array. Set the variable to zero if pwStreamNumbers is
On output, receives the number of elements that were copied into pwStreamNumbers. Each element is the identifier of a selected stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | The pwStreamNumbers array is smaller than the number of selected streams. See Remarks. |
?
To get the number of selected streams, set pwStreamNumbers to *pwNumStreams equal to the number of selected streams. Then allocate an array of that size and call the method again, passing the array in the pwStreamNumbers parameter.
The following code shows these steps:
DisplaySelectedStreams( *pSplitter)\t\n { WORD count = 0; hr = pSplitter->GetSelectedStreams( null , &count); if (hr ==) { WORD *pStreamIds = new (std::nothrow) WORD[count]; if (pStreamIds) { hr = pSplitter->GetSelectedStreams(pStreamIds, &count); if (SUCCEEDED(hr)) { for (WORD i = 0; i < count; i++) { printf(\"Selected stream ID: %d\\n\", pStreamIds[i]); } } delete [] pStreamIds; } else { hr = E_OUTOFMEMORY; } } return hr;\t\n }\t\n
Alternatively, you can allocate an array that is equal to the total number of streams and pass that to pwStreamNumbers.
Before calling this method, initialize *pwNumStreams to the number of elements in pwStreamNumbers. If pwStreamNumbers is *pwNumStreams to zero.
By default, no streams are selected by the splitter. Select streams by calling the
Applies to: desktop apps only
Sends packetized Advanced Systems Format (ASF) data to the ASF splitter for processing.
\t\nPointer to the
The offset into the data buffer where the splitter should begin parsing. This value is typically set to 0.
The length, in bytes, of the data to parse. This value is measured from the offset specified by cbBufferOffset. Set to 0 to process to the end of the buffer.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The pIBuffer parameter is The specified offset value in cbBufferOffset is greater than the length of the buffer. The total value of cbBufferOffset and cbLength is greater than the length of the buffer. |
| | The |
| | The splitter cannot process more input at this time. |
?
After using this method to parse data, you must call
If your ASF data contains variable-sized packets, you must set the
If the method returns ME_E_NOTACCEPTING, call GetNextSample to get the output samples, or call
The splitter might hold a reference count on the input buffer. Therefore, do not write over the valid data in the buffer after calling this method.
\t\nApplies to: desktop apps only
Retrieves a sample from the Advanced Systems Format (ASF) splitter after the data has been parsed.
\t\nReceives one of the following values.
| Value | Meaning |
|---|---|
| More samples are ready to be retrieved. Call GetNextSample in a loop until the pdwStatusFlags parameter receives the value zero. | |
| No additional samples are ready. Call |
?
If the method returns a sample in the ppISample parameter, this parameter receives the number of the stream to which the sample belongs.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The ASF data in the buffer is invalid. |
| | There is a gap in the ASF data. |
?
Before calling this method, call
The ASF splitter skips samples for unselected streams. To select streams, call
Applies to: desktop apps only
Resets the Advanced Systems Format (ASF) splitter and releases all pending samples.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Any samples waiting to be retrieved when Flush is called are lost.
\t\nApplies to: desktop apps only
Retrieves the send time of the last sample received.
\t\nReceives the send time of the last sample received.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| pdwLastSendTime is |
?
Applies to: desktop apps only
Configures the settings of a stream in an ASF file. The ASF stream configuration object exposes this interface. To obtain a reference to this interface, call the
Applies to: desktop apps only
Gets the major media type of the stream.
\t\nReceives the major media type for the stream. For a list of possible values, see Major Media Types.
If this method succeeds, it returns
Applies to: desktop apps only
Retrieves the stream number of the stream.
\t\nThe method returns the stream number.
Applies to: desktop apps only
Assigns a stream number to the stream.
\t\nThe number to assign to the stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Stream numbers start from 1 and do not need to be sequential.
\t\nApplies to: desktop apps only
Retrieves the media type of the stream.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To reduce unnecessary copying, the method returns a reference to the media type that is stored internally by the object. Do not modify the returned media type, as the results are not defined.
\t\nApplies to: desktop apps only
Sets the media type for the Advanced Systems Format (ASF) stream configuration object.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Some validation of the media type is performed by this method. However, a media type can be successfully set, but cause an error when the stream is added to the profile.
\t\nApplies to: desktop apps only
Retrieves the number of payload extensions that are configured for the stream.
\t\nReceives the number of payload extensions.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves information about an existing payload extension.
\t\nThe payload extension index. Valid indexes range from 0, to one less than the number of extensions obtained by calling
Receives a
Receives the number of bytes added to each sample for the extension.
Pointer to a buffer that receives information about this extension system. This information is the same for all samples and is stored in the content header (not in each sample). This parameter can be
On input, specifies the size of the buffer pointed to by pbExtensionSystemInfo. On output, receives the required size of the pbExtensionSystemInfo buffer in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | The buffer specified in pbExtensionSystemInfo is too small. |
| | The wPayloadExtensionNumber parameter is out of range. |
?
Applies to: desktop apps only
Configures a payload extension for the stream.
\t\nPointer to a
Number of bytes added to each sample for the extension.
A reference to a buffer that contains information about this extension system. This information is the same for all samples and is stored in the content header (not with each sample). This parameter can be
Amount of data, in bytes, that describes this extension system. If this value is 0, then pbExtensionSystemInfo can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Removes all payload extensions that are configured for the stream.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
None.
\t\nApplies to: desktop apps only
Creates a copy of the Advanced Systems Format (ASF) stream configuration object.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The cloned object is completely independent of the original.
\t\nApplies to: desktop apps only
Retrieves the stream number of the stream.
\t\nApplies to: desktop apps only
Retrieves the media type of the stream.
\t\nTo reduce unnecessary copying, the method returns a reference to the media type that is stored internally by the object. Do not modify the returned media type, as the results are not defined.
\t\nApplies to: desktop apps only
Note??This interface is not implemented in this version of Media Foundation.
Retrieves the stream number of a stream in the stream priority list.
\t\nApplies to: desktop apps only
Note??This interface is not implemented in this version of Media Foundation.
Retrieves the number of entries in the stream priority list.
\t\nReceives the number of streams in the stream priority list.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Note??This interface is not implemented in this version of Media Foundation.
Retrieves the stream number of a stream in the stream priority list.
\t\nZero-based index of the entry to retrieve from the stream priority list. To get the number of entries in the priority list, call
Receives the stream number of the stream priority entry.
Receives a Boolean value. If TRUE, the stream is mandatory.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
?
Applies to: desktop apps only
Note??This interface is not implemented in this version of Media Foundation.
Adds a stream to the stream priority list.
\t\nStream number of the stream to add.
If TRUE, the stream is mandatory.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream number. |
?
The stream priority list is built by appending entries to the list with each call to AddStream. The list is evaluated in descending order of importance. The most important stream should be added first, and the least important should be added last.
\t\nApplies to: desktop apps only
Note??This interface is not implemented in this version of Media Foundation.
Creates a copy of the ASF stream prioritization object.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The new object is completely independent of the original.
\t\nApplies to: desktop apps only
Selects streams in an Advanced Systems Format (ASF) file, based on the mutual exclusion information in the ASF header. The ASF stream selector object exposes this interface. To create the ASF stream selector, call
Applies to: desktop apps only
Retrieves the number of streams that are in the Advanced Systems Format (ASF) content.
\t\nReceives the number of streams in the content.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the number of outputs for the Advanced Systems Format (ASF) content.
\t\nReceives the number of outputs.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Outputs are streams in the ASF data section that will be parsed.
\t\nApplies to: desktop apps only
Retrieves the number of streams associated with an output.
\t\nThe output number for which to retrieve the stream count.
Receives the number of streams associated with the output.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid output number. |
?
An output is a stream in an ASF data section that will be parsed. If mutual exclusion is used, mutually exclusive streams share the same output.
\t\nApplies to: desktop apps only
Retrieves the stream numbers for all of the streams that are associated with an output.
\t\nThe output number for which to retrieve stream numbers.
Address of an array that receives the stream numbers associated with the output. The caller allocates the array. The array size must be at least as large as the value returned by the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid output number. |
?
An output is a stream in an ASF data section that will be parsed. If mutual exclusion is used, mutually exclusive streams share the same output.
\t\nApplies to: desktop apps only
Retrieves the output number associated with a stream.
\t\nThe stream number for which to retrieve an output number.
Receives the output number.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream number. |
?
Outputs are streams in the ASF data section that will be parsed.
\t\nApplies to: desktop apps only
Retrieves the manual output override selection that is set for a stream.
\t\nStream number for which to retrieve the output override selection.
Receives the output override selection. The value is a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets the selection status of an output, overriding other selection criteria.
\t\nOutput number for which to set selection.
Member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the number of mutual exclusion objects associated with an output.
\t\nOutput number for which to retrieve the count of mutually exclusive relationships.
Receives the number of mutual exclusions.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves a mutual exclusion object for an output.
\t\nOutput number for which to retrieve a mutual exclusion object.
Mutual exclusion number. This is an index of mutually exclusive relationships associated with the output. Set to a number between 0, and 1 less than the number of mutual exclusion objects retrieved by calling
Receives a reference to the mutual exclusion object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Outputs are streams in the ASF data section that will be parsed.
\t\nApplies to: desktop apps only
Selects a mutual exclusion record to use for a mutual exclusion object associated with an output.
\t\nThe output number for which to set a stream.
Index of the mutual exclusion for which to select.
Record of the specified mutual exclusion to select.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
An output is a stream in an Advanced Systems Format (ASF) data section that will be parsed. If mutual exclusion is used, mutually exclusive streams share the same output.
An ASF file can contain multiple mutually exclusive relationships, such as a file with both language based and bit-rate based mutual exclusion. If an output is involved in multiple mutually exclusive relationships, a record from each must be selected.
\t\nApplies to: desktop apps only
Retrieves the number of bandwidth steps that exist for the content. This method is used for multiple bit rate (MBR) content.
\t\nReceives the number of bandwidth steps.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Bandwidth steps are bandwidth levels used for multiple bit rate (MBR) content. If you stream MBR content, you can choose the bandwidth step that matches the network conditions to avoid interruptions during playback.
\t\nApplies to: desktop apps only
Retrieves the stream numbers that apply to a bandwidth step. This method is used for multiple bit rate (MBR) content.
\t\nBandwidth step number for which to retrieve information. Set this value to a number between 0, and 1 less than the number of bandwidth steps returned by
Receives the bit rate associated with the bandwidth step.
Address of an array that receives the stream numbers. The caller allocates the array. The array size must be at least as large as the value returned by the
Address of an array that receives the selection status of each stream, as an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Bandwidth steps are bandwidth levels used for MBR content. If you stream MBR content, you can choose the bandwidth step that matches the network conditions to avoid interruptions during playback.
\t\nApplies to: desktop apps only
Retrieves the index of a bandwidth step that is appropriate for a specified bit rate. This method is used for multiple bit rate (MBR) content.
\t\nThe bit rate to find a bandwidth step for.
Receives the step number. Use this number to retrieve information about the step by calling
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
In a streaming multiple bit rate (MBR) scenario, call this method with the current data rate of the network connection to determine the correct step to use. You can also call this method periodically throughout streaming to ensure that the best step is used.
\t\nApplies to: desktop apps only
Sets options for the stream selector.
\t\nBitwise OR of zero or more members of the MFASF_STREAMSELECTOR_FLAGS enumeration specifying the options to use.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets options for the stream selector.
\t\nApplies to: desktop apps | Metro style apps
Callback interface to notify the application when an asynchronous method completes.
\t\nFor more information about asynchronous methods in Microsoft Media Foundation, see Asynchronous Callback Methods.
This interface is also used to perform a work item in a Media Foundation work-queue. For more information, see Work Queues.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Provides configuration information to the dispatching thread for a callback.
\t\nReceives a flag indicating the behavior of the callback object's
| Value | Meaning |
|---|---|
| The callback does not take a long time to complete, but has no specific restrictions on what system calls it makes. The callback generally takes less than 30 milliseconds to complete. |
| The callback does very minimal processing. It takes less than 1 millisecond to complete. The callback must be invoked from one of the following work queues:
|
| Implies MFASYNC_FAST_IO_PROCESSING_CALLBACK, with the additional restriction that the callback does no processing (less than 50 microseconds), and the only system call it makes is SetEvent. The callback must be invoked from one of the following work queues:
|
| Blocking callback. |
| Reply callback. |
?
Receives the identifier of the work queue on which the callback is dispatched.
This value can specify one of the standard Media Foundation work queues, or a work queue created by the application. For list of standard Media Foundation work queues, see Work Queue Identifiers. To create a new work queue, call
If the work queue is not compatible with the value returned in pdwFlags, the Media Foundation platform returns
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. Assume the default behavior. |
?
The GetParameters method returns information about the callback so that the dispatching thread can optimize the process that it uses to invoke the callback.
If the method returns a value other than zero in the pdwFlags parameter, your Invoke method must meet the requirements described here. Otherwise, the callback might delay the pipeline.
If you want default values for both parameters, return E_NOTIMPL. The default values are given in the parameter descriptions on this page.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Called when an asynchronous operation is completed.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Within your implementation of Invoke, call the corresponding End... method.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Provides information about the result of an asynchronous operation.
\t\nUse this interface to complete an asynchronous operation. You get a reference to this interface when your callback object's
If you are implementing an asynchronous method, call
Any custom implementation of this interface must inherit the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method.
\t\nReceives a reference to the state object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There is no state object associated with this asynchronous result. |
?
The caller of the asynchronous method specifies the state object, and can use it for any caller-defined purpose. The state object can be
If you are implementing an asynchronous method, set the state object on the through the punkState parameter of the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the status of the asynchronous operation.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The operation completed successfully. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Sets the status of the asynchronous operation.
hrStatus
The status of the asynchronous operation.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
If you implement an asynchronous method, call SetStatus to set the status code for the operation.
Client: Requires Windows Vista.
Header: Defined in mfobjects.h; include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFAsyncResult InterfaceConceptsAsynchronous Callback Methods\t\nApplies to: desktop apps | Metro style apps
Returns an object associated with the asynchronous operation. The type of object, if any, depends on the asynchronous method that was called.
\t\nReceives a reference to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There is no object associated with this asynchronous result. |
?
Typically, this object is used by the component that implements the asynchronous method. It provides a way for the function that invokes the callback to pass information to the asynchronous End... method that completes the operation.
If you are implementing an asynchronous method, you can set the object through the punkObject parameter of the
If the asynchronous result object's internal
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method, without incrementing the object's reference count.
\t\nReturns a reference to the state object's
This method cannot be called remotely.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method.
\t\nThe caller of the asynchronous method specifies the state object, and can use it for any caller-defined purpose. The state object can be
If you are implementing an asynchronous method, set the state object on the through the punkState parameter of the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the status of the asynchronous operation.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns an object associated with the asynchronous operation. The type of object, if any, depends on the asynchronous method that was called.
\t\nTypically, this object is used by the component that implements the asynchronous method. It provides a way for the function that invokes the callback to pass information to the asynchronous End... method that completes the operation.
If you are implementing an asynchronous method, you can set the object through the punkObject parameter of the
If the asynchronous result object's internal
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method, without incrementing the object's reference count.
\t\nThis method cannot be called remotely.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[
Applies to: desktop apps only
Represents a description of an audio format.
\t\n To convert an audio media type into a
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents a description of a media format.
\t\n To create a new media type, call
All of the information in a media type is stored as attributes. To clone a media type, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets the major type of the format.
\t\nReceives the major type
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The major type is not set. |
?
This method is equivalent to getting the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the media type is a temporally compressed format. Temporal compression uses information from previously decoded samples when decompressing the current sample.
\t\nReceives a Boolean value. The value is TRUE if the format uses temporal compression, or
If this method succeeds, it returns
This method returns
If the method returns TRUE in pfCompressed, it is a hint that the format has temporal compression applied to it. If the method returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Compares two media types and determines whether they are identical. If they are not identical, the method indicates how the two formats differ.
\t\nPointer to the
Receives a bitwise OR of zero or more flags, indicating the degree of similarity between the two media types. The following flags are defined.
| Value | Meaning |
|---|---|
| The major types are the same. The major type is specified by the |
| The subtypes are the same, or neither media type has a subtype. The subtype is specified by the |
| The attributes in one of the media types are a subset of the attributes in the other, and the values of these attributes match, excluding the value of the Specifically, the method takes the media type with the smaller number of attributes and checks whether each attribute from that type is present in the other media type and has the same value (not including To perform other comparisons, use the |
| The user data is identical, or neither media type contains user data. User data is specified by the |
?
The method returns an
| Return code | Description |
|---|---|
| The types are not equal. Examine the pdwFlags parameter to determine how the types differ. |
| | The types are equal. |
| One or both media types are invalid. |
?
Both of the media types must have a major type, or the method returns E_INVALIDARG.
If the method succeeds and all of the comparison flags are set in pdwFlags, the return value is
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an alternative representation of the media type. Currently only the DirectShow
| Value | Meaning |
|---|---|
| Convert the media type to a DirectShow |
| Convert the media type to a DirectShow |
| Convert the media type to a DirectShow |
| Convert the media type to a DirectShow |
?
Receives a reference to a structure that contains the representation. The method allocates the memory for the structure. The caller must release the memory by calling
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The details of the media type do not match the requested representation. |
| | The media type is not valid. |
| | The media type does not support the requested representation. |
?
If you request a specific format structure in the guidRepresentation parameter, such as
You can also use the MFInitAMMediaTypeFromMFMediaType function to convert a Media Foundation media type into a DirectShow media type.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Frees memory that was allocated by the
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
The media type is created without any attributes.
\t\nApplies to: desktop apps | Metro style apps
Converts a Media Foundation audio media type to a
Receives the size of the
Contains a flag from the
If the wFormatTag member of the returned structure is
Applies to: desktop apps | Metro style apps
Gets the major type of the format.
\t\n This method is equivalent to getting the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the media type is a temporally compressed format. Temporal compression uses information from previously decoded samples when decompressing the current sample.
\t\n This method returns
If the method returns TRUE in pfCompressed, it is a hint that the format has temporal compression applied to it. If the method returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[GetAudioFormat is no longer available for use as of Windows?7. Instead, use the media type attributes to get the properties of the audio format.]
Applies to: desktop apps only
Returns a reference to a
This method returns a reference to a
If you need to convert the media type into a
There are no guarantees about how long the returned reference is valid.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[GetAudioFormat is no longer available for use as of Windows?7. Instead, use the media type attributes to get the properties of the audio format.]
Applies to: desktop apps only
Returns a reference to a
If you need to convert the media type into a
There are no guarantees about how long the returned reference is valid.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Sets the display name of the audio session. The Windows volume control displays this name.
\t\nIf the application does not set a display name, Windows creates one.
\t\nApplies to: desktop apps only
Assigns the audio session to a group of sessions.
\t\nA
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If two or more audio sessions share the same group, the Windows volume control displays one slider control for the entire group. Otherwise, it displays a slider for each session. For more information, see IAudioSessionControl::SetGroupingParam in the core audio API documentation.
\t\nApplies to: desktop apps only
Retrieves the group of sessions to which this audio session belongs.
\t\nReceives a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If two or more audio sessions share the same group, the Windows volume control displays one slider control for the entire group. Otherwise, it displays a slider for each session. For more information, see IAudioSessionControl::SetGroupingParam in the core audio API documentation.
\t\nApplies to: desktop apps only
Sets the display name of the audio session. The Windows volume control displays this name.
\t\nA null-terminated wide-character string that contains the display name.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the application does not set a display name, Windows creates one.
\t\nApplies to: desktop apps only
Retrieves the display name of the audio session. The Windows volume control displays this name.
\t\nReceives a reference to the display name string. The caller must free the memory allocated for the string by calling CoTaskMemFree.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the application does not set a display name, Windows creates one.
\t\nApplies to: desktop apps only
Sets the icon resource for the audio session. The Windows volume control displays this icon.
\t\nA wide-character string that specifies the icon. See Remarks.
If this method succeeds, it returns
The icon path has the format \"path,index\" or \"path,-id\", where path is the fully qualified path to a DLL, executable file, or icon file; index is the zero-based index of the icon within the file; and id is a resource identifier. Note that resource identifiers are preceded by a minus sign (-) to distinguish them from indexes. The path can contain environment variables, such as \"%windir%\". For more information, see IAudioSessionControl::SetIconPath in the Windows SDK.
\t\nApplies to: desktop apps only
Retrieves the icon resource for the audio session. The Windows volume control displays this icon.
\t\nReceives a reference to a wide-character string that specifies a shell resource. The format of the string is described in the topic
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the application did not set an icon path, the method returns an empty string (\"\").
For more information, see IAudioSessionControl::GetIconPath in the core audio API documentation.
\t\nApplies to: desktop apps only
Retrieves the group of sessions to which this audio session belongs.
\t\nIf two or more audio sessions share the same group, the Windows volume control displays one slider control for the entire group. Otherwise, it displays a slider for each session. For more information, see IAudioSessionControl::SetGroupingParam in the core audio API documentation.
\t\nApplies to: desktop apps only
Controls the volume levels of individual audio channels.
The streaming audio renderer (SAR) exposes this interface as a service. To get a reference to the interface, call
If your application does not require channel-level volume control, you can use the
Volume is expressed as an attenuation level, where 0.0 indicates silence and 1.0 indicates full volume (no attenuation). For each channel, the attenuation level is the product of:
For example, if the master volume is 0.8 and the channel volume is 0.5, the attenuation for that channel is 0.8 ? 0.5 = 0.4. Volume levels can exceed 1.0 (positive gain), but the audio engine clips any audio samples that exceed zero decibels.
Use the following formula to convert the volume level to the decibel (dB) scale:
Attenuation (dB) = 20 * log10(Level)
For example, a volume level of 0.50 represents 6.02 dB of attenuation.
\t\nApplies to: desktop apps only
Retrieves the number of channels in the audio stream.
\t\nReceives the number of channels in the audio stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets the volume level for a specified channel in the audio stream.
\t\nZero-based index of the audio channel. To get the number of channels, call
Volume level for the channel.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the volume level for a specified channel in the audio stream.
\t\nZero-based index of the audio channel. To get the number of channels, call
Receives the volume level for the channel.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets the individual volume levels for all of the channels in the audio stream.
\t\nNumber of elements in the pfVolumes array. The value must equal the number of channels. To get the number of channels, call
Address of an array of size dwCount, allocated by the caller. The array specifies the volume levels for all of the channels. Before calling the method, set each element of the array to the desired volume level for the channel.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the volume levels for all of the channels in the audio stream.
\t\nNumber of elements in the pfVolumes array. The value must equal the number of channels. To get the number of channels, call
Address of an array of size dwCount, allocated by the caller. The method fills the array with the volume level for each channel in the stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the number of channels in the audio stream.
\t\nApplies to: desktop apps | Metro style apps
Represents a buffer that contains a two-dimensional surface, such as a video frame.
\t\nTo get a reference to this interface, call QueryInterface on the media buffer.
To use a 2-D buffer, it is important to know the stride, which is the number of bytes needed to go from one row of pixels to the next. The stride may be larger than the image width, because the surface may contain padding bytes after each row of pixels. Stride can also be negative, if the pixels are oriented bottom-up in memory. For more information, see Image Stride.
Every video format defines a contiguous or packed representation. This representation is compatible with the standard layout of a DirectX surface in system memory, with no additional padding. For RGB video, the contiguous representation has a pitch equal to the image width in bytes, rounded up to the nearest DWORD boundary. For YUV video, the layout of the contiguous representation depends on the YUV format. For planar YUV formats, the Y plane might have a different pitch than the U and V planes.
If a media buffer supports the
Call the Lock2D method to access the 2-D buffer in its native format. The native format might not be contiguous. The buffer's
For uncompressed images, the amount of valid data in the buffer is determined by the width, height, and pixel layout of the image. For this reason, if you call Lock2D to access the buffer, do not rely on the values returned by
Applies to: desktop apps | Metro style apps
Gives the caller access to the memory in the buffer.
\t\nReceives a reference to the first byte of the top row of pixels in the image. The top row is defined as the top row when the image is presented to the viewer, and might not be the first row in memory.
Receives the surface stride, in bytes. The stride might be negative, indicating that the image is oriented from the bottom up in memory.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Cannot lock the Direct3D surface. |
| | The buffer cannot be locked at this time. |
?
If p is a reference to the first byte in a row of pixels, p + (*plPitch) points to the first byte in the next row of pixels. A buffer might contain padding after each row of pixels, so the stride might be wider than the width of the image in bytes. Do not access the memory that is reserved for padding bytes, because it might not be read-accessible or write-accessible. For more information, see Image Stride.
The reference returned in pbScanline0 remains valid as long as the caller holds the lock. When you are done accessing the memory, call
The values returned by the
The
When the underlying buffer is a Direct3D surface, the method fails if the surface is not lockable.
\t\nApplies to: desktop apps | Metro style apps
Unlocks a buffer that was previously locked. Call this method once for each call to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves a reference to the buffer memory and the surface stride.
\t\nReceives a reference to the first byte of the top row of pixels in the image.
Receives the stride, in bytes. For more information, see Image Stride.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | You must lock the buffer before calling this method. |
?
Before calling this method, you must lock the buffer by calling
Applies to: desktop apps | Metro style apps
Queries whether the buffer is contiguous in its native format.
\t\nReceives a Boolean value. The value is TRUE if the buffer is contiguous, and
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Retrieves the number of bytes needed to store the contents of the buffer in contiguous format.
\t\nReceives the number of bytes needed to store the contents of the buffer in contiguous format.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Copies this buffer into the caller's buffer, converting the data to contiguous format.
\t\nPointer to the destination buffer where the data will be copied. The caller allocates the buffer.
Size of the destination buffer, in bytes. To get the required size, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid size specified in pbDestBuffer. |
?
If the original buffer is not contiguous, this method converts the contents into contiguous format during the copy. For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Copies data to this buffer from a buffer that has a contiguous format.
\t\nPointer to the source buffer. The caller allocates the buffer.
Size of the source buffer, in bytes. To get the maximum size of the buffer, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method copies the contents of the source buffer into the buffer that is managed by this
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in the
Applies to: desktop apps | Metro style apps
Queries whether the buffer is contiguous in its native format.
\t\nFor a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Retrieves the number of bytes needed to store the contents of the buffer in contiguous format.
\t\nFor a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Controls how a byte stream buffers data from a network.
To get a reference to this interface, call QueryInterface on the byte stream object.
\t\nIf a byte stream implements this interface, a media source can use it to control how the byte stream buffers data. This interface is designed for byte streams that read data from a network.
A byte stream that implements this interface should also implement the
The byte stream must send a matching
After the byte stream sends an
The byte stream should not send any more buffering events after it reaches the end of the file.
If buffering is disabled, the byte stream does not send any buffering events. Internally, however, it might still buffer data while it waits for I/O requests to complete. Therefore,
If the byte stream is buffering data internally and the media source calls EnableBuffering with the value TRUE, the byte stream can send
After the presentation has started, the media source should forward and
Applies to: desktop apps | Metro style apps
Sets the buffering parameters.
\t\nPointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Enables or disables buffering.
\t\nSpecifies whether the byte stream buffers data. If TRUE, buffering is enabled. If
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Before calling this method, call
Applies to: desktop apps | Metro style apps
Stops any buffering that is in progress.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The byte stream successfully stopped buffering. |
| No buffering was in progress. |
?
If the byte stream is currently buffering data, it stops and sends an
Applies to: desktop apps | Metro style apps
Sets the buffering parameters.
\t\nApplies to: desktop apps only
Stops the background transfer of data to the local cache.
\t\nThe byte stream resumes transferring data to the cache if the application does one of the following:
Applies to: desktop apps only
Stops the background transfer of data to the local cache.
\t\nIf this method succeeds, it returns
The byte stream resumes transferring data to the cache if the application does one of the following:
Applies to: desktop apps only
Creates a media source from a byte stream.
\t\nApplications do not use this interface directly. This interface is exposed by byte-stream handlers, which are used by the source resolver. When the byte-stream handler is given a byte stream, it parses the stream and creates a media source. Byte-stream handlers are registered by file name extension or MIME type.
\t\nApplies to: desktop apps only
Begins an asynchronous request to create a media source from a byte stream.
\t\nPointer to the byte stream's
String that contains the original URL of the byte stream. This parameter can be
Bitwise OR of zero or more flags. See Source Resolver Flags.
Pointer to the
Receives an
Pointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Unable to parse the byte stream. |
?
The dwFlags parameter must contain the
The byte-stream handler is responsible for parsing the stream and validating the contents. If the stream is not valid or the byte stream handler cannot parse the stream, the handler should return a failure code. The byte stream is not guaranteed to match the type of stream that the byte handler is designed to parse.
If the pwszURL parameter is not
When the operation completes, the byte-stream handler calls the
Applies to: desktop apps only
Completes an asynchronous request to create a media source.
\t\nPointer to the
Receives a member of the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The operation was canceled. See |
| | Unable to parse the byte stream. |
?
Call this method from inside the
Applies to: desktop apps only
Cancels the current request to create a media source.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
You can use this method to cancel a previous call to BeginCreateObject. Because that method is asynchronous, however, it might be completed before the operation can be canceled. Therefore, your callback might still be invoked after you call this method.
\t\nApplies to: desktop apps only
Retrieves the maximum number of bytes needed to create the media source or determine that the byte stream handler cannot parse this stream.
\t\nReceives the maximum number of bytes that are required.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the maximum number of bytes needed to create the media source or determine that the byte stream handler cannot parse this stream.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the last clock time that was correlated with system time.
\t\nAt some fixed interval, a clock correlates its internal clock ticks with the system time. (The system time is the time returned by the high-resolution performance counter.) This method returns:
The clock time is returned in the pllClockTime parameter and is expressed in units of the clock's frequency. If the clock's
The system time is returned in the phnsSystemTime parameter, and is always expressed in 100-nanosecond units.
To find out how often the clock correlates its clock time with the system time, call GetProperties. The correlation interval is given in the qwCorrelationRate member of the
Some clocks support rate changes through the
For the presentation clock, the clock time is the presentation time, and is always relative to the starting time specified in
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the clock.
\t\nReceives a bitwise OR of values from the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the last clock time that was correlated with system time.
\t\nReserved, must be zero.
Receives the last known clock time, in units of the clock's frequency.
Receives the system time that corresponds to the clock time returned in pllClockTime, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The clock does not have a time source. |
?
At some fixed interval, a clock correlates its internal clock ticks with the system time. (The system time is the time returned by the high-resolution performance counter.) This method returns:
The clock time is returned in the pllClockTime parameter and is expressed in units of the clock's frequency. If the clock's
The system time is returned in the phnsSystemTime parameter, and is always expressed in 100-nanosecond units.
To find out how often the clock correlates its clock time with the system time, call GetProperties. The correlation interval is given in the qwCorrelationRate member of the
Some clocks support rate changes through the
For the presentation clock, the clock time is the presentation time, and is always relative to the starting time specified in
Applies to: desktop apps | Metro style apps
Retrieves the clock's continuity key. (Not supported.)
\t\nReceives the continuity key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Continuity keys are currently not supported in Media Foundation. Clocks must return the value zero in the pdwContinuityKey parameter.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the current state of the clock.
\t\nReserved, must be zero.
Receives the clock state, as a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the properties of the clock.
\t\nPointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the clock.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the clock's continuity key. (Not supported.)
\t\nContinuity keys are currently not supported in Media Foundation. Clocks must return the value zero in the pdwContinuityKey parameter.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the properties of the clock.
\t\nApplies to: desktop apps | Metro style apps
Receives state-change notifications from the presentation clock.
\t\nTo receive state-change notifications from the presentation clock, implement this interface and call
This interface must be implemented by:
Presentation time sources. The presentation clock uses this interface to request change states from the time source.
Media sinks. Media sinks use this interface to get notifications when the presentation clock changes.
Other objects that need to be notified can implement this interface.
\t\nApplies to: desktop apps | Metro style apps
Called when the presentation clock starts.
\t\nThe system time when the clock started, in 100-nanosecond units.
The new starting time for the clock, in 100-nanosecond units. This parameter can also equal PRESENTATION_CURRENT_POSITION, indicating the clock has started or restarted from its current position.
If this method succeeds, it returns
This method is called whe the presentation clock's
The clock notifies the presentation time source by calling the time source's OnClockStart method. This call occurs synchronously within the Start method. If the time source returns an error from OnClockStart, the presentation clock's Start method returns an error and the state change does not take place.
For any object that is not the presentation time source, the OnClockStart method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.
The value given in llClockStartOffset is the presentation time when the clock starts, so it is relative to the start of the presentation. Media sinks should not render any data with a presentation time earlier than llClockStartOffSet. If a sample straddles the offset?that is, if the offset falls between the sample's start and stop times?the sink should either trim the sample so that only data after llClockStartOffset is rendered, or else simply drop the sample.
\t\nApplies to: desktop apps | Metro style apps
Called when the presentation clock stops.
\t\nThe system time when the clock stopped, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Deprecated. Do not use this error code. |
?
When the presentation clock's
For any object that is not the presentation time source, the OnClockStop method is called asynchronously, after the state change is completed.
If an object is already stopped, it should return
Note??Although the header file mferror.h defines an error code named
Applies to: desktop apps | Metro style apps
Called when the presentation clock pauses.
\t\nThe system time when the clock was paused, in 100-nanosecond units.
If this method succeeds, it returns
When the presentation clock's
For any object that is not the presentation time source, the OnClockPause method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.
\t\nApplies to: desktop apps | Metro style apps
Called when the presentation clock restarts from the same position while paused.
\t\nThe system time when the clock restarted, in 100-nanosecond units.
If this method succeeds, it returns
This method is called if the presentation clock is paused and the
The clock notifies the presentation time source by calling the time source's OnClockRestart method. This call occurs synchronously within the Start method. If the time source returns an error from OnClockRestart, the presentation clock's Start method returns an error and the state change does not take place.
For any object that is not the presentation time source, the OnClockRestart method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.
\t\nApplies to: desktop apps | Metro style apps
Called when the rate changes on the presentation clock.
\t\nThe system time when the rate was set, in 100-nanosecond units.
The new rate, as a multiplier of the normal playback rate.
If this method succeeds, it returns
When the presentation clock's
For any object that is not the presentation time source, the OnClockSetRate method is called asynchronously, after the state change is completed. In that case, the return value from this method is ignored.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the number of objects in the collection.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the number of objects in the collection.
\t\nReceives the number of objects in the collection.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves an object in the collection.
\t\nZero-based index of the object to retrieve. Objects are indexed in the order in which they were added to the collection.
Receives a reference to the object's
If this method succeeds, it returns
This method does not remove the object from the collection. To remove an object, call
Applies to: desktop apps | Metro style apps
Adds an object to the collection.
\t\nPointer to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If pUnkElement is
Applies to: desktop apps | Metro style apps
Removes an object from the collection.
\t\nZero-based index of the object to remove. Objects are indexed in the order in which they were added to the collection.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Adds an object at the specified index in the collection.
\t\nThe zero-based index where the object will be added to the collection.
The object to insert.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Removes all items from the collection.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the number of objects in the collection.
\t\nApplies to: desktop apps | Metro style apps
Retrieves a URL for performing a manual content enabling action.
\t\nIf the enabling action can be performed by navigating to a URL, this method returns the URL. If no such URL exists, the method returns a failure code.
The purpose of the URL depends on the content enabler type, which is obtained by calling
| Enable type | Purpose of URL |
|---|---|
| Individualization | Not applicable. |
| License acquisition | URL to obtain the license. Call |
| Revocation | URL to a webpage where the user can download and install an updated component. |
?
\t\nRetrieves the type of operation that this content enabler performs.
pType
[out] Receives a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
The following GUIDs are defined for the pType parameter.
| Value | Description |
|---|---|
| MFENABLETYPE_MF_RebootRequired | The user must reboot his or her computer. |
| MFENABLETYPE_MF_UpdateRevocationInformation | Update revocation information. |
| MFENABLETYPE_MF_UpdateUntrustedComponent | Update untrusted components. |
| MFENABLETYPE_WMDRMV1_LicenseAcquisition | License acquisition for Windows Media Digital Rights Management (DRM) version 1. |
| MFENABLETYPE_WMDRMV7_Individualization | Individualization. |
| MFENABLETYPE_WMDRMV7_LicenseAcquisition | License acquisition for Windows Media DRM version 7 or later. |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFContentEnabler InterfaceConceptsHow to Play Protected Media Files\t\nRetrieves a URL for performing a manual content enabling action.
ppwszURL
[out] Receives a reference to a buffer that contains the URL. The caller must release the memory for the buffer by calling CoTaskMemFree.
pcchURL
[out] Receives the length of the string retrieved in ppwszURL, including the terminating
pTrustStatus
[in, out] Receives a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No URL is available. |
If the enabling action can be performed by navigating to a URL, this method returns the URL. If no such URL exists, the method returns a failure code.
The purpose of the URL depends on the content enabler type, which is obtained by calling
| Enable type | Purpose of URL |
|---|---|
| Individualization | Not applicable. |
| License acquisition | URL to obtain the license. Call |
| Revocation | URL to a Web page where the user can download and install an updated component. |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFContentEnabler InterfaceConceptsHow to Play Protected Media Files\t\nApplies to: desktop apps | Metro style apps
Retrieves the data for a manual content enabling action.
\t\nReceives a reference to a buffer that contains the data. The caller must free the buffer by calling CoTaskMemFree.
Receives the size of the ppbData buffer.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No data is available. |
?
The purpose of the data depends on the content enabler type, which is obtained by calling
| Enable type | Purpose of data |
|---|---|
| Individualization | Not applicable. |
| License acquisition | HTTP POST data. |
| Revocation | |
?
\t\nApplies to: desktop apps | Metro style apps
Queries whether the content enabler can perform all of its actions automatically.
\t\nReceives a Boolean value. If TRUE, the content enabler can perform the enabing action automatically.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If this method returns TRUE in the pfAutomatic parameter, call the
If this method returns
Applies to: desktop apps | Metro style apps
Performs a content enabling action without any user interaction.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method is asynchronous. When the operation is complete, the content enabler sends an
To find out whether the content enabler supports this method, call
Applies to: desktop apps | Metro style apps
Requests notification when the enabling action is completed.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The method succeeded and no action was required. |
?
If you use a manual enabling action, call this method to be notified when the operation completes. If this method returns
You do not have to call MonitorEnable when you use automatic enabling by calling
Applies to: desktop apps | Metro style apps
Cancels a pending content enabling action.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The content enabler sends an
Retrieves the type of operation that this content enabler performs.
pType
[out] Receives a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
The following GUIDs are defined for the pType parameter.
| Value | Description |
|---|---|
| MFENABLETYPE_MF_RebootRequired | The user must reboot his or her computer. |
| MFENABLETYPE_MF_UpdateRevocationInformation | Update revocation information. |
| MFENABLETYPE_MF_UpdateUntrustedComponent | Update untrusted components. |
| MFENABLETYPE_WMDRMV1_LicenseAcquisition | License acquisition for Windows Media Digital Rights Management (DRM) version 1. |
| MFENABLETYPE_WMDRMV7_Individualization | Individualization. |
| MFENABLETYPE_WMDRMV7_LicenseAcquisition | License acquisition for Windows Media DRM version 7 or later. |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFContentEnabler InterfaceConceptsHow to Play Protected Media Files\t\nApplies to: desktop apps | Metro style apps
Queries whether the content enabler can perform all of its actions automatically.
\t\nIf this method returns TRUE in the pfAutomatic parameter, call the
If this method returns
Applies to: desktop apps | Metro style apps
Enables playback of protected content by providing the application with a reference to a content enabler object.
Applications that play protected content should implement this interface.
\t\nA content enabler is an object that performs some action that is required to play a piece of protected content. For example, the action might be obtaining a DRM license. Content enablers expose the
To use this interface, do the following:
Implement the interface in your application.
Create an attribute store by calling
Set the
Call
If the content requires a content enabler, the application's BeginEnableContent method is called. Usually this method called during the
Many content enablers send machine-specific data to the network, which can have privacy implications. One of the purposes of the
Applies to: desktop apps only
Ends an asynchronous request to perform a content enabling action. This method is called by the protected media path (PMP) to complete an asynchronous call to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
When the BeginEnableContent method completes asynchronously, the application notifies the PMP by invoking the asynchronous callback. The PMP calls EndEnableContent on the application to get the result code. This method is called on the application's thread from inside the callback method. Therefore, it must not block the thread that invoked the callback.
The application must return the success or failure code of the asynchronous processing that followed the call to BeginEnableContent.
\t\nApplies to: desktop apps only
Ends an asynchronous request to perform a content enabling action. This method is called by the protected media path (PMP) to complete an asynchronous call to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
When the BeginEnableContent method completes asynchronously, the application notifies the PMP by invoking the asynchronous callback. The PMP calls EndEnableContent on the application to get the result code. This method is called on the application's thread from inside the callback method. Therefore, it must not block the thread that invoked the callback.
The application must return the success or failure code of the asynchronous processing that followed the call to BeginEnableContent.
\t\nApplies to: desktop apps only
Enables the presenter for the enhanced video renderer (EVR) to request a specific frame from the video mixer.
The sample objects created by the
Applies to: desktop apps only
Called by the mixer to get the time and duration of the sample requested by the presenter.
\t\nReceives the desired sample time that should be mixed.
Receives the sample duration that should be mixed.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No time stamp was set for this sample. See |
?
Applies to: desktop apps only
Called by the presenter to set the time and duration of the sample that it requests from the mixer.
\t\nThe time of the requested sample.
The duration of the requested sample.
This value should be set prior to passing the buffer to the mixer for a Mix operation. The mixer sets the actual start and duration times on the sample before sending it back.
\t\nApplies to: desktop apps only
Clears the time stamps previously set by a call to
After this method is called, the
This method also clears the time stamp and duration and removes all attributes from the sample.
\t\nApplies to: desktop apps only
Initializes the Digital Living Network Alliance (DLNA) media sink.
The DLNA media sink exposes this interface. To get a reference to this interface, call CoCreateInstance. The CLSID is CLSID_MPEG2DLNASink.
\t\nApplies to: desktop apps only
Initializes the Digital Living Network Alliance (DLNA) media sink.
\t\nPointer to a byte stream. The DLNA media sink writes data to this byte stream. The byte stream must be writable.
If TRUE, the DLNA media sink accepts PAL video formats. Otherwise, it accepts NTSC video formats.
This method can return one of these values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The method was already called. |
| | The media sink's |
?
Applies to: desktop apps only
Configures Windows Media Digital Rights Management (DRM) for Network Devices on a network sink.
The Advanced Systems Format (ASF) streaming media sink exposes this interface. To get a reference to the
For more information, see Remarks.
\t\nTo stream protected content over a network, the ASF streaming media sink provides an output trust authority (OTA) that supports Windows Media DRM for Network Devices and implements the
The application gets a reference to
To stream the content, the application does the following:
To stream DRM-protected content over a network from a server to a client, an application must use the Microsoft Media Foundation Protected Media Path (PMP). The media sink and the application-provided HTTP byte stream exist in mfpmp.exe. Therefore, the byte stream must expose the
Note??This might affect how the code is packaged. The DLL that contains the HTTP byte stream and other dependent DLLs must be signed for the Protected Environment (PE-signed).
When the clock starts for the first time or restarts , the encrypter that is used for encrypting samples is retrieved, and the license response is cached.
Applies to: desktop apps only
Gets the license response for the specified request.
\t\nPointer to a byte array that contains the license request.
Size, in bytes, of the license request.
Receives a reference to a byte array that contains the license response. The caller must free the array by calling CoTaskMemFree.
Receives the size, in bytes, of the license response.
Receives the key identifier. The caller must release the string by calling SysFreeString.
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink was shut down. |
?
Applies to: desktop apps only
Not implemented in this release.
\t\nReceives a reference to a byte array that contains the license response. The caller must free the array by calling CoTaskMemFree.
Receives the size, in bytes, of the license response.
The method returns E_NOTIMPL.
Applies to: desktop apps only
Enables an application to use a Media Foundation transform (MFT) that has restrictions on its use.
\t\nIf you register an MFT that requires unlocking, include the
Applies to: desktop apps only
Unlocks a Media Foundation transform (MFT) so that the application can use it.
\t\nA reference to the
If this method succeeds, it returns
This method authenticates the caller, using a private communication channel between the MFT and the object that implements the
Applies to: desktop apps only
Sets the number of input pins on the DirectShow Enhanced Video Renderer (EVR) filter. To get a reference to this interface, call QueryInterface on the DirectShow EVR filter.
\t\nThe DirectShow EVR filter starts with one input pin, which corresponds to the reference stream. To create additional pins for video substreams, call SetNumberOfStreams.
The EVR media sink for Media Foundation does not support this interface. To add new streams to the EVR media sink, call
Applies to: desktop apps only
Sets the number of input pins on the EVR filter.
\t\nSpecifies the total number of input pins on the EVR filter. This value includes the input pin for the reference stream, which is created by default. For example, to mix one substream plus the reference stream, set this parameter to 2.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid number of streams. The minimum is one, and the maximum is 16. |
| This method has already been called, or at least one pin is already connected. |
?
After this method has been called, it cannot be called a second time on the same instance of the EVR filter. Also, the method fails if any input pins are connected.
\t\nApplies to: desktop apps only
Retrieves the number of input pins on the EVR filter. The EVR filter always has at least one input pin, which corresponds to the reference stream.
\t\nReceives the number of streams.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the number of input pins on the EVR filter. The EVR filter always has at least one input pin, which corresponds to the reference stream.
\t\nApplies to: desktop apps only
Configures the DirectShow Enhanced Video Renderer (EVR) filter. To get a reference to this interface, call QueryInterface on the EVR filter.
\t\nApplies to: desktop apps only
Sets the configuration parameters for the Microsoft DirectShow Enhanced Video Renderer Filter (EVR).
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
?
Applies to: desktop apps only
Gets the configuration parameters for the Microsoft DirectShow Enhanced Video Renderer Filter filter.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Gets the configuration parameters for the Microsoft DirectShow Enhanced Video Renderer Filter filter.
\t\nApplies to: desktop apps only
Notifies the media sink to asynchronously take any steps it needs to finish its tasks.
\t\nMany archive media sinks have steps they need to do at the end of archiving to complete their file operations, such as updating the header (for some formats) or flushing all pending writes to disk. In some cases, this may include expensive operations such as indexing the content. BeginFinalize is an asynchronous way to initiate final tasks.
When the finalize operation is complete, the callback object's
Applies to: desktop apps | Metro style apps
Implemented by media sink objects. This interface is the base interface for all Media Foundation media sinks. Stream sinks handle the actual processing of data on each stream.
\t\nApplies to: desktop apps | Metro style apps
Gets the characteristics of the media sink.
\t\nReceives a bitwise OR of zero or more flags. The following flags are defined:
| Value | Meaning |
|---|---|
| The media sink has a fixed number of streams. It does not support the |
| The media sink cannot match rates with an external clock. For best results, this media sink should be used as the time source for the presentation clock. If any other time source is used, the media sink cannot match rates with the clock, with poor results (for example, glitching). This flag should be used sparingly, because it limits how the pipeline can be configured. For more information about the presentation clock, see Presentation Clock. |
| The media sink is rateless. It consumes samples as quickly as possible, and does not synchronize itself to a presentation clock. Most archiving sinks are rateless. |
| The media sink requires a presentation clock. The presentation clock is set by calling the media sink's This flag is obsolete, because all media sinks must support the SetPresentationClock method, even if the media sink ignores the clock (as in a rateless media sink). |
| The media sink can accept preroll samples before the presentation clock starts. The media sink exposes the |
| The first stream sink (index 0) is a reference stream. The reference stream must have a media type before the media types can be set on the other stream sinks. |
?
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink's Shutdown method has been called. |
?
The characteristics of a media sink are fixed throughout the life time of the sink.
\t\nApplies to: desktop apps | Metro style apps
Adds a new stream sink to the media sink.
\t\nIdentifier for the new stream. The value is arbitrary but must be unique.
Pointer to the
Receives a reference to the new stream sink's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The specified stream identifier is not valid. |
| | The media sink's Shutdown method has been called. |
| | There is already a stream sink with the same stream identifier. |
| | This media sink has a fixed set of stream sinks. New stream sinks cannot be added. |
?
Not all media sinks support this method. If the media sink does not support this method, the
If pMediaType is
Applies to: desktop apps | Metro style apps
Removes a stream sink from the media sink.
\t\nIdentifier of the stream to remove. The stream identifier is defined when you call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| This particular stream sink cannot be removed. |
| | The stream number is not valid. |
| | The media sink has not been initialized. |
| | The media sink's Shutdown method has been called. |
| | This media sink has a fixed set of stream sinks. Stream sinks cannot be removed. |
?
After this method is called, the corresponding stream sink object is no longer valid. The
Not all media sinks support this method. If the media sink does not support this method, the
In some cases, the media sink supports this method but does not allow every stream sink to be removed. (For example, it might not allow stream 0 to be removed.)
\t\nApplies to: desktop apps | Metro style apps
Gets the number of stream sinks on this media sink.
\t\nReceives the number of stream sinks.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink's Shutdown method has been called. |
?
Applies to: desktop apps | Metro style apps
Gets a stream sink, specified by index.
\t\nZero-based index of the stream. To get the number of streams, call
Receives a reference to the stream's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid index. |
| | The media sink's Shutdown method has been called. |
?
Enumerating stream sinks is not a thread-safe operation, because stream sinks can be added or removed between calls to this method.
\t\nApplies to: desktop apps | Metro style apps
Gets a stream sink, specified by stream identifier.
\t\nStream identifier of the stream sink.
Receives a reference to the stream's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The stream identifier is not valid. |
| | The media sink's Shutdown method has been called. |
?
If you add a stream sink by calling the
To enumerate the streams by index number instead of stream identifier, call
Applies to: desktop apps | Metro style apps
Sets the presentation clock on the media sink.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The presentation clock does not have a time source. Call SetTimeSource on the presentation clock. |
| | The media sink's Shutdown method has been called. |
?
During streaming, the media sink attempts to match rates with the presentation clock. Ideally, the media sink presents samples at the correct time according to the presentation clock and does not fall behind. Rateless media sinks are an exception to this rule, as they consume samples as quickly as possible and ignore the clock. If the sink is rateless, the
The presentation clock must have a time source. Before calling this method, call
If pPresentationClock is non-
All media sinks must support this method.
\t\nApplies to: desktop apps | Metro style apps
Gets the presentation clock that was set on the media sink.
\t\nReceives a reference to the presentation clock's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No clock has been set. To set the presentation clock, call |
| | The media sink's Shutdown method has been called. |
?
Applies to: desktop apps | Metro style apps
Shuts down the media sink and releases the resources it is using.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink was shut down. |
?
If the application creates the media sink, it is responsible for calling Shutdown to avoid memory or resource leaks. In most applications, however, the application creates an activation object for the media sink, and the Media Session uses that object to create the media sink. In that case, the Media Session ? not the application ? shuts down the media sink. (For more information, see Activation Objects.)
After this method returns, all methods on the media sink return
Applies to: desktop apps | Metro style apps
Gets the characteristics of the media sink.
\t\nThe characteristics of a media sink are fixed throughout the life time of the sink.
\t\nApplies to: desktop apps | Metro style apps
Gets the number of stream sinks on this media sink.
\t\nApplies to: desktop apps | Metro style apps
Gets the presentation clock that was set on the media sink.
\t\nApplies to: desktop apps only
Notifies the media sink to asynchronously take any steps it needs to finish its tasks.
\t\nPointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Many archive media sinks have steps they need to do at the end of archiving to complete their file operations, such as updating the header (for some formats) or flushing all pending writes to disk. In some cases, this may include expensive operations such as indexing the content. BeginFinalize is an asynchronous way to initiate final tasks.
When the finalize operation is complete, the callback object's
Applies to: desktop apps only
Completes an asynchronous finalize operation.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this method after the
Applies to: desktop apps only
The
To enumerate registered DMOs, call the DMOEnum function.
\t\nApplies to: desktop apps only
This method is not implemented.
\t\nReserved.
Returns E_NOTIMPL.
In the default DMO streaming model, buffers are managed through the
In-place processing does not require the
// CMediaBuffer class.\t\n #include <dmo.h>\t\n class CMediaBuffer : public \t\n {\t\n private: DWORD m_cbLength; const DWORD m_cbMaxLength; LONG m_nRefCount; // Reference count BYTE *m_pbData; CMediaBuffer(DWORD cbMaxLength, & hr) : m_nRefCount(1), m_cbMaxLength(cbMaxLength), m_cbLength(0), m_pbData(null ) { m_pbData = new BYTE[cbMaxLength]; if (!m_pbData) { hr = E_OUTOFMEMORY; } } ~CMediaBuffer() { if (m_pbData) { delete [] m_pbData; } } public: // Function to create a new object and return // an AddRef'd interface reference. static Create(long cbMaxLen, **ppBuffer) { hr = ; CMediaBuffer *pBuffer = null ; if (ppBuffer == null ) { return E_POINTER; } pBuffer = new CMediaBuffer(cbMaxLen, hr); if (pBuffer == null ) { hr = E_OUTOFMEMORY; } if (SUCCEEDED(hr)) { *ppBuffer = pBuffer; (*ppBuffer)->AddRef(); } if (pBuffer) { pBuffer->Release(); } return hr; } // methods. STDMETHODIMP QueryInterface(REFIID riid, void **ppv) { if (ppv == null ) { return E_POINTER; } else if (riid == IID_IMediaBuffer || riid == IID_IUnknown) { *ppv = static_cast< *>(this); AddRef(); return ; } else { *ppv = null ; return E_NOINTERFACE; } } STDMETHODIMP_(ULONG) AddRef() { return InterlockedIncrement(&m_nRefCount); } STDMETHODIMP_(ULONG) Release() { LONG lRef = InterlockedDecrement(&m_nRefCount); if (lRef == 0) { delete this; // m_cRef is no longer valid! Return lRef. } return lRef; } // methods. STDMETHODIMP SetLength(DWORD cbLength) { if (cbLength > m_cbMaxLength) { return E_INVALIDARG; } m_cbLength = cbLength; return ; } STDMETHODIMP GetMaxLength(DWORD *pcbMaxLength) { if (pcbMaxLength == null ) { return E_POINTER; } *pcbMaxLength = m_cbMaxLength; return ; } STDMETHODIMP GetBufferAndLength(BYTE **ppbBuffer, DWORD *pcbLength) { // Either parameter can be null , but not both. if (ppbBuffer == null && pcbLength == null ) { return E_POINTER; } if (ppbBuffer) { *ppbBuffer = m_pbData; } if (pcbLength) { *pcbLength = m_cbLength; } return ; }\t\n }; Applies to: desktop apps only
The GetBufferAndLength method retrieves the buffer and the size of the valid data in the buffer.
Address of a reference that receives the buffer array. Can be
Pointer to a variable that receives the size of the valid data, in bytes. Can be
Returns an
| Return code | Description |
|---|---|
| |
| | Success |
?
Either parameter can be
The value returned in the pcbLength parameter is the size of the valid data in the buffer, not the buffer's allocated size. To obtain the buffer's allocated size, call the
Applies to: desktop apps only
The
Applies to: desktop apps only
The GetInputStreamInfo method retrieves information about an input stream, such as any restrictions on the number of samples per buffer, and whether the stream performs lookahead on the input data. This information never changes.
Zero-based index of an input stream on the DMO.
Pointer to a variable that receives a bitwise combination of zero or more DMO_INPUT_STREAM_INFO_FLAGS flags.
Returns an
| Return code | Description |
|---|---|
| Invalid stream index |
| |
| | Success |
?
The
The application must be sure to allocate sufficient buffers for the DMO to process the input. Call the
Applies to: desktop apps only
The GetInputType method retrieves a preferred media type for a specified input stream.
Zero-based index of an input stream on the DMO.
Zero-based index on the set of acceptable media types.
Pointer to a
Returns an
| Return code | Description |
|---|---|
| Invalid stream index. |
| Type index is out of range. |
| Insufficient memory. |
| |
| | Success. |
?
Call this method to enumerate an input stream's preferred media types. The DMO assigns each media type an index value in order of preference. The most preferred type has an index of zero. To enumerate all the types, make successive calls while incrementing the type index until the method returns DMO_E_NO_MORE_ITEMS. The DMO is not guaranteed to enumerate every media type that it supports.
The format block in the returned type might be
If the method succeeds, call MoFreeMediaType to free the format block. (This function is also safe to call when the format block is
To set the media type, call the
To test whether a particular media type is acceptable, call SetInputType with the
To test whether the dwTypeIndex parameter is in range, set pmt to
Applies to: desktop apps only
The SetOutputType method sets the media type on an output stream, or tests whether a media type is acceptable.
Zero-based index of an output stream on the DMO.
Pointer to a
Bitwise combination of zero or more flags from the DMO_SET_TYPE_FLAGS enumeration.
Returns an
| Return code | Description |
|---|---|
| Invalid stream index |
| Media type was not accepted |
| Media type is not acceptable |
| | Media type was set successfully, or is acceptable |
?
Call this method to test, set, or clear the media type on an output stream:
The media types that are currently set on other streams can affect whether the media type is acceptable.
\t\nApplies to: desktop apps only
The GetInputMaxLatency method retrieves the maximum latency on a specified input stream.
Zero-based index of an input stream on the DMO.
Pointer to a variable that receives the maximum latency.
Returns an
| Return code | Description |
|---|---|
| Invalid stream index. |
| Failure. |
| Not implemented. Assume zero latency. |
| | Success. |
?
The latency is the difference between a time stamp on the input stream and the corresponding time stamp on the output stream. The maximum latency is the largest possible difference in the time stamps. For a DMO, determine the maximum latency as follows:
Under this definition, latency does not include the time that it takes to process samples. Nor does it include any latency introduced by the size of the input buffer.
For the special case where a DMO processes exactly one sample at a time, the maximum latency is simply the difference in time stamps.
Latency is defined only when samples have time stamps, and the time stamps increase or decrease monotonically. Maximum latency might depend on the media types for the input and output streams.
\t\nApplies to: desktop apps only
The FreeStreamingResources method frees resources allocated by the DMO. Calling this method is always optional.
Returns
This method releases any resources that the
If the DMO does not support this method, the method returns
Regardless of whether the method fails or succeeds, the application can continue to call other methods on the DMO. The DMO might need to re-initialize resources that were previously freed.
\t\nApplies to: desktop apps only
The GetInputStatus method queries whether an input stream can accept more input data.
Zero-based index of an input stream on the DMO.
Pointer to a variable that receives either zero or
Returns an
| Return code | Description |
|---|---|
| Invalid stream index |
| | Success |
?
If the input stream will accept more data, the method returns the
The status of an input stream can change only as the result of one of the following method calls.
| Method | Description |
|---|---|
| | Signals a discontinuity on the specified input stream. |
| | Flushes all internally buffered data. |
| | Delivers a buffer to the specified input stream. |
| | Generates output from the current input data. |
?
\t\nApplies to: desktop apps only
The ProcessInput method delivers a buffer to the specified input stream.
Zero-based index of an input stream on the DMO.
Pointer to the buffer's
Bitwise combination of zero or more flags from the DMO_INPUT_DATA_BUFFER_FLAGS enumeration.
Time stamp that specifies the start time of the data in the buffer. If the buffer has a valid time stamp, set the
Reference time specifying the duration of the data in the buffer. If this value is valid, set the
Returns an
| Return code | Description |
|---|---|
| Invalid stream index. |
| Data cannot be accepted. |
| No output to process. |
| | Success. |
?
The input buffer specified in the pBuffer parameter is read-only. The DMO will not modify the data in this buffer. All write operations occur on the output buffers, which are given in a separate call to the
If the DMO does not process all the data in the buffer, it keeps a reference count on the buffer. It releases the buffer once it has generated all the output, unless it needs to perform lookahead on the data. (To determine whether a DMO performs lookahead, call the
If this method returns DMO_E_NOTACCEPTING, call ProcessOutput until the input stream can accept more data. To determine whether the stream can accept more data, call the
If the method returns S_FALSE, no output was generated from this input and the application does not need to call ProcessOutput. However, a DMO is not required to return S_FALSE in this situation; it might return
Applies to: desktop apps only
The ProcessOutput method generates output from the current input data.
Bitwise combination of zero or more flags from the DMO_PROCESS_OUTPUT_FLAGS enumeration.
Number of output buffers.
Pointer to an array of
Pointer to a variable that receives a reserved value (zero). The application should ignore this value.
Returns an
| Return code | Description |
|---|---|
| Failure |
| Invalid argument |
| |
| No output was generated |
| | Success |
?
The pOutputBuffers parameter points to an array of
Each
When the application calls ProcessOutput, the DMO processes as much input data as possible. It writes the output data to the output buffers, starting from the end of the data in each buffer. (To find the end of the data, call the
If the DMO fills an entire output buffer and still has input data to process, the DMO returns the
If the method returns S_FALSE, no output was generated. However, a DMO is not required to return S_FALSE in this situation; it might return
Discarding data:
You can discard data from a stream by setting the
For each stream in which pBuffer is
To check whether a stream is discardable or optional, call the
Applies to: desktop apps | Metro style apps
Requests permission to perform a specified action on the stream.
\t\nThis method verifies whether the user has permission to perform a specified action on the stream. The ITA does any work needed to verify the user's right to perform the action, such as checking licenses.
To verify the user's rights, the ITA might need to perform additional steps that require interaction with the user or consent from the user. For example, it might need to acquire a new license or individualize a DRM component. In that case, the ITA creates an activation object for a content enabler and returns the activation object's
The Media Session returns the
The application calls
The application calls
The Media Session calls RequestAccess again.
The return value signals whether the user has permission to perform the action:
If the user already has permission to perform the action, the method returns
If the user does not have permission, the method returns a failure code and sets *ppContentEnablerActivate to
If the ITA must perform additional steps that require interaction with the user, the method returns a failure code and returns the content enabler's
The Media Session will not allow the action unless this method returns
A stream can go to multiple outputs, so this method might be called multiple times with different actions, once for every output.
\t\nApplies to: desktop apps | Metro style apps
Retrieves a decrypter transform.
\t\nInterface identifier (IID) of the interface being requested. Currently this value must be IID_IMFTransform, which requests the
Receives a reference to the interface. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The decrypter does not support the requested interface. |
| | This input trust authority (ITA) does not provide a decrypter. |
?
The decrypter should be created in a disabled state, where any calls to
An ITA is not required to provide a decrypter. If the source content is not encrypted, the method should return
The ITA must create a new instance of its decrypter for each call to GetDecrypter. Do not return multiple references to the same decrypter. They must be separate instances because the Media Session might place them in two different branches of the topology.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the policy that defines which output protection systems are allowed for this stream, and the configuration data for each protection system.
\t\nThe action that will be performed on this stream, specified as a member of the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Notifies the input trust authority (ITA) that a requested action is about to be performed.
\t\nPointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Before calling this method, the Media Session calls
Applies to: desktop apps | Metro style apps
Notifies the input trust authority (ITA) when the number of output trust authorities (OTAs) that will perform a specified action has changed.
\t\nPointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The ITA can update its internal state if needed. If the method returns a failure code, the Media Session cancels the action.
\t\nApplies to: desktop apps | Metro style apps
Resets the input trust authority (ITA) to its initial state.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
When this method is called, the ITA should disable any decrypter that was returned in the
Applies to: desktop apps only
Registers one or more Media Foundation transforms (MFTs) in the caller's process.
\t\nThis method is similar to the
Unlike
Applies to: desktop apps only
Registers one or more Media Foundation transforms (MFTs) in the caller's process.
\t\nA reference to an array of
The number of elements in the pMFTs array.
If this method succeeds, it returns
This method is similar to the
Unlike
Applies to: desktop apps | Metro style apps
Represents a block of memory that contains media data. Use this interface to access the data in the buffer.
\t\nIf the buffer contains 2-D image data (such as an uncompressed video frame), you should query the buffer for the
To get a buffer from a media sample, call one of the following
To create a new buffer object, use one of the following functions.
| Function | Description |
|---|---|
| | Creates a buffer and allocates system memory. |
| | Creates a media buffer that wraps an existing media buffer. |
| | Creates a buffer that manages a DirectX surface. |
| | Creates a buffer and allocates system memory with a specified alignment. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gives the caller access to the memory in the buffer, for reading or writing
\t\nReceives the maximum amount of data that can be written to the buffer. This parameter can be
Receives the length of the valid data in the buffer, in bytes. This parameter can be
Receives a reference to the start of the buffer.
This method gives the caller access to the entire buffer, up to the maximum size returned in the pcbMaxLength parameter. The value returned in pcbCurrentLength is the size of any valid data already in the buffer, which might be less than the total buffer size.
The reference returned in ppbBuffer is guaranteed to be valid, and can safely be accessed across the entire buffer for as long as the lock is held. When you are done accessing the buffer, call
Locking the buffer does not prevent other threads from calling Lock, so you should not rely on this method to synchronize threads.
This method does not allocate any memory, or transfer ownership of the memory to the caller. Do not release or free the memory; the media buffer will free the memory when the media buffer is destroyed.
If you modify the contents of the buffer, update the current length by calling
If the buffer supports the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Unlocks a buffer that was previously locked. Call this method once for every call to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | For Direct3D surface buffers, an error occurred when unlocking the surface. |
?
It is an error to call Unlock if you did not call Lock previously.
After calling this method, do not use the reference returned by the Lock method. It is no longer guaranteed to be valid.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the valid data in the buffer.
\t\nReceives the length of the valid data, in bytes. If the buffer does not contain any valid data, the value is zero.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the length of the valid data in the buffer.
\t\nLength of the valid data, in bytes. This value cannot be greater than the allocated size of the buffer, which is returned by the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The specified length is greater than the maximum size of the buffer. |
?
Call this method if you write data into the buffer.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the allocated size of the buffer.
\t\nReceives the allocated size of the buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The buffer might or might not contain any valid data, and if there is valid data in the buffer, it might be smaller than the buffer's allocated size. To get the length of the valid data, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the valid data in the buffer.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the allocated size of the buffer.
\t\nThe buffer might or might not contain any valid data, and if there is valid data in the buffer, it might be smaller than the buffer's allocated size. To get the length of the valid data, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the event type. The event type indicates what happened to trigger the event. It also defines the meaning of the event value.
\t\nReceives the event type. For a list of event types, see Media Foundation Events.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the extended type of the event.
\t\nReceives a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To define a custom event, create a new extended-type
Some standard Media Foundation events also use the extended type to differentiate between types of event data.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an
Receives the event status. If the operation that generated the event was successful, the value is a success code. A failure code means that an error condition triggered the event.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents an event generated by a Media Foundation object. Use this interface to get information about the event.
To get a reference to this interface, call
If you are implementing an object that generates events, call the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the event type. The event type indicates what happened to trigger the event. It also defines the meaning of the event value.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the extended type of the event.
\t\nTo define a custom event, create a new extended-type
Some standard Media Foundation events also use the extended type to differentiate between types of event data.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents an event generated by a Media Foundation object. Use this interface to get information about the event.
To get a reference to this interface, call
If you are implementing an object that generates events, call the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves events from any Media Foundation object that generates events.
\t\nAn object that supports this interface maintains a queue of events. The client of the object can retrieve the events either synchronously or asynchronously. The synchronous method is GetEvent. The asynchronous methods are BeginGetEvent and EndGetEvent.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the next event in the queue. This method is synchronous.
\t\nSpecifies one of the following values.
| Value | Meaning |
|---|---|
| The method blocks until the event generator queues an event. |
| The method returns immediately. |
?
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
| | There is a pending request. |
| | There are no events in the queue. |
| | The object was shut down. |
?
This method executes synchronously.
If the queue already contains an event, the method returns
If dwFlags is 0, the method blocks indefinitely until a new event is queued, or until the event generator is shut down.
If dwFlags is MF_EVENT_FLAG_NO_WAIT, the method fails immediately with the return code
This method returns
Applies to: desktop apps | Metro style apps
Begins an asynchronous request for the next event in the queue.
\t\nPointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
| | There is a pending request with the same callback reference and a different state object. |
| | There is a pending request with a different callback reference. |
| | The object was shut down. |
| There is a pending request with the same callback reference and state object. |
?
When a new event is available, the event generator calls the
Do not call BeginGetEvent a second time before calling EndGetEvent. While the first call is still pending, additional calls to the same object will fail. Also, the
Applies to: desktop apps | Metro style apps
Completes an asynchronous request for the next event in the queue.
\t\nPointer to the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object was shut down. |
?
Call this method from inside your application's
Applies to: desktop apps | Metro style apps
Puts a new event in the object's queue.
\t\nSpecifies the event type. The event type is returned by the event's
The extended type. If the event does not have an extended type, use the value GUID_NULL. The extended type is returned by the event's
A success or failure code indicating the status of the event. This value is returned by the event's
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object was shut down. |
?
Applies to: desktop apps | Metro style apps
Provides an event queue for applications that need to implement the
This interface is exposed by a helper object that implements an event queue. If you are writing a component that implements the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the next event in the queue. This method is synchronous.
Call this method inside your implementation of
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous request for the next event in the queue.
Call this method inside your implementation of
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous request for the next event in the queue.
Call this method inside your implementation of
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Puts an event in the queue.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Shutdown method was called. |
?
Call this method when your component needs to raise an event that contains attributes. To create the event object, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an event, sets a
Call this method inside your implementation of
You can also call this method when your component needs to raise an event that does not contain attributes. If the event data is an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an event, sets an
Specifies the event type of the event to be added to the queue. The event type is returned by the event's
The extended type of the event. If the event does not have an extended type, use the value GUID_NULL. The extended type is returned by the event's
A success or failure code indicating the status of the event. This value is returned by the event's
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Shutdown method was called. |
?
Call this method when your component needs to raise an event that contains an
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Shuts down the event queue.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this method when your component shuts down. After this method is called, all
This method removes all of the events from the queue.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Provides playback controls for protected and unprotected content. The Media Session and the protected media path (PMP) session objects expose this interface. This interface is the primary interface that applications use to control the Media Foundation pipeline.
To obtain a reference to this interface, call
Applies to: desktop apps only
Sets a topology on the Media Session.
\t\n Bitwise OR of zero or more flags from the
Pointer to the topology object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The operation cannot be performed in the Media Session's current state. |
| | The Media Session has been shut down. |
| | The topology has invalid values for one or more of the following attributes: |
| Protected content cannot be played while debugging. |
?
If pTopology is a full topology, set the
If the Media Session is currently paused or stopped, the SetTopology method does not take effect until the next call to
If the Media Session is currently running, or on the next call to Start, the SetTopology method does the following:
This method is asynchronous. If the method returns
Applies to: desktop apps only
Clears all of the presentations that are queued for playback in the Media Session.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The operation cannot be performed in the Media Session's current state. |
| | The Media Session has been shut down. |
?
This method is asynchronous. When the operation completes, the Media Session sends an
This method does not clear the current topology; it only removes topologies that are placed in the queue, waiting for playback. To remove the current topology, call
Applies to: desktop apps only
Starts the Media Session.
\t\nPointer to a
The following time format GUIDs are defined:
| Value | Meaning |
|---|---|
| Presentation time. The pvarStartPosition parameter must have one of the following
All media sources support this time format. |
| Segment offset. This time format is supported by the Sequencer Source. The starting time is an offset within a segment. Call the |
| Note??Requires Windows?7 or later. Skip to a playlist entry. The pvarStartPosition parameter specifies the index of the playlist entry, relative to the current entry. For example, the value 2 skips forward two entries. To skip backward, pass a negative value. The If a media source supports this time format, the |
?
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The operation cannot be performed in the Media Session's current state. |
| | The Media Session has been shut down. |
?
When this method is called, the Media Session starts the presentation clock and begins to process media samples.
This method is asynchronous. When the method completes, the Media Session sends an
Applies to: desktop apps only
Provides playback controls for protected and unprotected content. The Media Session and the protected media path (PMP) session objects expose this interface. This interface is the primary interface that applications use to control the Media Foundation pipeline.
To obtain a reference to this interface, call
Applies to: desktop apps only
Provides playback controls for protected and unprotected content. The Media Session and the protected media path (PMP) session objects expose this interface. This interface is the primary interface that applications use to control the Media Foundation pipeline.
To obtain a reference to this interface, call
Applies to: desktop apps only
Closes the Media Session and releases all of the resources it is using.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The Media Session has been shut down. |
?
This method is asynchronous. When the operation completes, the Media Session sends an
After the Close method is called, the only valid methods on the Media Session are the following:
All other methods return
Applies to: desktop apps only
Shuts down the Media Session and releases all the resources used by the Media Session.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this method when you are done using the Media Session, before the final call to IUnknown::Release. Otherwise, your application will leak memory.
After this method is called, other
Applies to: desktop apps only
Retrieves the Media Session's presentation clock.
\t\nReceives a reference to the presentation clock's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Media Session does not have a presentation clock. |
| | The Media Session has been shut down. |
?
The application can query the returned
Applies to: desktop apps only
Retrieves the capabilities of the Media Session, based on the current presentation.
\t\nReceives a bitwise OR of zero or more of the following flags.
| Value | Meaning |
|---|---|
| The Media Session can be paused. |
| The Media Session supports forward playback at rates faster than 1.0. |
| The Media Session supports reverse playback. |
| The Media Session can be seeked. |
| The Media Session can be started. |
?
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
| | The Media Session has been shut down. |
?
Retrieves a pending or current topology from the media session.
dwGetFullTopologyFlags
[in] Bitwise OR of zero or more flags from the
TopoId
[in] Identifier of the topology to retrieve. This parameter is ignored if the
ppFullTopo
[out] Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media session has been shut down. |
If the
This method can be used to retrieve the topology for the current presentation or any pending presentations. It cannot be used to retrieve a topology that has already ended.
The topology returned in ppFullTopo is a full topology, not a partial topology.
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFMediaSession Interface\t\nApplies to: desktop apps only
Retrieves the Media Session's presentation clock.
\t\nThe application can query the returned
Applies to: desktop apps only
Retrieves the capabilities of the Media Session, based on the current presentation.
\t\nApplies to: desktop apps | Metro style apps
Enables a media sink to receive samples before the presentation clock is started.
To get a reference to this interface, call QueryInterface on the media sink.
\t\nMedia sinks can implement this interface to support seamless playback and transitions. If a media sink exposes this interface, it can receive samples before the presentation clock starts. It can then pre-process the samples, so that rendering can begin immediately when the clock starts. Prerolling helps to avoid glitches during playback.
If a media sink supports preroll, the media sink's
Applies to: desktop apps | Metro style apps
Notifies the media sink that the presentation clock is about to start.
\t\n The upcoming start time for the presentation clock, in 100-nanosecond units. This time is the same value that will be given to the
If this method succeeds, it returns
After this method is called, the media sink sends any number of
During preroll, the media sink can prepare the samples that it receives, so that they are ready to be rendered. It does not actually render any samples until the clock starts.
\t\nApplies to: desktop apps | Metro style apps
Implemented by media source objects.
Media sources are objects that generate media data. For example, the data might come from a video file, a network stream, or a hardware device, such as a camera. Each media source contains one or more streams, and each stream delivers data of one type, such as audio or video.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the characteristics of the media source.
\t\nReceives a bitwise OR of zero or more flags from the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media source's Shutdown method has been called. |
?
The characteristics of a media source can change at any time. If this happens, the source sends an
Applies to: desktop apps | Metro style apps
Retrieves a copy of the media source's presentation descriptor. Applications use the presentation descriptor to select streams and to get information about the source content.
\t\nReceives a reference to the presentation descriptor's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media source's Shutdown method has been called. |
?
The presentation descriptor contains the media source's default settings for the presentation. The application can change these settings by selecting or deselecting streams, or by changing the media type on a stream. Do not modify the presentation descriptor unless the source is stopped. The changes take affect when the source's
Applies to: desktop apps | Metro style apps
Starts, seeks, or restarts the media source by specifying where to start playback.
\t\n Pointer to the
Pointer to a
Specifies where to start playback. The units of this parameter are indicated by the time format given in pguidTimeFormat. If the time format is GUID_NULL, the variant type must be VT_I8 or VT_EMPTY. Use VT_I8 to specify a new starting position, in 100-nanosecond units. Use VT_EMPTY to start from the current position. Other time formats might use other
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The start position is past the end of the presentation (ASF media source). |
| | A hardware device was unable to start streaming. This error code can be returned by a media source that represents a hardware device, such as a camera. For example, if the camera is already being used by another application, the method might return this error code. |
| | The start request is not valid. For example, the start position is past the end of the presentation. |
| | The media source's Shutdown method has been called. |
| | The media source does not support the time format specified in pguidTimeFormat. |
?
This method is asynchronous. If the operation succeeds, the media source sends the following events:
If the start operation fails asynchronously (after the method returns
A call to Start results in a seek if the previous state was started or paused, and the new starting position is not VT_EMPTY. Not every media source can seek. If a media source can seek, the
Events from the media source are not synchronized with events from the media streams. If you seek a media source, therefore, you can still receive samples from the earlier position after getting the
When a stream plays to the end, the stream sends an
If the starting position is past the end of a selected stream (but before the end of the presentation), the stream should send
During reverse playback, the start of the file is considered the end of the stream. For more information, see Implementing Rate Control.
Implementing StartWhen a media source executes a seek, it should start at the first key frame before the seek time, so that the decoder can decode the samples for the target start time. The pipeline will discard any decoded samples that are too early.
If the start time is VT_EMPTY and the previous state was started or paused, the source should resume from its current position. In this case, it is not necessary to resend the previous key frame, because the decoder will still have the data that was previously sent.
When validating the pPresentationDescriptor parameter, the media source should check only for the information that it needs to function correctly. In particular, the client can add private attributes to the presentation descriptor. The presence of additional attributes should not cause the Start method to fail.
After Start is called, each stream on the media source must do one of the following:
For more information, see Writing a Custom Media Source.
\t\nApplies to: desktop apps | Metro style apps
Stops all active streams in the media source.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media source's Shutdown method has been called. |
?
This method is asynchronous. When the operation completes, the media source sends and
When a media source is stopped, its current position reverts to zero. After that, if the Start method is called with VT_EMPTY for the starting position, playback starts from the beginning of the presentation.
While the source is stopped, no streams produce data.
\t\nApplies to: desktop apps | Metro style apps
Pauses all active streams in the media source.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid state transition. The media source must be in the started state. |
| | The media source's Shutdown method has been called. |
?
This method is asynchronous. When the operation completes, the media source sends and
The media source must be in the started state. The method fails if the media source is paused or stopped.
While the source is paused, calls to
Not every media source can pause. If a media source can pause, the
Applies to: desktop apps | Metro style apps
Shuts down the media source and releases the resources it is using.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the application creates the media source, either directly or through the source resolver, the application is responsible for calling Shutdown to avoid memory or resource leaks.
After this method is called, methods on the media source and all of its media streams return
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the media source.
\t\nThe characteristics of a media source can change at any time. If this happens, the source sends an
Applies to: desktop apps only
Notifies the source when playback has reached the end of a segment. For timelines, this corresponds to reaching a mark-out point.
\t\nApplies to: desktop apps only
Notifies the source when playback has reached the end of a segment. For timelines, this corresponds to reaching a mark-out point.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Enables an application to get a topology from the sequencer source. This interface is exposed by the sequencer source object.
\t\nApplies to: desktop apps only
Returns a topology for a media source that builds an internal topology.
\t\nA reference to the
Receives a reference to the topology's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. For example, a |
?
Applies to: desktop apps | Metro style apps
Represents one stream in a media source.
\t\nStreams are created when a media source is started. For each stream, the media source sends an
Applies to: desktop apps | Metro style apps
Retrieves a reference to the media source that created this media stream.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media source's Shutdown method has been called. |
?
Applies to: desktop apps | Metro style apps
Retrieves a stream descriptor for this media stream.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media source's Shutdown method has been called. |
?
Do not modify the stream descriptor. To change the presentation, call
Applies to: desktop apps | Metro style apps
Requests a sample from the media source.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The end of the stream was reached. |
| | The media source is stopped. |
| | The source's Shutdown method has been called. |
?
If pToken is not
When the next sample is available, the media stream stream does the following:
If the media stream cannot fulfill the caller's request for a sample, it simply releases the token object and skips steps 2 and 3.
The caller should monitor the reference count on the request token. If the media stream sends an
Because the Media Foundation pipeline is multithreaded, the source's RequestSample method might get called after the source has stopped. If the media source is stopped, the method should return
Note??Earlier versions of the documentation listed the wrong error code for this case.
If the media source is paused, the method succeeds, but the stream does not deliver the sample until the source is started again.
If a media source enounters an error asynchronously while processing data, it should signal the error in one of the following ways (but not both):
Applies to: desktop apps | Metro style apps
Retrieves a reference to the media source that created this media stream.
\t\nApplies to: desktop apps | Metro style apps
Retrieves a stream descriptor for this media stream.
\t\nDo not modify the stream descriptor. To change the presentation, call
Applies to: desktop apps | Metro style apps
Retrieves a media type from the object's list of supported media types.
\t\nMedia types are returned in the approximate order of preference. The list of supported types is not guaranteed to be complete. To test whether a particular media type is supported, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Queries whether the object supports a specified media type.
pMediaType
[in] Pointer to the
ppMediaType
[out] Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object does not support this media type. |
If the object supports the media type given in pMediaType, the method returns
The ppMediaType parameter is optional. If the method fails, the object might use ppMediaType to return a media type that the object does support, and which closely matches the one given in pMediaType. The method is not guaranteed to return a media type in ppMediaType. If no type is returned, this parameter receives a
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFMediaTypeHandler Interface\t\nApplies to: desktop apps | Metro style apps
Retrieves the number of media types in the object's list of supported media types.
\t\nReceives the number of media types in the list.
If this method succeeds, it returns
To get the supported media types, call
For a media source, the media type handler for each stream must contain at least one supported media type. For media sinks, the media type handler for each stream might contain zero media types. In that case, the application must provide the medai type. To test whether a particular media type is supported, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a media type from the object's list of supported media types.
\t\n Zero-based index of the media type to retrieve. To get the number of media types in the list, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The dwIndex parameter is out of range. |
?
Media types are returned in the approximate order of preference. The list of supported types is not guaranteed to be complete. To test whether a particular media type is supported, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the object's media type.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid request. |
?
For media sources, setting the media type means the source will generate data that conforms to that media type. For media sinks, setting the media type means the sink can receive data that conforms to that media type.
Any implementation of this method should check whether pMediaType differs from the object's current media type. If the types are identical, the method should return
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current media type of the object.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No media type is set. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets the major media type of the object.
\t\nReceives a
If this method succeeds, it returns
The major type identifies what kind of data is in the stream, such as audio or video. To get the specific details of the format, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of media types in the object's list of supported media types.
\t\n To get the supported media types, call
For a media source, the media type handler for each stream must contain at least one supported media type. For media sinks, the media type handler for each stream might contain zero media types. In that case, the application must provide the medai type. To test whether a particular media type is supported, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current media type of the object.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets the major media type of the object.
\t\nThe major type identifies what kind of data is in the stream, such as audio or video. To get the specific details of the format, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets a list of the languages in which metadata is available.
\t\nFor more information about language tags, see RFC 1766, \"Tags for the Identification of Languages\".
To set the current language, call
Applies to: desktop apps | Metro style apps
Sets the language for setting and retrieving metadata.
\t\nPointer to a null-terminated string containing an RFC 1766-compliant language tag.
If this method succeeds, it returns
For more information about language tags, see RFC 1766, \"Tags for the Identification of Languages\".
\t\nApplies to: desktop apps | Metro style apps
Gets the current language setting.
\t\nReceives a reference to a null-terminated string containing an RFC 1766-compliant language tag. The caller must release the string by calling CoTaskMemFree.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The metadata provider does not support multiple languages. |
| | No language was set. |
?
For more information about language tags, see RFC 1766, \"Tags for the Identification of Languages.\"
The
Applies to: desktop apps | Metro style apps
Gets a list of the languages in which metadata is available.
\t\n A reference to a
The returned
If this method succeeds, it returns
For more information about language tags, see RFC 1766, \"Tags for the Identification of Languages\".
To set the current language, call
Applies to: desktop apps | Metro style apps
Sets the value of a metadata property.
\t\nPointer to a null-terminated string containing the name of the property.
Pointer to a
If this method succeeds, it returns
Applies to: desktop apps | Metro style apps
Gets the value of a metadata property.
\t\n A reference to a null-terminated string that containings the name of the property. To get the list of property names, call
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The requested property was not found. |
?
Applies to: desktop apps | Metro style apps
Deletes a metadata property.
\t\nPointer to a null-terminated string containing the name of the property.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The property was not found. |
?
For a media source, deleting a property from the metadata collection does not change the original content.
\t\nApplies to: desktop apps | Metro style apps
Gets a list of all the metadata property names on this object.
\t\nPointer to a
If this method succeeds, it returns
Applies to: desktop apps | Metro style apps
Gets a list of the languages in which metadata is available.
\t\nFor more information about language tags, see RFC 1766, \"Tags for the Identification of Languages\".
To set the current language, call
Applies to: desktop apps | Metro style apps
Gets a list of all the metadata property names on this object.
\t\nApplies to: desktop apps | Metro style apps
Gets metadata from a media source or other object.
If a media source supports this interface, it must expose the interface as a service. To get a reference to this interface from a media source, call
Use this interface to get a reference to the
Applies to: desktop apps | Metro style apps
Gets a collection of metadata, either for an entire presentation, or for one stream in the presentation.
\t\n Pointer to the
If this parameter is zero, the method retrieves metadata that applies to the entire presentation. Otherwise, this parameter specifies a stream identifier, and the method retrieves metadata for that stream. To get the stream identifier for a stream, call
Reserved. Must be zero.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No metadata is available for the requested stream or presentation. |
?
This topic describes how to implement the
It is rare that you will need to write a custom implementation of the
First, your implementation must inherit the
Second, your object should call
The following code shows a basic implementation of the
///////////////////////////////////////////////////////////////////////////////\t\n // CMyAsyncResult\t\n //\t\n // Custom implementation of\t\n. All implementations of this \t\n // interface must inherit the structure.\t\n // \t\n /////////////////////////////////////////////////////////////////////////////// class CMyAsyncResult : public \t\n {\t\n protected: LONG m_cRef; // Reference count. m_bLockPlatform; // Locked the Media Foundation platform? * m_pState; // Caller's state object. * m_pObject; // Optional object. See . // Constructor. CMyAsyncResult( *pCallback, *pState, *phr) : m_cRef(1), m_bLockPlatform( ), m_pObject( null ), m_pState(pState) { *phr =(); m_bLockPlatform = TRUE; // Initialize the members. ZeroMemory(&this->overlapped, sizeof(OVERLAPPED)); hrStatusResult = ; dwBytesTransferred = 0; hEvent = null ; this->pCallback = pCallback; if (pCallback) { this->pCallback->AddRef(); } if (m_pState) { m_pState->AddRef(); } } virtual ~CMyAsyncResult() { SafeRelease(&pCallback); SafeRelease(&m_pState); SafeRelease(&m_pObject); if (m_bLockPlatform) {(); } } public: // Static method to create an instance of this object. static CreateInstance( *pCallback, // Callback to invoke. *pState, // Optional state object. CMyAsyncResult **ppResult // Receives a reference to the object. ) { hr = ; *ppResult = null ; CMyAsyncResult *pResult = new (std::nothrow) CMyAsyncResult(pCallback, pState, &hr); if (pResult ==null ) { return E_OUTOFMEMORY; } if (FAILED(hr)) { delete pResult; return hr; } // If the callback isnull , create an event that will be signaled. if (pCallback ==null ) { pResult->hEvent = CreateEvent(null ,, , null ); if (pResult->hEvent ==null ) { hr = HRESULT_FROM_WIN32(GetLastError()); } } if (SUCCEEDED(hr)) { *ppResult = pResult; // Return the reference to the caller. } else { pResult->Release(); } return hr; } // SetObject: Sets the optional result object. // (This method is not part of the interface.)SetObject( *pObject) { SafeRelease(&m_pObject); m_pObject = pObject; if (pObject) { m_pObject->AddRef(); } return ; } // methods. STDMETHODIMP QueryInterface(REFIID riid, void **ppv) { static const QITAB qit[] = { QITABENT(CMyAsyncResult, ), { 0 } }; return QISearch(this, qit, riid, ppv); } STDMETHODIMP_(ULONG) AddRef() { return InterlockedIncrement(&m_cRef); } STDMETHODIMP_(ULONG) Release() { LONG cRef = InterlockedDecrement(&m_cRef); if (cRef == 0) { delete this; } return cRef; } // methods. STDMETHODIMP GetState( ** ppunkState) { if (ppunkState == null ) { return E_POINTER; } *ppunkState = m_pState; if (m_pState) { (*ppunkState)->AddRef(); } return; } STDMETHODIMP GetStatus( void) { return hrStatusResult; } STDMETHODIMP STDMETHODCALLTYPE SetStatus( hrStatus) { hrStatusResult = hrStatus; return ; } STDMETHODIMP GetObject( **ppObject) { if (ppObject == null ) { return E_POINTER; } *ppObject = m_pObject; if (m_pObject) { (*ppObject)->AddRef(); } return; } * STDMETHODCALLTYPE GetStateNoAddRef() { return m_pState; // Warning! Can be null . }\t\n };\t\n
Applies to: desktop apps only
Retrieves the password.
\t\nIf the password is not available, the method might succeed and set *pcbData to zero.
\t\nApplies to: desktop apps only
Sets the user name.
\t\nPointer to a buffer that contains the user name. If fDataIsEncrypted is
Size of pbData, in bytes. If fDataIsEncrypted is
If TRUE, the user name is encrypted. Otherwise, the user name is not encrypted.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets the password.
\t\nPointer to a buffer that contains the password. If fDataIsEncrypted is
Size of pbData, in bytes. If fDataIsEncrypted is
If TRUE, the password is encrypted. Otherwise, the password is not encrypted.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the user name.
\t\nPointer to a buffer that receives the user name. To find the required buffer size, set this parameter to
On input, specifies the size of the pbData buffer, in bytes. On output, receives the required buffer size. If fEncryptData is
If TRUE, the method returns an encrypted string. Otherwise, the method returns an unencrypted string.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the user name is not available, the method might succeed and set *pcbData to zero.
\t\nApplies to: desktop apps only
Retrieves the password.
\t\nPointer to a buffer that receives the password. To find the required buffer size, set this parameter to
On input, specifies the size of the pbData buffer, in bytes. On output, receives the required buffer size. If fEncryptData is
If TRUE, the method returns an encrypted string. Otherwise, the method returns an unencrypted string.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the password is not available, the method might succeed and set *pcbData to zero.
\t\nApplies to: desktop apps only
Queries whether logged-on credentials should be used.
\t\nReceives a Boolean value. If logged-on credentials should be used, the value is TRUE. Otherwise, the value is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Specifies how user credentials are stored.
\t\nIf no flags are specified, the credentials are cached in memory. This method can be implemented by the credential manager and called by the network source.
\t\nApplies to: desktop apps only
Retrieves the credential object for the specified URL.
\t\nA null-terminated wide-character string containing the URL for which the credential is needed.
A null-terminated wide-character string containing the realm for the authentication.
Bitwise OR of zero or more flags from the
Receives a reference to the
Receives a bitwise OR of zero or more flags from the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Reports whether the credential object provided successfully passed the authentication challenge.
\t\nPointer to the
TRUE if the credential object succeeded in the authentication challenge; otherwise,
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method is called by the network source into the credential manager.
\t\nApplies to: desktop apps only
Specifies how user credentials are stored.
\t\nPointer to the
Bitwise OR of zero or more flags from the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If no flags are specified, the credentials are cached in memory. This method can be implemented by the credential manager and called by the network source.
\t\nApplies to: desktop apps only
Implemented by applications to provide user credentials for a network source.
To use this interface, implement it in your application. Then create a property store object and set the MFNETSOURCE_CREDENTIAL_MANAGER property. The value of the property is a reference to your application's
Media Foundation does not provide a default implementation of this interface. Applications that support authentication must implement this interface.
\t\nApplies to: desktop apps only
Begins an asynchronous request to retrieve the user's credentials.
\t\nPointer to an
Pointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Completes an asynchronous request to retrieve the user's credentials.
\t\nPointer to an
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Specifies whether the user's credentials succeeded in the authentication challenge. The network source calls this method to informs the application whether the user's credentials were authenticated.
\t\nPointer to the
Boolean value. The value is TRUE if the credentials succeeded in the authentication challenge. Otherwise, the value is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Determines the next proxy to use.
\t\nApplies to: desktop apps only
Initializes the proxy locator object.
\t\nNull-terminated wide-character string containing the hostname of the destination server.
Null-terminated wide-character string containing the destination URL.
Reserved. Set to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Determines the next proxy to use.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There are no more proxy objects. |
?
Applies to: desktop apps only
Keeps a record of the success or failure of using the current proxy.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the current proxy information including hostname and port.
\t\nPointer to a buffer that receives a null-terminated string containing the proxy hostname and port. This parameter can be
On input, specifies the number of elements in the pszStr array. On output, receives the required size of the buffer.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The buffer specified in pszStr is too small. |
?
Applies to: desktop apps only
Creates a new instance of the default proxy locator.
\t\nReceives a reference to the new proxy locator object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Creates a proxy locator object, which determines the proxy to use.
The network source uses this interface to create the proxy locator object. Applications can provide their own implementation of this interface by setting the MFNETSOURCE_PROXYLOCATORFACTORY property. on the source resolver. If the application does not set this property, the network source uses the default proxy locator provided by Media Foundation.
\t\nApplies to: desktop apps only
Creates an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves a supported protocol by index
\t\nApplies to: desktop apps only
Retrieves the number of protocols supported by the network scheme plug-in.
\t\nReceives the number of protocols.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves a supported protocol by index
\t\nZero-based index of the protocol to retrieve. To get the number of supported protocols, call
Receives a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The value passed in the nProtocolIndex parameter was greater than the total number of supported protocols, returned by GetNumberOfSupportedProtocols. |
?
Applies to: desktop apps only
Not implemented in this release.
\t\nThis method returns
Applies to: desktop apps only
Retrieves the number of protocols supported by the network scheme plug-in.
\t\nApplies to: desktop apps only
Stores the data needed to marshal an interface across a process boundary.
\t\nApplies to: desktop apps only
Stores the data needed to marshal an interface across a process boundary.
\t\nInterface identifier of the interface to marshal.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Marshals an interface from data stored in the stream.
\t\nInterface identifier of the interface to marshal.
Receives a reference to the requested interface. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Encapsulates a usage policy from an input trust authority (ITA). Output trust authorities (OTAs) use this interface to query which protection systems they are required to enforce by the ITA.
\t\nRetrieves a list of the output protection systems that the output trust authority (OTA) must enforce, along with configuration data for each protection system.
dwAttributes
[in] Describes the output that is represented by the OTA calling this method. This value is a bitwise OR of zero or more of the following flags.
| Value | Description |
|---|---|
| MFOUTPUTATTRIBUTE_BUS | Hardware bus. |
| MFOUTPUTATTRIBUTE_COMPRESSED | The output sends compressed data. If this flag is absent, the output sends uncompressed data. |
| MFOUTPUTATTRIBUTE_BUSIMPLEMENTATION | Reserved. Do not use. |
| MFOUTPUTATTRIBUTE_DIGITAL | The output sends a digital signal. If this flag is absent, the output sends an analog signal. |
| MFOUTPUTATTRIBUTE_NONSTANDARDIMPLEMENTATION | Reserved. Do not use. |
| MFOUTPUTATTRIBUTE_SOFTWARE | Reserved. Do not use. |
| MFOUTPUTATTRIBUTE_VIDEO | The output sends video data. If this flag is absent, the output sends audio data. |
guidOutputSubType
[in] Indicates a specific family of output connectors that is represented by the OTA calling this method. Possible values include the following.
| Value | Description |
|---|---|
| MFCONNECTOR_AGP | AGP bus. |
| MFCONNECTOR_COMPONENT | Component video. |
| MFCONNECTOR_COMPOSITE | Composite video. |
| MFCONNECTOR_D_JPN | Japanese D connector. (Connector conforming to the EIAJ RC-5237 standard.) |
| MFCONNECTOR_DISPLAYPORT_EMBEDDED | Embedded DisplayPort connector. |
| MFCONNECTOR_DISPLAYPORT_EXTERNAL | External DisplayPort connector. |
| MFCONNECTOR_DVI | Digital video interface (DVI) connector. |
| MFCONNECTOR_HDMI | High-definition multimedia interface (HDMI) connector. |
| MFCONNECTOR_LVDS | Low voltage differential signaling (LVDS) connector. |
| MFCONNECTOR_PCI | PCI bus. |
| MFCONNECTOR_PCI_Express | PCI Express bus. |
| MFCONNECTOR_PCIX | PCI-X bus. |
| MFCONNECTOR_SPDIF | Audio data sent over a connector via S/PDIF. |
| MFCONNECTOR_SVIDEO | S-Video connector. |
| MFCONNECTOR_UDI_EMBEDDED | Embedded Unified Display Interface (UDI). |
| MFCONNECTOR_UDI_EXTERNAL | External UDI. |
| MFCONNECTOR_UNKNOWN | Unknown connector type. You can use this value to initialize variables, but it is not a valid connector type. |
| MFCONNECTOR_VGA | VGA connector. |
rgGuidProtectionSchemasSupported
[in] Pointer to an array of
cProtectionSchemasSupported
[in] Number of elements in the rgGuidProtectionSchemasSupported array.
ppRequiredProtectionSchemas
[out] Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFOutputPolicy Interface\t\nApplies to: desktop apps | Metro style apps
Retrieives a
Receives a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
All of the policy objects and output schemas from the same ITA should return the same originator identifier (including dynamic policy changes). This value enables the OTA to distinguish policies that originate from different ITAs, so that the OTA can update dynamic policies correctly.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the minimum version of the global revocation list (GRL) that must be enforced by the protected environment for this policy.
\t\nReceives the minimum GRL version.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieives a
All of the policy objects and output schemas from the same ITA should return the same originator identifier (including dynamic policy changes). This value enables the OTA to distinguish policies that originate from different ITAs, so that the OTA can update dynamic policies correctly.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the minimum version of the global revocation list (GRL) that must be enforced by the protected environment for this policy.
\t\nApplies to: desktop apps | Metro style apps
Encapsulates information about an output protection system and its corresponding configuration data.
\t\nIf the configuration information for the output protection system does not require more than a DWORD of space, the configuration information is retrieved in the GetConfigurationData method. If more than a DWORD of configuration information is needed, it is stored using the
Applies to: desktop apps | Metro style apps
Retrieves the output protection system that is represented by this object. Output protection systems are identified by
Receives the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Returns configuration data for the output protection system. The configuration data is used to enable or disable the protection system, and to set the protection levels.
\t\nReceives the configuration data. The meaning of this data depends on the output protection system.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves a
Receives a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
All of the policy objects and output schemas from the same ITA should return the same originator identifier (including dynamic policy changes). This value enables the OTA to distinguish policies that originate from different ITAs, so that the OTA can update dynamic policies correctly.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the output protection system that is represented by this object. Output protection systems are identified by
Applies to: desktop apps | Metro style apps
Returns configuration data for the output protection system. The configuration data is used to enable or disable the protection system, and to set the protection levels.
\t\nApplies to: desktop apps | Metro style apps
Retrieves a
All of the policy objects and output schemas from the same ITA should return the same originator identifier (including dynamic policy changes). This value enables the OTA to distinguish policies that originate from different ITAs, so that the OTA can update dynamic policies correctly.
\t\nApplies to: desktop apps | Metro style apps
Encapsulates the functionality of one or more output protection systems that a trusted output supports. This interface is exposed by output trust authority (OTA) objects. Each OTA represents a single action that the trusted output can perform, such as play, copy, or transcode. An OTA can represent more than one physical output if each output performs the same action.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the action that is performed by this output trust authority (OTA).
\t\nReceives a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Sets one or more policy objects on the output trust authority (OTA).
\t\nThe address of an array of
The number of elements in the ppPolicy array.
Receives either a reference to a buffer allocated by the OTA, or the value
Note??Currently this parameter is reserved. An OTA should set the reference to
Receives the size of the ppbTicket buffer, in bytes. If ppbTicket receives the value
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The policy was negotiated successfully, but the OTA will enforce it asynchronously. |
| | The OTA does not support the requirements of this policy. |
?
If the method returns MF_S_WAIT_FOR_POLICY_SET, the OTA sends an
Applies to: desktop apps | Metro style apps
Sets one or more policy objects on the output trust authority (OTA).
\t\nThe address of an array of
The number of elements in the ppPolicy array.
Receives either a reference to a buffer allocated by the OTA, or the value
Note??Currently this parameter is reserved. An OTA should set the reference to
Receives the size of the ppbTicket buffer, in bytes. If ppbTicket receives the value
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The policy was negotiated successfully, but the OTA will enforce it asynchronously. |
| | The OTA does not support the requirements of this policy. |
?
If the method returns MF_S_WAIT_FOR_POLICY_SET, the OTA sends an
Applies to: desktop apps | Metro style apps
Retrieves the action that is performed by this output trust authority (OTA).
\t\nApplies to: desktop apps only
Controls how media sources and transforms are enumerated in Microsoft Media Foundation.
To get a reference to this interface, call
Media Foundation provides a set of built-in media sources and decoders. Applications can enumerate them as follows:
Applications might also enumerate these objects indirectly. For example, if an application uses the topology loader to resolve a partial topology, the topology loader calls
Third parties can implement their own custom media sources and decoders, and register them for enumeration so that other applications can use them.
To control the enumeration order, Media Foundation maintains two process-wide lists of CLSIDs: a preferred list and a blocked list. An object whose CLSID appears in the preferred list appears first in the enumeration order. An object whose CLSID appears on the blocked list is not enumerated.
The lists are initially populated from the registry. Applications can use the
The preferred list contains a set of key/value pairs, where the keys are strings and the values are CLSIDs. These key/value pairs are defined as follows:
The following examples show the various types of key:
To search the preferred list by key name, call the
The blocked list contains a list of CLSIDs. To enumerate the entire list, call the
Applies to: desktop apps only
Searches the preferred list for a class identifier (CLSID) that matches a specified key name.
\t\nMember of the
The key name to match. For more information about the format of key names, see the Remarks section of
Receives a CLSID from the preferred list.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| No CLSID matching this key was found. |
?
Applies to: desktop apps only
Gets a class identifier (CLSID) from the preferred list, specified by index value.
\t\nMember of the
The zero-based index of the CLSID to retrieve.
Receives the key name associated with the CLSID. The caller must free the memory for the returned string by calling the CoTaskMemFree function. For more information about the format of key names, see the Remarks section of
Receives the CLSID at the specified index.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| The index parameter is out of range. |
?
Applies to: desktop apps only
Adds a class identifier (CLSID) to the preferred list or removes a CLSID from the list.
\t\nMember of the
The key name for the CLSID. For more information about the format of key names, see the Remarks section of
The CLSID to add to the list. If this parameter is
If this method succeeds, it returns
The preferred list is global to the caller's process. Calling this method does not affect the list in other process.
\t\nApplies to: desktop apps only
Queries whether a class identifier (CLSID) appears in the blocked list.
\t\nMember of the
The CLSID to search for.
The method returns an
| Return code | Description |
|---|---|
| | The specified CLSID appears in the blocked list. |
| Invalid argument. |
| The specified CLSID is not in the blocked list. |
?
Applies to: desktop apps only
Gets a class identifier (CLSID) from the blocked list.
\t\nMember of the
The zero-based index of the CLSID to retrieve.
Receives the CLSID at the specified index.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| The index parameter is out of range. |
?
Applies to: desktop apps only
Adds a class identifier (CLSID) to the blocked list, or removes a CLSID from the list.
\t\nMember of the
The CLSID to add or remove.
Specifies whether to add or remove the CSLID. If the value is TRUE, the method adds the CLSID to the blocked list. Otherwise, the method removes it from the list.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
?
The blocked list is global to the caller's process. Calling this method does not affect the list in other processes.
\t\nApplies to: desktop apps only
Note??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Represents a media item. A media item is an abstraction for a source of media data, such as a video file. Use this interface to get information about the source, or to change certain playback settings, such as the start and stop times. To get a reference to this interface, call one of the following methods:
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets a reference to the MFPlay player object that created the media item.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the URL that was used to create the media item.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| No URL is associated with this media item. |
| | The |
?
This method applies when the application calls
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the object that was used to create the media item.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The media item was created from a URL, not from an object. |
| | The |
?
The object reference is set if the application uses
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the application-defined value stored in the media item.
\t\nIf this method succeeds, it returns
You can assign this value when you first create the media item, by specifying it in the dwUserData parameter of the
This method can be called after the player object is shut down.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Stores an application-defined value in the media item.
\t\nThis method can return one of these values.
This method can be called after the player object is shut down.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the start and stop times for the media item.
\t\nIf this method succeeds, it returns
The pguidStartPositionType and pguidStopPositionType parameters receive the units of time that are used. Currently, the only supported value is MFP_POSITIONTYPE_100NS.
| Value | Description |
|---|---|
| MFP_POSITIONTYPE_100NS | 100-nanosecond units. The time parameter (pvStartValue or pvStopValue) uses the following data type:
|
?
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets the start and stop time for the media item.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | Invalid start or stop time. Any of the following can cause this error:
|
?
By default, a media item plays from the beginning to the end of the file. This method adjusts the start time and/or the stop time:
The pguidStartPositionType and pguidStopPositionType parameters give the units of time that are used. Currently, the only supported value is MFP_POSITIONTYPE_100NS.
| Value | Description |
|---|---|
| MFP_POSITIONTYPE_100NS | 100-nanosecond units. The time parameter (pvStartValue or pvStopValue) uses the following data type:
To clear a previously set time, use an empty |
?
The adjusted start and stop times are used the next time that
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries whether the media item contains a video stream.
\t\nIf this method succeeds, it returns
To select or deselect streams before playback starts, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries whether the media item contains an audio stream.
\t\nIf this method succeeds, it returns
To select or deselect streams before playback starts, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries whether the media item contains protected content.
Note??Currently
If this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the duration of the media item.
\t\nIf this method succeeds, it returns
The method returns the total duration of the content, regardless of any values set through
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the number of streams (audio, video, and other) in the media item.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries whether a stream is selected to play.
\t\nIf this method succeeds, it returns
To select or deselect a stream, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Selects or deselects a stream.
\t\nIf this method succeeds, it returns
You can use this method to change which streams are selected. The change goes into effect the next time that
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries the media item for a stream attribute.
\t\nIf this method succeeds, it returns
Stream attributes describe an individual stream (audio, video, or other) within the presentation. To get an attribute that applies to the entire presentation, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries the media item for a presentation attribute.
\t\nIf this method succeeds, it returns
Presentation attributes describe the presentation as a whole. To get an attribute that applies to an individual stream within the presentation, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets various flags that describe the media item.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets a media sink for the media item. A media sink is an object that consumes the data from one or more streams.
\t\nIf this method succeeds, it returns
By default, the MFPlay player object renders audio streams to the Streaming Audio Renderer (SAR) and video streams to the Enhanced Video Renderer (EVR). You can use the SetStreamSink method to provide a different media sink for an audio or video stream; or to support other stream types besides audio and video. You can also use it to configure the SAR or EVR before they are used.
Call this method before calling
To reset the media item to use the default media sink, set pMediaSink to
If the application is running over Remote Desktop, and you call this method with a non-
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets a property store that contains metadata for the source, such as author or title.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets a reference to the MFPlay player object that created the media item.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the object that was used to create the media item.
\t\nThe object reference is set if the application uses
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the application-defined value stored in the media item.
\t\nYou can assign this value when you first create the media item, by specifying it in the dwUserData parameter of the
This method can be called after the player object is shut down.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries whether the media item contains protected content.
Note??Currently
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the number of streams (audio, video, and other) in the media item.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets various flags that describe the media item.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets a property store that contains metadata for the source, such as author or title.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Contains methods to play media files.
The MFPlay player object exposes this interface. To get a reference to this interface, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Contains methods to play media files.
The MFPlay player object exposes this interface. To get a reference to this interface, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Pauses playback. While playback is paused, the most recent video frame is displayed, and audio is silent.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object's Shutdown method was called. |
?
This method completes asynchronously. When the operation completes, the application's
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Stops playback.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object's Shutdown method was called. |
?
This method completes asynchronously. When the operation completes, the application's
The current media item is still valid. After playback stops, the playback position resets to the beginning of the current media item.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Steps forward one video frame.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Cannot frame step. Reasons for this error code include:
|
| | The object's Shutdown method was called. |
| | The media source does not support frame stepping, or the current playback rate is negative. |
?
This method completes asynchronously. When the operation completes, the application's
The player object does not support frame stepping during reverse playback (that is, while the playback rate is negative).
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets the playback position.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| The value of pvPositionValue is not valid. |
| | No media item has been queued. |
| | The object's Shutdown method was called. |
?
If you call this method while playback is stopped, the new position takes effect after playback resumes.
This method completes asynchronously. When the operation completes, the application's
If playback was started before SetPosition is called, playback resumes at the new position. If playback was paused, the video is refreshed to display the current frame at the new position.
If you make two consecutive calls to SetPosition with guidPositionType equal to MFP_POSITIONTYPE_100NS, and the second call is made before the first call has completed, the second call supersedes the first. The status code for the superseded call is set to S_FALSE in the event data for that call. This behavior prevents excessive latency from repeated calls to SetPosition, as each call may force the media source to perform a relatively lengthy seek operation.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current playback position.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | No media item has been queued. |
| | The object's Shutdown method was called. |
?
The playback position is calculated relative to the start time of the media item, which can be specified by calling
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the playback duration of the current media item.
\t\nThis method can return one of these values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media source does not have a duration. This error can occur with a live source, such as a video camera. |
| | There is no current media item. |
?
This method calculates the playback duration, taking into account the start and stop times for the media item. To set the start and stop times, call
For example, suppose that you load a 30-second audio file and set the start time equal to 2 seconds and stop time equal to 10 seconds. The
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets the playback rate.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The flRate parameter is zero. |
| | The object's Shutdown method was called. |
?
This method completes asynchronously. When the operation completes, the application's
The method sets the nearest supported rate, which will depend on the underlying media source. For example, if flRate is 50 and the source's maximum rate is 8? normal rate, the method will set the rate to 8.0. The actual rate is indicated in the event data for the
To find the range of supported rates, call
This method does not support playback rates of zero, although Media Foundation defines a meaning for zero rates in some other contexts.
The new rate applies only to the current media item. Setting a new media item resets the playback rate to 1.0.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current playback rate.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the range of supported playback rates.
\t\nThis method can return one of these values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not support playback in the requested direction (either forward or reverse). |
?
Playback rates are expressed as a ratio of the current rate to the normal rate. For example, 1.0 indicates normal playback speed, 0.5 indicates half speed, and 2.0 indicates twice speed. Positive values indicate forward playback, and negative values indicate reverse playback.\t\n
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current playback state of the MFPlay player object.
\t\nIf this method succeeds, it returns
This method can be called after the player object has been shut down.
Many of the
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Creates a media item from a URL.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | Invalid request. This error can occur when fSync is |
| | The object's Shutdown method was called. |
| | Unsupported protocol. |
?
This method does not queue the media item for playback. To queue the item for playback, call
The CreateMediaItemFromURL method can be called either synchronously or asynchronously:
The callback interface is set when you first call
If you make multiple asynchronous calls to CreateMediaItemFromURL, they are not guaranteed to complete in the same order. Use the dwUserData parameter to match created media items with pending requests.
Currently, this method returns
Internally, this method creates a media source. To configure the media source, do the following:
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Creates a media item from an object.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | Invalid request. This error can occur when fSync is |
| | The object's Shutdown method was called. |
?
The pIUnknownObj parameter must specify one of the following:
This method does not queue the media item for playback. To queue the item for playback, call
The CreateMediaItemFromObject method can be called either synchronously or asynchronously:
The callback interface is set when you first call
If you make multiple asynchronous calls to CreateMediaItemFromObject, they are not guaranteed to complete in the same order. Use the dwUserData parameter to match created media items with pending requests.
Configuring the SourceIf pIUnknownObj points to a byte stream, you can configure the media source by performing the following steps:
If pIUnknownObj points to a media source, you can configure the source at the time that you create it.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queues a media item for playback.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | The media item contains protected content. MFPlay currently does not support protected content. |
| | No audio playback device was found. This error can occur if the media source contains audio, but no audio playback devices are available on the system. |
| | The object's Shutdown method was called. |
?
This method completes asynchronously. When the operation completes, the application's
To create a media item, call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Clears the current media item.
Note??This method is currently not implemented.
\t\nIf this method succeeds, it returns
This method stops playback and releases the player object's references to the current media item.
This method completes asynchronously. When the operation completes, the application's
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets a reference to the current media item.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There is no current media item. |
| | There is no current media item. |
| | The object's Shutdown method was called. |
?
The
The previous remark also applies to setting the media item in the
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current audio volume.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets the audio volume.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The flVolume parameter is invalid. |
?
If you call this method before playback starts, the setting is applied after playback starts.
This method does not change the master volume level for the player's audio session. Instead, it adjusts the per-channel volume levels for audio stream(s) that belong to the current media item. Other streams in the audio session are not affected. For more information, see Managing the Audio Session.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current audio balance.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets the audio balance.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The flBalance parameter is invalid. |
?
If you call this method before playback starts, the setting is applied when playback starts.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries whether the audio is muted.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Mutes or unmutes the audio.
\t\nIf this method succeeds, it returns
If you call this method before playback starts, the setting is applied after playback starts.
This method does not mute the entire audio session to which the player belongs. It mutes only the streams from the current media item. Other streams in the audio session are not affected. For more information, see Managing the Audio Session. \t\n
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the size and aspect ratio of the video. These values are computed before any scaling is done to fit the video into the destination window.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
At least one parameter must be non-
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the range of video sizes that can be displayed without significantly degrading performance or image quality.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
At least one parameter must be non-
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets the video source rectangle.
MFPlay clips the video to this rectangle and stretches the rectangle to fill the video window.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
MFPlay stretches the source rectangle to fill the entire video window. By default, MFPlay maintains the source's correct aspect ratio, letterboxing if needed. The letterbox color is controlled by the
This method fails if no media item is currently set, or if the current media item does not contain video.
To set the video position before playback starts, call this method inside your event handler for the
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the video source rectangle.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Specifies whether the aspect ratio of the video is preserved during playback.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
This method fails if no media item is currently set, or if the current media item does not contain video.
To set the aspect-ratio mode before playback starts, call this method inside your event handler for the
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current aspect-ratio correction mode. This mode controls whether the aspect ratio of the video is preserved during playback.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the window where the video is displayed.
\t\nIf this method succeeds, it returns
The video window is specified when you first call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Updates the video frame.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
Call this method when your application's video playback window receives either a WM_PAINT or WM_SIZE message. This method performs two functions:
Important??Call the GDI BeginPaint function before calling UpdateVideo.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Sets the color for the video border. The border color is used to letterbox the video.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| The object's Shutdown method was called. |
?
This method fails if no media item is currently set, or if the current media item does not contain video.
To set the border color before playback starts, call this method inside your event handler for the
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current color of the video border. The border color is used to letterbox the video.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The current media item does not contain video. |
| | The object's Shutdown method was called. |
?
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Applies an audio or video effect to playback.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | This effect was already added. |
?
The object specified in the pEffect parameter can implement either a video effect or an audio effect. The effect is applied to any media items set after the method is called. It is not applied to the current media item.
For each media item, the effect is applied to the first selected stream of the matching type (audio or video). If a media item has two selected streams of the same type, the second stream does not receive the effect. The effect is ignored if the media item does not contain a stream that matches the effect type. For example, if you set a video effect and play a file that contains just audio, the video effect is ignored, although no error is raised.
The effect is applied to all subsequent media items, until the application removes the effect. To remove an effect, call
If you set multiple effects of the same type (audio or video), they are applied in the same order in which you call InsertEffect.
Remote Playback OptimizationsAudio and video effects might be incompatible with optimizations that are used for remote playback. The following remarks apply only to audio or video effects that are actually used during playback:
In other words, required effects have priority over remote optimizations, but optional effects do not.
Remote optimizations might be disabled for other reasons. For example, they are disabled if you set the
Non-audio, non-video effects do not affect remote optimizations. Also, if you insert a required effect but the source does not contain any streams of that type, remote optimizations are not disabled.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Removes an effect that was added with the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The effect was not found. |
?
The change applies to the next media item that is set on the player. The effect is not removed from the current media item.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Removes all effects that were added with the
If this method succeeds, it returns
The change applies to the next media item that is set on the player. The effects are not removed from the current media item.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Shuts down the MFPlay player object and releases any resources the object is using.
\t\nIf this method succeeds, it returns
After this method is called, most
The player object automatically shuts itself down when its reference count reaches zero. You can use the Shutdown method to shut down the player before all of the references have been released.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current playback rate.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current playback state of the MFPlay player object.
\t\nThis method can be called after the player object has been shut down.
Many of the
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets a reference to the current media item.
\t\nThe
The previous remark also applies to setting the media item in the
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current audio volume.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current audio balance.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Queries whether the audio is muted.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the video source rectangle.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current aspect-ratio correction mode. This mode controls whether the aspect ratio of the video is preserved during playback.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the window where the video is displayed.
\t\nThe video window is specified when you first call
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Gets the current color of the video border. The border color is used to letterbox the video.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Callback interface for the
To set the callback, pass an
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Called by the MFPlay player object to notify the application of a playback event.
\t\n The specific type of playback event is given in the eEventType member of the
It is safe to call
Applies to: desktop apps only
Enables a media source to receive a reference to the
If a media source exposes this interface, the Protected Media Path (PMP) Media Session calls SetPMPHost with a reference to the
Applies to: desktop apps only
Provides a reference to the
If this method succeeds, it returns
The
Applies to: desktop apps only
Provides a reference to the
The
Applies to: desktop apps only
Enables a media source in the application process to create objects in the protected media path (PMP) process.
\t\nThis interface is used when a media source resides in the application process but the Media Session resides in a PMP process. The media source can use this interface to create objects in the PMP process. For example, to play DRM-protected content, the media source typically must create an input trust authority (ITA) in the PMP process.
To use this interface, the media source implements the
You can also get a reference to this interface by calling
Applies to: desktop apps only
Blocks the protected media path (PMP) process from ending.
\t\nIf this method succeeds, it returns
When this method is called, it increments the lock count on the PMP process. For every call to this method, the application should make a corresponding call to
Applies to: desktop apps only
Decrements the lock count on the protected media path (PMP) process. Call this method once for each call to
If this method succeeds, it returns
Applies to: desktop apps only
Creates an object in the protect media path (PMP) process, from a CLSID.
\t\nThe CLSID of the object to create.
A reference to the
The interface identifier (IID) of the interface to retrieve.
Receives a reference to the requested interface. The caller must release the interface.
If this method succeeds, it returns
You can use the pStream parameter to initialize the object after it is created.
\t\nApplies to: desktop apps only
Creates an object in the protected media path (PMP) process.
\t\nApplies to: desktop apps only
Blocks the protected media path (PMP) process from ending.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
When this method is called, it increments the lock count on the PMP process. For every call to this method, the application should make a corresponding call to
Applies to: desktop apps only
Decrements the lock count on the protected media path (PMP) process. Call this method once for each call to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Creates an object in the protected media path (PMP) process.
\t\nCLSID of the object to create.
Interface identifier of the interface to retrieve.
Receives a reference to the requested interface. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Represents a presentation clock, which is used to schedule when samples are rendered and to synchronize multiple streams.
\t\nTo create a new instance of the presentation clock, call the
To get the presentation clock from the Media Session, call
Applies to: desktop apps | Metro style apps
Sets the time source for the presentation clock. The time source is the object that drives the clock by providing the current time.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The time source does not have a frequency of 10 MHz. |
| | The time source has not been initialized. |
?
The presentation clock cannot start until it has a time source.
The time source is automatically registered to receive state change notifications from the clock, through the time source's
This time source have a frequency of 10 MHz. See
Applies to: desktop apps | Metro style apps
Retrieves the clock's presentation time source.
\t\nReceives a reference to the time source's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No time source was set on this clock. |
?
Applies to: desktop apps | Metro style apps
Retrieves the latest clock time.
\t\nReceives the latest clock time, in 100-nanosecond units. The time is relative to when the clock was last started.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The clock does not have a presentation time source. Call |
?
This method does not attempt to smooth out jitter or otherwise account for any inaccuracies in the clock time.
\t\nApplies to: desktop apps | Metro style apps
Registers an object to be notified whenever the clock starts, stops, or pauses, or changes rate.
\t\nPointer to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Before releasing the object, call
Applies to: desktop apps | Metro style apps
Unregisters an object that is receiving state-change notifications from the clock.
\t\nPointer to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Starts the presentation clock.
\t\nInitial starting time, in 100-nanosecond units. At the time the Start method is called, the clock's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No time source was set on this clock. |
?
This method is valid in all states (stopped, paused, or running).
If the clock is paused and restarted from the same position (llClockStartOffset is PRESENTATION_CURRENT_POSITION), the presentation clock sends an
The presentation clock initiates the state change by calling OnClockStart or OnClockRestart on the clock's time source. This call is made synchronously. If it fails, the state change does not occur. If the call succeeds, the state changes, and the clock notifies the other state-change subscribers by calling their OnClockStart or OnClockRestart methods. These calls are made asynchronously.
If the clock is already running, calling Start again has the effect of seeking the clock to the new StartOffset position.
\t\nApplies to: desktop apps | Metro style apps
Stops the presentation clock. While the clock is stopped, the clock time does not advance, and the clock's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No time source was set on this clock. |
| | The clock is already stopped. |
?
This method is valid when the clock is running or paused.
The presentation clock initiates the state change by calling
Applies to: desktop apps | Metro style apps
Pauses the presentation clock. While the clock is paused, the clock time does not advance, and the clock's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No time source was set on this clock. |
| | The clock is already paused. |
| | The clock is stopped. This request is not valid when the clock is stopped. |
?
This method is valid when the clock is running. It is not valid when the clock is paused or stopped.
The presentation clock initiates the state change by calling
Applies to: desktop apps | Metro style apps
Retrieves the clock's presentation time source.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the latest clock time.
\t\nThis method does not attempt to smooth out jitter or otherwise account for any inaccuracies in the clock time.
\t\nApplies to: desktop apps | Metro style apps
Describes the details of a presentation. A presentation is a set of related media streams that share a common presentation time.
\t\nPresentation descriptors are used to configure media sources and some media sinks. To get the presentation descriptor from a media source, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of stream descriptors in the presentation. Each stream descriptor contains information about one stream in the media source. To retrieve a stream descriptor, call the
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a stream descriptor for a stream in the presentation. The stream descriptor contains information about the stream.
\t\nZero-based index of the stream. To find the number of streams in the presentation, call the
Receives a Boolean value. The value is TRUE if the stream is currently selected, or
Receives a reference to the stream descriptor's
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Selects a stream in the presentation.
\t\nThe stream number to select, indexed from zero. To find the number of streams in the presentation, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| dwDescriptorIndex is out of range. |
?
If a stream is selected, the media source will generate data for that stream. The media source will not generated data for deselected streams. To deselect a stream, call
To query whether a stream is selected, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Deselects a stream in the presentation.
\t\n The stream number to deselect, indexed from zero. To find the number of streams in the presentation, call the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| dwDescriptorIndex is out of range. |
?
If a stream is deselected, no data is generated for that stream. To select the stream again, call
To query whether a stream is selected, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates a copy of this presentation descriptor.
\t\nReceives a reference to the
If this method succeeds, it returns
This method performs a shallow copy of the presentation descriptor. The stream descriptors are not cloned. Therefore, use caution when modifying the presentation presentation descriptor or its stream descriptors.
If the original presentation descriptor is from a media source, do not modify the presentation descriptor unless the source is stopped. If you use the presentation descriptor to configure a media sink, do not modify the presentation descriptor after the sink is configured.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of stream descriptors in the presentation. Each stream descriptor contains information about one stream in the media source. To retrieve a stream descriptor, call the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Provides the clock times for the presentation clock.
\t\nThis interface is implemented by presentation time sources. A presentation time source is an object that provides the clock time for the presentation clock. For example, the audio renderer is a presentation time source. The rate at which the audio renderer consumes audio samples determines the clock time. If the audio format is 44100 samples per second, the audio renderer will report that one second has passed for every 44100 audio samples it plays. In this case, the timing is provided by the sound card.
To set the presentation time source on the presentation clock, call
A presentation time source must also implement the
Media Foundation provides a presentation time source that is based on the system clock. To create this object, call the
Applies to: desktop apps | Metro style apps
Retrieves the underlying clock that the presentation time source uses to generate its clock times.
\t\nReceives a reference to the clock's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | This time source does not expose an underlying clock. |
?
A presentation time source must support stopping, starting, pausing, and rate changes. However, in many cases the time source derives its clock times from a hardware clock or other device. The underlying clock is always running, and might not support rate changes.
Optionally, a time source can expose the underlying clock by implementing this method. The underlying clock is always running, even when the presentation time source is paused or stopped. (Therefore, the underlying clock returns the
The underlying clock is useful if you want to make decisions based on the clock times while the presentation clock is stopped or paused.
If the time source does not expose an underlying clock, the method returns
Applies to: desktop apps | Metro style apps
Retrieves the underlying clock that the presentation time source uses to generate its clock times.
\t\nA presentation time source must support stopping, starting, pausing, and rate changes. However, in many cases the time source derives its clock times from a hardware clock or other device. The underlying clock is always running, and might not support rate changes.
Optionally, a time source can expose the underlying clock by implementing this method. The underlying clock is always running, even when the presentation time source is paused or stopped. (Therefore, the underlying clock returns the
The underlying clock is useful if you want to make decisions based on the clock times while the presentation clock is stopped or paused.
If the time source does not expose an underlying clock, the method returns
Applies to: desktop apps | Metro style apps
Enables the quality manager to adjust the audio or video quality of a component in the pipeline.
This interface is exposed by pipeline components that can adjust their quality. Typically it is exposed by decoders and stream sinks. For example, the enhanced video renderer (EVR) implements this interface. However, media sources can also implement this interface.
To get a reference to this interface from a media source, call
The quality manager typically obtains this interface when the quality manager's
Applies to: desktop apps | Metro style apps
Sets the drop mode. In drop mode, a component drops samples, more or less aggressively depending on the level of the drop mode.
\t\nRequested drop mode, specified as a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The component does not support the specified mode or any higher modes. |
?
If this method is called on a media source, the media source might switch between thinned and non-thinned output. If that occurs, the affected streams will send an
Applies to: desktop apps | Metro style apps
Sets the quality level. The quality level determines how the component consumes or produces samples.
\t\nRequested quality level, specified as a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The component does not support the specified quality level or any levels below it. |
?
Applies to: desktop apps | Metro style apps
Retrieves the current drop mode.
\t\nReceives the drop mode, specified as a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the current quality level.
\t\nReceives the quality level, specified as a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Drops samples over a specified interval of time.
\t\nAmount of time to drop, in 100-nanosecond units. This value is always absolute. If the method is called multiple times, do not add the times from previous calls.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object does not support this method. |
?
Ideally the quality manager can prevent a renderer from falling behind. But if this does occur, then simply lowering quality does not guarantee the renderer will ever catch up. As a result, audio and video might fall out of sync. To correct this problem, the quality manager can call DropTime to request that the renderer drop samples quickly over a specified time interval. After that period, the renderer stops dropping samples.
This method is primarily intended for the video renderer. Dropped audio samples cause audio glitching, which is not desirable.
If a component does not support this method, it should return
Applies to: desktop apps | Metro style apps
Retrieves the current drop mode.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the current quality level.
\t\nApplies to: desktop apps | Metro style apps
Enables a pipeline object to adjust its own audio or video quality, in response to quality messages.
\t\nThis interface enables a pipeline object to respond to quality messages from the media sink. Currently, it is supported only for video decoders.
If a video decoder exposes
If the decoder exposes
The preceding remarks apply to the default implementation of the quality manager; custom quality managers can implement other behaviors.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Forwards an
If this method succeeds, it returns
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Queries an object for the number of quality modes it supports. Quality modes are used to adjust the trade-off between quality and speed when rendering audio or video.
The default presenter for the enhanced video renderer (EVR) implements this interface. The EVR uses the interface to respond to quality messages from the quality manager.
\t\nApplies to: desktop apps | Metro style apps
Gets the maximum drop mode. A higher drop mode means that the object will, if needed, drop samples more aggressively to match the presentation clock.
\t\nReceives the maximum drop mode, specified as a member of the
If this method succeeds, it returns
To get the current drop mode, call the
Applies to: desktop apps | Metro style apps
Gets the minimum quality level that is supported by the component.
\t\nReceives the minimum quality level, specified as a member of the
If this method succeeds, it returns
To get the current quality level, call the
Applies to: desktop apps | Metro style apps
Gets the maximum drop mode. A higher drop mode means that the object will, if needed, drop samples more aggressively to match the presentation clock.
\t\nTo get the current drop mode, call the
Applies to: desktop apps | Metro style apps
Gets the minimum quality level that is supported by the component.
\t\nTo get the current quality level, call the
Applies to: desktop apps only
Called when the media processor is about to deliver an input sample to a pipeline component.
\t\nThis method is called for every sample passing through every pipeline component. Therefore, the method must return quickly to avoid introducing too much latency into the pipeline.
\t\nApplies to: desktop apps only
Called when the Media Session is about to start playing a new topology.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
In a typical quality manager this method does the following:
Enumerates the nodes in the topology.
Calls
Queries for the
The quality manager can then use the
Applies to: desktop apps only
Called when the Media Session selects a presentation clock.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Called when the media processor is about to deliver an input sample to a pipeline component.
\t\nPointer to the
Index of the input stream on the topology node.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method is called for every sample passing through every pipeline component. Therefore, the method must return quickly to avoid introducing too much latency into the pipeline.
\t\nApplies to: desktop apps only
Called after the media processor gets an output sample from a pipeline component.
\t\nPointer to the
Index of the output stream on the topology node.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method is called for every sample passing through every pipeline component. Therefore, the method must return quickly to avoid introducing too much latency into the pipeline.
\t\nApplies to: desktop apps only
Called when a pipeline component sends an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Called when the Media Session is shutting down.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The quality manager should release all references to the Media Session when this method is called.
\t\nApplies to: desktop apps | Metro style apps
Gets or sets the playback rate.
\t\nObjects can expose this interface as a service. To obtain a reference to the interface, call
For more information, see About Rate Control.
To discover the playback rates that an object supports, use the
Applies to: desktop apps | Metro style apps
Sets the playback rate.
\t\nIf TRUE, the media streams are thinned. Otherwise, the stream is not thinned. For media sources and demultiplexers, the object must thin the streams when this parameter is TRUE. For downstream transforms, such as decoders and multiplexers, this parameter is informative; it notifies the object that the input streams are thinned. For information, see About Rate Control.
The requested playback rate. Postive values indicate forward playback, negative values indicate reverse playback, and zero indicates scrubbing (the source delivers a single frame).
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object does not support reverse playback. |
| | The object does not support thinning. |
| | The object does not support the requested playback rate. |
| | The object cannot change to the new rate while in the running state. |
?
The Media Session prevents some transitions between rate boundaries, depending on the current playback state:
| Playback State | Forward/Reverse | Forward/Zero | Reverse/Zero |
|---|---|---|---|
| Running | No | No | No |
| Paused | No | Yes | No |
| Stopped | Yes | Yes | Yes |
?
If the transition is not supported, the method returns
When a media source completes a call to SetRate, it sends the
If a media source switches between thinned and non-thinned playback, the streams send an
When the Media Session completes a call to SetRate, it sends the
Applies to: desktop apps | Metro style apps
Gets the current playback rate.
\t\nReceives the current playback rate.
Receives the value TRUE if the stream is currently being thinned. If the object does not support thinning, this parameter always receives the value
Applies to: desktop apps | Metro style apps
Queries the range of playback rates that are supported, including reverse playback.
To get a reference to this interface, call
Applications can use this interface to discover the fastest and slowest playback rates that are possible, and to query whether a given playback rate is supported. Applications obtain this interface from the Media Session. Internally, the Media Session queries the objects in the pipeline. For more information, see How to Determine Supported Rates.
To get the current playback rate and to change the playback rate, use the
Playback rates are expressed as a ratio the normal playback rate. Reverse playback is expressed as a negative rate. Playback is either thinned or non-thinned. In thinned playback, some of the source data is skipped (typically delta frames). In non-thinned playback, all of the source data is rendered.
You might need to implement this interface if you are writing a pipeline object (media source, transform, or media sink). For more information, see Implementing Rate Control.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the slowest playback rate supported by the object.
\t\nSpecifies whether to query to the slowest forward playback rate or reverse playback rate. The value is a member of the
If TRUE, the method retrieves the slowest thinned playback rate. Otherwise, the method retrieves the slowest non-thinned playback rate. For information about thinning, see About Rate Control.
Receives the slowest playback rate that the object supports.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object does not support reverse playback. |
| | The object does not support thinning. |
?
The value returned in plfRate represents a lower bound. Playback at this rate is not guaranteed. Call
If eDirection is
Applies to: desktop apps | Metro style apps
Gets the fastest playback rate supported by the object.
\t\nSpecifies whether to query to the fastest forward playback rate or reverse playback rate. The value is a member of the
If TRUE, the method retrieves the fastest thinned playback rate. Otherwise, the method retrieves the fastest non-thinned playback rate. For information about thinning, see About Rate Control.
Receives the fastest playback rate that the object supports.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object does not support reverse playback. |
| | The object does not support thinning. |
?
For some formats (such as ASF), thinning means dropping all frames that are not I-frames. If a component produces stream data, such as a media source or a demultiplexer, it should pay attention to the fThin parameter and return
If the component processes or receives a stream (most transforms or media sinks), it may ignore this parameter if it does not care whether the stream is thinned. In the Media Session's implementation of rate support, if the transforms do not explicitly support reverse playback, the Media Session will attempt to playback in reverse with thinning but not without thinning. Therefore, most applications will set fThin to TRUE when using the Media Session for reverse playback.
If eDirection is
Applies to: desktop apps | Metro style apps
Queries whether the object supports a specified playback rate.
\t\nIf TRUE, the method queries whether the object supports the playback rate with thinning. Otherwise, the method queries whether the object supports the playback rate without thinning. For information about thinning, see About Rate Control.
The playback rate to query.
If the object does not support the playback rate given in flRate, this parameter receives the closest supported playback rate. If the method returns
The method returns an
| Return code | Description |
|---|---|
| | The object supports the specified rate. |
| | The object does not support reverse playback. |
| | The object does not support thinning. |
| | The object does not support the specified rate. |
?
Applies to: desktop apps | Metro style apps
Creates an instance of either the sink writer or the source reader.
\t\nTo get a reference to this interface, call the CoCreateInstance function. The CLSID is CLSID_MFReadWriteClassFactory. Call the
As an alternative to using this interface, you can call any of the following functions:
Internally, these functions use the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Creates an instance of the sink writer or source reader, given a URL.
\t\nThe CLSID of the object to create.
| Value | Meaning |
|---|---|
| Create the sink writer. The ppvObject parameter receives an |
| Create the source reader. The ppvObject parameter receives an |
?
A null-terminated string that contains a URL. If clsid is CLSID_MFSinkWriter, the URL specifies the name of the output file. The sink writer creates a new file with this name. If clsid is CLSID_MFSourceReader, the URL specifies the input file for the source reader.
A reference to the
This parameter can be
The IID of the requested interface.
Receives a reference to the requested interface. The caller must release the interface.
If this method succeeds, it returns
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Creates an instance of the sink writer or source reader, given an
The CLSID of the object to create.
| Value | Meaning |
|---|---|
| Create the sink writer. The ppvObject parameter receives an |
| Create the source reader. The ppvObject parameter receives an |
?
A reference to the
| Value | Meaning |
|---|---|
| Pointer to a byte stream. If clsid is CLSID_MFSinkWriter, the sink writer writes data to this byte stream. If clsid is CLSID_MFSourceReader, this byte stream provides the source data for the source reader. | |
| Pointer to a media sink. Applies only when clsid is CLSID_MFSinkWriter. | |
| Pointer to a media source. Applies only when clsid is CLSID_MFSourceReader. |
?
A reference to the
This parameter can be
The IID of the requested interface.
Receives a reference to the requested interface. The caller must release the interface.
If this method succeeds, it returns
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps only
Notifies a pipeline object to register itself with the Multimedia Class Scheduler Service (MMCSS).
Any pipeline object that creates worker threads should implement this interface.
\t\nMedia Foundation provides a mechanism for applications to associate branches in the topology with MMCSS tasks. A topology branch is defined by a source node in the topology and all of the nodes downstream from it. An application registers a topology branch with MMCSS by setting the
When the application registers a topology branch with MMCSS, the Media Session queries every pipeline object in that branch for the
When the application unregisters the topology branch, the Media Session calls UnregisterThreads.
If a pipeline object creates its own worker threads but does not implement this interface, it can cause priority inversions in the Media Foundation pipeline, because high-priority processing threads might be blocked while waiting for the component to process data on a thread with lower priority.
Pipeline objects that do not create worker threads do not need to implement this interface.
\t\nApplies to: desktop apps only
Notifies the object to register its worker threads with the Multimedia Class Scheduler Service (MMCSS).
\t\nThe MMCSS task identifier.
The name of the MMCSS task.
If this method succeeds, it returns
The object's worker threads should register themselves with MMCSS by calling AvSetMmThreadCharacteristics, using the task name and identifier specified in this method.
\t\nApplies to: desktop apps only
Notifies the object to unregister its worker threads from the Multimedia Class Scheduler Service (MMCSS).
\t\nIf this method succeeds, it returns
The object's worker threads should unregister themselves from MMCSS by calling AvRevertMmThreadCharacteristics.
\t\nApplies to: desktop apps only
Specifies the work queue for the topology branch that contains this object.
\t\nThe identifier of the work queue, or the value MFASYNC_CALLBACK_QUEUE_UNDEFINED. See Remarks.
If this method succeeds, it returns
An application can register a branch of the topology to use a private work queue. The Media Session notifies any pipeline object that supports
When the application unregisters the topology branch, the Media Session calls SetWorkQueue again with the value MFASYNC_CALLBACK_QUEUE_UNDEFINED.
\t\nApplies to: desktop apps only
Specifies the work queue for the topology branch that contains this object.
\t\n An application can register a branch of the topology to use a private work queue. The Media Session notifies any pipeline object that supports
When the application unregisters the topology branch, the Media Session calls SetWorkQueue again with the value MFASYNC_CALLBACK_QUEUE_UNDEFINED.
\t\nApplies to: desktop apps only
Used by the Microsoft Media Foundation proxy/stub DLL to marshal certain asynchronous method calls across process boundaries.
Applications do not use or implement this interface.
\t\nApplies to: desktop apps only
Used by the Microsoft Media Foundation proxy/stub DLL to marshal certain asynchronous method calls across process boundaries.
Applications do not use or implement this interface.
\t\nApplies to: desktop apps only
Modifies a topology for use in a Terminal Services environment.
\t\nTo use this interface, do the following:
The application must call UpdateTopology before calling
Applies to: desktop apps only
Modifies a topology for use in a Terminal Services environment.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If the application is running in a Terminal Services client session, call this method before calling
Applies to: desktop apps only
Retrieves a reference to the remote object for which this object is a proxy.
\t\nApplies to: desktop apps only
Retrieves a reference to the remote object for which this object is a proxy.
\t\nInterface identifier (IID) of the requested interface.
Receives a reference to the requested interface. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets and retrieves Synchronized Accessible Media Interchange (SAMI) styles on the SAMI Media Source.
\t\n To get a reference to this interface, call
Gets the total number of SAMI styles supported by the media source.
pdwCount
[out] Pointer to a DWORD that receives the number of SAMI styles. This parameter cannot be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| E_POINTER | |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFSAMIStyle Interface\t\nApplies to: desktop apps only
Gets a list of the style names defined in the SAMI file.
\t\nPointer to a
If this method succeeds, it returns
Applies to: desktop apps only
Sets the current style on the SAMI media source.
\t\nPointer to a null-terminated string containing the name of the style. To clear the current style, pass an empty string (\"\"). To get the list of style names, call
If this method succeeds, it returns
Gets the currently selected SAMI style on the media source.
pwszStyle
[out] Pointer to a null-terminated string that receives the name of the style. Value of \"\" indicates that no style has been set. This parameter cannot be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| E_POINTER | |
To avoid memory leaks, the caller must de-allocate the returned string by calling CoTaskMemFree.
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFSAMIStyle Interface\t\nGets the total number of SAMI styles supported by the media source.
pdwCount
[out] Pointer to a DWORD that receives the number of SAMI styles. This parameter cannot be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| E_POINTER | |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFSAMIStyle Interface\t\nApplies to: desktop apps only
Gets a list of the style names defined in the SAMI file.
\t\nApplies to: desktop apps | Metro style apps
Represents a media sample, which is a container object for media data. For video, a sample typically contains one video frame. For audio data, a sample typically contains multiple audio samples, rather than a single sample of audio.
A media sample contains zero or more buffers. Each buffer manages a block of memory, and is represented by the
To create a new media sample, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves flags associated with the sample.
Currently no flags are defined. Instead, metadata for samples is defined using attributes. To get attibutes from a sample, use the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets flags associated with the sample.
Currently no flags are defined. Instead, metadata for samples is defined using attributes. To set attibutes on a sample, use the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the presentation time of the sample.
\t\nReceives the presentation time, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The sample does not have a presentation time. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the presentation time of the sample.
\t\nThe presentation time, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Some pipeline components require samples that have time stamps. Generally the component that generates the data for the sample also sets the time stamp. The Media Session might modify the time stamps.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the duration of the sample.
\t\nReceives the duration, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The sample does not have a specified duration. |
?
If the sample contains more than one buffer, the duration includes the data from all of the buffers.
If the retrieved duration is zero, or if the method returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the duration of the sample.
\t\nDuration of the sample, in 100-nanosecond units.
If this method succeeds, it returns
This method succeeds if the duration is negative, although negative durations are probably not valid for most types of data. It is the responsibility of the object that consumes the sample to validate the duration.
The duration can also be zero. This might be valid for some types of data. For example, the sample might contain stream metadata with no buffers.
Until this method is called, the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of buffers in the sample.
\t\nReceives the number of buffers in the sample. A sample might contain zero buffers.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets a buffer from the sample, by index.
Note??In most cases, it is safer to use the
A sample might contain more than one buffer. Use the GetBufferByIndex method to enumerate the individual buffers.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Converts a sample with multiple buffers into a sample with a single buffer.
\t\nReceives a reference to the
If the sample contains more than one buffer, this method copies the data from the original buffers into a new buffer, and replaces the original buffer list with the new buffer. The new buffer is returned in the ppBuffer parameter.
If the sample contains a single buffer, this method returns a reference to the original buffer. In typical use, most samples do not contain multiple buffers.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds a buffer to the end of the list of buffers in the sample.
\t\nPointer to the buffer's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
?
For uncompressed video data, each buffer should contain a single video frame, and samples should not contain multiple frames. In general, storing multiple buffers in a sample is discouraged.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Removes a buffer at a specified index from the sample.
\t\nIndex of the buffer. To find the number of buffers in the sample, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Removes all of the buffers from the sample.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the total length of the valid data in all of the buffers in the sample. The length is calculated as the sum of the values retrieved by the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Copies the sample data to a buffer. This method concatenates the valid data from all of the buffers of the sample, in order.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
| | The buffer is not large enough to contain the data. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves flags associated with the sample.
Currently no flags are defined. Instead, metadata for samples is defined using attributes. To get attibutes from a sample, use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the presentation time of the sample.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the duration of the sample.
\t\nIf the sample contains more than one buffer, the duration includes the data from all of the buffers.
If the retrieved duration is zero, or if the method returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of buffers in the sample.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the total length of the valid data in all of the buffers in the sample. The length is calculated as the sum of the values retrieved by the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps only
Callback interface to get media data from the sample-grabber sink.
\t\nThe sample-grabber sink enables an application to get data from the Media Foundation pipeline without implementing a custom media sink. To use the sample-grabber sink, the application must perform the following steps:
Implement the
Call
Create a topology that includes an output node with the sink's
Pass this topology to the Media Session.
During playback, the sample-grabber sink calls methods on the application's callback.
You cannot use the sample-grabber sink to get protected content.
\t\nApplies to: desktop apps only
Called when the presentation clock is set on the sample-grabber sink.
\t\nPointer to the presentation clock's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method should return quickly, or it might interfere with playback. Do not block the thread, wait on events, or perform other lengthy operations inside this method.
\t\nApplies to: desktop apps only
Called when the sample-grabber sink receives a new media sample.
\t\nThe major type that specifies the format of the data. For a list of possible values, see Major Media Types.
Reserved.
The presentation time for this sample, in 100-nanosecond units. If the sample does not have a presentation time, the value of this parameter is _I64_MAX.
The duration of the sample, in 100-nanosecond units. If the sample does not have a duration, the value of this parameter is _I64_MAX.
A reference to a buffer that contains the sample data.
Size of the pSampleBuffer buffer, in bytes.
If this method succeeds, it returns
If you use the sample-grabber sink in a playback topology, this method should return quickly, or it might interfere with playback. Do not block the thread, wait on events, or perform other lengthy operations inside this method.
\t\nApplies to: desktop apps only
Called when the sample-grabber sink is shut down.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method is called when the sink's
The OnShutdown method should return quickly, or it might interfere with playback. Do not block the thread, wait on events, or perform other lengthy operations inside this method.
\t\nApplies to: desktop apps only
Extends the
This callback interface is used with the sample-grabber sink. It extends the
The OnProcessSampleEx method adds a parameter that contains the attributes for the media sample. You can use the attributes to get information about the sample, such as field dominance and telecine flags.
To use this interface, do the following:
Applies to: desktop apps only
Called when the sample-grabber sink receives a new media sample.
\t\nThe major type
Sample flags. The sample-grabber sink gets the value of this parameter by calling the
The presentation time for this sample, in 100-nanosecond units. If the sample does not have a presentation time, the value of this parameter is _I64_MAX
The duration of the sample, in 100-nanosecond units. If the sample does not have a duration, the value of this parameter is _I64_MAX.
A reference to a buffer that contains the sample data.
The size, in bytes, of the pSampleBuffer buffer.
A reference to the
If this method succeeds, it returns
If you use the sample-grabber sink in a playback topology, this method should return quickly, or it might interfere with playback. Do not block the thread, wait on events, or perform other lengthy operations inside this method.
\t\nApplies to: desktop apps | Metro style apps
Retrieves initialization information for sample protection from the upstream component.
\t\nThis method must be implemented by the upstream component. The method fails if the component does not support the requested sample protection version. Downstream components do not implement this method and should return E_NOTIMPL.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the version of sample protection that the component implements on input.
\t\nReceives a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the version of sample protection that the component implements on output.
\t\nReceives a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the sample protection certificate.
\t\nSpecifies the version number of the sample protection scheme for which to receive a certificate. The version number is specified as a
Receives a reference to a buffer containing the certificate. The caller must free the memory for the buffer by calling CoTaskMemFree.
Receives the size of the ppCert buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
?
For certain version numbers of sample protection, the downstream component must provide a certificate. Components that do not support these version numbers can return E_NOTIMPL.
\t\nApplies to: desktop apps | Metro style apps
Retrieves initialization information for sample protection from the upstream component.
\t\nSpecifies the version number of the sample protection scheme. The version number is specified as a
Identifier of the output stream. The identifier corresponds to the output stream identifier returned by the
Pointer to a certificate provided by the downstream component.
Size of the certificate, in bytes.
Receives a reference to a buffer that contains the initialization information for downstream component. The caller must free the memory for the buffer by calling CoTaskMemFree.
Receives the size of the ppbSeed buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
?
This method must be implemented by the upstream component. The method fails if the component does not support the requested sample protection version. Downstream components do not implement this method and should return E_NOTIMPL.
\t\nApplies to: desktop apps | Metro style apps
Initializes sample protection on the downstream component.
\t\nSpecifies the version number of the sample protection scheme. The version number is specified as a
Identifier of the input stream. The identifier corresponds to the output stream identifier returned by the
Pointer to a buffer that contains the initialization data provided by the upstream component. To retrieve this buffer, call
Size of the pbSeed buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the version of sample protection that the component implements on input.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the version of sample protection that the component implements on output.
\t\nApplies to: desktop apps only
Persists media data from a source byte stream to an application-provided byte stream.
The byte stream used for HTTP download implements this interface. To get a reference to this interface, call
Applies to: desktop apps only
Begins saving a Windows Media file to the application's byte stream.
\t\nPointer to the
Pointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
When the operation completes, the callback object's
Applies to: desktop apps only
Completes the operation started by
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Cancels the operation started by
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the percentage of content saved to the provided byte stream.
\t\nReceives the percentage of completion.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the percentage of content saved to the provided byte stream.
\t\nApplies to: desktop apps only
Retrieves the client's certificate.
\t\nApplies to: desktop apps only
Retrieves the client's certificate.
\t\nReceives a reference to a buffer allocated by the object. The buffer contains the client's certificate. The caller must release the buffer by calling CoTaskMemFree.
Receives the size of the ppCert buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Passes the encrypted session key to the client.
\t\nPointer to a buffer that contains the encrypted session key. This parameter can be
Size of the pbEncryptedSessionKey buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Implemented by the Sequencer Source. The sequencer source enables an application to create a sequence of topologies. To create the sequencer source, call
Applies to: desktop apps only
Adds a topology to the end of the queue.
\t\nPointer to the
A combination of flags from the
Receives the sequencer element identifier for this topology.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The source topology node is missing one of the following attributes: |
?
The sequencer plays topologies in the order they are queued. You can queue as many topologies as you want to preroll.
The application must indicate to the sequencer when it has queued the last topology on the Media Session. To specify the last topology, set the SequencerTopologyFlags_Last flag in the dwFlags parameter when you append the topology. The sequencer uses this information to end playback with the pipeline. Otherwise, the sequencer waits indefinitely for a new topology to be queued.
\t\nApplies to: desktop apps only
Deletes a topology from the queue.
\t\nThe sequencer element identifier of the topology to delete.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Maps a presentation descriptor to its associated sequencer element identifier and the topology it represents.
\t\nPointer to the
Receives the sequencer element identifier. This value is assigned by the sequencer source when the application calls
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The presentation descriptor is not valid. |
| This segment was canceled. |
?
The topology returned in ppTopology is the original topology that the application specified in AppendTopology. The source nodes in this topology contain references to the native sources. Do not queue this topology on the Media Session. Instead, call
Updates a topology in the queue.
dwId
[in] Sequencer element identifier of the topology to update.
pTopology
[in] Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The sequencer source has been shut down. |
This method is asynchronous. When the operation is completed, the sequencer source sends an
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFSequencerSource InterfaceOther ResourcesSequencer Source\t\nApplies to: desktop apps only
Updates the flags for a topology in the queue.
\t\nSequencer element identifier of the topology to update.
Bitwise OR of flags from the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Queries an object for a specified service interface.
\t\nA service is an interface that is exposed by one object but might be implemented by another object. The GetService method is equivalent to QueryInterface, with the following difference: when QueryInterface retrieves a reference to an interface, it is guaranteed that you can query the returned interface and get back the original interface. The GetService method does not make this guarantee, because the retrieved interface might be implemented by a separate object.
The
Applies to: desktop apps | Metro style apps
Retrieves a service interface.
\t\nThe service identifier (SID) of the service. For a list of service identifiers, see Service Interfaces.
The interface identifier (IID) of the interface being requested.
Receives the interface reference. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The object does not support the service. |
?
Applies to: desktop apps | Metro style apps
Queries the status of an earlier call to the
Until Shutdown is called, the GetShutdownStatus method returns
If an object's Shutdown method is asynchronous, pStatus might receive the value
Applies to: desktop apps | Metro style apps
Shuts down a Media Foundation object and releases all resources associated with the object.
\t\nIf this method succeeds, it returns
The
Applies to: desktop apps | Metro style apps
Queries the status of an earlier call to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | The Shutdown method has not been called on this object. |
?
Until Shutdown is called, the GetShutdownStatus method returns
If an object's Shutdown method is asynchronous, pStatus might receive the value
Applies to: desktop apps | Metro style apps
Queries the status of an earlier call to the
Until Shutdown is called, the GetShutdownStatus method returns
If an object's Shutdown method is asynchronous, pStatus might receive the value
Applies to: desktop apps | Metro style apps
Begins an asynchronous request to create an object from a URL.
When the Source Resolver creates a media source from a URL, it passes the request to a scheme handler. The scheme handler might create a media source directly from the URL, or it might return a byte stream. If it returns a byte stream, the source resolver use a byte-stream handler to create the media source from the byte stream.
\t\nThe dwFlags parameter must contain the
If the
The following table summarizes the behavior of these two flags when passed to this method:
| Flag | Object created |
|---|---|
| Media source or byte stream | |
| Byte stream |
?
The
When the operation completes, the scheme handler calls the
Applies to: desktop apps | Metro style apps
Begins an asynchronous request to create an object from a URL.
When the Source Resolver creates a media source from a URL, it passes the request to a scheme handler. The scheme handler might create a media source directly from the URL, or it might return a byte stream. If it returns a byte stream, the source resolver use a byte-stream handler to create the media source from the byte stream.
\t\n The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Cannot open the URL with the requested access (read or write). |
| | Unsupported byte stream type. |
?
The dwFlags parameter must contain the
If the
The following table summarizes the behavior of these two flags when passed to this method:
| Flag | Object created |
|---|---|
| Media source or byte stream | |
| Byte stream |
?
The
When the operation completes, the scheme handler calls the
Applies to: desktop apps | Metro style apps
Cancels the current request to create an object from a URL.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
You can use this method to cancel a previous call to BeginCreateObject. Because that method is asynchronous, however, it might be completed before the operation can be canceled. Therefore, your callback might still be invoked after you call this method.
The operation cannot be canceled if BeginCreateObject returns
Applies to: desktop apps only
Controls the master volume level of the audio session associated with the streaming audio renderer (SAR) and the audio capture source.
The SAR and the audio capture source expose this interface as a service. To get a reference to the interface, call
To control the volume levels of individual channels, use the
Volume is expressed as an attenuation level, where 0.0 indicates silence and 1.0 indicates full volume (no attenuation). For each channel, the attenuation level is the product of:
The master volume level of the audio session.
The volume level of the channel.
For example, if the master volume is 0.8 and the channel volume is 0.5, the attenuaton for that channel is 0.8 ? 0.5 = 0.4. Volume levels can exceed 1.0 (positive gain), but the audio engine clips any audio samples that exceed zero decibels. To change the volume level of individual channels, use the
Use the following formula to convert the volume level to the decibel (dB) scale:
Attenuation (dB) = 20 * log10(Level)
For example, a volume level of 0.50 represents 6.02 dB of attenuation.
\t\nApplies to: desktop apps only
Sets the master volume level.
\t\nVolume level. Volume is expressed as an attenuation level, where 0.0 indicates silence and 1.0 indicates full volume (no attenuation).
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The audio renderer is not initialized. |
| | The audio renderer was removed from the pipeline. |
?
Events outside of the application can change the master volume level. For example, the user can change the volume from the system volume-control program (SndVol). If an external event changes the master volume, the audio renderer sends an
Applies to: desktop apps only
Retrieves the master volume level.
\t\nReceives the volume level. Volume is expressed as an attenuation level, where 0.0 indicates silence and 1.0 indicates full volume (no attenuation).
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The audio renderer is not initialized. |
| | The audio renderer was removed from the pipeline. |
?
If an external event changes the master volume, the audio renderer sends an
Applies to: desktop apps only
Mutes or unmutes the audio.
\t\nSpecify TRUE to mute the audio, or
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The audio renderer is not initialized. |
| | The audio renderer was removed from the pipeline. |
?
This method does not change the volume level returned by the
Applies to: desktop apps only
Queries whether the audio is muted.
\t\nReceives a Boolean value. If TRUE, the audio is muted; otherwise, the audio is not muted.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The audio renderer is not initialized. |
| | The audio renderer was removed from the pipeline. |
?
Calling
Applies to: desktop apps only
Retrieves the master volume level.
\t\nIf an external event changes the master volume, the audio renderer sends an
Applies to: desktop apps only
Queries whether the audio is muted.
\t\nCalling
Applies to: desktop apps | Metro style apps
Implemented by the Microsoft Media Foundation sink writer object.
\t\nTo create the sink writer, call one of the following functions:
Alternatively, use the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Adds a stream to the sink writer.
\t\nA reference to the
Receives the zero-based index of the new stream.
If this method succeeds, it returns
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Sets the input format for a stream on the sink writer.
\t\nThe zero-based index of the stream. The index is received by the pdwStreamIndex parameter of the
A reference to the
A reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The underlying media sink does not support the format, no conversion is possible, or a dynamic format change is not possible. |
| | The dwStreamIndex parameter is invalid. |
| | Could not find an encoder for the encoded format. |
?
The input format does not have to match the target format that is written to the media sink. If the formats do not match, the method attempts to load an encoder that can encode from the input format to the target format.
After streaming begins?that is, after the first call to
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Initializes the sink writer for writing.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The request is invalid. |
?
Call this method after you configure the input streams and before you send any data to the sink writer.
You must call BeginWriting before calling any of the following methods:
The underlying media sink must have at least one input stream. Otherwise, BeginWriting returns
If BeginWriting succeeds, any further calls to BeginWriting return
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Delivers a sample to the sink writer.
\t\nThe zero-based index of the stream for this sample.
A reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The request is invalid. |
?
You must call
By default, the sink writer limits the rate of incoming data by blocking the calling thread inside the WriteSample method. This prevents the application from delivering samples too quickly. To disable this behavior, set the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Indicates a gap in an input stream.
\t\nThe zero-based index of the stream.
The position in the stream where the gap in the data occurs. The value is given in 100-nanosecond units, relative to the start of the stream.
If this method succeeds, it returns
For video, call this method once for each missing frame. For audio, call this method at least once per second during a gap in the audio. Set the
Internally, this method calls
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Places a marker in the specified stream.
\t\nThe zero-based index of the stream.
Pointer to an application-defined value. The value of this parameter is returned to the caller in the pvContext parameter of the caller's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The request is invalid. |
?
To use this method, you must provide an asynchronous callback when you create the sink writer. Otherwise, the method returns
Markers provide a way to be notified when the media sink consumes all of the samples in a stream up to a certain point. The media sink does not process the marker until it has processed all of the samples that came before the marker. When the media sink processes the marker, the sink writer calls the application's OnMarker method. When the callback is invoked, you know that the sink has consumed all of the previous samples for that stream.
For example, to change the format midstream, call PlaceMarker at the point where the format changes. When OnMarker is called, it is safe to call
Internally, this method calls
Note??The pvContext parameter of the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Notifies the media sink that a stream has reached the end of a segment.
\t\nThe zero-based index of a stream, or
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The request is invalid. |
?
You must call
This method sends an
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Flushes one or more streams.
\t\nThe zero-based index of the stream to flush, or
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The request is invalid. |
?
You must call
For each stream that is flushed, the sink writer drops all pending samples, flushes the encoder, and sends an
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Completes all writing operations on the sink writer.
\t\nIf this method succeeds, it returns
Call this method after you send all of the input samples to the sink writer. The method performs any operations needed to create the final output from the media sink.
If you provide a callback interface when you create the sink writer, this method completes asynchronously. When the operation completes, the
Internally, this method calls
After this method is called, the following methods will fail:
If you do not call Finalize, the output from the media sink might be incomplete or invalid. For example, required file headers might be missing from the output file.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Queries the underlying media sink or encoder for an interface.
\t\nThe zero-based index of a stream to query, or
A service identifier
The interface identifier (IID) of the interface being requested.
Receives a reference to the requested interface. The caller must release the interface.
If this method succeeds, it returns
If the dwStreamIndex parameter equals
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets statistics about the performance of the sink writer.
\t\nThe zero-based index of a stream to query, or
A reference to an
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| | Invalid stream number. |
?
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Callback interface for the Microsoft Media Foundation sink writer.
\t\nSet the callback reference by setting the
The callback methods can be called from any thread, so an object that implements this interface must be thread-safe.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Called when the
Returns an
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Called when the
Returns an
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps only
Called by the network source when the open operation begins or ends.
\t\nThe networks source calls this method with the following event types.
For more information, see How to Get Events from the Network Source.
\t\nApplies to: desktop apps only
Called by the network source when the open operation begins or ends.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The networks source calls this method with the following event types.
For more information, see How to Get Events from the Network Source.
\t\nApplies to: desktop apps | Metro style apps
Implemented by the Microsoft Media Foundation source reader object.
\t\nTo create the source reader, call one of the following functions:
Alternatively, use the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Queries whether a stream is selected.
\t\nThe stream to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
?
Receives TRUE if the stream is selected and will generate data. Receives
If this method succeeds, it returns
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Selects or deselects one or more streams.
\t\nThe stream to set. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| All streams. |
?
Specify TRUE to select streams or
If this method succeeds, it returns
There are two common uses for this method:
For an example of deselecting a stream, see Tutorial: Decoding Audio.
If a stream is deselected, the
Stream selection does not affect how the source reader loads or unloads decoders in memory. In particular, deselecting a stream does not force the source reader to unload the decoder for that stream.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets a format that is supported natively by the media source.
\t\nSpecifies which stream to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
?
The zero-based index of the media type to retrieve.
Receives a reference to the
This method queries the underlying media source for its native output format. Potentially, each source stream can produce more than one output format. Use the dwMediaTypeIndex parameter to loop through the available formats. Generally, file sources offer just one format per stream, but capture devices might offer several formats.
The method returns a copy of the media type, so it is safe to modify the object received in the ppMediaType parameter.
To set the output type for a stream, call the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets the current media type for a stream.
\t\nThe stream to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
?
Receives a reference to the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Sets the media type for a stream.
This media type defines that format that the Source Reader produces as output. It can differ from the native format provided by the media source. See Remarks for more information.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | At least one decoder was found for the native stream type, but the type specified by pMediaType was rejected. |
| | One or more sample requests are still pending. |
| | The dwStreamIndex parameter is invalid. |
| | Could not find a decoder for the native stream type. |
?
For each stream, you can set the media type to any of the following:
The source reader does not support audio resampling. If you need to resample the audio, you can use the Audio Resampler DSP.
If you set the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Seeks to a new position in the media source.
\t\nA
| Value | Meaning |
|---|---|
| 100-nanosecond units. |
?
Some media sources might support additional values.
The position from which playback will be started. The units are specified by the guidTimeFormat parameter. If the guidTimeFormat parameter is GUID_NULL, set the variant type to VT_I8.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | One or more sample requests are still pending. |
?
The SetCurrentPosition method does not guarantee exact seeking. The accuracy of the seek depends on the media content. If the media content contains a video stream, the SetCurrentPosition method typically seeks to the nearest key frame before the desired position. The distance between key frames depends on several factors, including the encoder implementation, the video content, and the particular encoding settings used to encode the content. The distance between key frame can vary within a single video file (for example, depending on scene complexity).
After seeking, the application should call
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Reads the next sample from the media source.
\t\nThe stream to pull data from. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| Get the next available sample, regardless of which stream. |
?
A bitwise OR of zero or more flags from the
Receives the zero-based index of the stream.
Receives a bitwise OR of zero or more flags from the
Receives the time stamp of the sample, or the time of the stream event indicated in pdwStreamFlags. The time is given in 100-nanosecond units.
Receives a reference to the
If the requested stream is not selected, the return code is
This method can complete synchronously or asynchronously. If you provide a callback reference when you create the source reader, the method is asynchronous. Otherwise, the method is synchronous. For more information about setting the callback reference, see
In asynchronous mode:
[out] parameters must be In synchronous mode:
In synchronous mode, if the dwStreamIndex parameter is
This method can return flags in the pdwStreamFlags parameter without returning a media sample in ppSample. Therefore, the ppSample parameter can receive a
If there is a gap in the stream, pdwStreamFlags receives the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Flushes one or more streams.
\t\nThe stream to flush. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| All streams. |
?
If this method succeeds, it returns
The Flush method discards all queued samples and cancels all pending sample requests.
This method can complete either synchronously or asynchronously. If you provide a callback reference when you create the source reader, the method is asynchronous. Otherwise, the method is synchronous. For more information about the setting the callback reference, see
In synchronous mode, the method blocks until the operation is complete.
In asynchronous mode, the application's
Note??In Windows?7, there was a bug in the implementation of this method, which causes OnFlush to be called before the flush operation completes. A hotfix is available that fixes this bug. For more information, see http://support.microsoft.com/kb/979567.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Queries the underlying media source or decoder for an interface.
\t\nThe stream or object to query. If the value is
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| The media source. |
?
A service identifier
The interface identifier (IID) of the interface being requested.
Receives a reference to the requested interface. The caller must release the interface.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets an attribute from the underlying media source.
\t\nThe stream or object to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| The media source. |
?
A
Otherwise, if the dwStreamIndex parameter specifies a stream, guidAttribute specifies a stream descriptor attribute. For a list of values, see Stream Descriptor Attributes.
A reference to a
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nA reference to the
Pointer to the
Call CoInitialize(Ex) and
Internally, the source reader calls the
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nA reference to the
Pointer to the
Call CoInitialize(Ex) and
Internally, the source reader calls the
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nA reference to the
Pointer to the
Call CoInitialize(Ex) and
Internally, the source reader calls the
This function is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets a format that is supported natively by the media source.
\t\nSpecifies which stream to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
?
The zero-based index of the media type to retrieve.
Receives a reference to the
This method queries the underlying media source for its native output format. Potentially, each source stream can produce more than one output format. Use the dwMediaTypeIndex parameter to loop through the available formats. Generally, file sources offer just one format per stream, but capture devices might offer several formats.
The method returns a copy of the media type, so it is safe to modify the object received in the ppMediaType parameter.
To set the output type for a stream, call the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Selects or deselects one or more streams.
\t\nThe stream to set. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| All streams. |
?
Specify TRUE to select streams or
If this method succeeds, it returns
There are two common uses for this method:
For an example of deselecting a stream, see Tutorial: Decoding Audio.
If a stream is deselected, the
Stream selection does not affect how the source reader loads or unloads decoders in memory. In particular, deselecting a stream does not force the source reader to unload the decoder for that stream.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Sets the media type for a stream.
This media type defines that format that the Source Reader produces as output. It can differ from the native format provided by the media source. See Remarks for more information.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| At least one decoder was found for the native stream type, but the type specified by pMediaType was rejected. |
| One or more sample requests are still pending. |
| The dwStreamIndex parameter is invalid. |
| Could not find a decoder for the native stream type. |
?
For each stream, you can set the media type to any of the following:
The source reader does not support audio resampling. If you need to resample the audio, you can use the Audio Resampler DSP.
If you set the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Sets the media type for a stream.
This media type defines that format that the Source Reader produces as output. It can differ from the native format provided by the media source. See Remarks for more information.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| At least one decoder was found for the native stream type, but the type specified by pMediaType was rejected. |
| One or more sample requests are still pending. |
| The dwStreamIndex parameter is invalid. |
| Could not find a decoder for the native stream type. |
?
For each stream, you can set the media type to any of the following:
The source reader does not support audio resampling. If you need to resample the audio, you can use the Audio Resampler DSP.
If you set the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Seeks to a new position in the media source.
\t\nThe SetCurrentPosition method does not guarantee exact seeking. The accuracy of the seek depends on the media content. If the media content contains a video stream, the SetCurrentPosition method typically seeks to the nearest key frame before the desired position. The distance between key frames depends on several factors, including the encoder implementation, the video content, and the particular encoding settings used to encode the content. The distance between key frame can vary within a single video file (for example, depending on scene complexity).
After seeking, the application should call
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets the current media type for a stream.
\t\nThe stream to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
?
Receives a reference to the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Reads the next sample from the media source.
\t\nThe stream to pull data from. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| Get the next available sample, regardless of which stream. |
?
A bitwise OR of zero or more flags from the
Receives the zero-based index of the stream.
Receives a bitwise OR of zero or more flags from the
Receives the time stamp of the sample, or the time of the stream event indicated in pdwStreamFlags. The time is given in 100-nanosecond units.
Receives a reference to the
If the requested stream is not selected, the return code is MF_E_INVALIDREQUEST. See
This method can complete synchronously or asynchronously. If you provide a callback reference when you create the source reader, the method is asynchronous. Otherwise, the method is synchronous. For more information about setting the callback reference, see
In asynchronous mode:
[out] parameters must be In synchronous mode:
In synchronous mode, if the dwStreamIndex parameter is
This method can return flags in the pdwStreamFlags parameter without returning a media sample in ppSample. Therefore, the ppSample parameter can receive a
If there is a gap in the stream, pdwStreamFlags receives the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Flushes one or more streams.
\t\nThe stream to flush. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| All streams. |
?
If this method succeeds, it returns
The Flush method discards all queued samples and cancels all pending sample requests.
This method can complete either synchronously or asynchronously. If you provide a callback reference when you create the source reader, the method is asynchronous. Otherwise, the method is synchronous. For more information about the setting the callback reference, see
In synchronous mode, the method blocks until the operation is complete.
In asynchronous mode, the application's
Note??In Windows?7, there was a bug in the implementation of this method, which causes OnFlush to be called before the flush operation completes. A hotfix is available that fixes this bug. For more information, see http://support.microsoft.com/kb/979567.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Queries the underlying media source or decoder for an interface.
\t\nThe stream or object to query. If the value is
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| The media source. |
?
A service identifier
The interface identifier (IID) of the interface being requested.
Receives a reference to the requested interface. The caller must release the interface.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets an attribute from the underlying media source.
\t\nThe stream or object to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| The media source. |
?
A
Otherwise, if the dwStreamIndex parameter specifies a stream, guidAttribute specifies a stream descriptor attribute. For a list of values, see Stream Descriptor Attributes.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Gets an attribute from the underlying media source.
\t\nThe stream or object to query. The value can be any of the following.
| Value | Meaning |
|---|---|
| The zero-based index of a stream. |
| The first video stream. |
| The first audio stream. |
| The media source. |
?
A
Otherwise, if the dwStreamIndex parameter specifies a stream, guidAttribute specifies a stream descriptor attribute. For a list of values, see Stream Descriptor Attributes.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Callback interface for the Microsoft Media Foundation source reader.
\t\nUse the
The callback methods can be called from any thread, so an object that implements this interface must be thread-safe.
If you do not specify a callback reference, the source reader operates synchronously.
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Called when the
Returns an
The pSample parameter might be
If there is a gap in the stream, dwStreamFlags contains the
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Called when the
Returns an
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Called when the source reader receives certain events from the media source.
\t\nFor stream events, the value is the zero-based index of the stream that sent the event. For source events, the value is
A reference to the
Returns an
In the current implementation, the source reader uses this method to forward the following events to the application:
This interface is available on Windows?Vista if Platform Update Supplement for Windows?Vista is installed.
\t\nApplies to: desktop apps | Metro style apps
Creates a media source or a byte stream from a URL. This method is synchronous.
\t\nThe dwFlags parameter must contain either the
For local files, you can pass the file name in the pwszURL parameter; the file: scheme is not required.
Note??This method cannot be called remotely.
\t\nApplies to: desktop apps | Metro style apps
Creates a media source or a byte stream from a URL. This method is synchronous.
\t\nNull-terminated string that contains the URL to resolve.
Bitwise OR of one or more flags. See Source Resolver Flags.
Pointer to the
Receives a member of the
Receives a reference to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The dwFlags parameter contains mutually exclusive flags. |
| | The URL scheme is not supported. |
?
The dwFlags parameter must contain either the
For local files, you can pass the file name in the pwszURL parameter; the file: scheme is not required.
Note??This method cannot be called remotely.
\t\nApplies to: desktop apps | Metro style apps
Creates a media source from a byte stream. This method is synchronous.
\t\n Pointer to the byte stream's
Null-terminated string that contains the URL of the byte stream. The URL is optional and can be
Bitwise OR of flags. See Source Resolver Flags.
Pointer to the
Receives a member of the
Receives a reference to the media source's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The dwFlags parameter contains mutually exclusive flags. |
| | This byte stream is not supported. |
?
The dwFlags parameter must contain the
The source resolver attempts to find one or more byte-stream handlers for the byte stream, based on the file name extension of the URL, or the MIME type of the byte stream (or both). The URL is specified in the optional pwszURL parameter, and the MIME type may be specified in the
Note??This method cannot be called remotely.
\t\nApplies to: desktop apps | Metro style apps
Begins an asynchronous request to create a media source or a byte stream from a URL.
\t\nNull-terminated string that contains the URL to resolve.
Bitwise OR of flags. See Source Resolver Flags.
Pointer to the
Receives an
Pointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The dwFlags parameter contains mutually exclusive flags. |
| | The URL scheme is not supported. |
?
The dwFlags parameter must contain either the
For local files, you can pass the file name in the pwszURL parameter; the file: scheme is not required.
When the operation completes, the source resolver calls the
The usage of the pProps parameter depends on the implementation of the media source.
\t\nApplies to: desktop apps | Metro style apps
Completes an asynchronous request to create an object from a URL.
\t\n Pointer to the
Receives a member of the
Receives a reference to the media source's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The operation was canceled. |
?
Call this method from inside your application's
Applies to: desktop apps | Metro style apps
Begins an asynchronous request to create a media source from a byte stream.
\t\nA reference to the byte stream's
A null-terminated string that contains the original URL of the byte stream. This parameter can be
A bitwise OR of one or more flags. See Source Resolver Flags.
A reference to the
Receives an
A reference to the
A oointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The dwFlags parameter contains mutually exclusive flags. |
| | The byte stream is not supported. |
| | The byte stream does not support seeking. |
?
The dwFlags parameter must contain the
The source resolver attempts to find one or more byte-stream handlers for the byte stream, based on the file name extension of the URL, or the MIME type of the byte stream (or both). The URL is specified in the optional pwszURL parameter, and the MIME type may be specified in the
When the operation completes, the source resolver calls the
Applies to: desktop apps | Metro style apps
Completes an asynchronous request to create a media source from a byte stream.
\t\nPointer to the
Receives a member of the
Receives a reference to the media source's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The application canceled the operation. |
?
Call this method from inside your application's
Applies to: desktop apps | Metro style apps
Cancels an asynchronous request to create an object.
\t\n Pointer to the
If this method succeeds, it returns
You can use this method to cancel a previous call to BeginCreateObjectFromByteStream or BeginCreateObjectFromURL. Because these methods are asynchronous, however, they might be completed before the operation can be canceled. Therefore, your callback might still be invoked after you call this method.
Note??This method cannot be called remotely.
\t\nApplies to: desktop apps only
Indicates whether the server SSL certificate must be verified by the caller, Media Foundation, or the
Applies to: desktop apps only
Gets the client SSL certificate synchronously.
\t\nPointer to a string that contains the URL for which a client-side SSL certificate is required. Media Foundation can resolve the scheme and send the request to the server.
Pointer to the buffer that stores the certificate.This caller must free the buffer by calling CoTaskMemFree.
Pointer to a DWORD variable that receives the number of bytes required to hold the certificate data in the buffer pointed by *ppbData.
If this method succeeds, it returns
Applies to: desktop apps only
Starts an asynchronous call to get the client SSL certificate.
\t\nA null-terminated string that contains the URL for which a client-side SSL certificate is required. Media Foundation can resolve the scheme and send the request to the server.
A reference to the
A reference to the
If this method succeeds, it returns
When the operation completes, the callback object's
Applies to: desktop apps only
Completes an asynchronous request to get the client SSL certificate.
\t\nA reference to the
Receives a reference to the buffer that stores the certificate.The caller must free the buffer by calling CoTaskMemFree.
Receives the size of the ppbData buffer, in bytes.
If this method succeeds, it returns
Call this method after the
Applies to: desktop apps only
Indicates whether the server SSL certificate must be verified by the caller, Media Foundation, or the
Pointer to a string that contains the URL that is sent to the server.
Pointer to a
Pointer to a
If this method succeeds, it returns
Applies to: desktop apps only
Called by Media Foundation when the server SSL certificate has been received; indicates whether the server certificate is accepted.
\t\nPointer to a string that contains the URL used to send the request to the server, and for which a server-side SSL certificate has been received.
Pointer to a buffer that contains the server SSL certificate.
Pointer to a DWORD variable that indicates the size of pbData in bytes.
Pointer to a
If this method succeeds, it returns
Applies to: desktop apps | Metro style apps
Gets information about one stream in a media source.
\t\nA presentation descriptor contains one or more stream descriptors. To get the stream descriptors from a presentation descriptor, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an identifier for the stream.
\t\nReceives the stream identifier.
If this method succeeds, it returns
The stream identifier uniquely identifies a stream within a presentation. It does not change throughout the lifetime of the stream. For example, if the presentation changes while the source is running, the index number of the stream may change, but the stream identifier does not.
In general, stream identifiers do not have a specific meaning, other than to identify the stream. Some media sources may assign stream identifiers based on meaningful values, such as packet identifiers, but this depends on the implementation.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a media type handler for the stream. The media type handler can be used to enumerate supported media types for the stream, get the current media type, and set the media type.
\t\nReceives a reference to the
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an identifier for the stream.
\t\nThe stream identifier uniquely identifies a stream within a presentation. It does not change throughout the lifetime of the stream. For example, if the presentation changes while the source is running, the index number of the stream may change, but the stream identifier does not.
In general, stream identifiers do not have a specific meaning, other than to identify the stream. Some media sources may assign stream identifiers based on meaningful values, such as packet identifiers, but this depends on the implementation.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a media type handler for the stream. The media type handler can be used to enumerate supported media types for the stream, get the current media type, and set the media type.
\t\nThis interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Called by the streaming media client before the Media Session starts streaming to specify the byte offset or the time offset.
\t\nApplies to: desktop apps | Metro style apps
Called by the streaming media client before the Media Session starts streaming to specify the byte offset or the time offset.
\t\nA Boolean value that specifies whether qwSeekOffset gives a byte offset of a time offset.
| Value | Meaning |
|---|---|
| The qwSeekOffset parameter specifies a byte offset. |
| The qwSeekOffset parameter specifies the time position in 100-nanosecond units. |
?
A byte offset or a time offset, depending on the value passed in fSeekOffsetIsByteOffset. Time offsets are specified in 100-nanosecond units.
If this method succeeds, it returns
Applies to: desktop apps | Metro style apps
Places a marker in the stream.
\t\nThis method causes the stream sink to send an
Applies to: desktop apps | Metro style apps
Retrieves the media sink that owns this stream sink.
\t\nReceives a reference to the media sink's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink's Shutdown method has been called. |
| | This stream was removed from the media sink and is no longer valid. |
?
Applies to: desktop apps | Metro style apps
Retrieves the stream identifier for this stream sink.
\t\nReceives the stream identifier. If this stream sink was added by calling
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink's Shutdown method has been called. |
| | This stream was removed from the media sink and is no longer valid. |
?
Applies to: desktop apps | Metro style apps
Retrieves the media type handler for the stream sink. You can use the media type handler to find which formats the stream supports, and to set the media type on the stream.
\t\nReceives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink's Shutdown method has been called. |
| | This stream was removed from the media sink and is no longer valid. |
?
If the stream sink currently does not support any media types, this method returns a media type handler that fails any calls to
Applies to: desktop apps | Metro style apps
Delivers a sample to the stream. The media sink processes the sample.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink is in the wrong state to receive a sample. For example, preroll is complete but the presenation clock has not started yet. |
| | The sample has an invalid time stamp. See Remarks. |
| | The media sink is paused or stopped and cannot process the sample. |
| | The presentation clock was not set. Call |
| | The sample does not have a time stamp. |
| | The stream sink has not been initialized. |
| | The media sink's Shutdown method has been called. |
| | This stream was removed from the media sink and is no longer valid. |
?
Call this method when the stream sink sends an
This method can return
Negative time stamps.
Time stamps that jump backward (within the same stream).
The time stamps for one stream have drifted too far from the time stamps on another stream within the same media sink (for example, an archive sink that multiplexes the streams).
Not every media sink returns an error code in these situations.
\t\nApplies to: desktop apps | Metro style apps
Places a marker in the stream.
\t\n Specifies the marker type, as a member of the
Optional reference to a
Optional reference to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media sink's Shutdown method has been called. |
| | This stream was removed from the media sink and is no longer valid. |
?
This method causes the stream sink to send an
Applies to: desktop apps | Metro style apps
Causes the stream sink to drop any samples that it has received and has not rendered yet.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The stream sink has not been initialized yet. You might need to set a media type. |
| | The media sink's Shutdown method has been called. |
| | This stream was removed from the media sink and is no longer valid. |
?
If any samples are still queued from previous calls to the
Any pending marker events from the
This method is synchronous. It does not return until the sink has discarded all pending samples.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the media sink that owns this stream sink.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the stream identifier for this stream sink.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the media type handler for the stream sink. You can use the media type handler to find which formats the stream supports, and to set the media type on the stream.
\t\nIf the stream sink currently does not support any media types, this method returns a media type handler that fails any calls to
Applies to: desktop apps only
Converts between Society of Motion Picture and Television Engineers (SMPTE) time codes and 100-nanosecond time units.
\t\nIf an object supports this interface, it must expose the interface as a service. To get a reference to the interface, call
The Advanced Streaming Format (ASF) media source exposes this interface.
\t\nApplies to: desktop apps only
Starts an asynchronous call to convert Society of Motion Picture and Television Engineers (SMPTE) time code to 100-nanosecond units.
\t\nTime in SMPTE time code to convert. The vt member of the
Pointer to the
PPointer to the
The method returns an
| Return code | Description |
|---|---|
| pPropVarTimecode is not VT_I8. |
| | The object's Shutdown method was called. |
| | The byte stream is not seekable. The time code cannot be read from the end of the byte stream. |
?
When the asynchronous method completes, the callback object's
The value of pPropVarTimecode is a 64-bit unsigned value typed as a LONGLONG. The upper DWORD contains the range. (A range is a continuous series of time codes.) The lower DWORD contains the time code in the form of a hexadecimal number 0xhhmmssff, where each 2-byte sequence is read as a decimal value.
void CreateTimeCode( DWORD dwFrames, DWORD dwSeconds, DWORD dwMinutes, DWORD dwHours, DWORD dwRange,\t\n*pvar )\t\n { ULONGLONG ullTimecode = ((ULONGLONG)dwRange) << 32; ullTimecode += dwFrames % 10; ullTimecode += (( (ULONGLONG)dwFrames ) / 10) << 4; ullTimecode += (( (ULONGLONG)dwSeconds ) % 10) << 8; ullTimecode += (( (ULONGLONG)dwSeconds ) / 10) << 12; ullTimecode += (( (ULONGLONG)dwMinutes ) % 10) << 16; ullTimecode += (( (ULONGLONG)dwMinutes ) / 10) << 20; ullTimecode += (( (ULONGLONG)dwHours ) % 10) << 24; ullTimecode += (( (ULONGLONG)dwHours ) / 10) << 28; pvar->vt = VT_I8; pvar->hVal.QuadPart = (LONGLONG)ullTimecode;\t\n }\t\n
Applies to: desktop apps only
Completes an asynchronous request to convert time in Society of Motion Picture and Television Engineers (SMPTE) time code to 100-nanosecond units.
\t\nPointer to the
Receives the converted time.
If this method succeeds, it returns
Call this method after the
Applies to: desktop apps only
Starts an asynchronous call to convert time in 100-nanosecond units to Society of Motion Picture and Television Engineers (SMPTE) time code.
\t\nThe time to convert, in 100-nanosecond units.
Pointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The object's Shutdown method was called. |
| | The byte stream is not seekable. The time code cannot be read from the end of the byte stream. |
?
When the asynchronous method completes, the callback object's
Applies to: desktop apps only
Completes an asynchronous request to convert time in 100-nanosecond units to Society of Motion Picture and Television Engineers (SMPTE) time code.
\t\nA reference to the
A reference to a
If this method succeeds, it returns
Call this method after the
The value of pPropVarTimecode is a 64-bit unsigned value typed as a LONGLONG. The upper DWORD contains the range. (A range is a continuous series of time codes.) The lower DWORD contains the time code in the form of a hexadecimal number 0xhhmmssff, where each 2-byte sequence is read as a decimal value.
\t\nParseTimeCode( const & var, DWORD *pdwRange, DWORD *pdwFrames, DWORD *pdwSeconds, DWORD *pdwMinutes, DWORD *pdwHours )\t\n { if (var.vt != VT_I8) { return E_INVALIDARG; } ULONGLONG ullTimeCode = (ULONGLONG)var.hVal.QuadPart; DWORD dwTimecode = (DWORD)(ullTimeCode & 0xFFFFFFFF); *pdwRange = (DWORD)(ullTimeCode >> 32); *pdwFrames = dwTimecode & 0x0000000F; *pdwFrames += (( dwTimecode & 0x000000F0) >> 4 ) * 10; *pdwSeconds = ( dwTimecode & 0x00000F00) >> 8; *pdwSeconds += (( dwTimecode & 0x0000F000) >> 12 ) * 10; *pdwMinutes = ( dwTimecode & 0x000F0000) >> 16; *pdwMinutes += (( dwTimecode & 0x00F00000) >> 20 ) * 10; *pdwHours = ( dwTimecode & 0x0F000000) >> 24; *pdwHours += (( dwTimecode & 0xF0000000) >> 28 ) * 10; return ;\t\n }\t\n
Applies to: desktop apps only
Sets a timer that invokes a callback at the specified time.
\t\nIf the clock is stopped, the method returns MF_S_CLOCK_STOPPED. The callback will not be invoked until the clock is started.
\t\nApplies to: desktop apps only
Sets a timer that invokes a callback at the specified time.
\t\nBitwise OR of zero or more flags from the
The time at which the timer should fire, in units of the clock's frequency. The time is either absolute or relative to the current time, depending on the value of dwFlags.
Pointer to the
Pointer to the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The clock was shut down. |
| The method succeeded, but the clock is stopped. |
?
If the clock is stopped, the method returns MF_S_CLOCK_STOPPED. The callback will not be invoked until the clock is started.
\t\nApplies to: desktop apps only
Cancels a timer that was set using the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Because the timer is dispatched asynchronously, the application's timer callback might get invoked even if this method succeeds.
\t\nApplies to: desktop apps only
Converts a partial topology into a full topology. The topology loader exposes this interface.
\t\nTo create the topology loader, call the
Applies to: desktop apps only
Creates a fully loaded topology from the input partial topology.
\t\nA reference to the
Receives a reference to the
A reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | One or more output nodes contain |
?
This method creates any intermediate transforms that are needed to complete the topology. It also sets the input and output media types on all of the objects in the topology. If the method succeeds, the full topology is returned in the ppOutputTopo parameter.
You can use the pCurrentTopo parameter to provide a full topology that was previously loaded. If this topology contains objects that are needed in the new topology, the topology loader can re-use them without creating them again. This caching can potentially make the process faster. The objects from pCurrentTopo will not be reconfigured, so you can specify a topology that is actively streaming data. For example, while a topology is still running, you can pre-load the next topology.
Before calling this method, you must ensure that the output nodes in the partial topology have valid
Applies to: desktop apps only
Gets the output nodes in the topology.
\t\nApplies to: desktop apps only
Gets the identifier of the topology.
\t\nReceives the identifier, as a TOPOID value.
If this method succeeds, it returns
Applies to: desktop apps only
Adds a node to the topology.
\t\nPointer to the node's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| pNode is invalid, possibly because the node already exists in the topology. |
?
Applies to: desktop apps only
Removes a node from the topology.
\t\nPointer to the node's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The specified node is not a member of this topology. |
?
This method does not destroy the node, so the
The method breaks any connections between the specified node and other nodes.
\t\nApplies to: desktop apps only
Gets the number of nodes in the topology.
\t\nReceives the number of nodes.
If this method succeeds, it returns
Applies to: desktop apps only
Gets a node in the topology, specified by index.
\t\n The zero-based index of the node. To get the number of nodes in the topology, call
Receives a reference to the node's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The index is less than zero. |
| | No node can be found at the index wIndex. |
?
Applies to: desktop apps only
Removes all nodes from the topology.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
You do not need to clear a topology before disposing of it. The Clear method is called automatically when the topology is destroyed.
\t\nApplies to: desktop apps only
Converts this topology into a copy of another topology.
\t\n A reference to the
If this method succeeds, it returns
This method does the following:
Applies to: desktop apps only
Gets a node in the topology, specified by node identifier.
\t\n The identifier of the node to retrieve. To get a node's identifier, call
Receives a reference to the node's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The topology does not contain a node with this identifier. |
?
Applies to: desktop apps only
Gets the source nodes in the topology.
\t\nReceives a reference to the
If this method succeeds, it returns
Applies to: desktop apps only
Gets the output nodes in the topology.
\t\n Receives a reference to the
If this method succeeds, it returns
Applies to: desktop apps only
Gets the identifier of the topology.
\t\nApplies to: desktop apps only
Gets the number of nodes in the topology.
\t\nApplies to: desktop apps only
Gets the source nodes in the topology.
\t\nApplies to: desktop apps only
Gets the output nodes in the topology.
\t\nApplies to: desktop apps only
Connects an output stream from this node to the input stream of another node.
\t\nNode connections represent data flow from one node to the next. The streams are logical, and are specified by index.
If the node is already connected at the specified output, the method breaks the existing connection. If dwOutputIndex or dwInputIndexOnDownstreamNode specify streams that do not exist yet, the method adds as many streams as needed.
This method checks for certain invalid conditions:
An output node cannot have any output connections. If you call this method on an output node, the method returns E_FAIL.
A node cannot be connected to itself. If pDownstreamNode specifies the same node as the method call, the method returns E_INVALIDARG.
However, if the method succeeds, it does not guarantee that the node connection is valid. It is possible to create a partial topology that the topology loader cannot resolve. If so, the
To break an existing node connection, call
Applies to: desktop apps only
Sets the object associated with this node.
\t\nA reference to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
All node types support this method, but the object reference is not used by every node type.
| Node type | Object reference |
|---|---|
| Source node. | Not used. |
| Transform node. | |
| Output node | |
| Tee node. | Not used. |
?
If the object supports
Applies to: desktop apps only
Gets the object associated with this node.
\t\n Receives a reference to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There is no object associated with this node. |
?
Applies to: desktop apps only
Retrieves the node type.
\t\nReceives the node type, specified as a member of the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the identifier of the node.
\t\nReceives the identifier.
If this method succeeds, it returns
When a node is first created, it is assigned an identifier. Node identifiers are unique within a topology, but can be reused across several topologies. The topology loader uses the identifier to look up nodes in the previous topology, so that it can reuse objects from the previous topology.
To find a node in a topology by its identifier, call
Applies to: desktop apps only
Sets the identifier for the node.
\t\nThe identifier for the node.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The TOPOID has already been set for this object. |
?
When a node is first created, it is assigned an identifier. Typically there is no reason for an application to override the identifier. Within a topology, each node identifier should be unique.
\t\nApplies to: desktop apps only
Retrieves the number of input streams that currently exist on this node.
\t\nReceives the number of input streams.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The input streams may or may not be connected to output streams on other nodes. To get the node that is connected to a specified input stream, call
The
Applies to: desktop apps only
Retrieves the number of output streams that currently exist on this node.
\t\nReceives the number of output streams.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The output streams may or may not be connected to input streams on other nodes. To get the node that is connected to a specific output stream on this node, call
The
Applies to: desktop apps only
Connects an output stream from this node to the input stream of another node.
\t\nZero-based index of the output stream on this node.
Pointer to the
Zero-based index of the input stream on the other node.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The method failed. |
| Invalid parameter. |
?
Node connections represent data flow from one node to the next. The streams are logical, and are specified by index.
If the node is already connected at the specified output, the method breaks the existing connection. If dwOutputIndex or dwInputIndexOnDownstreamNode specify streams that do not exist yet, the method adds as many streams as needed.
This method checks for certain invalid conditions:
An output node cannot have any output connections. If you call this method on an output node, the method returns E_FAIL.
A node cannot be connected to itself. If pDownstreamNode specifies the same node as the method call, the method returns E_INVALIDARG.
However, if the method succeeds, it does not guarantee that the node connection is valid. It is possible to create a partial topology that the topology loader cannot resolve. If so, the
To break an existing node connection, call
Applies to: desktop apps only
Disconnects an output stream on this node.
\t\nZero-based index of the output stream to disconnect.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The dwOutputIndex parameter is out of range. |
| | The specified output stream is not connected to another node. |
?
If the specified output stream is connected to another node, this method breaks the connection.
\t\nApplies to: desktop apps only
Retrieves the node that is connected to a specified input stream on this node.
\t\nZero-based index of an input stream on this node.
Receives a reference to the
Receives the index of the output stream that is connected to this node's input stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The index is out of range. |
| | The specified input stream is not connected to another node. |
?
Retrieves the node that is connected to a specified output stream on this node.
dwOutputIndex
[in] Zero-based index of an output stream on this node.
ppDownstreamNode
[out] Receives a reference to the
pdwInputIndexOnDownstreamNode
[out] Receives the index of the input stream that is connected to this node's output stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| E_INVALIDARG | The index is out of range. |
| | The specified input stream is not connected to another node. |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFTopologyNode InterfaceConceptsTopologies\t\nApplies to: desktop apps only
Sets the preferred media type for an output stream on this node.
\t\nZero-based index of the output stream.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| This node is an output node. |
?
The preferred type is a hint for the topology loader.
Do not call this method after loading a topology or setting a topology on the Media Session. Changing the preferred type on a running topology can cause connection errors.
If no output stream exists at the specified index, the method creates new streams up to and including the specified index number.
Output nodes cannot have outputs. If this method is called on an output node, it returns E_NOTIMPL
\t\nApplies to: desktop apps only
Retrieves the preferred media type for an output stream on this node.
\t\nZero-based index of the output stream.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| This node does not have a preferred output type. |
| Invalid stream index. |
| This node is an output node. |
?
Output nodes cannot have outputs. If this method is called on an output node, it returns E_NOTIMPL.
The preferred output type provides a hint to the topology loader. In a fully resolved topology, there is no guarantee that every topology node will have a preferred output type. To get the actual media type for a node, you must get a reference to the node's underlying object. (For more information, see
Applies to: desktop apps only
Sets the preferred media type for an input stream on this node.
\t\nZero-based index of the input stream.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| This node is a source node. |
?
The preferred type is a hint for the topology loader.
Do not call this method after loading a topology or setting a topology on the Media Session. Changing the preferred type on a running topology can cause connection errors.
If no input stream exists at the specified index, the method creates new streams up to and including the specified index number.
Source nodes cannot have inputs. If this method is called on a source node, it returns E_NOTIMPL.
\t\nApplies to: desktop apps only
Retrieves the preferred media type for an input stream on this node.
\t\nZero-based index of the input stream.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| This node does not have a preferred input type. |
| Invalid stream index. |
| This node is a source node. |
?
Source nodes cannot have inputs. If this method is called on a source node, it returns E_NOTIMPL.
The preferred input type provides a hint to the topology loader. In a fully resolved topology, there is no guarantee that every topology node will have a preferred input type. To get the actual media type for a node, you must get a reference to the node's underlying object. (For more information, see
Applies to: desktop apps only
Copies the data from another topology node into this node.
\t\n A reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The node types do not match. |
?
The two nodes must have the same node type. To get the node type, call
This method copies the object reference, preferred types, and attributes from pNode to this node. It also copies the TOPOID that uniquely identifies each node in a topology. It does not duplicate any of the connections from pNode to other nodes.
The purpose of this method is to copy nodes from one topology to another. Do not use duplicate nodes within the same topology.
\t\nApplies to: desktop apps only
Sets the object associated with this node.
\t\nAll node types support this method, but the object reference is not used by every node type.
| Node type | Object reference |
|---|---|
| Source node. | Not used. |
| Transform node. | |
| Output node | |
| Tee node. | Not used. |
?
If the object supports
Applies to: desktop apps only
Gets the object associated with this node.
\t\nApplies to: desktop apps only
Retrieves the node type.
\t\nApplies to: desktop apps only
Retrieves the identifier of the node.
\t\nWhen a node is first created, it is assigned an identifier. Node identifiers are unique within a topology, but can be reused across several topologies. The topology loader uses the identifier to look up nodes in the previous topology, so that it can reuse objects from the previous topology.
To find a node in a topology by its identifier, call
Applies to: desktop apps only
Retrieves the number of input streams that currently exist on this node.
\t\nThe input streams may or may not be connected to output streams on other nodes. To get the node that is connected to a specified input stream, call
The
Applies to: desktop apps only
Retrieves the number of output streams that currently exist on this node.
\t\nThe output streams may or may not be connected to input streams on other nodes. To get the node that is connected to a specific output stream on this node, call
The
Applies to: desktop apps only
Updates the attributes of one or more nodes in the current topology.
\t\nCurrently the only attribute that can be updated is the
Applies to: desktop apps only
Updates the attributes of one or more nodes in the current topology.
\t\nReserved.
The number of elements in the pUpdates array.
Pointer to an array of
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Currently the only attribute that can be updated is the
Applies to: desktop apps only
Enables a custom video mixer or video presenter to get interface references from the Enhanced Video Renderer (EVR). The mixer can also use this interface to get interface references from the presenter, and the presenter can use it to get interface references from the mixer.
To use this interface, implement the
Retrieves an interface from the enhanced video renderer (EVR), or from the video mixer or video presenter.
Type
[in] Specifies the scope of the search. Currently this parameter is ignored. Use the value
dwIndex
[in] Reserved, must be zero.
guidService
[in] Service
riid
[in] Interface identifier of the requested interface.
ppvObjects
[out] Array of interface references. If the method succeeds, each member of the array is initialized to the requested interface. The caller must release the interface references when the EVR calls
pnObjects
[in, out] On input, a reference to a value that specifies the size of the ppvObjects array. The value must be at least 1. On output, receives the number of valid references copied into the ppvObjects array. In the current implementation, there is no particular reason to specify an array size larger than one element.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| E_INVALIDARG | Invalid argument. |
| E_NOINTERFACE | The requested interface is not available. |
| | The method was not called from inside the InitServicePointers method. See Remarks. |
| | The object does not support the specified service |
This method can be called only from inside the
The presenter can use this method to query the EVR and the mixer. The mixer can use it to query the EVR and the presenter. Which objects are queried depends on the caller and the service
| Caller | Service | Objects queried |
|---|---|---|
| Presenter | MR_VIDEO_RENDER_SERVICE | EVR |
| Presenter | MR_VIDEO_MIXER_SERVICE | Mixer |
| Mixer | MR_VIDEO_RENDER_SERVICE | Presenter and EVR |
The following interfaces are available from the EVR:
IMediaEventSink Interface
The IMediaEventSink interface is documented in the DirectShow SDK documentation.
The following interfaces are available from the mixer:
Client: Requires Windows Vista.
Header: Include evr.h.
Library: Use strmiids.lib.
ReferenceIMFTopologyServiceLookup InterfaceConceptsHow to Write an EVR Presenter\t\nApplies to: desktop apps only
Initializes a video mixer or presenter. This interface is implemented by mixers and presenters, and enables them to query the enhanced video renderer (EVR) for interface references.
\t\nWhen the EVR loads the video mixer and the video presenter, the EVR queries the object for this interface and calls InitServicePointers. Inside the InitServicePointers method, the object can query the EVR for interface references.
\t\nSignals the mixer or presenter to query the enhanced video renderer (EVR) for interface references.
pLookup
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
The
When the EVR calls
Client: Requires Windows Vista.
Header: Include evr.h.
Library: Use strmiids.lib.
ReferenceIMFTopologyServiceLookupClient Interface\t\nApplies to: desktop apps only
Signals the object to release the interface references obtained from the enhanced video renderer (EVR).
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
After this method is called, any interface references obtained during the previous call to
Applies to: desktop apps | Metro style apps
Sets the owner for the sample.
\t\nWhen this method is called, the sample holds an additional reference count on itself. When every other object releases its reference counts on the sample, the sample invokes the pSampleAllocator callback method. To get a reference to the sample, call
After the callback is invoked, the sample clears the callback. To reinstate the callback, you must call SetAllocator again.
It is safe to pass in the sample's
Applies to: desktop apps | Metro style apps
Sets the owner for the sample.
\t\nPointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The owner was already set. This method cannot be called twice on the sample. |
?
When this method is called, the sample holds an additional reference count on itself. When every other object releases its reference counts on the sample, the sample invokes the pSampleAllocator callback method. To get a reference to the sample, call
After the callback is invoked, the sample clears the callback. To reinstate the callback, you must call SetAllocator again.
It is safe to pass in the sample's
Applies to: desktop apps only
Implemented by the transcode profile object.
The transcode profile stores configuration settings that the topology builder uses to generate the transcode topology for the output file. These configuration settings are specified by the caller and include audio and video stream properties, encoder settings, and container settings that are specified by the caller.
To create the transcode profile object, call
Applies to: desktop apps only
Sets audio stream configuration settings in the transcode profile.
To get a list of compatible audio media types supported by the Media Foundation transform (MFT) encoder , call
If this method succeeds, it returns
Applies to: desktop apps only
Gets the audio stream settings that are currently set in the transcode profile.
\t\nReceives a reference to the
If this method succeeds, it returns
If there are no audio attributes set in the transcode profile, the call to GetAudioAttributes succeeds and ppAttrs receives
To get a specific attribute value, the caller must call the appropriate
Applies to: desktop apps only
Sets video stream configuration settings in the transcode profile.
For example code, see
If this method succeeds, it returns
Applies to: desktop apps only
Gets the video stream settings that are currently set in the transcode profile.
\t\nReceives a reference to the
If this method succeeds, it returns
If there are no container attributes set in the transcode profile, the GetVideoAttributes method succeeds and ppAttrs receives
To get a specific attribute value, the caller must call the appropriate
Applies to: desktop apps only
Sets container configuration settings in the transcode profile.
For example code, see
If this method succeeds, it returns
Applies to: desktop apps only
Gets the container settings that are currently set in the transcode profile.
\t\nReceives a reference to the
If this method succeeds, it returns
If there are no container attributes set in the transcode profile, the call to GetContainerAttributes succeeds and ppAttrs receives
To get a specific attribute value, the caller must call the appropriate
Applies to: desktop apps only
Gets the audio stream settings that are currently set in the transcode profile.
\t\nIf there are no audio attributes set in the transcode profile, the call to GetAudioAttributes succeeds and ppAttrs receives
To get a specific attribute value, the caller must call the appropriate
Applies to: desktop apps only
Gets the video stream settings that are currently set in the transcode profile.
\t\nIf there are no container attributes set in the transcode profile, the GetVideoAttributes method succeeds and ppAttrs receives
To get a specific attribute value, the caller must call the appropriate
Applies to: desktop apps only
Gets the container settings that are currently set in the transcode profile.
\t\nIf there are no container attributes set in the transcode profile, the call to GetContainerAttributes succeeds and ppAttrs receives
To get a specific attribute value, the caller must call the appropriate
Applies to: desktop apps only
Implemented by the transcode sink activation object.
The transcode sink activation object can be used to create any of the following file sinks:
To use this interface, perform the following steps:
Applies to: desktop apps only
Sets the name of the encoded output file.
\t\nPointer to a null-terminated string that contains the name of the output file.
If this method succeeds, it returns
The media sink will create a local file with the specified file name.
Alternately, you can call
Applies to: desktop apps only
Sets an output byte stream for the transcode media sink.
\t\nA reference to the
If this method succeeds, it returns
Call this method to provide a writeable byte stream that will receive the transcoded data.
Alternatively, you can provide the name of an output file, by calling
The pByteStreamActivate parameter must specify an activation object that creates a writeable byte stream. Internally, the transcode media sink calls
*pByteStream = null ; hr = pByteStreamActivate->ActivateObject(IID_IMFByteStream, (void**)&pByteStream); Currently, Microsoft Media Foundation does not provide any byte-stream activation objects. To use this method, an application must provide a custom implementation of
Applies to: desktop apps only
Sets the transcoding profile on the transcode sink activation object.
\t\nA reference to the
If this method succeeds, it returns
Before calling this method, initialize the profile object as follows:
Applies to: desktop apps only
Gets the media types for the audio and video streams specified in the transcode profile.
\t\nA reference to an
If the method succeeds, the method assigns
If this method succeeds, it returns
Before calling this method, call
Applies to: desktop apps only
Sets the name of the encoded output file.
\t\nThe media sink will create a local file with the specified file name.
Alternately, you can call
Applies to: desktop apps only
Sets an output byte stream for the transcode media sink.
\t\nCall this method to provide a writeable byte stream that will receive the transcoded data.
Alternatively, you can provide the name of an output file, by calling
The pByteStreamActivate parameter must specify an activation object that creates a writeable byte stream. Internally, the transcode media sink calls
*pByteStream = null ; hr = pByteStreamActivate->ActivateObject(IID_IMFByteStream, (void**)&pByteStream); Currently, Microsoft Media Foundation does not provide any byte-stream activation objects. To use this method, an application must provide a custom implementation of
Applies to: desktop apps only
Sets the transcoding profile on the transcode sink activation object.
\t\nBefore calling this method, initialize the profile object as follows:
Applies to: desktop apps only
Gets the media types for the audio and video streams specified in the transcode profile.
\t\nBefore calling this method, call
Applies to: desktop apps | Metro style apps
Implemented by all Media Foundation Transforms (MFTs).
\t\nApplies to: desktop apps | Metro style apps
Gets the minimum and maximum number of input and output streams for this Media Foundation transform (MFT).
\t\nReceives the minimum number of input streams.
Receives the maximum number of input streams. If there is no maximum, receives the value MFT_STREAMS_UNLIMITED.
Receives the minimum number of output streams.
Receives the maximum number of output streams. If there is no maximum, receives the value MFT_STREAMS_UNLIMITED.
If this method succeeds, it returns
If the MFT has a fixed number of streams, the minimum and maximum values are the same.
It is not recommended to create an MFT that supports zero inputs or zero outputs. An MFT with no inputs or no outputs may not be compatible with the rest of the Media Foundation pipeline. You should create a Media Foundation sink or source for this purpose instead.
When an MFT is first created, it is not guaranteed to have the minimum number of streams. To find the actual number of streams, call
This method should not be called with
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetStreamLimits. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Gets the current number of input and output streams on this Media Foundation transform (MFT).
\t\nReceives the number of input streams.
Receives the number of output streams.
If this method succeeds, it returns
The number of streams includes unselected streams?that is, streams with no media type or a
This method should not be called with
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetStreamCount. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Gets the stream identifiers for the input and output streams on this Media Foundation transform (MFT).
\t\nNumber of elements in the pdwInputIDs array.
Pointer to an array allocated by the caller. The method fills the array with the input stream identifiers. The array size must be at least equal to the number of input streams. To get the number of input streams, call
If the caller passes an array that is larger than the number of input streams, the MFT must not write values into the extra array entries.
Number of elements in the pdwOutputIDs array.
Pointer to an array allocated by the caller. The method fills the array with the output stream identifiers. The array size must be at least equal to the number of output streams. To get the number of output streams, call GetStreamCount.
If the caller passes an array that is larger than the number of output streams, the MFT must not write values into the extra array entries.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. See Remarks. |
| | One or both of the arrays is too small. |
?
Stream identifiers are necessary because some MFTs can add or remove streams, so the index of a stream may not be unique. Therefore,
This method can return E_NOTIMPL if both of the following conditions are true:
This method must be implemented if any of the following conditions is true:
All input stream identifiers must be unique within an MFT, and all output stream identifiers must be unique. However, an input stream and an output stream can share the same identifier.
If the client adds an input stream, the client assigns the identifier, so the MFT must allow arbitrary identifiers, as long as they are unique. If the MFT creates an output stream, the MFT assigns the identifier.
By convention, if an MFT has exactly one fixed input stream and one fixed output stream, it should assign the identifier 0 to both streams.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetStreamIDs. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Gets the buffer requirements and other information for an input stream on this Media Foundation transform (MFT).
\t\n Input stream identifier. To get the list of stream identifiers, call
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream identifier. |
?
It is valid to call this method before setting the media types.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputStreamInfo. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Gets the buffer requirements and other information for an output stream on this Media Foundation transform (MFT).
\t\n Output stream identifier. To get the list of stream identifiers, call
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream number. |
?
It is valid to call this method before setting the media types.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputStreamInfo. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Gets the global attribute store for this Media Foundation transform (MFT).
\t\n Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not support attributes. |
?
Use the
Implementation of this method is optional unless the MFT needs to support a particular set of attributes. Exception: Hardware-based MFTs must implement this method. See Hardware MFTs.
\t\nApplies to: desktop apps | Metro style apps
Gets the attribute store for an input stream on this Media Foundation transform (MFT).
\t\n Input stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not support input stream attributes. |
| | Invalid stream identifier. |
?
Implementation of this method is optional unless the MFT needs to support a particular set of attributes.
To get the attribute store for the entire MFT, call
Applies to: desktop apps | Metro style apps
Gets the attribute store for an output stream on this Media Foundation transform (MFT).
\t\n Output stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not support output stream attributes. |
| | Invalid stream identifier. |
?
Implementation of this method is optional unless the MFT needs to support a particular set of attributes.
To get the attribute store for the entire MFT, call
Applies to: desktop apps | Metro style apps
Removes an input stream from this Media Foundation transform (MFT).
\t\nIdentifier of the input stream to remove.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The transform has a fixed number of input streams. |
| | The stream is not removable, or the transform currently has the minimum number of input streams it can support. |
| | Invalid stream identifier. |
| | The transform has unprocessed input buffers for the specified stream. |
?
If the transform has a fixed number of input streams, the method returns E_NOTIMPL.
An MFT might support this method but not allow certain input streams to be removed. If an input stream can be removed, the
If the transform still has unprocessed input for that stream, the method might succeed or it might return
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTDeleteInputStream. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Adds one or more new input streams to this Media Foundation transform (MFT).
\t\nNumber of streams to add.
Array of stream identifiers. The new stream identifiers must not match any existing input streams.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| The MFT has a fixed number of input streams. |
?
If the new streams exceed the maximum number of input streams for this transform, the method returns E_INVALIDARG. To find the maximum number of input streams, call
If any of the new stream identifiers conflicts with an existing input stream, the method returns E_INVALIDARG.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTAddInputStreams. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Gets an available media type for an input stream on this Media Foundation transform (MFT).
\t\n Input stream identifier. To get the list of stream identifiers, call
Index of the media type to retrieve. Media types are indexed from zero and returned in approximate order of preference.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not have a list of available input types. |
| | Invalid stream identifier. |
| | The dwTypeIndex parameter is out of range. |
| | You must set the output types before setting the input types. |
?
The MFT defines a list of available media types for each input stream and orders them by preference. This method enumerates the available media types for an input stream. To enumerate the available types, increment dwTypeIndex until the method returns
Setting the media type on one stream might change the available types for another stream, or change the preference order. However, an MFT is not required to update the list of available types dynamically. The only guaranteed way to test whether you can set a particular input type is to call
In some cases, an MFT cannot return a list of input types until one or more output types are set. If so, the method returns
An MFT is not required to implement this method. However, most MFTs should implement this method, unless the supported types are simple and can be discovered through the
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputAvailableType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesIf the MFT stores a media type internally, the MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
\t\nApplies to: desktop apps | Metro style apps
Gets an available media type for an output stream on this Media Foundation transform (MFT).
\t\n Output stream identifier. To get the list of stream identifiers, call
Index of the media type to retrieve. Media types are indexed from zero and returned in approximate order of preference.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not have a list of available output types. |
| | Invalid stream identifier. |
| | The dwTypeIndex parameter is out of range. |
| | You must set the input types before setting the output types. |
?
The MFT defines a list of available media types for each output stream and orders them by preference. This method enumerates the available media types for an output stream. To enumerate the available types, increment dwTypeIndex until the method returns MF_E_NO_MORE_TYPES.
Setting the media type on one stream can change the available types for another stream (or change the preference order). However, an MFT is not required to update the list of available types dynamically. The only guaranteed way to test whether you can set a particular input type is to call
In some cases, an MFT cannot return a list of output types until one or more input types are set. If so, the method returns
An MFT is not required to implement this method. However, most MFTs should implement this method, unless the supported types are simple and can be discovered through the
This method can return a partial media type. A partial media type contains an incomplete description of a format, and is used to provide a hint to the caller. For example, a partial type might include just the major type and subtype GUIDs. However, after the client sets the input types on the MFT, the MFT should generally return at least one complete output type, which can be used without further modification. For more information, see Complete and Partial Media Types.
Some MFTs cannot provide an accurate list of output types until the MFT receives the first input sample. For example, the MFT might need to read the first packet header to deduce the format. An MFT should handle this situation as follows:
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputAvailableType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesIf the MFT stores a media type internally, the MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
\t\nApplies to: desktop apps | Metro style apps
Sets, tests, or clears the media type for an input stream on this Media Foundation transform (MFT).
\t\n Input stream identifier. To get the list of stream identifiers, call
Pointer to the
Zero or more flags from the _MFT_SET_TYPE_FLAGS enumeration.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The MFT cannot use the proposed media type. |
| | Invalid stream identifier. |
| | The proposed type is not valid. This error code indicates that the media type itself is not configured correctly; for example, it might contain mutually contradictory attributes. |
| | The MFT cannot switch types while processing data. Try draining or flushing the MFT. |
| | You must set the output types before setting the input types. |
| | The MFT could not find a suitable DirectX Video Acceleration (DXVA) configuration. |
?
This method can be used to set, test without setting, or clear the media type:
Setting the media type on one stream may change the acceptable types on another stream.
An MFT may require the caller to set one or more output types before setting the input type. If so, the method returns
If the MFT supports DirectX Video Acceleration (DXVA) but is unable to find a suitable DXVA configuration (for example, if the graphics driver does not have the right capabilities), the method should return
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTSetInputType. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Sets, tests, or clears the media type for an output stream on this Media Foundation transform (MFT).
\t\n Output stream identifier. To get the list of stream identifiers, call
Pointer to the
Zero or more flags from the _MFT_SET_TYPE_FLAGS enumeration.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The transform cannot use the proposed media type. |
| | Invalid stream identifier. |
| | The proposed type is not valid. This error code indicates that the media type itself is not configured correctly; for example, it might contain mutually contradictory flags. |
| | The MFT cannot switch types while processing data. Try draining or flushing the MFT. |
| | You must set the input types before setting the output types. |
| | The MFT could not find a suitable DirectX Video Acceleration (DXVA) configuration. |
?
This method can be used to set, test without setting, or clear the media type:
Setting the media type on one stream may change the acceptable types on another stream.
An MFT may require the caller to set one or more input types before setting the output type. If so, the method returns
If the MFT supports DirectX Video Acceleration (DXVA) but is unable to find a suitable DXVA configuration (for example, if the graphics driver does not have the right capabilities), the method should return
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTSetOutputType. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Gets the current media type for an input stream on this Media Foundation transform (MFT).
\t\n Input stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream identifier. |
| | The input media type has not been set. |
?
If the specified input stream does not yet have a media type, the method returns
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputCurrentType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesThe MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
\t\nApplies to: desktop apps | Metro style apps
Gets the current media type for an output stream on this Media Foundation transform (MFT).
\t\n Output stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream identifier. |
| | The output media type has not been set. |
?
If the specified output stream does not yet have a media type, the method returns
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputCurrentType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesThe MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
\t\nApplies to: desktop apps | Metro style apps
Queries whether an input stream on this Media Foundation transform (MFT) can accept more data.
\t\n Input stream identifier. To get the list of stream identifiers, call
Receives a member of the _MFT_INPUT_STATUS_FLAGS enumeration, or zero. If the value is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream identifier. |
| | The media type is not set on one or more streams. |
?
If the method returns the
Use this method to test whether the input stream is ready to accept more data, without incurring the overhead of allocating a new sample and calling ProcessInput.
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output (or both).
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputStatus. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Queries whether the Media Foundation transform (MFT) is ready to produce output data.
\t\n Receives a member of the _MFT_OUTPUT_STATUS_FLAGS enumeration, or zero. If the value is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
| | The media type is not set on one or more streams. |
?
If the method returns the
MFTs are not required to implement this method. If the method returns E_NOTIMPL, you must call ProcessOutput to determine whether the transform has output data.
If the MFT has more than one output stream, but it does not produce samples at the same time for each stream, it can set the
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputStatus. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Sets the range of time stamps the client needs for output.
\t\nSpecifies the earliest time stamp. The Media Foundation transform (MFT) will accept input until it can produce an output sample that begins at this time; or until it can produce a sample that ends at this time or later. If there is no lower bound, use the value MFT_OUTPUT_BOUND_LOWER_UNBOUNDED.
Specifies the latest time stamp. The MFT will not produce an output sample with time stamps later than this time. If there is no upper bound, use the value MFT_OUTPUT_BOUND_UPPER_UNBOUNDED.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
| | The media type is not set on one or more streams. |
?
This method can be used to optimize preroll, especially in formats that have gaps between time stamps, or formats where the data must start on a sync point, such as MPEG-2. Calling this method is optional, and implementation of this method by an MFT is optional. If the MFT does not implement the method, the return value is E_NOTIMPL.
If an MFT implements this method, it must limit its output data to the range of times specified by hnsLowerBound and hnsUpperBound. The MFT discards any input data that is not needed to produce output within this range. If the sample boundaries do not exactly match the range, the MFT should split the output samples, if possible. Otherwise, the output samples can overlap the range.
For example, suppose the output range is 100 to 150 milliseconds (ms), and the output format is video with each frame lasting 33 ms. A sample with a time stamp of 67 ms overlaps the range (67 + 33 = 100) and is produced as output. A sample with a time stamp of 66 ms is discarded (66 + 33 = 99). Similarly, a sample with a time stamp of 150 ms is produced as output, but a sample with a time stamp of 151 is discarded.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTSetOutputBounds. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Sends an event to an input stream on this Media Foundation transform (MFT).
\t\n Input stream identifier. To get the list of stream identifiers, call
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
| | Invalid stream number. |
| | The media type is not set on one or more streams. |
| The pipeline should not propagate the event. |
?
An MFT can handle sending the event downstream, or it can let the pipeline do this, as indicated by the return value:
To send the event downstream, the MFT adds the event to the collection object that is provided by the client in the pEvents member of the
Events must be serialized with the samples that come before and after them. Attach the event to the output sample that follows the event. (The pipeline will process the event first, and then the sample.) If an MFT holds back one or more samples between calls to
If an MFT does not hold back samples and does not need to examine any events, it can return E_NOTIMPL.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessEvent. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Sends a message to the Media Foundation transform (MFT).
\t\n The message to send, specified as a member of the
Message parameter. The meaning of this parameter depends on the message type.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream number. Applies to the |
| | The media type is not set on one or more streams. |
?
Before calling this method, set the media types on all input and output streams.
The MFT might ignore certain message types. If so, the method returns
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessMessage. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Delivers data to an input stream on this Media Foundation transform (MFT).
\t\n Input stream identifier. To get the list of stream identifiers, call
Pointer to the
Reserved. Must be zero.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| | Invalid stream identifier. |
| | The input sample requires a valid sample duration. To set the duration, call Some MFTs require that input samples have valid durations. Some MFTs do not require sample durations. |
| | The input sample requires a time stamp. To set the time stamp, call Some MFTs require that input samples have valid time stamps. Some MFTs do not require time stamps. |
| | The transform cannot process more input at this time. |
| | The media type is not set on one or more streams. |
| | The media type is not supported for DirectX Video Acceleration (DXVA). A DXVA-enabled decoder might return this error code. |
?
Note??If you are converting a DirectX Media Object (DMO) to an MFT, be aware that S_FALSE is not a valid return code for
In most cases, if the method succeeds, the MFT stores the sample and holds a reference count on the
If the MFT already has enough input data to produce an output sample, it does not accept new input data, and ProcessInput returns
An exception to this rule is the
An MFT can process the input data in the ProcessInput method. However, most MFTs wait until the client calls ProcessOutput.
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output. It should never be in both states or neither state. An MFT should only accept as much input as it needs to generate at least one output sample, at which point ProcessInput returns
If an MFT encounters a non-fatal error in the input data, it can simply drop the data and attempt to recover when it gets the more input data. To request more input data, the MFT returns
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessInput. See Creating Hybrid DMO/MFT Objects.
Asynchronous ProcessingThe previous remarks describe the synchronous processing model. To support asynchronous processing, see Asynchronous MFTs.
\t\nApplies to: desktop apps | Metro style apps
Generates output from the current input data.
\t\nBitwise OR of zero or more flags from the _MFT_PROCESS_OUTPUT_FLAGS enumeration.
Number of elements in the pOutputSamples array. The value must be at least 1.
Pointer to an array of
Receives a bitwise OR of zero or more flags from the _MFT_PROCESS_OUTPUT_STATUS enumeration.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The ProcessOutput method was called on an asynchronous MFT that was not expecting this method call. |
| | Invalid stream identifier in the dwStreamID member of one or more |
| | The transform cannot produce output data until it receives more input data. |
| | The format has changed on an output stream, or there is a new preferred format, or there is a new output stream. |
| | You must set the media type on one or more streams of the MFT. |
?
Note??If you are converting a DirectX Media Object (DMO) to an MFT, be aware that S_FALSE is not a valid return code for
The size of the pOutputSamples array must be equal to or greater than the number of selected output streams. The number of selected output streams equals the total number of output streams minus the number of deselected streams. A stream is deselected if it has the
This method generates output samples and can also generate events. If the method succeeds, at least one of the following conditions is true:
If MFT_UNIQUE_METHOD_NAMES is defined before including Mftransform.h, this method is renamed MFTProcessOutput. See Creating Hybrid DMO/MFT Objects.
Output BuffersThe MFT returns output data for a stream through the pSample member of the
These flags remain constant unless the media type for the output stream changes.
If the caller allocates the media sample, the media sample must contain a buffer that is large enough to hold the output data. To find the buffer requirements, call GetOutputStreamInfo. The MFT writes the output data to the start of the buffer, overwriting any data that already exists in the buffer.
If the MFT allocates the sample, the MFT also allocates the buffers for the sample.
If the MFT has multiple output streams, the streams might produce output at different rates, so some streams might have output while other streams do not. If a stream did not any produce output, the MFT sets the
If no output streams have data, and the MFT has no events to return, then ProcessOutput returns
The MFT cannot return more than one sample per stream in a single call to ProcessOutput. If there is more output data available for a stream after ProcessOutput returns, the MFT sets the
If the MFT has enough data to produce output, it should refuse to accept any more input until ProcessOutput has been called enough times to pull all of the available output. (An exception is when the
The MFT can return a collection of event objects in the pEvents member of each
To send an event to the caller, the MFT performs the following steps inside ProcessOutput:
Events do not have time stamps. The caller should process the events before processing the output samples. In other words, events occur at the point in the stream immediately after the previous call to ProcessOutput, and prior to any output samples returned from the current ProcessOutput call.
It is valid for the ProcessOutput method to return one or more events and zero output samples.
The caller is responsible for releasing any events that the MFT allocates. When the method returns, check the pEvents member of each
// Release the events that an MFT might allocate in().\t\n void ReleaseEventCollection(DWORD cOutputBuffers, * pBuffers)\t\n { for (DWORD i = 0; i < cOutputBuffers; i++) { if (pBuffers[i].pEvents) { pBuffers[i].pEvents->Release(); pBuffers[i].pEvents = null ; } }\t\n }\t\n
An MFT should not use the
The ProcessOutput method can cause any of the following changes in an output stream:
It is possible that all three of these actions will result from a single call to ProcessOutput. The caller must respond to them in the order listed here?first deletions, then additions, then format changes.
The
An input sample might have attributes, which are accessed through the
For a list of sample attributes, see Sample Attributes.
Asynchronous ProcessingThe previous remarks describe the synchronous processing model. To support asynchronous processing, see Asynchronous MFTs.
\t\nApplies to: desktop apps | Metro style apps
Gets the global attribute store for this Media Foundation transform (MFT).
\t\n Use the
Implementation of this method is optional unless the MFT needs to support a particular set of attributes. Exception: Hardware-based MFTs must implement this method. See Hardware MFTs.
\t\nApplies to: desktop apps | Metro style apps
Queries whether the Media Foundation transform (MFT) is ready to produce output data.
\t\n If the method returns the
MFTs are not required to implement this method. If the method returns E_NOTIMPL, you must call ProcessOutput to determine whether the transform has output data.
If the MFT has more than one output stream, but it does not produce samples at the same time for each stream, it can set the
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputStatus. See Creating Hybrid DMO/MFT Objects.
\t\nApplies to: desktop apps | Metro style apps
Implemented by components that provide input trust authorities (ITAs). This interface is used to get the ITA for each of the component's streams.
\t\nApplies to: desktop apps | Metro style apps
Retrieves the input trust authority (ITA) for a specified stream.
\t\nThe stream identifier for which the ITA is being requested.
The interface identifier (IID) of the interface being requested. Currently the only supported value is IID_IMFInputTrustAuthority.
Receives a reference to the ITA's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The ITA does not expose the requested interface. |
?
Applies to: desktop apps | Metro style apps
Implemented by components that provide output trust authorities (OTAs). Any Media Foundation transform (MFT) or media sink that is designed to work within the protected media path (PMP) and also sends protected content outside the Media Foundation pipeline must implement this interface.
The policy engine uses this interface to negotiate what type of content protection should be applied to the content. Applications do not use this interface directly.
\t\nIf an MFT supports
Applies to: desktop apps | Metro style apps
Gets an output trust authority (OTA), specified by index.
\t\n Zero-based index of the OTA to retrieve. To get the number of OTAs provided by this object, call
Receives a reference to the
If this method succeeds, it returns
Applies to: desktop apps | Metro style apps
Queries whether this output is a policy sink, meaning it handles the rights and restrictions required by the input trust authority (ITA).
\t\nReceives a Boolean value. If TRUE, this object is a policy sink. If
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
A trusted output is generally considered to be a policy sink if it does not pass the media content that it receives anywhere else; or, if it does pass the media content elsewhere, either it protects the content using some proprietary method such as encryption, or it sufficiently devalues the content so as not to require protection.
\t\nApplies to: desktop apps | Metro style apps
Queries whether this output is a policy sink, meaning it handles the rights and restrictions required by the input trust authority (ITA).
\t\nA trusted output is generally considered to be a policy sink if it does not pass the media content that it receives anywhere else; or, if it does pass the media content elsewhere, either it protects the content using some proprietary method such as encryption, or it sufficiently devalues the content so as not to require protection.
\t\nApplies to: desktop apps only
Enables a plug-in component for the enhanced video renderer (EVR) to work with protected media.
To work in the protected media path (PMP), a custom EVR mixer or presenter must implement this interface. The EVR obtains a reference to this interface by calling QueryInterface on the plug-in component.
This interface is required only if the plug-in is a trusted component, designed to work in the PMP. It is not required for playing clear content in an unprotected process.
\t\nApplies to: desktop apps only
Queries whether the plug-in has any transient vulnerabilities at this time.
\t\nReceives a Boolean value. If TRUE, the plug-in has no transient vulnerabilities at the moment and can receive protected content. If
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method provides a way for the plug-in to report temporary conditions that would cause the input trust authority (ITA) to distrust the plug-in. For example, if an EVR presenter is in windowed mode, it is vulnerable to GDI screen captures.
To disable screen capture in Direct3D, the plug-in must do the following:
Create the Direct3D device in full-screen exlusive mode.
Specify the
In addition, the graphics adapter must support the Windows Vista Display Driver Model (WDDM) and the Direct3D extensions for Windows Vista (sometimes called D3D9Ex or D3D9L).
If these conditions are met, the presenter can return TRUE in the pYes parameter. Otherwise, it should return
The EVR calls this method whenever the device changes. If the plug-in returns
This method should be used only to report transient conditions. A plug-in that is never in a trusted state should not implement the
Applies to: desktop apps only
Queries whether the plug-in can limit the effective video resolution.
\t\nReceives a Boolean value. If TRUE, the plug-in can limit the effective video resolution. Otherwise, the plug-in cannot limit the video resolution. If the method fails, the EVR treats the value as
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Constriction is a protection mechanism that limits the effective resolution of the video frame to a specified maximum number of pixels.
Video constriction can be implemented by either the mixer or the presenter.
If the method returns TRUE, the EVR might call
Applies to: desktop apps only
Limits the effective video resolution.
\t\nMaximum number of source pixels that may appear in the final video image, in thousands of pixels. If the value is zero, the video is disabled. If the value is MAXDWORD (0xFFFFFFFF), video constriction is removed and the video may be rendered at full resolution.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method limits the effective resolution of the video image. The actual resolution on the target device might be higher, due to stretching the image.
The EVR might call this method at any time if the
Applies to: desktop apps only
Enables or disables the ability of the plug-in to export the video image.
\t\nBoolean value. Specify TRUE to disable image exporting, or
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
An EVR plug-in might expose a way for the application to get a copy of the video frames. For example, the standard EVR presenter implements
If the plug-in supports image exporting, this method enables or disables it. Before this method has been called for the first time, the EVR assumes that the mechanism is enabled.
If the plug-in does not support image exporting, this method should return
While image exporting is disabled, any associated export method, such as GetCurrentImage, should return
Applies to: desktop apps only
Limits the effective video resolution.
\t\nThis method limits the effective resolution of the video image. The actual resolution on the target device might be higher, due to stretching the image.
The EVR might call this method at any time if the
Applies to: desktop apps only
Returns the device identifier supported by a video renderer component. This interface is implemented by mixers and presenters for the enhanced video renderer (EVR). If you replace either of these components, the mixer and presenter must report the same device identifier.
\t\nApplies to: desktop apps only
Returns the identifier of the video device supported by an EVR mixer or presenter.
\t\nReceives the device identifier. Generally, the value is IID_IDirect3DDevice9.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The video renderer has been shut down. |
?
If a mixer or presenter uses Direct3D 9, it must return the value IID_IDirect3DDevice9 in pDeviceID. The EVR's default mixer and presenter both return this value. If you write a custom mixer or presenter, it can return some other value. However, the mixer and presenter must use matching device identifiers.
\t\nApplies to: desktop apps only
Returns the identifier of the video device supported by an EVR mixer or presenter.
\t\nIf a mixer or presenter uses Direct3D 9, it must return the value IID_IDirect3DDevice9 in pDeviceID. The EVR's default mixer and presenter both return this value. If you write a custom mixer or presenter, it can return some other value. However, the mixer and presenter must use matching device identifiers.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Gets the size and aspect ratio of the video, prior to any stretching by the video renderer.
\t\nReceives the size of the native video rectangle. This parameter can be
Receives the aspect ratio of the video. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| At least one of the parameters must be non- |
| | The video renderer has been shut down. |
?
If no media types have been set on any video streams, the method succeeds but all parameters are set to zero.
You can set pszVideo or pszARVideo to
Applies to: desktop apps only
Gets the range of sizes that the enhanced video renderer (EVR) can display without significantly degrading performance or image quality.
\t\nReceives the minimum ideal size. This parameter can be
Receives the maximum ideal size. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| At least one parameter must be non- |
| | The video renderer has been shut down. |
?
You can set pszMin or pszMax to
Applies to: desktop apps only
Sets the source and destination rectangles for the video.
\t\nPointer to an
Specifies the destination rectangle. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| At least one parameter must be non- |
| | The video renderer has been shut down. |
?
The source rectangle defines which portion of the video is displayed. It is specified in normalized coordinates. For more information, see
The destination rectangle defines a rectangle within the clipping window where the video appears. It is specified in pixels, relative to the client area of the window. To fill the entire window, set the destination rectangle to {0, 0, width, height}, where width and height are dimensions of the window client area. The default destination rectangle is {0, 0, 0, 0}.
To update just one of these rectangles, set the other parameter to
Before setting the destination rectangle (prcDest), you must set the video window by calling
Retrieves the source and destination rectangles for the video.
pnrcSource
[out] Pointer to an
prcDest
[out] Receives the current destination rectangle. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| E_POINTER | One or more required parameters are |
| | The video renderer has been shut down. |
You can set pnrcSource or prcDest to
Client: Requires Windows Vista.
Header: Include evr.h.
Library: Use strmiids.lib.
ReferenceIMFVideoDisplayControl InterfaceConceptsEnhanced Video RendererUsing the Video Display Controls\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Sets the clipping window for the video.
\t\nHandle to the window where the enhanced video renderer (EVR) will draw the video.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| hwndVideo does not specify a valid window. |
| DWM thumbnails were not enabled/disabled. |
?
The EVR will not display any video unless the application calls this method with a valid window handle.
For protected content, this method might disable Desktop Window Manager (DWM) thumbnail previews for the window. If thumbnail previews cannot be disabled, the method returns S_FALSE.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Repaints the current video frame. Call this method whenever the application receives a WM_PAINT message.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The EVR cannot repaint the frame at this time. This error can occur while the EVR is switching between full-screen and windowed mode. The caller can safely ignore this error. |
| | The video renderer has been shut down. |
?
Applies to: desktop apps only
Gets a copy of the current image being displayed by the video renderer.
\t\nPointer to a sizeof( before calling the method.
Receives a reference to a buffer that contains a packed Windows device-independent bitmap (DIB). The caller must free the memory for the bitmap by calling CoTaskMemFree.
Receives the size of the buffer returned in pDib, in bytes.
Receives the time stamp of the captured image.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The content is protected and the license does not permit capturing the image. |
| | The video renderer has been shut down. |
?
This method can be called at any time. However, calling the method too frequently degrades the video playback performance.
This method retrieves a copy of the final composited image, which includes any substreams, alpha-blended bitmap, aspect ratio correction, background color, and so forth.
In windowed mode, the bitmap is the size of the destination rectangle specified in
Applies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\n[This API is not supported and may be altered or unavailable in the future. ]
Applies to: desktop apps only
Sets or unsets full-screen rendering mode.
To implement full-screen playback, an application should simply resize the video window to cover the entire area of the monitor. Also set the window to be a topmost window, so that the application receives all mouse-click messages. For more information about topmost windows, see the documentation for the SetWindowPos function.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The video renderer has been shut down. |
?
The default EVR presenter implements full-screen mode using Direct3D exclusive mode.
If you use this method to switch to full-screen mode, set the application window to be a topmost window and resize the window to cover the entire monitor. This ensures that the application window receives all mouse-click messages. Also set the keyboard focus to the application window. When you switch out of full-screen mode, restore the window's original size and position.
By default, the cursor is still visible in full-screen mode. To hide the cursor, call ShowCursor.
The transition to and from full-screen mode occurs asynchronously. To get the current mode, call
Applies to: desktop apps only
Queries whether the enhanced video renderer (EVR) is currently in full-screen mode.
\t\nReceives a Boolean value. If TRUE, the EVR is in full-screen mode. If
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The EVR is currently switching between full-screen and windowed mode. |
?
Applies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) displays video.
The EVR presenter implements this interface. To get a reference to the interface, call
If you implement a custom presenter for the EVR, the presenter can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Queries whether the enhanced video renderer (EVR) is currently in full-screen mode.
\t\nApplies to: desktop apps only
Represents a description of a video format.
\t\nIf the major type of a media type is
Applications should avoid using this interface except when a method or function requires an
[GetVideoFormat is no longer available for use as of Windows?7. Instead, use the media type attributes to get the properties of the video format.]
Applies to: desktop apps only
Returns a reference to an
This method returns a reference to an
If you need to convert the media type into an
There are no guarantees about how long the returned reference is valid.
\t\n[GetVideoFormat is no longer available for use as of Windows?7. Instead, use the media type attributes to get the properties of the video format.]
Applies to: desktop apps only
Returns a reference to an
If you need to convert the media type into an
There are no guarantees about how long the returned reference is valid.
\t\nApplies to: desktop apps only
Alpha-blends a static bitmap image with the video displayed by the Enhanced Video Renderer (EVR).
The EVR mixer implements this interface. To get a reference to the interface, call
If you implement a custom mixer for the EVR, the mixer can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Sets a bitmap image for the enhanced video renderer (EVR) to alpha-blend with the video.
\t\nPointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The blending parameters defined in the pBmpParms structure are not valid. |
?
The application can provide the image either as a GDI bitmap or as a Direct3D surface. The EVR mixer blends the image with the next video frame and all subsequent frames, until the image is changed or removed. The image can contain embedded per-pixel alpha information so that transparent regions can be defined. Transparent areas can also be identified using a color key value.
If you use a Direct3D surface, the surface format must be 32-bit RGB, either
There is no defined limit to how frequently you can pass images to the video renderer. However, changing the image several times per second can impact the performance and smoothness of the video.
\t\nApplies to: desktop apps only
Removes the current bitmap and releases any resources associated with it.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No bitmap is currently set. |
?
Applies to: desktop apps only
Updates the current alpha-blending settings, including the source and destination rectangles, the color key, and other information. You can update some or all of the blending parameters.
\t\nPointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The blending parameters defined in the pBmpParms structure are not valid. |
| | No bitmap is currently set. You must call |
?
The video must be playing for the changes to take effect.
\t\nApplies to: desktop apps only
Retrieves the current settings that the enhanced video renderer (EVR) uses to alpha-blend the bitmap with the video.
\t\nPointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No bitmap is currently set. You must call |
?
This method returns the current values of all the blending parameters, not just those that the application specified. Ignore the dwFlags member of the structure.
\t\nApplies to: desktop apps only
Sets a bitmap image for the enhanced video renderer (EVR) to alpha-blend with the video.
\t\nThe application can provide the image either as a GDI bitmap or as a Direct3D surface. The EVR mixer blends the image with the next video frame and all subsequent frames, until the image is changed or removed. The image can contain embedded per-pixel alpha information so that transparent regions can be defined. Transparent areas can also be identified using a color key value.
If you use a Direct3D surface, the surface format must be 32-bit RGB, either
There is no defined limit to how frequently you can pass images to the video renderer. However, changing the image several times per second can impact the performance and smoothness of the video.
\t\nApplies to: desktop apps only
Retrieves the current settings that the enhanced video renderer (EVR) uses to alpha-blend the bitmap with the video.
\t\nThis method returns the current values of all the blending parameters, not just those that the application specified. Ignore the dwFlags member of the structure.
\t\nApplies to: desktop apps only
Controls how the Enhanced Video Renderer (EVR) mixes video substreams. Applications can use this interface to control video mixing during playback.
The EVR mixer implements this interface. To get a reference to the interface, call
If you implement a custom mixer for the EVR, the mixer can optionally expose this interface as a service.
\t\nApplies to: desktop apps only
Sets the z-order of a video stream.
\t\nIdentifier of the stream. For the EVR media sink, the stream identifier is defined when the
Z-order value. The z-order of the reference stream must be zero. The maximum z-order value is the number of streams minus one.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The value of dwZ is larger than the maximum z-order value. |
| | Invalid z-order for this stream. For the reference stream, dwZ must be zero. For all other streams, dwZ must be greater than zero. |
| | Invalid stream identifier. |
?
The EVR draws the video streams in the order of their z-order values, starting with zero. The reference stream must be first in the z-order, and the remaining streams can be in any order.
\t\nApplies to: desktop apps only
Retrieves the z-order of a video stream.
\t\nIdentifier of the stream. For the EVR media sink, the stream identifier is defined when the
Receives the z-order value.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream identifier. |
?
Applies to: desktop apps only
Sets the position of a video stream within the composition rectangle.
\t\nIdentifier of the stream. For the EVR media sink, the stream identifier is defined when the
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The coordinates of the bounding rectangle given in pnrcOutput are not valid. |
| | Invalid stream identifier. |
?
The mixer draws each video stream inside a bounding rectangle that is specified relative to the final video image. This bounding rectangle is given in normalized coordinates. For more information, see
The coordinates of the bounding rectangle must fall within the range [0.0, 1.0]. Also, the X and Y coordinates of the upper-left corner cannot exceed the X and Y coordinates of the lower-right corner. In other words, the bounding rectangle must fit entirely within the composition rectangle and cannot be flipped vertically or horizontally.
The following diagram shows how the EVR mixes substreams.
The output rectangle for the stream is specified by calling SetStreamOutputRect. The source rectangle is specified by calling
Applies to: desktop apps only
Retrieves the position of a video stream within the composition rectangle.
\t\nThe identifier of the stream. For the EVR media sink, the stream identifier is defined when the
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid stream identifier. |
?
Applies to: desktop apps only
Controls preferences for video deinterlacing.
The default video mixer for the Enhanced Video Renderer (EVR) implements this interface.
To get a reference to the interface, call
Applies to: desktop apps only
Sets the preferences for video deinterlacing.
\t\nBitwise OR of zero or more flags from the
If this method succeeds, it returns
Applies to: desktop apps only
Gets the current preferences for video deinterlacing.
\t\nReceives a bitwise OR of zero or more flags from the
If this method succeeds, it returns
Applies to: desktop apps only
Gets the current preferences for video deinterlacing.
\t\nApplies to: desktop apps only
Maps a position on an input video stream to the corresponding position on an output video stream.
To obtain a reference to this interface, call
Applies to: desktop apps only
Maps output image coordinates to input image coordinates. This method provides the reverse transformation for components that map coordinates on the input image to different coordinates on the output image.
\t\nX-coordinate of the output image, normalized to the range [0...1].
Y-coordinate of the output image, normalized to the range [0...1].
Output stream index for the coordinate mapping.
Input stream index for the coordinate mapping.
Receives the mapped x-coordinate of the input image, normalized to the range [0...1].
Receives the mapped y-coordinate of the input image, normalized to the range [0...1].
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The video renderer has been shut down. |
?
In the following diagram, R(dest) is the destination rectangle for the video. You can obtain this rectangle by calling
The position of P relative to R(dest) in normalized coordinates is calculated as follows:
float xn = float(x + 0.5) / widthDest;\t\n float xy = float(y + 0.5) / heightDest;\t\n where widthDest and heightDest are the width and height of R(dest) in pixels.
To calculate the position of P relative to R1, call MapOutputCoordinateToInputStream as follows:
float x1 = 0, y1 = 0;\t\n hr = pMap->MapOutputCoordinateToInputStream(xn, yn, 0, dwInputStreamIndex, &x1, &y1);The values returned in x1 and y1 are normalized to the range [0...1]. To convert back to pixel coordinates, scale these values by the size of R1:
int scaledx = int(floor(x1 * widthR1));\t\n int scaledy = int(floor(xy * heightR1));Note that x1 and y1 might fall outside the range [0...1] if P lies outside of R1.
\t\nApplies to: desktop apps only
Represents a video presenter. A video presenter is an object that receives video frames, typically from a video mixer, and presents them in some way, typically by rendering them to the display. The enhanced video renderer (EVR) provides a default video presenter, and applications can implement custom presenters.
The video presenter receives video frames as soon as they are available from upstream. The video presenter is responsible for presenting frames at the correct time and for synchronizing with the presentation clock.
\t\nApplies to: desktop apps only
Sends a message to the video presenter. Messages are used to signal the presenter that it must perform some action, or that some event has occurred.
\t\nSpecifies the message as a member of the
Message parameter. The meaning of this parameter depends on the message type.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The video renderer has been shut down. |
?
Applies to: desktop apps only
Represents a video presenter. A video presenter is an object that receives video frames, typically from a video mixer, and presents them in some way, typically by rendering them to the display. The enhanced video renderer (EVR) provides a default video presenter, and applications can implement custom presenters.
The video presenter receives video frames as soon as they are available from upstream. The video presenter is responsible for presenting frames at the correct time and for synchronizing with the presentation clock.
\t\nApplies to: desktop apps only
Represents a video presenter. A video presenter is an object that receives video frames, typically from a video mixer, and presents them in some way, typically by rendering them to the display. The enhanced video renderer (EVR) provides a default video presenter, and applications can implement custom presenters.
The video presenter receives video frames as soon as they are available from upstream. The video presenter is responsible for presenting frames at the correct time and for synchronizing with the presentation clock.
\t\nApplies to: desktop apps only
Controls video processing in the Enhanced Video Renderer (EVR). The operations controlled through this interface include color adjustment (ProcAmp), noise filters, and detail filters.
The EVR mixer implements this interface. To get a reference to the interface, call
If you implement a custom mixer for the EVR, the mixer can optionally expose this interface as a service.
\t\nThis interface provides access to functionality that is implemented by the graphics driver. The driver provides one or more video processor modes, which are identified by
To use this interface, perform the following steps:
Initialize the media types on the EVR input streams. (If you are using the Media Session, this occurs after the topology is resolved. Wait for the Media Session to send the
Call
Call
Call
Call
Call
Applies to: desktop apps only
Retrieves the video processor modes that the video driver supports.
\t\nReceives the number of video processor modes.
Receives a reference to an array of GUIDs. The number of elements in the array is returned in the lpdwNumProcessingModes parameter. The caller must release the memory for the array by calling CoTaskMemFree. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media type for the reference stream is not set. |
?
Video processor modes are identified by
Before calling this method, you must set the media type for the reference stream. Which modes are available might depend on the media type of the reference stream.
\t\nApplies to: desktop apps only
Retrieves the capabilities of a video processor mode.
\t\nPointer to a
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media type for the reference stream is not set. |
?
Before calling this method, you must set the media type for the reference stream.
\t\nApplies to: desktop apps only
Retrieves the application's preferred video processor mode. To set the preferred mode, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media type for the reference stream is not set. |
| The application has not specified a preferred video processor mode. |
?
Applies to: desktop apps only
Sets the preferred video processor mode. The EVR will attempt to use this mode when playback starts.
\t\nPointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The requested mode is not valid. |
| | The mixer has already allocated Direct3D resources and cannot change modes. |
| | The media type for the reference stream is not set. |
?
Before calling this method, set the media type for the reference stream as follows:
DirectShow EVR filter: Connect pin 0.
EVR media sink: Set the media type for stream 0.
Mixer (standalone): Set the media type for input stream 0 and set the media type for the output stream.
Which modes are available might depend on the reference stream's media type.
Call this method before video playback begins.
\t\nApplies to: desktop apps only
Retrieves the range of values for a color adjustment (ProcAmp) setting.
\t\nThe ProcAmp setting to query. For a list of possible values, see ProcAmp Settings.
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid value for dwProperty. |
| | No video processor mode has been set. |
| | The media type for the reference stream is not set. |
?
This method returns the range of values that the current video processor mode supports for the specified ProcAmp setting.
This method fails if the video processor mode has not been set on the mixer. To select a video processor mode, call
To find out which ProcAmp settings the driver supports, call
Applies to: desktop apps only
Retrieves the current settings for one or more color adjustment (ProcAmp) settings.
\t\nBitwise OR of one or more flags, specifying which operations to query. For a list of flags, see ProcAmp Settings.
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The media type for the reference stream is not set. |
?
Before calling this method, you must set the media type for the reference stream.
Until the mixer's video processor mode is set, the returned values are all zero. After the processor mode is set, the returned values reflect the current mode. To select a video processor mode, call
To find out which ProcAmp settings the driver supports, call
Applies to: desktop apps only
Sets one or more color adjustment (ProcAmp) settings.
\t\nBitwise OR of one or more flags, specifying which ProcAmp values to set. For a list of flags, see ProcAmp Settings.
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The dwFlags parameter is invalid, or one or more values in pValues is not within the correct range. |
| | The media type for the reference stream is not set. |
?
Before calling this method, set the video processor mode. To select a video processor mode, call
To find out which ProcAmp settings the driver supports, call
Applies to: desktop apps only
Retrieves the range of values for a specified image filter setting.
\t\nThe image filtering parameter to query. For a list of possible values, see DXVA Image Filter Settings.
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The driver does not support this filter setting. |
| Invalid value for dwProperty. |
| | No video processor mode has been set. |
| | The specified operation is not available. |
| | The media type for the reference stream is not set. |
?
This method returns the range of values that the current video processor mode supports for the specified image filter setting.
This method fails if the video processor mode has not been set on the mixer. To select a video processor mode, call
To find out which image filters the driver supports, call
Applies to: desktop apps only
Retrieves the current setting for an image filter.
\t\nThe filter setting to query. For a list of possible values, see DXVA Image Filter Settings.
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The value of dwProperty is invalid. |
| | The media type for the reference stream is not set. |
?
Before calling this method, you must set the media type for the reference stream.
Until the mixer's video processor mode is set, the returned values are all zero. After the processor mode is set, the returned values reflect the current mode. To select a video processor mode, call
To find out which image filters the driver supports, call
Applies to: desktop apps only
Sets a parameter for an image filter.
\t\nThe image filtering parameter to set. For a list of possible values, see DXVA Image Filter Settings.
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The value of dwProperty is invalid. |
| | The media type for the reference stream is not set. |
?
Before calling this method, set the video processor mode. To select a video processor mode, call
To find out which image filters the driver supports, call
Applies to: desktop apps only
Retrieves the background color for the composition rectangle. The background color is used for letterboxing the video image.
\t\nPointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Sets the background color for the composition rectangle. The background color is used for letterboxing the video image.
\t\nBackground color, specified as a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Retrieves the application's preferred video processor mode. To set the preferred mode, call
Applies to: desktop apps only
Retrieves the background color for the composition rectangle. The background color is used for letterboxing the video image.
\t\nApplies to: desktop apps only
Sets a new mixer or presenter for the Enhanced Video Renderer (EVR).
Both the EVR media sink and the DirectShow EVR filter implement this interface. To get a reference to the interface, call QueryInterface on the media sink or the filter. Do not use
The EVR activation object returned by the
Applies to: desktop apps only
Sets a new mixer or presenter for the enhanced video renderer (EVR).
\t\nPointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Either the mixer or the presenter is invalid. |
| | The mixer and presenter cannot be replaced in the current state. (EVR media sink.) |
| | The video renderer has been shut down. |
| One or more input pins are connected. (DirectShow EVR filter.) |
?
Call this method directly after creating the EVR, before you do any of the following:
Call
Call
Connect any pins on the EVR filter, or set any media types on EVR media sink.
The EVR filter returns VFW_E_WRONG_STATE if any of the filter's pins are connected. The EVR media sink returns
The device identifiers for the mixer and the presenter must match. The
If the video renderer is in the protected media path (PMP), the mixer and presenter objects must be certified safe components and pass any trust authority verification that is being enforced. Otherwise, this method will fail.
\t\nApplies to: desktop apps | Metro style apps
Allocates video samples for a video media sink.
The stream sinks on the enhanced video renderer (EVR) expose this interface as a service. To obtain a reference to the interface, call
Applies to: desktop apps | Metro style apps
Specifies the Direct3D device manager for the video media sink to use.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The media sink uses the Direct3D device manager to obtain a reference to the Direct3D device, which it uses to allocate Direct3D surfaces. The device manager enables multiple objects in the pipeline (such as a video renderer and a video decoder) to share the same Direct3D device.
\t\nApplies to: desktop apps | Metro style apps
Releases all of the video samples that have been allocated.
\t\nThe method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Specifies the number of samples to allocate and the media type for the samples.
\t\nNumber of samples to allocate.\t\t
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | Invalid media type. |
?
Retrieves a video sample.
ppSample
[out] Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | No samples are available. |
Client: Requires Windows Vista.
Header: Include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFVideoSampleAllocator Interface\t\nApplies to: desktop apps | Metro style apps
Specifies the Direct3D device manager for the video media sink to use.
\t\nThe media sink uses the Direct3D device manager to obtain a reference to the Direct3D device, which it uses to allocate Direct3D surfaces. The device manager enables multiple objects in the pipeline (such as a video renderer and a video decoder) to share the same Direct3D device.
\t\nApplies to: desktop apps | Metro style apps
Sets the callback object that receives notification whenever a video sample is returned to the allocator.
\t\nTo get a video sample from the allocator, call the
The allocator holds at most one callback reference. Calling this method again replaces the previous callback reference.
\t\nApplies to: desktop apps | Metro style apps
Sets the callback object that receives notification whenever a video sample is returned to the allocator.
\t\nA reference to the
If this method succeeds, it returns
To get a video sample from the allocator, call the
The allocator holds at most one callback reference. Calling this method again replaces the previous callback reference.
\t\nApplies to: desktop apps | Metro style apps
Gets the number of video samples that are currently available for use.
\t\nReceives the number of available samples.
If this method succeeds, it returns
To get a video sample from the allocator, call the
Applies to: desktop apps | Metro style apps
Sets the callback object that receives notification whenever a video sample is returned to the allocator.
\t\nTo get a video sample from the allocator, call the
The allocator holds at most one callback reference. Calling this method again replaces the previous callback reference.
\t\nApplies to: desktop apps | Metro style apps
The callback for the
Applies to: desktop apps | Metro style apps
Called when a video sample is returned to the allocator.
\t\nIf this method succeeds, it returns
To get a video sample from the allocator, call the
Applies to: desktop apps only
This interface is not supported.
\t\nApplies to: desktop apps only
Note??This method is not supported.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Note??This method is not supported.
\t\nIf this method succeeds, it returns
Applies to: desktop apps only
Note??This method is not supported.
\t\nApplies to: desktop apps only
Registers the topology work queues with the Multimedia Class Scheduler Service (MMCSS).
\t\nEach source node in the topology defines one branch of the topology. The branch includes every topology node that receives data from that node. An application can assign each branch of a topology its own work queue and then associate those work queues with MMCSS tasks.
To use this method, perform the following steps.
The BeginRegisterTopologyWorkQueuesWithMMCSS method is asynchronous. When the operation completes, the callback object's
To unregister the topology work queues from MMCSS, call
Applies to: desktop apps only
Registers the topology work queues with the Multimedia Class Scheduler Service (MMCSS).
\t\nA reference to the
A reference to the
If this method succeeds, it returns
Each source node in the topology defines one branch of the topology. The branch includes every topology node that receives data from that node. An application can assign each branch of a topology its own work queue and then associate those work queues with MMCSS tasks.
To use this method, perform the following steps.
The BeginRegisterTopologyWorkQueuesWithMMCSS method is asynchronous. When the operation completes, the callback object's
To unregister the topology work queues from MMCSS, call
Applies to: desktop apps only
Completes an asynchronous request to register the topology work queues with the Multimedia Class Scheduler Service (MMCSS).
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this method when the
Applies to: desktop apps only
Unregisters the topology work queues from the Multimedia Class Scheduler Service (MMCSS).
\t\nPointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method is asynchronous. When the operation completes, the callback object's
Applies to: desktop apps only
Completes an asynchronous request to unregister the topology work queues from the Multimedia Class Scheduler Service (MMCSS).
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this method when the
Applies to: desktop apps only
Retrieves the Multimedia Class Scheduler Service (MMCSS) class for a specified branch of the current topology.
\t\nIdentifies the work queue assigned to this topology branch. The application defines this value by setting the
Pointer to a buffer that receives the name of the MMCSS class. This parameter can be
On input, specifies the size of the pwszClass buffer, in characters. On output, receives the required size of the buffer, in characters. The size includes the terminating null character.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There is no work queue with the specified identifier. |
| | The pwszClass buffer is too small to receive the class name. |
?
Applies to: desktop apps only
Retrieves the Multimedia Class Scheduler Service (MMCSS) task identifier for a specified branch of the current topology.
\t\nIdentifies the work queue assigned to this topology branch. The application defines this value by setting the
Receives the task identifier.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Associates a platform work queue with a Multimedia Class Scheduler Service (MMCSS) task.
\t\nThe platform work queue to register with MMCSS. See Work Queue Identifiers. To register all of the standard work queues to the same MMCSS task, set this parameter to MFASYNC_CALLBACK_QUEUE_ALL.
The name of the MMCSS task to be performed.
The unique task identifier. To obtain a new task identifier, set this value to zero.
A reference to the
A reference to the
If this method succeeds, it returns
This method is asynchronous. When the operation completes, the callback object's
To unregister the work queue from the MMCSS class, call
Applies to: desktop apps only
Completes an asynchronous request to associate a platform work queue with a Multimedia Class Scheduler Service (MMCSS) task.
\t\nPointer to the
The unique task identifier.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this function when the
To unregister the work queue from the MMCSS class, call
Applies to: desktop apps only
Unregisters a platform work queue from a Multimedia Class Scheduler Service (MMCSS) task.
\t\nPlatform work queue to register with MMCSS. See
Pointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method is asynchronous. When the operation completes, the callback object's
Applies to: desktop apps only
Completes an asynchronous request to unregister a platform work queue from a Multimedia Class Scheduler Service (MMCSS) task.
\t\nPointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this method when the
Applies to: desktop apps only
Retrieves the Multimedia Class Scheduler Service (MMCSS) class for a specified platform work queue.
\t\nPlatform work queue to query. See
Pointer to a buffer that receives the name of the MMCSS class. This parameter can be
On input, specifies the size of the pwszClass buffer, in characters. On output, receives the required size of the buffer, in characters. The size includes the terminating null character.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The pwszClass buffer is too small to receive the class name. |
?
Applies to: desktop apps only
Retrieves the Multimedia Class Scheduler Service (MMCSS) task identifier for a specified platform work queue.
\t\nPlatform work queue to query. See
Receives the task identifier.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps only
Specifies the protection level for Analog Copy Protection (ACP).
\t\nThis enumeration is numerically equivalent to the COPP_ACP_Protection_Level enumeration used in Certified Output Protection Protocol. The
ACP is disabled.
ACP protection level 1.
ACP protection level 2.
ACP protection level 3.
The DXGKMDT_OPM_DPCP_PROTECTION_LEVEL enumeration indicates the protection levels for a protected output that supports DisplayPort Content Protection (DPCP).
\t\nDPCP protects digital video signals from DisplayPort output connectors. For more information about DisplayPort, see the DisplayPort article.
\t\nIndicates that DPCP does not protect the output's signal.
Indicates that DPCP protects the output's signal.
The DXGKMDT_OPM_HDCP_PROTECTION_LEVEL enumeration indicates the protection levels for a protected output that supports High-bandwidth Digital Content Protection (HDCP).
\t\nHDCP protects digital video signals from digital video output connectors. Currently, OPM can use HDCP to protect data from Digital Video Interface (DVI) and High-Definition Multimedia Interface (HDMI) connector outputs. For more information about the HDCP system, see the HDCP Specification Revision 1.1.
\t\nIndicates that HDCP does not protect the output's signal.
Indicates that HDCP protects the output's signal.
Applies to: desktop apps only
Specifies the aspect ratio for ETSI EN 300 294.
\t\nThis enumeration is numerically equivalent to the COPP_ImageAspectRatio_EN300294 enumeration used in Certified Output Protection Protocol (COPP).
\t\nFull format 4:3.
Box 14:9 center.
Box 14:9 top.
Box 16:9 center.
Box 16:9 top.
Box > 16:9 center.
Full format 4:3 (shoot and protect 14:9 center).
Full format 16:9 (anamorphic).
Applies to: desktop apps only
Specifies whether the
Applies to: desktop apps only
Creates an Output Protection Manager (OPM) object for each physical monitor that is associated with a particular
The monitor handle for which to create OPM objects. There are several functions that return
A member of the
| Value | Meaning |
|---|---|
| The returned | |
| The returned |
?
Receives the number of
Receives a reference to an array of
If this function succeeds, it returns
A single
The
Applies to: desktop apps only
Creates an Output Protection Manager (OPM) object for each physical monitor that is associated with a particular Direct3D device.
\t\n Pointer to the
A member of the
| Value | Meaning |
|---|---|
| The returned | |
| The returned |
?
Receives the number of
Receives a reference to an array of
If this function succeeds, it returns
A single Direct3D device can be associated with several physical monitors. Each physical monitor has its own connector. The application must set the protection mechanism individually for each physical monitor, by using the
The
Applies to: desktop apps only
Represents a video output for an Output Protection Manager (OPM) session.
To get a reference to this interface, call one of the following functions:
Applies to: desktop apps only
Begins the initialization sequence for an Output Protection Manager (OPM) session.
\t\nPointer to an
Receives a reference to a buffer containing the display driver's certificate. The method allocates the memory for the buffer. The caller must release the memory by calling CoTaskMemFree.
Receives the length of the buffer pointed to by ppbCertificate.
If this method succeeds, it returns
This method is equivalent to the IAMCertifiedOutputProtection::KeyExchange method in Certified Output Protection Protocol (COPP).
The method returns a certificate chain that contains the driver's 2048-bit RSA public key. The caller must validate the certificate chain and then call
This method supports both OPM semantics and COPP semantics. COPP semantics are supported for backward compatibility; new applications should use OPM semantics.
OPM SemanticsThe method returns an X.509 certificate chain. The certificate chain is encoded with ASN.1 Distinguished Encoding Rules (DER).
COPP SemanticsThe method returns a COPP certificate chain. The certificate chain is returned as a UTF-8 string. You can treat the buffer returned in ppbCertificate as an array of chars.
\t\nApplies to: desktop apps only
Completes the initialization sequence for an Output Protection Manager (OPM) session.
\t\nPointer to an
Returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | An unexpected error occurred the display driver. |
| | The encrypted parameters in pParameters are incorrect. |
?
This method is equivalent to the IAMCertifiedOutputProtection::SessionSequenceStart method in Certified Output Protection Protocol (COPP).
The pParameters parameter points to an
Encrypt this number with RAEAS-OAEP, encryption using the display driver's public encryption key. The public encryption key is contained in the certificate returned in the ppbCertificate parameter of the StartInitialization method.
The application must use cryptographically secure random numbers. The CryptGenRandom function is recommended, although not required.
\t\nApplies to: desktop apps only
Sends an Output Protection Manager (OPM) status request to the display driver.
\t\nPointer to an
Pointer to an
Returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The OPM object was created with Certified Output Protection Protocol (COPP) semantics. |
?
This method is equivalent to the IAMCertifiedOutputProtection::ProtectionStatus method in COPP.
The
Applies to: desktop apps only
Sends an Output Protection Manager (OPM) status request to the display driver. Use this method when OPM is emulating Certified Output Protection Manager (COPP).
\t\nPointer to an
Pointer to an
Returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | The OPM object was created with OPM semantics, not COPP semantics. |
?
This method is equivalent to the IAMCertifiedOutputProtection::ProtectionStatus method in COPP.
The
Applies to: desktop apps only
Configures a video output. This method sends an Output Protection Manager (OPM) or Certified Output Protection Protocol (COPP) command to the driver.
\t\nPointer to an
The size of the pbAdditionalParameters buffer, in bytes.
Pointer to a buffer that contains additional information for the command.
If this method succeeds, it returns
This method is equivalent to the IAMCertifiedOutputProtection::ProtectionCommand method in COPP.
This method supports both OPM semantics and COPP semantics. COPP semantics are supported for backward compatibility; new applications should use OPM semantics.
OPM SemanticsSome OPM commands require additional configuration information to be passed in the pbAdditionalParameters parameter. The ulAdditionalParametersSize parameter specifies the size of the additional data.
COPP SemanticsThe pbAdditionalParameters parameter must be
The DXGKMDT_OPM_ACP_AND_CGMSA_SIGNALING structure describes how the signal that goes through the physical connector that is associated with the protected output object is protected.
\t\nA DXGKMDT_OPM_RANDOM_NUMBER structure that contains a protected output object's 128-bit cryptographically secure random number. This random number is generated by an application and supplied to the display miniport driver in a call to the driver's DxgkDdiOPMGetCOPPCompatibleInformation function. This random number is supplied to the driver in the rnRandomNumber member of the DXGKMDT_OPM_COPP_COMPATIBLE_GET_INFO_PARAMETERS structure.
A bitwise OR combination of the values from the DXGKMDT_OPM_STATUS enumeration that indicates the status of a protected output.
A valid bitwise OR combination of values from the DXGKMDT_OPM_PROTECTION_STANDARD enumeration that indicates the types of television signals that the physical connector that is associated with a protected output can carry.
A valid bitwise OR combination of values from the DXGKMDT_OPM_PROTECTION_STANDARD enumeration that indicates the types of television signals that the physical connector that is associated with a protected output currently carries.
Reserved. Must be set to zero.
A mask value that indicates the valid bits in the following ulAspectRatioData1 member.
32-bit data that indicates the aspect ratio value that is currently set for the active protection standard.
A mask value that indicates the valid bitfields in the following ulAspectRatioData2 member.
32-bit data for additional aspect ratio information that is used for specific protection standards. This data can be used to read End and Q0 values for EIA-608-B, or active format description for CEA-805-A Type B packets.
A mask value that indicates the valid bitfields in the following ulAspectRatioData3 member.
32-bit data for additional aspect ratio information that is used for specific protection standards. This data can be used to read End and Q0 values for EIA-608-B, or active format description for CEA-805-A Type B packets.
Reserved. Must be set to zero.
Reserved. Must be set to zero.
The DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT structure describes the format of the signal that is transmitted from a physical connector that is associated with a protected output to a monitor.
\t\nA DXGKMDT_OPM_RANDOM_NUMBER structure that contains a protected output object's 128-bit cryptographically secure random number. This random number is generated by an application and supplied to the display miniport driver in a call to the driver's DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation function. This random number is supplied to the driver in the rnRandomNumber member of the DXGKMDT_OPM_GET_INFO_PARAMETERS or DXGKMDT_OPM_COPP_COMPATIBLE_GET_INFO_PARAMETERS structure.
A bitwise OR combination of the values of the DXGKMDT_OPM_STATUS enumeration that indicates the status of a protected output.
The width, in pixels, of each video frame in the signal that is transmitted from the physical connector.
The height, in pixels, of each video frame in the signal that is transmitted from the physical connector. If the signal is interlaced, this value is the height of the video frame and not the height of either the even or the odd field.
A DXGKMDT_OPM_INTERLEAVE_FORMAT-typed value that specifies how the scan lines in a video frame are ordered.
A D3DDDIFORMAT-typed value that identifies the Direct3D surface format of the signal.
The numerator for the refresh rate of the signal, in Hz.
The denominator for the refresh rate of the signal, in Hz.
The DXGKMDT_OPM_CONFIGURE_PARAMETERS structure contains parameters that are used to configure a protected output object in a call to the DxgkDdiOPMConfigureProtectedOutput function.
\t\nThe DXGKMDT_OPM_CONNECTED_HDCP_DEVICE_INFORMATION structure contains High-bandwidth Digital Content Protection (HDCP) information that is retrieved in a call to the DxgkDdiOPMGetInformation function.
\t\nThe DXGKMDT_OPM_COPP_COMPATIBLE_GET_INFO_PARAMETERS structure contains parameters that are used to retrieve information from a protected output object in a call to the DxgkDdiOPMGetCOPPCompatibleInformation function.
\t\nApplies to: desktop apps only
Contains initialization parameters for an Output Protection Manager (OPM) session.
\t\nThe layout of this structure is identical to the AMCOPPSignature structure used in Certified Output Protection Protocol (COPP).
\t\nApplies to: desktop apps only
Contains the result from an OPM_GET_CODEC_INFO query.
\t\nApplies to: desktop apps only
Contains information for the OPM_GET_CODEC_INFO command.
\t\nApplies to: desktop apps only
Contains a Message Authentication Code (MAC) for an Output Protection Manager (OPM) message.
\t\nThe DXGKMDT_OPM_CONNECTED_HDCP_DEVICE_INFORMATION structure contains High-bandwidth Digital Content Protection (HDCP) information that is retrieved in a call to the DxgkDdiOPMGetInformation function.
\t\nApplies to: desktop apps only
Contains a Message Authentication Code (MAC) for an Output Protection Manager (OPM) message.
\t\nApplies to: desktop apps only
Contains the result from an OPM_GET_OUTPUT_ID status request.
\t\nApplies to: desktop apps only
Contains a Message Authentication Code (MAC) for an Output Protection Manager (OPM) message.
\t\nApplies to: desktop apps only
Contains a Message Authentication Code (MAC) for an Output Protection Manager (OPM) message.
\t\nApplies to: desktop apps only
Contains information for the OPM_SET_ACP_AND_CGMSA_SIGNALING command in Output Protection Manager (OPM).
This command causes the driver to insert Wide Screen Signaling (WSS) codes or other data packets in the television signal, as required by some Analog Copy Protection (ACP) and Copy Generation Management System ? Analog (CGMS-A) specifications. For example:
The layout of this structure is identical to the DXVA_COPPSetSignalingCmdData structure used in Certified Output Protection Manager (COPP).
\t\nApplies to: desktop apps only
Contains information for the OPM_SET_ACP_AND_CGMSA_SIGNALING command in Output Protection Manager (OPM).
This command causes the driver to insert Wide Screen Signaling (WSS) codes or other data packets in the television signal, as required by some Analog Copy Protection (ACP) and Copy Generation Management System ? Analog (CGMS-A) specifications. For example:
The layout of this structure is identical to the DXVA_COPPSetSignalingCmdData structure used in Certified Output Protection Manager (COPP).
\t\nThe DXGKMDT_OPM_SET_PROTECTION_LEVEL_PARAMETERS structure contains parameters to set the protection level of a protected output in a call to the DxgkDdiOPMConfigureProtectedOutput function.
\t\nExternal events can alter the nature of the protection that is applied to a connector or even modify the type of the connector. The display miniport driver must report these events to OPM applications whenever the driver receives a call to its DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation function. The display miniport driver must report the following external events by returning the specified status flags from the DXGKMDT_OPM_STATUS enumeration only on the next call to DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation after the events occur:
If the connection between the computer and the display device is working properly, the display miniport driver should set the DXGKMDT_OPM_STATUS_NORMAL status flag in the ulStatusFlags member of the DXGKMDT_OPM_STANDARD_INFORMATION, DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT, DXGKMDT_OPM_ACP_AND_CGMSA_SIGNALING, or DXGKMDT_OPM_CONNECTED_HDCP_DEVICE_INFORMATION structure.
If the computer and the display device become disconnected, the display miniport driver should set the DXGKMDT_OPM_STATUS_LINK_LOST status flag in the ulStatusFlags member of the DXGKMDT_OPM_STANDARD_INFORMATION, DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT, DXGKMDT_OPM_ACP_AND_CGMSA_SIGNALING, or DXGKMDT_OPM_CONNECTED_HDCP_DEVICE_INFORMATION structure.
If the end-user causes the configuration of the physical connector to change, the display miniport driver should set the DXGKMDT_OPM_STATUS_RENEGOTIATION_REQUIRED status flag in the ulStatusFlags member of the DXGKMDT_OPM_STANDARD_INFORMATION, DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT, DXGKMDT_OPM_ACP_AND_CGMSA_SIGNALING, or DXGKMDT_OPM_CONNECTED_HDCP_DEVICE_INFORMATION structure.
If tampering with the graphics adapter or the adapter's display miniport driver has occurred, the display miniport driver should set the DXGKMDT_OPM_STATUS_TAMPERING_DETECTED status flag in the ulStatusFlags member of the DXGKMDT_OPM_STANDARD_INFORMATION, DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT, DXGKMDT_OPM_ACP_AND_CGMSA_SIGNALING, or DXGKMDT_OPM_CONNECTED_HDCP_DEVICE_INFORMATION structure.
If a revoked High-bandwidth Digital Content Protection (HDCP) device is directly or indirectly attached to a connector and if HDCP is enabled, the display miniport driver should set the DXGKMDT_OPM_STATUS_REVOKED_HDCP_DEVICE_ATTACHED status flag in the ulStatusFlags member of the DXGKMDT_OPM_STANDARD_INFORMATION or DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT structure. If HDCP is not enabled, the driver is not required to set this status flag. The driver sets this status value only from a call to its DxgkDdiOPMGetInformation function to determine if HDCP is enabled.
The display miniport driver returns a reference to a DXGKMDT_OPM_STANDARD_INFORMATION, DXGKMDT_OPM_ACTUAL_OUTPUT_FORMAT, DXGKMDT_OPM_ACP_AND_CGMSA_SIGNALING, or DXGKMDT_OPM_CONNECTED_HDCP_DEVICE_INFORMATION structure in the abRequestedInformation member of the DXGKMDT_OPM_REQUESTED_INFORMATION structure. A reference to DXGKMDT_OPM_REQUESTED_INFORMATION is returned through the RequestedInformation parameter of DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation.
For example, consider two media playback applications, A and B. Each application controls, via OPM, the HDCP protection level of the connector that attaches the computer to the display monitor. Each application controls its own unique protected output. If the connector becomes unplugged, the next time either application initiates a DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation request to its protected output, the display miniport driver should return the DXGKMDT_OPM_STATUS_LINK_LOST status flag.
Assume application A is the first to initiate a call to DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation on its protected output. Application A then receives the DXGKMDT_OPM_STATUS_LINK_LOST flag and acts accordingly. If application A initiates a subsequent DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation call, it should not receive the DXGKMDT_OPM_STATUS_LINK_LOST flag, unless the connector becomes unplugged again. When application B initiates a call to DxgkDdiOPMGetInformation or DxgkDdiOPMGetCOPPCompatibleInformation on its protected output, it receives the DXGKMDT_OPM_STATUS_LINK_LOST flag and acts accordingly. Again, application B should not receive the DXGKMDT_OPM_STATUS_LINK_LOST flag again until the connector becomes unplugged again.
?
?
Send
Build date: 2/23/2012
\t\nApplies to: desktop apps only
Contains an image that is stored as metadata for a media source. This structure is used as the data item for the WM/Picture metadata attribute.
\t\nThe WM/Picture attribute is defined in the Windows Media Format SDK. The attribute contains a picture related to the content, such as album art.
To get this attribute from a media source, call
Image data.
This format differs from the WM_PICTURE structure used in the Windows Media Format SDK. The WM_PICTURE structure contains internal references to two strings and the image data. If the structure is copied, these references become invalid. The
Applies to: desktop apps only
Contains an image that is stored as metadata for a media source. This structure is used as the data item for the WM/Picture metadata attribute.
\t\nThe WM/Picture attribute is defined in the Windows Media Format SDK. The attribute contains a picture related to the content, such as album art.
To get this attribute from a media source, call
Image data.
This format differs from the WM_PICTURE structure used in the Windows Media Format SDK. The WM_PICTURE structure contains internal references to two strings and the image data. If the structure is copied, these references become invalid. The
Applies to: desktop apps only
Specifies an index for the ASF indexer object.
\t\nThe index object of an ASF file can contain a number of distinct indexes. Each index is identified by the type of index and the stream number. No ASF index object can contain more than one index for a particular combination of stream number and index type.
\t\nThe type of index. Currently this value must be GUID_NULL, which specifies time-based indexing.
The stream number to which this structure applies.
Applies to: desktop apps only
Specifies an index for the ASF indexer object.
\t\nThe index object of an ASF file can contain a number of distinct indexes. Each index is identified by the type of index and the stream number. No ASF index object can contain more than one index for a particular combination of stream number and index type.
\t\nThe type of index. Currently this value must be GUID_NULL, which specifies time-based indexing.
The stream number to which this structure applies.
Applies to: desktop apps only
Specifies an index for the ASF indexer object.
\t\nThe index object of an ASF file can contain a number of distinct indexes. Each index is identified by the type of index and the stream number. No ASF index object can contain more than one index for a particular combination of stream number and index type.
\t\nThe type of index. Currently this value must be GUID_NULL, which specifies time-based indexing.
The stream number to which this structure applies.
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps | Metro style apps
Defines the properties of a clock.
\t\n The interval at which the clock correlates its clock time with the system time, in 100-nanosecond units. If the value is zero, the correlation is made whenever the
The unique identifier of the underlying device that provides the time. If two clocks have the same unique identifier, they are based on the same device. If the underlying device is not shared between two clocks, the value can be GUID_NULL.
A bitwise OR of flags from the
The clock frequency in Hz. A value of MFCLOCK_FREQUENCY_HNS means that the clock has a frequency of 10 MHz (100-nanosecond ticks), which is the standard MFTIME time unit in Media Foundation. If the
The amount of inaccuracy that may be present on the clock, in parts per billion (ppb). For example, an inaccuracy of 50 ppb means the clock might drift up to 50 seconds per billion seconds of real time. If the tolerance is not known, the value is MFCLOCK_TOLERANCE_UNKNOWN. This constant is equal to 50 parts per million (ppm).
The amount of jitter that may be present, in 100-nanosecond units. Jitter is the variation in the frequency due to sampling the underlying clock. Jitter does not include inaccuracies caused by drift, which is reflected in the value of dwClockTolerance.
For clocks based on a single device, the minimum jitter is the length of the tick period (the inverse of the frequency). For example, if the frequency is 10 Hz, the jitter is 0.1 second, which is 1,000,000 in MFTIME units. This value reflects the fact that the clock might be sampled just before the next tick, resulting in a clock time that is one period less than the actual time. If the frequency is greater than 10 MHz, the jitter should be set to 1 (the minimum value).
If a clock's underlying hardware device does not directly time stamp the incoming data, the jitter also includes the time required to dispatch the driver's interrupt service routine (ISR). In that case, the expected jitter should include the following values:
| Value | Meaning |
|---|---|
| Jitter due to time stamping during the device driver's ISR. |
| Jitter due to time stamping during the deferred procedure call (DPC) processing. |
| Jitter due to dropping to normal thread execution before time stamping. |
?
Applies to: desktop apps only
The
This structure is identical to the DirectShow
Major type
Subtype
If TRUE, samples are of a fixed size. This field is informational only. For audio, it is generally set to TRUE. For video, it is usually TRUE for uncompressed video and
If TRUE, samples are compressed using temporal (interframe) compression. (A value of TRUE indicates that not all frames are key frames.) This field is informational only.
Size of the sample in bytes. For compressed data, the value can be zero.
| Format type | Format structure |
|---|---|
| DVINFO |
| |
| |
| None. |
| |
| |
| |
?
Not used. Set to
Size of the format block of the media type.
Pointer to the format structure. The structure type is specified by the formattype member. The format structure must be present, unless formattype is GUID_NULL or FORMAT_None.
Applies to: desktop apps only
Contains coefficients used to transform multichannel audio into a smaller number of audio channels. This process is called fold-down.
\t\nTo specify this information in the media type, set the
The ASF media source supports fold-down from six channels (5.1 audio) to two channels (stereo). It gets the information from the g_wszFold6To2Channels3 attribute in the ASF header. This attribute is documented in the Windows Media Format SDK documentation.
\t\nSize of the structure, in bytes.
Number of source channels.
Number of destination channels.
Specifies the assignment of audio channels to speaker positions in the transformed audio. This member is a bitwise OR of flags that define the speaker positions. For a list of valid flags, see
Array that contains the fold-down coefficients. The number of coefficients is cSrcChannels?cDstChannels. If the number of coefficients is less than the size of the array, the remaining elements in the array are ignored. For more information about how the coefficients are applied, see Windows Media Audio Professional Codec Features.
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains format data for a binary stream in an Advanced Streaming Format (ASF) file.
\t\nThis structure is used with the
This structure corresponds to the first 60 bytes of the Type-Specific Data field of the Stream Properties Object, in files where the stream type is ASF_Binary_Media. For more information, see the ASF specification.
The Format Data field of the Type-Specific Data field is contained in the
Major media type. This value is the
Media subtype.
If TRUE, samples have a fixed size in bytes. Otherwise, samples have variable size.
If TRUE, the data in this stream uses temporal compression. Otherwise, samples are independent of each other.
If bFixedSizeSamples is TRUE, this member specifies the sample size in bytes. Otherwise, the value is ignored and should be 0.
Format type
Applies to: desktop apps only
Defines custom color primaries for a video source. The color primaries define how to convert colors from RGB color space to CIE XYZ color space.
\t\nThis structure is used with the
Red x-coordinate.
Red y-coordinate.
Green x-coordinate.
Green y-coordinate.
Blue x-coordinate.
Blue y-coordinate.
White point x-coordinate.
White point y-coordinate.
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Specifies a rectangular area within a video frame.
\t\n An
An
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains one palette entry in a color table.
\t\nThis union can be used to represent both RGB palettes and Y'Cb'Cr' palettes. The video format that defines the palette determines which union member should be used.
\t\n
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Contains information that is common to every type of MFPlay event.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Event structure for the
To get a reference to this structure, cast the pEventHeader parameter of the
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Event structure for the
To get a reference to this structure, cast the pEventHeader parameter of the
Media items are created asynchronously. If multiple items are created, the operations can complete in any order, not necessarily in the same order as the method calls. You can use the dwUserData member to identify the items, if you have simultaneous requests pending.
\t\nApplies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Event structure for the
To get a reference to this structure, cast the pEventHeader parameter of the
If one or more streams could not be connected to a media sink, the event property store contains the MFP_PKEY_StreamRenderingResults property. The value of the property is an array of
Applies to: desktop apps only
Important??Deprecated. This API may be removed from future releases of Windows. Applications should use the Media Session for playback.
Event structure for the
To get a reference to this structure, cast the pEventHeader parameter of the
If MFEventType is
| Property | Description |
|---|---|
| MFP_PKEY_StreamIndex | The index of the stream whose format changed. |
?
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nThis topic describes how to create a media type that describes an uncompressed video format. For more information about media types generally, see About Media Types.
To create a complete uncompressed video type, set the following attributes on the
Applies to: desktop apps only
Contains information about a revoked component.
\t\nSpecifies the reason for the revocation. The following values are defined.
| Value | Meaning |
|---|---|
| A boot driver could not be verified. |
| A certificate in a trusted component's certificate chain was revoked. |
| The high-security certificate for authenticating the protected environment (PE) was revoked. The high-security certificate is typically used by ITAs that handle high-definition content and next-generation formats such as HD-DVD. |
| A certificate's extended key usage (EKU) object is invalid. |
| The root certificate is not valid. |
| The low-security certificate for authenticating the PE was revoked. The low-security certificate is typically used by ITAs that handle standard-definition content and current-generation formats. |
| A trusted component was revoked. |
| The GRL was not found. |
| Could not load the global revocation list (GRL). |
| The GRL signature is invalid. |
| A certificate chain was not well-formed, or a boot driver is unsigned or is signed with an untrusted certificate. |
| A component was signed by a test certificate. |
?
In addition, one of the following flags might be present, indicating the type of component that failed to load.
| Value | Meaning |
|---|---|
| User-mode component. |
| Kernel-mode component. |
?
Contains a hash of the file header.
Contains a hash of the public key in the component's certificate.
File name of the revoked component.
Applies to: desktop apps only
Contains information about one or more revoked components.
\t\nRevocation information version.
Number of elements in the pRRComponents array.
Array of
Applies to: desktop apps | Metro style apps
Contains statistics about the performance of the sink writer.
\t\nThe size of the structure, in bytes.
The time stamp of the most recent sample given to the sink writer. The sink writer updates this value each time the application calls
The time stamp of the most recent sample to be encoded. The sink writer updates this value whenever it calls
The time stamp of the most recent sample given to the media sink. The sink writer updates this value whenever it calls
The time stamp of the most recent stream tick. The sink writer updates this value whenever the application calls
The system time of the most recent sample request from the media sink. The sink writer updates this value whenever it receives an
The number of samples received.
The number of samples encoded.
The number of samples given to the media sink.
The number of stream ticks received.
The amount of data, in bytes, currently waiting to be processed.
The total amount of data, in bytes, that has been sent to the media sink.
The number of pending sample requests.
The average rate, in media samples per 100-nanoseconds, at which the application sent samples to the sink writer.
The average rate, in media samples per 100-nanoseconds, at which the sink writer sent samples to the encoder.
The average rate, in media samples per 100-nanoseconds, at which the sink writer sent samples to the media sink.
Applies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps only
Contains private data for the
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
\t\nApplies to: desktop apps | Metro style apps
Contains information about an output buffer for a Media Foundation transform. This structure is used in the
You must provide an
MFTs can support two different allocation models for output samples:
To find which model the MFT supports for a given output stream, call
| Flag | Allocation Model |
|---|---|
| The MFT allocates the output samples for the stream. Set pSample to | |
| The MFT supports both allocation models. | |
| Neither (default) | The client must allocate the output samples for the stream. |
?
The behavior of ProcessOutput depends on the initial value of pSample and the value of the dwFlags parameter in the ProcessOutput method.
If pSample is
Restriction: This output stream must have the
If pSample is
Restriction: This output stream must have the
If pSample is non-
Restriction: This output stream must not have the
Any other combinations are invalid and cause ProcessOutput to return E_INVALIDARG.
Each call to ProcessOutput can produce zero or more events and up to one sample per output stream.
\t\nApplies to: desktop apps | Metro style apps
Contains information about an output stream on a Media Foundation transform (MFT). To get these values, call
Before the media types are set, the only values that should be considered valid is the
After you set a media type on all of the input and output streams (not including optional streams), all of the values returned by the GetOutputStreamInfo method are valid. They might change if you set different media types.
\t\nApplies to: desktop apps only
Contains information about the audio and video streams for the transcode sink activation object.
To get the information stored in this structure, call
The
Applies to: desktop apps only
Contains media type information for registering a Media Foundation transform (MFT).
\t\nThe major media type. For a list of possible values, see Major Media Types.
The media subtype. For a list of possible values, see the following topics:
Applies to: desktop apps only
Contains parameters for the
Applies to: desktop apps only
Specifies a bitmap for the enhanced video renderer (EVR) to alpha-blend with the video.
\t\nTo specify a GDI bitmap, create a device context and call SelectObject to select the bitmap into the DC. Then set the hdc member of the structure equal to the handle to the DC and set the GetBitmapFromDC member to TRUE.
\t\nIf TRUE, the hdc member is used. Otherwise, the pDDs member is used.
A union that contains the following members.
Handle to the device context (DC) of a GDI bitmap. If GetBitmapFromDC is
Pointer to the
Applies to: desktop apps only
Specifies a bitmap for the enhanced video renderer (EVR) to alpha-blend with the video.
\t\nTo specify a GDI bitmap, create a device context and call SelectObject to select the bitmap into the DC. Then set the hdc member of the structure equal to the handle to the DC and set the GetBitmapFromDC member to TRUE.
\t\nIf TRUE, the hdc member is used. Otherwise, the pDDs member is used.
A union that contains the following members.
Handle to the device context (DC) of a GDI bitmap. If GetBitmapFromDC is
Pointer to the
Applies to: desktop apps only
Specifies a rectangular area within a video frame.
\t\n An
An
A
Applies to: desktop apps only
Describes a video format.
\t\nApplications should avoid using this structure. Instead, it is recommended that applications use attributes to describe the video format. For a list of media type attributes, see Media Type Attributes. With attributes, you can set just the format information that you know, which is easier (and more likely to be accurate) than trying to fill in complete format information for the
To initialize a media type object from an
You can use the
Size of the structure, in bytes. This value includes the size of the palette entries that may appear after the surfaceInfo member.
Video subtype. See Video Subtype GUIDs.
Applies to: desktop apps only
Describes a video format.
\t\nApplications should avoid using this structure. Instead, it is recommended that applications use attributes to describe the video format. For a list of media type attributes, see Media Type Attributes. With attributes, you can set just the format information that you know, which is easier (and more likely to be accurate) than trying to fill in complete format information for the
To initialize a media type object from an
You can use the
Size of the structure, in bytes. This value includes the size of the palette entries that may appear after the surfaceInfo member.
Video subtype. See Video Subtype GUIDs.
Applies to: desktop apps only
Describes a video format.
\t\nApplications should avoid using this structure. Instead, it is recommended that applications use attributes to describe the video format. For a list of media type attributes, see Media Type Attributes. With attributes, you can set just the format information that you know, which is easier (and more likely to be accurate) than trying to fill in complete format information for the
To initialize a media type object from an
You can use the
Size of the structure, in bytes. This value includes the size of the palette entries that may appear after the surfaceInfo member.
Video subtype. See Video Subtype GUIDs.
Applies to: desktop apps | Metro style apps
Defines a normalized rectangle, which is used to specify sub-rectangles in a video rectangle. When a rectangle N is normalized relative to some other rectangle R, it means the following:
The coordinate (0.0, 0.0) on N is mapped to the upper-left corner of R.
The coordinate (1.0, 1.0) on N is mapped to the lower-right corner of R.
Any coordinates of N that fall outside the range [0...1] are mapped to positions outside the rectangle R. A normalized rectangle can be used to specify a region within a video rectangle without knowing the resolution or even the aspect ratio of the video. For example, the upper-left quadrant is defined as {0.0, 0.0, 0.5, 0.5}.
\t\nX-coordinate of the upper-left corner of the rectangle.
Y-coordinate of the upper-left corner of the rectangle.
X-coordinate of the lower-right corner of the rectangle.
Y-coordinate of the lower-right corner of the rectangle.
Applies to: desktop apps only
Describes a video format.
\t\nApplications should avoid using this structure. Instead, it is recommended that applications use attributes to describe the video format. For a list of media type attributes, see Media Type Attributes. With attributes, you can set just the format information that you know, which is easier (and more likely to be accurate) than trying to fill in complete format information for the
To initialize a media type object from an
You can use the
Size of the structure, in bytes. This value includes the size of the palette entries that may appear after the surfaceInfo member.
Video subtype. See Video Subtype GUIDs.
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
\n An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Shuts down the Microsoft Media Foundation platform. Call this function once for every call to
If this function succeeds, it returns
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Enumerates the raw input devices attached to the system.
\t\nAn array of
If pRawInputDeviceList is
The size of a
If the function is successful, the return value is the number of devices stored in the buffer pointed to by pRawInputDeviceList.
On any other error, the function returns (UINT) -1 and GetLastError returns the error indication.
The devices returned from this function are the mouse, the keyboard, and other Human Interface Device (HID) devices.
To get more detailed information about the attached devices, call GetRawInputDeviceInfo using the hDevice from
Retrieves the information about the raw input devices for the current application.
\t\nAn array of
The number of
The size, in bytes, of a
If successful, the function returns a non-negative number that is the number of
If the pRawInputDevices buffer is too small or
To receive raw input from a device, an application must register it by using RegisterRawInputDevices.
\t\nRetrieves information about the raw input device.
\t\nA handle to the raw input device. This comes from the lParam of the WM_INPUT message, from the hDevice member of
Specifies what data will be returned in pData. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
| pData points to a string that contains the device name. For this uiCommand only, the value in pcbSize is the character count (not the byte count). |
| pData points to an |
| pData points to the previously parsed data. |
?
A reference to a buffer that contains the information specified by uiCommand. If uiCommand is sizeof( before calling GetRawInputDeviceInfo.
The size, in bytes, of the data in pData.
If successful, this function returns a non-negative number indicating the number of bytes copied to pData.
If pData is not large enough for the data, the function returns -1. If pData is
Call GetLastError to identify any other errors.
Registers the devices that supply the raw input data.
\t\nAn array of
The number of
The size, in bytes, of a
TRUE if the function succeeds; otherwise,
To receive WM_INPUT messages, an application must first register the raw input devices using RegisterRawInputDevices. By default, an application does not receive raw input.
To receive WM_INPUT_DEVICE_CHANGE messages, an application must specify the
If a
Performs a buffered read of the raw input data.
\t\nA reference to a buffer of
The size, in bytes, of a
The size, in bytes, of the
If pData is
If an error occurs, the return value is (UINT)-1. Call GetLastError for the error code.
Using GetRawInputBuffer, the raw input data is buffered in the array of
The NEXTRAWINPUTBLOCK macro allows an application to traverse an array of
Note??To get the correct size of the raw input buffer, do not use *pcbSize, use *pcbSize * 8 instead. To ensure GetRawInputBuffer behaves properly on WOW64, you must align the
[StructLayout(LayoutKind.Explicit)]\t\n internal struct \t\n { [FieldOffset(0)] public header; [FieldOffset(16+8)] public mouse; [FieldOffset(16+8)] public keyboard; [FieldOffset(16+8)] public hid;\t\n }\t\n Retrieves the raw input from the specified device.
\t\nA handle to the
The command flag. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
| Get the header information from the |
| Get the raw data from the |
?
A reference to the data that comes from the
The size, in bytes, of the data in pData.
The size, in bytes, of the
If pData is
If there is an error, the return value is (UINT)-1.
GetRawInputData gets the raw input one
Defines the raw input data coming from any device.
\t\nThe size, in bytes, of the
The type of raw input data. This member can be one of the following values.
| Value | Meaning |
|---|---|
| Data comes from an HID that is not a keyboard or a mouse. |
| Data comes from a keyboard. |
| Data comes from a mouse. |
?
If dwType is
If dwType is
If dwType is
Defines the raw input data coming from the specified Human Interface Device (HID).
\t\nThe vendor identifier for the HID.
The product identifier for the HID.
The version number for the HID.
The top-level collection Usage Page for the device.
The top-level collection Usage for the device.
Defines the raw input data coming from the specified keyboard.
\t\nFor the keyboard, the Usage Page is 1 and the Usage is 6.
\t\nThe type of the keyboard.
The subtype of the keyboard.
The scan code mode.
The number of function keys on the keyboard.
The number of LED indicators on the keyboard.
The total number of keys on the keyboard.
Defines the raw input data coming from the specified mouse.
\t\nFor the mouse, the Usage Page is 1 and the Usage is 2.
\t\nThe identifier of the mouse device.
The number of buttons for the mouse.
The number of data points per second. This information may not be applicable for every mouse device.
TRUE if the mouse has a wheel for horizontal scrolling; otherwise,
Describes the format of the raw input from a Human Interface Device (HID).
\t\nEach WM_INPUT can indicate several inputs, but all of the inputs come from the same HID. The size of the bRawData array is dwSizeHid *\tdwCount.
\t\nThe size, in bytes, of each HID input in bRawData.
The number of HID inputs in bRawData.
The raw input data, as an array of bytes.
Contains the raw input from a device.
\t\nThe handle to this structure is passed in the lParam parameter of WM_INPUT.
To get detailed information -- such as the header and the content of the raw input -- call GetRawInputData.
To read the
To get device specific information, call GetRawInputDeviceInfo with the hDevice from
Raw input is available only when the application calls RegisterRawInputDevices with valid device specifications.
\t\nThe raw input data.
If the data comes from a mouse, this is the raw input data.
If the data comes from a keyboard, this is the raw input data.
If the data comes from an HID, this is the raw input data.
Defines information for the raw input devices.
\t\nIf
If
Top level collection Usage page for the raw input device.
Top level collection Usage for the raw input device.
Mode flag that specifies how to interpret the information provided by usUsagePage and usUsage. It can be zero (the default) or one of the following values. By default, the operating system sends raw input from devices with the specified top level collection (TLC) to the registered application as long as it has the window focus.
| Value | Meaning |
|---|---|
| If set, the application command keys are handled. |
| If set, the mouse button click does not activate the other window. |
| If set, this enables the caller to receive WM_INPUT_DEVICE_CHANGE notifications for device arrival and device removal. Windows?XP:??This flag is not supported until Windows?Vista |
| If set, this specifies the top level collections to exclude when reading a complete usage page. This flag only affects a TLC whose usage page is already specified with |
| If set, this enables the caller to receive input in the background only if the foreground application does not process it. In other words, if the foreground application is not registered for raw input, then the background application that is registered will receive the input. Windows?XP:??This flag is not supported until Windows?Vista |
| If set, this enables the caller to receive the input even when the caller is not in the foreground. Note that hwndTarget must be specified. |
| If set, the application-defined keyboard device hotkeys are not handled. However, the system hotkeys; for example, ALT+TAB and CTRL+ALT+DEL, are still handled. By default, all keyboard hotkeys are handled. |
| If set, this prevents any devices specified by usUsagePage or usUsage from generating legacy messages. This is only for the mouse and keyboard. See Remarks. |
| If set, this specifies all devices whose top level collection is from the specified usUsagePage. Note that usUsage must be zero. To exclude a particular top level collection, use |
| If set, this removes the top level collection from the inclusion list. This tells the operating system to stop reading from a device which matches the top level collection. |
?
A handle to the target window. If
Contains information about a raw input device.
\t\nA handle to the raw input device.
The type of device. This can be one of the following values.
| Value | Meaning |
|---|---|
| The device is an HID that is not a keyboard and not a mouse. |
| The device is a keyboard. |
| The device is a mouse. |
?
Contains the header information that is part of the raw input data.
\t\nTo get more information on the device, use hDevice in a call to GetRawInputDeviceInfo.
\t\nThe type of raw input. It can be one of the following values.
| Value | Meaning |
|---|---|
| Raw input comes from some device that is not a keyboard or a mouse. |
| Raw input comes from the keyboard. |
| Raw input comes from the mouse. |
?
The size, in bytes, of the entire input packet of data. This includes
A handle to the device generating the raw input data.
The value passed in the wParam parameter of the WM_INPUT message.
Contains information about the state of the keyboard.
\t\nThe scan code from the key depression. The scan code for keyboard overrun is KEYBOARD_OVERRUN_MAKE_CODE.
Flags for scan code information. It can be one or more of the following.
| Value | Meaning |
|---|---|
| The key is up. |
| This is the left version of the key. |
| This is the right version of the key. |
| The key is down. |
?
Reserved; must be zero.
Windows message compatible virtual-key code. For more information, see Virtual Key Codes.
The corresponding window message, for example
The device-specific additional information for the event.
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
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| BlendEnable | |
| SrcBlend | |
| DstBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DstBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask[8] |
?
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nCreate a blend-state object that encapsules blend state for the output-merger stage.
\nAn 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.
Create a blend-state object that encapsules blend state for the output-merger stage.
\nAn 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.
Create a blend-state object that encapsules blend state for the output-merger stage.
\nAn 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.
Create a blend-state object that encapsules blend state for the output-merger stage.
\nAn 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.
Create a blend-state object that encapsules blend state for the output-merger stage.
\nPointer to a blend-state description (see
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.
Create a blend-state object that encapsules blend state for the output-merger stage.
\nPointer to a blend-state description (see
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.
Create a blend-state object that encapsules blend state for the output-merger stage.
\nPointer to a blend-state description (see
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.
Texture width (in texels). The range is from 1 to
Texture height (in texels). The range is from 1 to
Texture depth (in texels). The range is from 1 to
Number of textures in the array. The range is from 1 to
The maximum number of mipmap levels in the texture. See the remarks in
Texture format (see
A member of the DXGI_USAGE enumerated type that describes the surface usage and CPU access options for the back buffer. The back buffer can be used for shader input or render-target output.
\nBecause
\n This class is caching
Create a sampler-state object that encapsulates sampling information for a texture.
\t\n4096 unique sampler state objects can be created on a device at a time.
If an application attempts to create a sampler-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique sampler state objects will stay the same.
\t\nCreate a sampler-state object that encapsulates sampling information for a texture.
\t\n4096 unique sampler state objects can be created on a device at a time.
If an application attempts to create a sampler-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique sampler state objects will stay the same.
\t\nCreate a sampler-state object that encapsulates sampling information for a texture.
\t\n4096 unique sampler state objects can be created on a device at a time.
If an application attempts to create a sampler-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique sampler state objects will stay the same.
\t\nCreate a rasterizer state object that tells the rasterizer stage how to behave.
\t\n4096 unique rasterizer state objects can be created on a device at a time.
If an application attempts to create a rasterizer-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique rasterizer state objects will stay the same.
\t\nCreate a rasterizer state object that tells the rasterizer stage how to behave.
\t\n4096 unique rasterizer state objects can be created on a device at a time.
If an application attempts to create a rasterizer-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique rasterizer state objects will stay the same.
\t\nCreate a rasterizer state object that tells the rasterizer stage how to behave.
\t\n4096 unique rasterizer state objects can be created on a device at a time.
If an application attempts to create a rasterizer-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique rasterizer state objects will stay the same.
\t\n4096 unique depth-stencil state objects can be created on a device at a time.
If an application attempts to create a depth-stencil-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique depth-stencil state objects will stay the same.
\t\n4096 unique depth-stencil state objects can be created on a device at a time.
If an application attempts to create a depth-stencil-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique depth-stencil state objects will stay the same.
\t\n4096 unique depth-stencil state objects can be created on a device at a time.
If an application attempts to create a depth-stencil-state interface with the same state as an existing interface, the same interface will be returned and the total number of unique depth-stencil state objects will stay the same.
\t\nTexture width (in texels). The range is from 1 to
Texture height (in texels). The range is from 1 to
Texture depth (in texels). The range is from 1 to
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.
| Differences between Direct3D 9 and Direct3D 11/10: Unlike Direct3D 9, the full extent of the resource view is always cleared. Viewport and scissor settings are not applied. |
?
Pointer to the depth stencil to be cleared.
Identify the type of data to clear (see
Clear the depth buffer with this value. This value will be clamped between 0 and 1.
Clear the stencil buffer with this value.
| Differences between Direct3D 9 and Direct3D 11/10: Unlike Direct3D 9, the full extent of the resource view is always cleared. Viewport and scissor settings are not applied. |
?
\t\nThis API copies the lower ni bits from each array element i to the corresponding channel, where ni is the number of bits in the ith channel of the resource format (for example, R8G8B8_FLOAT has 8 bits for the first 3 channels). This works on any UAV with no format conversion. For a raw or structured buffer view, only the first array element value is used.
\t\nThis API works on FLOAT, UNORM, and SNORM unordered access views (UAVs), with format conversion from FLOAT to *NORM where appropriate. On other UAVs, the operation is invalid and the call will not reach the driver.
\t\n D3D11_BOX sourceRegion;\t\n sourceRegion.left = 120;\t\n sourceRegion.right = 200;\t\n sourceRegion.top = 100;\t\n sourceRegion.bottom = 220;\t\n sourceRegion.front = 0;\t\n sourceRegion.back = 1; pd3dDeviceContext->CopySubresourceRegion( pDestTexture, 0, 10, 20, 0, pSourceTexture, 0, &sourceRegion ); \t\n \t\n Notice, that for a 2D texture, front and back are set to 0 and 1 respectively. \t\n D3D11_BOX sourceRegion;\t\n sourceRegion.left = 120;\t\n sourceRegion.right = 200;\t\n sourceRegion.top = 100;\t\n sourceRegion.bottom = 220;\t\n sourceRegion.front = 0;\t\n sourceRegion.back = 1; pd3dDeviceContext->CopySubresourceRegion( pDestTexture, 0, 10, 20, 0, pSourceTexture, 0, &sourceRegion ); \t\n \t\n Notice, that for a 2D texture, front and back are set to 0 and 1 respectively. \t\n Copies data from a buffer holding variable length data.
\t\nPointer to an
Pointer to
Offset from the start of pDstBuffer to write 32-bit UINT structure (vertex) count from pSrcView.
Restore all default settings.
\t\nThis method resets any device context to the default settings. This sets all input/output resource slots, shaders, input layouts, predications, scissor rectangles, depth-stencil state, rasterizer state, blend state, sampler state, and viewports to
For a scenario where you would like to clear a list of commands recorded so far, call
Draw indexed, non-instanced primitives.
\t\nNumber of indices to draw.
The location of the first index read by the GPU from the index buffer.
A value added to each index before reading a vertex from the vertex buffer.
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.
\t\nDraw non-indexed, non-instanced primitives.
\t\nNumber of vertices to draw.
Index of the first vertex, which is usually an offset in a vertex buffer; it could also be used as the first vertex id generated for a shader parameter marked with the SV_TargetId system-value semantic.
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.
\t\nDraw indexed, instanced primitives.
\t\nNumber of indices read from the index buffer for each instance.
Number of instances to draw.
The location of the first index read by the GPU from the index buffer.
A value added to each index before reading a vertex from the vertex buffer.
A value added to each index before reading per-instance data from a vertex buffer.
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.
\t\nDraw non-indexed, instanced primitives.
\t\nNumber of vertices to draw.
Number of instances to draw.
Index of the first vertex.
A value added to each index before reading per-instance data from a vertex buffer.
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.
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).
\t\nDraw geometry of an unknown size.
\t\nA draw API submits work to the rendering pipeline. This API submits work of an unknown size that was processed by the input assembler, vertex shader, and stream-output stages; the work may or may not have gone through the geometry-shader stage.
After data has been streamed out to stream-output 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,
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
Draw indexed, instanced, GPU-generated primitives.
\t\nA reference to an
Offset in pBufferForArgs to the start of the GPU generated primitives.
When an application creates a buffer that is associated with the
Draw instanced, GPU-generated primitives.
\t\nA reference to an
Offset in pBufferForArgs to the start of the GPU generated primitives.
When an application creates a buffer that is associated with the
Execute a command list from a thread group.
\t\nThe number of groups dispatched in the x direction. ThreadGroupCountX must be less than
The number of groups dispatched in the y direction. ThreadGroupCountY must be less than
The number of groups dispatched in the z direction. ThreadGroupCountZ must be less than
You call the Dispatch method to execute commands in a compute shader. A compute shader can be run on many threads in parallel, within a thread group. Index a particular thread, within a thread group using a 3D vector given by (x,y,z).
In the following illustration, assume a thread group with 50 threads where the size of the group is given by (5,5,2). A single thread is identified from a thread group with 50 threads in it, using the vector (4,1,1).
The following illustration shows the relationship between the parameters passed to
Execute a command list over one or more thread groups.
\t\nA reference to an
A byte-aligned offset between the start of the buffer and the arguments.
You call the DispatchIndirect method to execute commands in a compute shader.
When an application creates a buffer that is associated with the
Sends queued-up commands in the command buffer to the graphics processing unit (GPU).
\t\nMost applications don't need to call this method. If an application calls this method when not necessary, it incurs a performance penalty. Each call to Flush incurs a significant amount of overhead.
When Microsoft 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. Typically, the Direct3D runtime sends these commands to the GPU automatically whenever the runtime determines that they need to be sent, such as when the command buffer is full or when an application maps a resource. Flush sends the commands manually.
We recommend that you use Flush when the CPU waits for an arbitrary amount of time (such as when you call the Sleep function).
Because Flush operates asynchronously, it can return either before or after the GPU finishes executing the queued graphics commands. However, the graphics commands eventually always complete. You can call the
Microsoft Direct3D?11 defers the destruction of objects. Therefore, an application can't rely upon objects immediately being destroyed. By calling Flush, you destroy any objects whose destruction was deferred. If an application requires synchronous destruction of an object, we recommend that the application release all its references, call
Direct3D?11 defers the destruction of objects like views and resources until it can efficiently destroy them. This deferred destruction can cause problems with flip presentation model swap chains. Flip presentation model swap chains have the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL flag set. When you create a flip presentation model swap chain, you can associate only one swap chain at a time with an
Most applications typically use the
Sets the blend state of the output-merger stage.
\t\nPointer to a blend-state interface (see
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
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| BlendEnable | |
| SrcBlend | |
| DstBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DstBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask[8] |
?
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets the blend state of the output-merger stage.
\t\nPointer to a blend-state interface (see
Array of blend factors, one for each RGBA component. This requires a blend state object that specifies the
32-bit sample coverage. The default value is 0xffffffff. See remarks.
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
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| BlendEnable | |
| SrcBlend | |
| DstBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DstBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask[8] |
?
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets the blend state of the output-merger stage.
\t\nPointer to a blend-state interface (see
Array of blend factors, one for each RGBA component. This requires a blend state object that specifies the
32-bit sample coverage. The default value is 0xffffffff. See remarks.
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
| State | Default Value |
|---|---|
| AlphaToCoverageEnable | |
| BlendEnable | |
| SrcBlend | |
| DstBlend | |
| BlendOp | |
| SrcBlendAlpha | |
| DstBlendAlpha | |
| BlendOpAlpha | |
| RenderTargetWriteMask[8] |
?
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nPointer to a depth-stencil state interface (see
Reference value to perform against when doing a depth-stencil test. See remarks.
To create a depth-stencil state interface, call
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nSets the rasterizer state for the rasterizer stage of the pipeline.
\t\nAll scissor rects must be set atomically as one operation. Any scissor rects not defined by the call are disabled.
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
All scissor rects must be set atomically as one operation. Any scissor rects not defined by the call are disabled.
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
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; if a geometry shader does not specify the semantic, Direct3D will use the first viewport in the array.
\t\nAll 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; if a geometry shader does not specify the semantic, Direct3D will use the first viewport in the array.
\t\nAll 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; if a geometry shader does not specify the semantic, Direct3D will use the first viewport in the array.
\t\nBind one or more render targets atomically and the depth-stencil buffer to the output-merger stage.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nThe maximum number of active render targets a device can have active at any given time is set by a #define in D3D11.h called D3D11_SIMULTANEOUS_RENDER_TARGET_COUNT. It is invalid to try to set the same subresource to multiple render target slots. Any render targets not defined by this call are set to
If any subresources are also currently bound for reading in a different stage or writing (perhaps in a different part of the pipeline), those bind points will be set to
The method will hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
If the render-target views were created from an array resource type, then all of the render-target views must have the same array size. This restriction also applies to the depth-stencil view, its array size must match that of the render-target views being bound.
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.
\t\nBind an index buffer to the input-assembler stage.
\t\nA reference to an
For information about creating index buffers, see How to: 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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nFor 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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nFor 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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nBind a vertex buffer to the input-assembler stage.
\t\nFor 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
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 hold a reference to the interfaces passed in. This differs from the device state behavior in Direct3D 10.
\t\nTexture width (in texels). The range is from 1 to
Texture height (in texels). The range is from 1 to
Texture depth (in texels). The range is from 1 to
Number of textures in the array. The range is from 1 to
The maximum number of mipmap levels in the texture. See the remarks in
Texture format (see
Structure that specifies multisampling parameters for the texture. See
Value that identifies how the texture is to be read from and written to. The most common value is
Flags (see
Flags (see
Flags (see
Describes a shader signature.
\t\nDescribes a semantic signature.
\t\nA shader can take n inputs and can produce m outputs. The order of the input (or output) parameters, their associated types, and any attached semantics make up the shader signature. Each shader has an input and an output signature.
When compiling a shader or an effect, some API calls validate shader signatures That is, they compare the output signature of one shader (like a vertex shader) with the input signature of another shader (like a pixel shader). This ensures that a shader outputs data that is compatible with a downstream shader that is consuming that data. Compatible means that a shader signature is a exact-match subset of the preceding shader stage. Exact match means parameter types and semantics must exactly match. Subset means that a parameter that is not required by a downstream stage, does not need to include that parameter in its shader signature.
Get a shader-signature from a shader or an effect by calling APIs such as
A per-parameter string that identifies how the data will be used.
Semantic index that modifies the semantic. Used to differentiate different parameters that use the same semantic.
The register that will contain this variable's data.
A predefined string that determines the functionality of certain pipeline stages. See D3D10_NAME.
The per-component-data type that is stored in a register. See D3D10_REGISTER_COMPONENT_TYPE. Each register can store up to four-components of data.
Mask which indicates which components of a register are used.
Mask which indicates whether a given component is never written (if the signature is an output signature) or always read (if the signature is an input signature).
Indicates which stream the geometry shader is using for the signature parameter.
The HLSL semantic associated with this element in a shader input-signature.
The semantic index for the element. A semantic index modifies a semantic, with an integer index number. A semantic index is only needed in a case where there is more than one element with the same semantic. For example, a 4x4 matrix would have four components each with the semantic name
matrix, however each of the four component would have different semantic indices (0, 1, 2, and 3).
The data type of the element data. See
Optional. Offset (in bytes) between each element. Use D3D11_APPEND_ALIGNED_ELEMENT for convenience to define the current element directly after the previous one, including any packing if necessary.
The HLSL semantic associated with this element in a shader input-signature.
The semantic index for the element. A semantic index modifies a semantic, with an integer index number. A semantic index is only needed in a case where there is more than one element with the same semantic. For example, a 4x4 matrix would have four components each with the semantic name
matrix, however each of the four component would have different semantic indices (0, 1, 2, and 3).
The data type of the element data. See
Optional. Offset (in bytes) between each element. Use D3D11_APPEND_ALIGNED_ELEMENT for convenience to define the current element directly after the previous one, including any packing if necessary.
The shader variable is a scalar.
The shader variable is a vector.
The shader variable is a row-major matrix.
The shader variable is a column-major matrix.
The shader variable is an object.
The shader variable is a structure.
The shader variable is a class.
The shader variable is an interface.
Values that identify various data, texture, and buffer types that can be assigned to a shader variable.
\t\nA call to the
The types in a structured buffer describe the structure of the elements in the buffer. The layout of these types generally match their C++ struct counterparts. The following examples show structured buffers:
struct mystruct {float4 val; uint ind;}; RWStructuredBuffer<mystruct> rwbuf;\t\n RWStructuredBuffer<float3> rwbuf2;The variable is a void reference.
The variable is a boolean.
The variable is an integer.
The variable is a floating-point number.
The variable is a string.
The variable is a texture.
The variable is a 1D texture.
The variable is a 2D texture.
The variable is a 3D texture.
The variable is a texture cube.
The variable is a sampler.
The variable is a sampler.
The variable is a sampler.
The variable is a sampler.
The variable is a sampler.
The variable is a pixel shader.
The variable is a vertex shader.
The variable is a pixel shader.
The variable is a vertex shader.
The variable is an unsigned integer.
The variable is an 8-bit unsigned integer.
The variable is a geometry shader.
The variable is a rasterizer-state object.
The variable is a depth-stencil-state object.
The variable is a blend-state object.
The variable is a buffer.
The variable is a constant buffer.
The variable is a texture buffer.
The variable is a 1D-texture array.
The variable is a 2D-texture array.
The variable is a render-target view.
The variable is a depth-stencil view.
The variable is a 2D-multisampled texture.
The variable is a 2D-multisampled-texture array.
The variable is a texture-cube array.
The variable holds a compiled hull-shader binary.
The variable holds a compiled domain-shader binary.
The variable is an interface.
The variable holds a compiled compute-shader binary.
The variable is a double precision (64-bit) floating-point number.
The variable is a 1D read-and-write texture.
The variable is an array of 1D read-and-write textures.
The variable is a 2D read-and-write texture.
The variable is an array of 2D read-and-write textures.
The variable is a 3D read-and-write texture.
The variable is a read-and-write buffer.
The variable is a byte-address buffer.
The variable is a read-and-write byte-address buffer.
The variable is a structured buffer.
For more information about structured buffer, see the Remarks section.
The variable is a read-and-write structured buffer.
The variable is an append structured buffer.
The variable is a consume structured buffer.
Runtime parameters for initialization of the XACT engine.
\t\n| Xbox 360 |
|---|
| Memory for this member must be allocated using XMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
| Windows |
|---|
| Memory for this member must be allocated using CoTaskMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
| Value | Description |
|---|---|
| XACT_FLAG_ENGINE_CREATE_MANAGEDATA | Indicates that XACT should free the buffer pointed to by pGlobalSettingsBuffer when initialization is complete. Note XACT will not attempt to free the memory if the buffer allocation fails. ? |
| Xbox 360 |
|---|
| This member is needed only if XACT_FLAG_ENGINE_CREATE_MANAGEDATA is specified in globalSettingsFlags, so that XMemFree can receive the correct values when XACT frees the buffer. Otherwise, globalSettingsAllocAttributes is ignored. These flags should match the XALLOC_ATTRIBUTES values that were specified to XMemAlloc when the memory buffer pointed to by pGlobalSettingsBuffer was allocated. |
| Windows |
|---|
| This parameter has no relevance and is ignored. |
| Xbox 360 |
|---|
| This parameter is undefined. |
Retrieves the properties of the cue.
[Content-driven]
\t\nGetProperties will allocate memory for the
| Xbox 360 |
|---|
| GetProperties performs memory allocation using XMemAlloc. The caller should free the memory using XMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
| Windows |
|---|
| The caller should free the memory using CoTaskMemAlloc. The caller should free the memory using CoTaskMemFree. As an example: LPXACT_CUE_INSTANCE_PROPERTIES pCueProperties = |
Plays a prepared cue.
[Content-driven]
\t\nReturns
Stops a cue.
[Content-driven]
\t\n| Value | Description |
|---|---|
| Indicates the cue should stop immediately, ignoring any release phase or transition specified in the content.? |
| Note |
|---|
| Specifying a value of 0 causes Stop to account for the release phase and/or transition specified in the XACT. |
Returns
Retrieves the current operating state of a cue.
[Content-driven]
\t\n| Value | Description |
|---|---|
| Created, but nothing else? | |
| Preparing to play? | |
| Prepared, but not yet played? | |
| Playing, but can be paused? | |
| Stopping? | |
| Stopped? | |
| Paused? |
| Note |
|---|
| States represented by these flags are not necessarily mutually exclusive. Therefore, test states using the & (and) operation rather than the == (equals) operation. |
Returns
This function informs the caller what activity the cue is performing at the moment the call is made. The state returned from GetState indicates only the current condition.
Only
Destroys the cue.
[Content-driven]
\t\n
Sets the volume level that each source channel of the cue should play in each of its destination channels.
[Content-driven]
\t\nReturns
The SetMatrixCoefficients method is primarily used for creating the illusion of the cue being played at some position in 3D space. However, it is recommended to use the XACT methods provided for interacting with X3DAudio instead of calling SetMatrixCoefficients directly. The XACT's X3DAudio helper methods handle calculating and applying a cue's matrix coefficients by calling SetMatrixCoefficients. See How To: Integrate X3DAudio with XACT for more information.
\t\nRetrieves the corresponding index for a variable name string.
[Content-driven]
\t\nThe index of the variable if it exists, or XACTVARIABLEINDEX_INVALID otherwise.
Stores a new value to a variable, referenced by its index.
[Content-driven]
\t\nReturns
If the variable is private or read-only, SetVariable returns XACTENGINE_E_INVALIDVARIABLEINDEX.
If nValue falls outside of it's assigned range (or XACTVARIABLEVALUE_MIN to XACTVARIABLEVALUE_MAX), SetVariable returns E_FAIL. In this case, the variable is clamped within valid range and a warning message is sent to the debugger.
Retrieves the value of a variable by its index.
[Content-driven]
\t\nSets the volume level of each channel of the final output for the voice. These channels are mapped to the input channels of a specified destination voice.
\t\n| Note |
|---|
| If the voice sends to a single target voice specifying |
For example, when rendering two-channel stereo input into 5.1 output that is weighted toward the front channels?but is absent from the center and low-frequency channels?the matrix might have the values shown in the following table.
| Output | Left Input | Right Input |
|---|---|---|
| Left | 1.0 | 0.0 |
| Right | 0.0 | 1.0 |
| Front Center | 0.0 | 0.0 |
| LFE | 0.0 | 0.0 |
| Rear Left | 0.8 | 0.0 |
| Rear Right | 0.0 | 0.8 |
Note that the left and right input are fully mapped to the output left and right channels; 80 percent of the left and right input is mapped to the rear left and right channels.
See Remarks for more information on volume levels.
Returns
Volume levels are expressed as floating-point amplitude multipliers between -
Retrieves the current operating state of a cue.
[Content-driven]
\t\nThis function informs the caller what activity the cue is performing at the moment the call is made. The state returned from GetState indicates only the current condition.
Only
This section contains information about the methods used with the
Retrieves information about a specific renderer.
| Xbox 360 |
|---|
| This method is not supported on the Xbox 360 platform. |
[Content-driven]
\t\nInitializes the XACT engine.
[Content-driven]
\t\nReturns
This function creates the XACT engine and data structures. It should be called in an application only once per
If a title passes an instance of the XAudio2 engine to Initialize and uses auditioning the XAudio2 mastering voice must have a volume meter XAPO attached to it. See XAudio2CreateVolumeMeter for information on creating the volume meter and SetEffectChain for information on attaching the volume meter.
\t\nShuts down the XACT engine and frees any resources in use.
[Content-driven]
\t\nReturns
This method destroys all existing cues, sound banks, and wave banks. It blocks until all cues are destroyed. The method also flushes all pending notifications and unregisters all notification descriptions. No XACT API or method calls can be made after calling this function.
\t\nPerforms periodic work that is required by the XACT engine.
[Code-driven]
[Content-driven]
\t\nReturns
This method drives the XACT engine and is typically called every 30 to 100 milliseconds (about once every one to four frames).
\t\nCreates a sound bank for use by the XACT engine.
[Content-driven]
\t\n| Xbox 360 |
|---|
| Memory for this member must be allocated by using XMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. Xbox 360 sound banks must be allocated from physical memory (and not the heap). The XALLOC_MEMTYPE_PHYSICAL memory type must be specified as dwMemoryType when memory is allocated through XMemAlloc. |
| Windows |
|---|
| Memory for this member must be allocated by using CoTaskMemAlloc when specifying the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
| Value | Description |
|---|---|
| XACT_FLAG_ENGINE_CREATE_MANAGEDATA | Indicates that XACT should free the buffer that the pvBuffer parameter points to, when the sound bank data is released. Note XACT does not attempt to free the memory if the buffer allocation fails. ? |
| Xbox 360 |
|---|
| This parameter is needed only if XACT_FLAG_ENGINE_CREATE_MANAGEDATA is specified in dwFlags. This is so that XMemFree can receive the correct values when the XACT frees the buffer. Otherwise, dwAllocAttributes is ignored. These flags should match the XALLOC_ATTRIBUTES values that were specified to XMemAlloc when the memory buffer that pvBuffer points to was allocated. |
| Windows |
|---|
| This parameter has no relevance and is ignored. |
Returns
Creates an in-memory wave bank for use by the XACT engine.
[Code-driven]
[Content-driven]
\t\n| Xbox 360 |
|---|
| Memory for this member must be allocated by using XMemAlloc when you specify the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. Xbox 360 wavebanks must be created with caching enabled. The PAGE_WRITECOMBINE and PAGE_NOCACHE flags must not be used when calling XMemAlloc. Xbox 360 wavebanks must be allocated from physical memory (and not the heap). The XALLOC_MEMTYPE_PHYSICAL memory type must be specified as dwMemoryType when memory is allocated through XMemAlloc. |
| Windows |
|---|
| Memory for this member must be allocated by using CoTaskMemAlloc when you specify the XACT_FLAG_ENGINE_CREATE_MANAGEDATA flag. |
| Value | Description |
|---|---|
| XACT_FLAG_ENGINE_CREATE_MANAGEDATA | Indicates that XACT frees the buffer that the pvBuffer parameter points to, when the wave bank data is released. Note XACT does not attempt to free the memory if the buffer allocation fails. ? |
| Xbox 360 |
|---|
| This parameter is needed only if XACT_FLAG_ENGINE_CREATE_MANAGEDATA is specified in dwFlags. This is so that XMemFree can receive the correct values when the XACT engine frees the buffer. Otherwise, dwAllocAttributes is ignored. These flags should match the XALLOC_ATTRIBUTES values that were specified to XMemAlloc when the memory buffer that pvBuffer points to was allocated. |
| Windows |
|---|
| This parameter has no relevance and is ignored. |
Returns
Creates an
[Code-driven]
[Content-driven]
\t\nReturns
Do not use a sound that is associated with a streaming wave bank unless you know that the wave bank is prepared.
To ascertain that the wave bank is prepared, do one of the following:
Create an XACTNOTIFICATIONTYPE_WAVEBANKPREPARED notification by using
?or?
Issue a query about the state of the wave bank by using
Prepares a wave object from a standard PCM, XMA (Xbox 360) file.
[Code-driven]
\t\n| Value | Description |
|---|---|
| XACT_FLAG_BACKGROUND_MUSIC | Marks the waves as background music.Xbox 360 This flag is supported only on the Xbox 360 platform. ? |
| XACT_FLAG_UNITS_MS | Indicates that the units passed in are measured in milliseconds.? |
| XACT_FLAG_UNITS_SAMPLES | Indicates that the units passed in are in samples.? |
Returns
If this API is used to prepare XMA content, the content must be encoded by using 64K block size.
PrepareWave does not support xWMA. xWMA content can be prepared using one of the following methods:
Creates an in-memory
[Code-driven]
\t\nReturns
The application must make sure that the any buffers passed in (data, seek table) are valid through the lifetime of this wave.
| Xbox 360 |
|---|
| If this API is used to prepare XMA content, the content must be encoded with 64K block size. When using XMAEncode, specify \"/b 64\" on the command line to create 64K blocks. |
Creates a streaming wave object for the file handle that is passed in.
[Code-driven]
\t\n| Value | Description |
|---|---|
| XACT_FLAG_BACKGROUND_MUSIC | Marks the waves as background music. Xbox 360 This flag is supported only on the Xbox 360 platform.? |
| XACT_FLAG_UNITS_MS | Indicates that the units passed in are measured in milliseconds.? |
| XACT_FLAG_UNITS_SAMPLES | Indicates that the units passed in are in samples.? |
Returns
If this API is used to prepare XMA content, the content must be encoded with 64K block size. ADPCM files are currently not supported.
\t\nRegisters an event notification.
[Content-driven]
\t\nReturns
Cancels registration of an event notification.
[Content-driven]
\t\n| Note |
|---|
| Attempting to unregister a notification that has not been registered has no effect. |
Returns
Retrieves the sound category index that corresponds to a friendly name string.
[Content-driven]
\t\nReturns a category index for the friendly name if successful. Otherwise, XACTCATEGORY_INVALID.
Sets the volume of a sound category.
[Content-driven]
\t\nReturns
The volume is a floating point scale where 0.0 means -96db, 1.0 means 0db, and 2.0 means +6db.
\t\nPauses or resumes playback of a category.
[Content-driven]
\t\nReturns
A stopping or stopped cue cannot be paused.
\t\nRetrieves the corresponding index for a global variable name string.
[Content-driven]
\t\nThe index of the global variable if it exists. Otherwise, XACTVARIABLEINDEX_INVALID.
Stores a new value to a global variable, which is referenced by its index.
[Content-driven]
\t\nReturns
Retrieves the value of a global variable by its index.
[Content-driven]
\t\nWave bank segment identifiers.
\t\nPlays a cue. Optionally, returns an instance handle to the cue object for further control.
[Content-driven]
\t\nRetrieves a sound cue index based on a string that represents the friendly name of the cue.
[Content-driven]
\t\n| Note |
|---|
| This string is case sensitive. |
Returns the cue index that is associated with szFriendlyName. If the cue index is not found, XACTINDEX_INVALID is returned.
Retrieves the number of cues in the sound bank.
[Content-driven]
\t\nReturns
Retrieves the properties of a cue.
[Content-driven]
\t\nPrepares a cue instance for playback.
[Content-driven]
\t\nThis method returns a valid cue instance that is ready to be played. All allocations and stream priming, if necessary, are performed by this method.
\t\nPlays a cue. Optionally, returns an instance handle to the cue object for further control.
[Content-driven]
\t\nStops a cue.
[Content-driven]
\t\n| Note |
|---|
| All instances of the cue that are specified by nCueIndex are stopped. |
| Value | Description |
|---|---|
| XACT_FLAG_SOUNDBANK_STOP_IMMEDIATE | Cue stops immediately. It ignores any release phase or transition that is specified in the content.? |
Returns
Destroys the sound bank.
[Content-driven]
\t\n
Retrieves the current state of the sound bank.
[Content-driven]
\t\n| Value | Description |
|---|---|
| XACT_SOUNDBANKSTATE_INUSE | Indicates that the sound bank is referenced by at least one valid cue instance or other client. For example, the game itself might reference the sound bank.? |
Returns
Plays a cue. Returns an instance handle to the cue object for further control.
\nPlays a cue. Returns an instance handle to the cue object for further control.
\nPlays a cue. Cue is automatically released when playback finished.
\nPrepares a cue instance for playback.
\nPrepares a cue instance for playback.
\nRetrieves the number of cues in the sound bank.
[Content-driven]
\t\nSets the volume value for each output of a wave.
[Code-driven]
\t\nThe final output volume of any channel is the matrix coefficient volume multiplied by the value that is specified by
Stops the wave.
[Code-driven]
\t\n| Value | Description |
|---|---|
| XACT_FLAG_STOP_RELEASE | Plays the wave to completion, then stops. For looping waves, this flag plays the current iteration to completion, then stops (ignoring any subsequent iterations). In either case, any release or tail is played. To stop the wave immediately, use the XACT_FLAG_STOP_IMMEDIATE flag.? |
| XACT_FLAG_STOP_IMMEDIATE | Stops the playback immediately.? |
Returns
Returns the state of the wave object.
[Code-driven]
\t\n| Value | Description |
|---|---|
| XACT_STATE_CREATED | Created, but nothing else.? |
| XACT_STATE_PREPARING | In the middle of preparing.? |
| XACT_STATE_PREPARED | Prepared, but not yet played.? |
| XACT_STATE_PLAYING | Playing, but can be paused.? |
| XACT_STATE_STOPPING | Stopping.? |
| XACT_STATE_STOPPED | Stopped.? |
| XACT_STATE_PAUSED | Paused. Can be combined with some of the other state flags.? |
| XACT_STATE_INUSE | Object is in use. Used by wave banks and sound banks.? |
| XACT_STATE_PREPAREFAILED | Object preparation failed.? |
Returns
Sets the pitch of a wave.
[Code-driven]
\t\nReturns
The value of pitch may be between XACTPITCH_MIN (-1200) and XACTPITCH_MAX (1200), which is approximately one semitone.
\t\nSets the volume of a wave.
[Code-driven]
\t\nReturns
Sets the volume value for each output of a wave.
[Code-driven]
\t\nReturns
The final output volume of any channel is the matrix coefficient volume multiplied by the value that is specified by
Retrieves the properties of the wave object.
[Code-driven]
\t\nReturns
Returns the state of the wave object.
[Code-driven]
\t\nSets the pitch of a wave.
[Code-driven]
\t\nThe value of pitch may be between XACTPITCH_MIN (-1200) and XACTPITCH_MAX (1200), which is approximately one semitone.
\t\nSets the volume of a wave.
[Code-driven]
\t\nRetrieves the properties of the wave object.
[Code-driven]
\t\nThis section contains information about the methods used with the
Destroys the wave bank.
[Content-driven]
\t\n
Returns the number of wave entries in the wave bank.
[Code-driven]
\t\nReturns
Returns the wave index for the friendly name of a wave in a wave bank.
[Code-driven]
\t\nWave index for the friendly name of a wave within a wave bank.
If the wave bank does not contain the friendly name, or if an entry does not exist for the name that is passed in, the method returns XACTINDEX_INVALID.
Gets the properties of a specific wave in a wave bank.
[Code-driven]
\t\nReturns
Starts the playback for a wave that is indicated by the wave index.
[Code-driven]
\t\n| Value | Description |
|---|---|
| XACT_FLAG_BACKGROUND_MUSIC | Marks the waves as background music.Xbox 360 This flag is supported only on the Xbox 360 platform.? |
| XACT_FLAG_UNITS_MS | Indicates that the units that are passed in are measured in milliseconds.? |
| XACT_FLAG_UNITS_SAMPLES | Indicates that the units that are passed in are in samples.? |
Retrieves the current state of the wave bank.
[Content-driven]
\t\n| Value | Description |
|---|---|
| XACT_WAVEBANKSTATE_INUSE | Indicates that the wave bank is referenced by at least one valid cue instance or other client. For example, the game itself might reference the wave bank.? |
| XACT_WAVEBANKSTATE_PREPARED | Indicates that the wave is prepared for use by a cue instance.? |
Returns
Returns the number of wave entries in the wave bank.
[Code-driven]
\t\nRetrieves the current state of the wave bank.
[Content-driven]
\t\nReports cue properties back to the client.
\t\nThis structure returns the non-instance specific cue properties for a cue. That is, it returns the properties shared across all instances of a cue.
\t\nFile I/O Callbacks
\t\nNotification structure for all XACT cue notifications.
\t\nProvides descriptions for registering, unregistering, and flushing notifications.
\t\n| Value\t\n | Supported Fields\t\n |
|---|---|
| XACTNOTIFICATIONTYPE_CUEPREPARED\t\n | None, sound bank, sound bank and cue index, cue instance\t\n |
| XACTNOTIFICATIONTYPE_CUEPLAY\t\n | None, sound bank, sound bank and cue index, cue instance\t\n |
| XACTNOTIFICATIONTYPE_CUESTOP\t\n | None, sound bank, sound bank and cue index, cue instance\t\n |
| XACTNOTIFICATIONTYPE_CUEDESTROYED\t\n | None, sound bank, sound bank and cue index, cue instance\t\n |
| XACTNOTIFICATIONTYPE_MARKER\t\n | None, sound bank, sound bank and cue index, cue instance\t\n |
| XACTNOTIFICATIONTYPE_SOUNDBANKDESTROYED\t\n | None, sound bank\t\n |
| XACTNOTIFICATIONTYPE_WAVEBANKDESTROYED\t\n | None, wave bank\t\n |
| XACTNOTIFICATIONTYPE_LOCALVARIABLECHANGED\t\n | None, sound bank, sound bank and cue index, cue instance\t\n |
| XACTNOTIFICATIONTYPE_GLOBALVARIABLECHANGED\t\n | None\t\n |
| XACTNOTIFICATIONTYPE_GUICONNECTED\t\n | None\t\n |
| XACTNOTIFICATIONTYPE_GUIDISCONNECTED\t\n | None\t\n |
| XACTNOTIFICATIONTYPE_WAVEPREPARED\t\n | None, wave bank and wave index, wave instance\t\n |
| XACTNOTIFICATIONTYPE_WAVEPLAY\t\n | None, sound bank, sound bank and cue index, cue instance, wave bank\t\n |
| XACTNOTIFICATIONTYPE_WAVESTOP\t\n | None, sound bank, sound bank and cue index, cue instance, wave bank\t\n |
| XACTNOTIFICATIONTYPE_WAVELOOPED\t\n | None, sound bank, sound bank and cue index, cue instance, wave bank, wave instance\t\n |
| XACTNOTIFICATIONTYPE_WAVEDESTROYED\t\n | None, wave bank and wave index, wave instance\t\n |
| XACTNOTIFICATIONTYPE_WAVEBANKPREPARED\t\n | None, wave bank\t\n |
| XACTNOTIFICATIONTYPE_WAVEBANKSTREAMING_INVALIDCONTENT\t\n | None, wave bank\t\n |
| Value | Description |
|---|---|
| XACT_FLAG_NOTIFICATION_PERSIST | Sets the notification to persist. If this flag is not set, the user receives no more than one notification of the type registered.? |
Notification structure for all GUI notifications.
\t\nNotification structure for all marker notifications.
\t\nNotification structure for all sound bank notifications.
\t\nNotification structure for all variable notifications.
\t\nNotification structure for all wave notifications.
\t\nNotification structure for all wave bank notifications.
\t\nReturns information about a particular renderer.
\t\n| Note |
|---|
| The friendly name is useful in presenting the audio devices that are available to the end user. However, the renderer id can be passed in the |
Returns the properties for a sound that is referenced by the active variation.
\t\nThe following is an example of iterating through the track properties represented by the arrTrackProperties member:
void EnumerateTrackProperties(LPXACT_SOUND_PROPERTIES pSoundProperties)\t\n { for (XACTINDEX nIndex = 0; nIndex < pSoundProperties->numTracks; ++nIndex) { // Do something with pSoundProperties->arrTrackProperties[nIndex]; }\t\n }\t\n \t\n Returns the properties of the sound variation that is currently active in a cue instance.
\t\nStreaming parameters for a wave bank.
\t\nXact.h also includes the following constant declaration:
typedef const XACT_WAVEBANK_STREAMING_PARAMETERS *LPCXACT_WAVEBANK_STREAMING_PARAMETERS;\t\n
| Windows |
|---|
| The file that is referenced by this handle must be opened with the following CreateFile flags: FILE_FLAG_OVERLAPPED | FILE_FLAG_NO_BUFFERING. |
The size of a DVD sector is 2048 bytes. Therefore, setting this value to 2 results in a packet size of 4096 bytes. Setting it to 3 specifies packets of 6144 bytes, setting it to 4 specifies packets of 8192 bytes, and so on.
The optimal DVD size is a multiple of 16 (1 DVD block = 16 DVD sectors).
Returns the properties of a track in an active sound variation in a cue instance.
\t\nThese properties are timing dependent. They may change when the
Returns the properties for the variation that is currently active in a cue instance.
\t\nContains the entry information from an XACT wave bank.
\t\nDWORD value representing both the flags and duration.
Flags for the wave bank entry. Can be the following values.
| Value | Description |
|---|---|
| WAVEBANKENTRY_FLAGS_READAHEAD | Indicates stream read-ahead is enabled.? |
| WAVEBANKENTRY_FLAGS_LOOPCACHE | Indicates one or more looping sounds use this wave.? |
| WAVEBANKENTRY_FLAGS_REMOVELOOPTAIL | Indicates removal of data after the end of the loop region.? |
Duration of the wave, in units of one sample. For instance, a ten second long wave sampled at 48KHz would have a duration of 480,000. This value is not affected by the number of channels, the number of bits per sample, or the compression format of the wave.
Contains the header information from an XACT wave bank.
\t\nContains the mini-wave format for an XACT wave bank.
\t\nFormat of the wave file. Can be one of the values in the following table.
| Value | Description |
|---|---|
| Specifies PCM wave format.? | |
| Specifies XMA2 format.? | |
| Specifies ADPCM wave format.? | |
| Specifies xWMA format.? |
Number of channels in the wave file. Can be a value from 1 to 6.
Sampling rate of the wave file or sample rate of the decoded audio for compressed formats.
Block alignment index. For xWMA the lower 6 bits are the block alignment index and the upper 2 bits are the bytes per second index.
Bit depth of the wave file. Can be one of the values in the following table.
| Value | Description |
|---|---|
| WAVEBANKMINIFORMAT_BITDEPTH_8 | Specifies 8-bit data. (PCM only)? |
| WAVEBANKMINIFORMAT_BITDEPTH_16 | Specifies 16-bit data. (PCM, XMA, ADPCM).? |
For xWMA this field indicates whether the format is in the WMA format (0) or the WMA Pro format (1).
Contains the region information for an XACT wave bank.
\t\nReturns the properties that are common to all waves.
\t\nXAPO instances are passed to XAudio2 as
For additional information on using XAPOs with XAudio2 see How to: Create an Effect Chain and How to: Use an XAPO in XAudio2.
\t\nXAudio2 audio data is interleaved, data from each channel is adjacent for a particular sample number. For example if there was a 4 channel wave playing into an XAudio2 source voice, the audio data would be a sample of channel 0, a sample of channel 1, a sample of channel 2, a sample of channel 3, and then the next sample of channels 0, 1, 2, 3, etc.
The AudioBytes and pAudioData members of
Memory allocated to hold a
See XAudio2 Callbacks for restrictions on callback implementation.
\t\nUsed in the
The role represents the audio scenarios?such as voice communications or media playback?that use this device as the default device on which to play.
\t\nThere are many preset values defined for the
All parameters related to sampling rate or time are relative to a 48kHz voice and must be scaled for use with other sampling rates. For example, setting ReflectionsDelay to 300ms gives a true 300ms delay when the reverb is hosted in a 48kHz voice, but becomes a 150ms delay when hosted in a 24kHz voice.
\t\n| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| PositionRight is ignored in mono-in/mono-out mode. |
| Note |
|---|
| PositionMatrixRight is ignored in mono-in/mono-out mode. |
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | +1 | +2 | +3 | +4 |
Note that a LowEQGain value of 8 results in the decay time of low frequencies being equal to the decay time at 1 kHz. Permitted range is from 0 to 12 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (Hz) | 50 | 100 | 150 | 200 | 250 | 300 | 350 | 400 | 450 | 500 |
Permitted range is from 0 to 9 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 |
Permitted range is from 0 to 8 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (kHz) | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 4.5 | 5 | 5.5 | 6 | 6.5 | 7 | 7.5 | 8 |
Permitted range is from 0 to 14 (no units).
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
This structure is used with the XAudio2
pPeakLevels and pRMSLevels are not returned by
ChannelCount must be set by the application to match the number of channels in the voice the effect is applied to.
\t\nThis method is valid only for source and submix voices, because mastering voices write directly to the device with no matrix mixing.
Volume levels are expressed as floating-point amplitude multipliers between -
The X3DAudio function
| Note |
|---|
Returns
This method is only valid for source and submix voices. Mastering voices can not send audio to another voice.
After calling SetOutputVoices a voice's current send levels will be replaced by a default send matrix. The
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
| Note |
|---|
| If pEffectChain is non- |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
The number of output channels allowed for a voice's effect chain is locked at creation of the voice. If you create the voice with an effect chain, any new effect chain passed to SetEffectChain must have the same number of input and output channels as the original effect chain. If you create the voice without an effect chain, the number of output channels allowed for the effect chain will default to the number of input channels for the voice. If any part of effect chain creation fails, none of it is applied.
After you attach an effect to an XAudio2 voice, XAudio2 takes control of the effect, and the client should not make any further calls to it. The simplest way to ensure this is to release all references to the effect.
It is illegal to call SetEffectChain from within a callback. If you call SetEffectChain within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Returns
Be careful when you enable an effect while the voice that hosts it is running. Such an action can result in a problem if the effect significantly changes the audio's pitch or volume.
The effects in a given XAudio2 voice's effect chain must consume and produce audio at that voice's processing sample rate. The only aspect of the audio format they can change is the channel count. For example a reverb effect can convert mono data to 5.1. The client can use the
EnableEffect takes effect immediately when you call it from an XAudio2 callback with an OperationSet of
Returns
The effects in a given XAudio2 voice's effect chain must consume and produce audio at that voice's processing sample rate. The only aspect of the audio format they can change is the channel count. For example a reverb effect can convert mono data to 5.1. The client can use the
Disabling an effect immediately removes it from the processing graph. Any pending audio in the effect?such as a reverb tail?is not played. Be careful disabling an effect while the voice that hosts it is running. This can result in an audible artifact if the effect significantly changes the audio's pitch or volume.
DisableEffect takes effect immediately when called from an XAudio2 callback with an OperationSet of
GetEffectState always returns the effect's actual current state. However, this may not be the state set by the most recent
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
The specific effect being used determines the valid size and format of the pParameters buffer. The call will fail if pParameters is invalid or if ParametersByteSize is not exactly the size that the effect expects. The client must take care to direct the SetEffectParameters call to the right effect. If this call is directed to a different effect that happens to accept the same parameter block size, the parameters will be interpreted differently. This may lead to unexpected results.
The memory pointed to by pParameters must not be freed immediately, because XAudio2 will need to refer to it later when the parameters actually are applied to the effect. This happens during the next audio processing pass if the OperationSet argument is
SetEffectParameters takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Note |
|---|
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
GetEffectParameters always returns the effect's actual current parameters. However, these may not match the parameters set by the most recent call to IXAudio2Voice::SetEffectParameters: the actual parameters are only changed the next time the audio engine runs after the
Returns
SetFilterParameters will fail if the voice was not created with the
This method is usable only on source and submix voices and has no effect on mastering voices.
| Note |
|---|
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Returns
SetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on a mastering voice's sends.
| Note |
|---|
GetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on mastering voices? sends.
| Note |
|---|
Returns
SetVolume controls a voice's master input volume level. The master volume level is applied at different times depending on the type of voice. For submix and mastering voices the volume level is applied just before the voice's built in filter and effect chain is applied. For source voices the master volume level is applied after the voice's filter and effect chain is applied.
Volume levels are expressed as floating-point amplitude multipliers between -
| Note |
|---|
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, with a maximum gain of 144.5 dB. A volume level of 1 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
SetChannelVolumes controls a voice's per-channel output levels and is applied just after the voice's final SRC and before its sends.
This method is valid only for source and submix voices, because mastering voices do not specify volume per channel.
Volume levels are expressed as floating-point amplitude multipliers between -
| Note |
|---|
| |
These settings are applied after the effect chain is applied. This method is valid only for source and submix voices, because mastering voices do not specify volume per channel.
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, with a maximum gain of 144.5 dB. A volume of 1 means there is no attenuation or gain, 0 means silence, and negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.
| Note |
|---|
| GetChannelVolumes always returns the volume levels most recently set by |
| Note |
|---|
| If the voice sends to a single target voice then specifying |
For example, when rendering two-channel stereo input into 5.1 output that is weighted toward the front channels?but is absent from the center and low-frequency channels?the matrix might have the values shown in the following table.
| Output | Left Input [Array Index] | Right Input [Array Index] |
|---|---|---|
| Left | 1.0 [0] | 0.0 [1] |
| Right | 0.0 [2] | 1.0 [3] |
| Front Center | 0.0 [4] | 0.0 [5] |
| LFE | 0.0 [6] | 0.0 [7] |
| Rear Left | 0.8 [8] | 0.0 [9] |
| Rear Right | 0.0 [10] | 0.8 [11] |
Note that the left and right input are fully mapped to the output left and right channels; 80 percent of the left and right input is mapped to the rear left and right channels.
See Remarks for more information on volume levels.
Returns
This method is valid only for source and submix voices, because mastering voices write directly to the device with no matrix mixing.
Volume levels are expressed as floating-point amplitude multipliers between -
The X3DAudio function
| Note |
|---|
| Note |
|---|
| If the voice sends to a single target voice then specifying |
This method applies only to source and submix voices, because mastering voices write directly to the device with no matrix mixing.
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, with a maximum gain of 144.5 dB. A volume level of 1 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.
See
| Note |
|---|
| GetOutputMatrix always returns the levels most recently set by |
If any other voice is currently sending audio to this voice, the method fails.
DestroyVoice waits for the audio processing thread to be idle, so it can take a little while (typically no more than a couple of milliseconds). This is necessary to guarantee that the voice will no longer make any callbacks or read any audio data, so the application can safely free up these resources as soon as the call returns.
To avoid title thread interruptions from a blocking DestroyVoice call, the application can destroy voices on a separate non-critical thread, or the application can use voice pooling strategies to reuse voices rather than destroying them. Note that voices can only be reused with audio that has the same data format and the same number of channels the voice was created with. A voice can play audio data with different sample rates than that of the voice by calling
It is illegal to call DestroyVoice from within a callback. If DestroyVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
\t\nThis method is only valid for source and submix voices. Mastering voices can not send audio to another voice.
After calling SetOutputVoices a voice's current send levels will be replaced by a default send matrix. The
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, with a maximum gain of 144.5 dB. A volume level of 1 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
If the XAudio2 engine is stopped, the voice stops running. However, it remains in the started state, so that it starts running again as soon as the engine starts.
When first created, source voices are in the stopped state. Submix and mastering voices are in the started state.
After Start is called it has no further effect if called again before
| Value | Description |
|---|---|
| Continue emitting effect output after the voice is stopped.? |
Returns
All source buffers that are queued on the voice and the current cursor position are preserved. This allows the voice to continue from where it left off, when it is restarted. The
By default, any pending output from voice effects?for example, reverb tails?is not played. Instead, the voice is immediately rendered silent. The
A voice stopped with the
Stop is always asynchronous, even if called within a callback.
| Note |
|---|
| XAudio2 never calls any voice callbacks for a voice if the voice is stopped (even if it was stopped with |
Returns
The voice processes and plays back the buffers in its queue in the order that they were submitted.
The
If the voice is started and has no buffers queued, the new buffer will start playing immediately. If the voice is stopped, the buffer is added to the voice's queue and will be played when the voice starts.
If only part of the given buffer should be played, the PlayBegin and PlayLength fields in the
If all or part of the buffer should be played in a continuous loop, the LoopBegin, LoopLength and LoopCount fields in
If an explicit play region is specified, it must begin and end within the given audio buffer (or, in the compressed case, within the set of samples that the buffer will decode to). In addition, the loop region cannot end past the end of the play region.
| Xbox 360 |
|---|
For certain audio formats, there may be additional restrictions on the valid endpoints of any play or loop regions; e.g. for XMA buffers, the regions can only begin or end at 128-sample boundaries in the decoded audio. |
The pBuffer reference can be reused or freed immediately after calling this method, but the actual audio data referenced by pBuffer must remain valid until the buffer has been fully consumed by XAudio2 (which is indicated by the
Up to
SubmitSourceBuffer takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Xbox 360 |
|---|
This method can be called from an Xbox system thread (most other XAudio2 methods cannot). However, a maximum of two source buffers can be submitted from a system thread at a time. |
If the voice is started, the buffer that is currently playing is not removed from the queue.
FlushSourceBuffers can be called regardless of whether the voice is currently started or stopped.
For every buffer removed, an OnBufferEnd callback will be made, but none of the other per-buffer callbacks (OnBufferStart, OnStreamEnd or OnLoopEnd) will be made.
FlushSourceBuffers does not change a the voice's running state, so if the voice was playing a buffer prior to the call, it will continue to do so, and will deliver all the callbacks for the buffer normally. This means that the OnBufferEnd callback for this buffer will take place after the OnBufferEnd callbacks for the buffers that were removed. Thus, an XAudio2 client that calls FlushSourceBuffers cannot expect to receive OnBufferEnd callbacks in the order in which the buffers were submitted.
No warnings for starvation of the buffer queue will be emitted when the currently playing buffer completes; it is assumed that the client has intentionally removed the buffers that followed it. However, there may be an audio pop if this buffer does not end at a zero crossing. If the application must ensure that the flush operation takes place while a specific buffer is playing?perhaps because the buffer ends with a zero crossing?it must call FlushSourceBuffers from a callback, so that it executes synchronously.
Calling FlushSourceBuffers after a voice is stopped and then submitting new data to the voice resets all of the voice's internal counters.
A voice's state is not considered reset after calling FlushSourceBuffers until the OnBufferEnd callback occurs (if a buffer was previously submitted) or
Discontinuity suppresses the warnings that normally occur in the debug build of XAudio2 when a voice runs out of audio buffers to play. It is preferable to mark the final buffer of a stream by tagging it with the
Because calling Discontinuity is equivalent to applying the
| Note |
|---|
| XAudio2 may consume its entire buffer queue and emit a warning before the Discontinuity call takes effect, so Discontinuity is not guaranteed to suppress the warnings. |
Returns
If the cursor for the voice is not in a loop region, ExitLoop does nothing.
\t\nReturns the voice's current cursor position data.
\t\nIf a client needs to obtain the correlated positions of several voices (i.e. to know exactly which sample of a given voice is playing when a given sample of another voice is playing) it must make GetState calls in an XAudio2 engine callback, to ensure that none of the voices advance while the calls are being made. See the XAudio2 Callbacks overview for information about using XAudio2 callbacks.
\t\nReturns
Frequency adjustment is expressed as source frequency / target frequency. Changing the frequency ratio changes the rate audio is played on the voice. A ratio greater than 1.0 will cause the audio to play faster and a ratio less than 1.0 will cause the audio to play slower. Additionally, the frequency ratio affects the pitch of audio on the voice. As an example, a value of 1.0 has no effect on the audio, whereas a value of 2.0 raises pitch by one octave and 0.5 lowers it by one octave.
If SetFrequencyRatio is called specifying a Ratio value outside the valid range, the method will set the frequency ratio to the nearest valid value. A warning also will be generated for debug builds.
| Note |
|---|
GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
For information on frequency ratios, see
Returns
The SetSourceSampleRate method supports reuse of XAudio2 voices by allowing a voice to play sounds with a variety of sample rates. To use SetSourceSampleRate the voice must have been created without the
The typical use of SetSourceSampleRate is to support voice pooling. For example to support voice pooling an application would precreate all the voices it expects to use. Whenever a new sound will be played the application chooses an inactive voice or ,if all voices are busy, picks the least important voice and calls SetSourceSampleRate on the voice with the new sound's sample rate. After SetSourceSampleRate has been called on the voice, the application can immediately start submitting and playing buffers with the new sample rate. This allows the application to avoid the overhead of creating and destroying voices frequently during gameplay.
\t\nReturns the voice's current cursor position data.
\t\nIf a client needs to obtain the correlated positions of several voices (i.e. to know exactly which sample of a given voice is playing when a given sample of another voice is playing) it must make GetState calls in an XAudio2 engine callback, to ensure that none of the voices advance while the calls are being made. See the XAudio2 Callbacks overview for information about using XAudio2 callbacks.
\t\nGetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
For information on frequency ratios, see
The SetSourceSampleRate method supports reuse of XAudio2 voices by allowing a voice to play sounds with a variety of sample rates. To use SetSourceSampleRate the voice must have been created without the
The typical use of SetSourceSampleRate is to support voice pooling. For example to support voice pooling an application would precreate all the voices it expects to use. Whenever a new sound will be played the application chooses an inactive voice or ,if all voices are busy, picks the least important voice and calls SetSourceSampleRate on the voice with the new sound's sample rate. After SetSourceSampleRate has been called on the voice, the application can immediately start submitting and playing buffers with the new sample rate. This allows the application to avoid the overhead of creating and destroying voices frequently during gameplay.
\t\nSee the XAudio2 Callbacks topic for restrictions on callback implementation.
\t\nReturns information about an audio output device.
\t\nReturns
GetDeviceDetails and
Returns
This method can be called multiple times, allowing different components or layers of the same application to manage their own engine callback implementations separately.
It is illegal to call RegisterForCallbacks from within a callback. If RegisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
\t\nIt is illegal to call UnregisterForCallbacks from within a callback. If UnregisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
\t\nXAudio2 supports PCM and ADPCM voice types. XAudio2 supports the following PCM formats.
8-bit (unsigned) integer PCM
16-bit integer PCM (optimal format for XAudio2)
20-bit integer PCM (either in 24 or 32 bit containers)
24-bit integer PCM (either in 24 or 32 bit containers)
32-bit integer PCM
32-bit float PCM (preferred format after 16-bit integer)
The number of channels in a source voice must be less than or equal to
| Note |
|---|
| Data formats such as ADPCM that require more information than provided by |
| Value | Description |
|---|---|
| No pitch control is available on the voice.? | |
| No sample rate conversion is available on the voice. The voice's outputs must have the same sample rate. Note The | |
| The filter effect should be available on this voice.? |
The maximum value for this argument is defined as
If MaxFrequencyRatio is less than 1.0, the voice will use that ratio immediately after being created (rather than the default of 1.0).
| Xbox 360 |
|---|
| For XMA voices, there is one more restriction on the MaxFrequencyRatio argument and the voice's sample rate. The product of these two numbers cannot exceed XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO for one-channel voices or XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL for voices with any other number of channels. If the value specified for MaxFrequencyRatio is too high for the specified format, the call to CreateSourceVoice fails and produces a debug message. |
| Note |
|---|
| You can use the lowest possible MaxFrequencyRatio value to reduce XAudio2's memory usage. |
Returns
See XAudio2 Error Codes for descriptions of XAudio2-specific error codes.
Source voices read audio data from the client. They process the data and send it to the XAudio2 processing graph.
A source voice includes a variable-rate sample rate conversion, to convert data from the source format sample rate to the output rate required for the voice send list. If you use a
You cannot create any source or submix voices until a mastering voice exists, and you cannot destory a mastering voice if any source or submix voices still exist.
Source voices are always processed before any submix or mastering voices. This means that you do not need a ProcessingStage parameter to control the processing order.
When first created, source voices are in the stopped state.
XAudio2 uses an internal memory pooler for voices with the same format. This means memory allocation for voices will occur less frequently as more voices are created and then destroyed. To minimize just-in-time allocations, a title can create the anticipated maximum number of voices needed up front, and then delete them as necessary. Voices will then be reused from the XAudio2 pool. The memory pool is tied to an XAudio2 engine instance. You can reclaim all the memory used by an instance of the XAudio2 engine by destroying the XAudio2 object and recreating it as necessary (forcing the memory pool to grow via preallocation would have to be reapplied as needed).
It is illegal to call CreateSourceVoice from within a callback. If you call CreateSourceVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
InputChannels must be less than or equal to
| Value | Description |
|---|---|
| The filter effect should be available on this voice.? |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
Submix voices receive the output of one or more source or submix voices. They process the output, and then send it to another submix voice or to a mastering voice.
A submix voice performs a sample rate conversion from the input sample rate to the input rate of its output voices in pSendList. If you specify multiple voice sends, they must all have the input same sample rate.
You cannot create any source or submix voices until a mastering voice exists, and you cannot destroy a mastering voice if any source or submix voices still exist.
When first created, submix voices are in the started state.
XAudio2 uses an internal memory pooler for voices with the same format. This means that memory allocation for voices will occur less frequently as more voices are created and then destroyed. To minimize just-in-time allocations, a title can create the anticipated maximum number of voices needed up front, and then delete them as necessary. Voices will then be reused from the XAudio2 pool. The memory pool is tied to an XAudio2 engine instance. You can reclaim all the memory used by an instance of the XAudio2 engine by destroying the XAudio2 object and recreating it as necessary (forcing the memory pool to grow via preallocation would have to be reapplied as needed).
It is illegal to call CreateSubmixVoice from within a callback. If you call CreateSubmixVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Creates and configures a mastering voice.
\t\nInputChannels must be less than or equal to
InputChannels can be set to
| Windows |
|---|
| Attempts to detect the system speaker configuration setup. |
| Xbox 360 |
|---|
| Defaults to 5.1 surround. |
InputSampleRate must be between
InputSampleRate can be set to
| Windows |
|---|
| Windows XP defaults to 44100. Windows Vista and Windows 7 default to the setting specified in the Sound Control Panel. The default for this setting is 44100 (or 48000 if required by the driver). |
| Xbox 360 |
|---|
| Defaults to 48000. |
Returns
Mastering voices receive the output of one or more source or submix voices. They process the data and send it to the audio output device.
Typically, a mastering voice should be created with an input sample rate that will be used by the majority of the title's audio content. The mastering voice performs a sample rate conversion from this input sample rate to the actual device output rate. Alternatively,
No source or submix voices can be created until a mastering voice exists, and a mastering voice cannot be destroyed if any source or submix voices still exist.
Mastering voices are always processed after all source and submix voices. This means that you need not specify a ProcessingStage parameter to control the processing order.
Several mastering voices can exist at once, but only one of them can be started. Only one device can be used by XAudio2 at a time.
When first created, mastering voices are in the started state.
It is illegal to call CreateMasteringVoice from within a callback. If CreateMasteringVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
\t\nReturns
After StartEngine is called, all started voices begin to consume audio. All enabled effects start running, and the resulting audio is sent to any connected output devices. When XAudio2 is first initialized, the engine is already in the started state.
It is illegal to call StartEngine from within a callback. If StartEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
\t\nWhen StopEngine is called, all output is stopped immediately. However, the audio graph is left untouched, preserving effect parameters, effect histories (for example, the data stored by a reverb effect in order to emit echoes of a previous sound), voice states, pending source buffers, cursor positions, and so forth. When the engine is restarted, the resulting audio output will be identical?apart from a period of silence?to the output that would have been produced if the engine had never been stopped.
It is illegal to call StopEngine from within a callback. If StopEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
\t\nReturns
CommitChanges does nothing if no operations are tagged with the given identifier.
See the XAudio2 Operation Sets overview about working with CommitChanges and XAudio2 interface methods that may be deferred.
\t\nFor specific information on the statistics returned by GetPerformanceData, see the
| Note |
|---|
| This function has no effect in this version of XAudio2. |
This function only has an effect in debug versions of the XAudio2 library. SetDebugConfiguration sets the debug configuration for all instances of XAudio2 in the current process, not just the one interface on which the call was made.
The default debug level produces only ERROR and WARNING messages. See
For specific information on the statistics returned by GetPerformanceData, see the
When streaming an xWMA file a few packets at a time,
In addition, when streaming an xWMA file a few packets at a time, the application should subtract pDecodedPacketCumulativeBytes[PacketCount-1] of the previous packet from all the entries of the currently submitted packet.
The members of
Memory allocated to hold a
Debugging messages can be completely turned off by initializing
Provides information about an audio device.
\t\nSetting
FilterParams; FilterParams.Frequency = 1.0f; FilterParams.OneOverQ = 1.0f; FilterParams.Type = LowPassFilter;
The following formulas show the relationship between the members of
Yl( n ) = F1 yb( n ) + yl( n - 1 )\t\n Yb( n ) = F1 yh( n ) + yb( n - 1 )\t\n Yh( n ) = x( n ) - yl( n ) - OneOverQ(yb( n - 1 )\t\n Yn( n ) = Yl(n) + Yh(n)\t\n
Where:
Yl = lowpass output\t\n Yb = bandpass output\t\n Yh = highpass output\t\n Yn = notch output\t\n F1 =\t\n.Frequency\t\n OneOverQ = .OneOverQ\t\n
If XAUDIO2_HELPER_FUNCTIONS is defined, XAudio2.h will include the XAudio2RadiansToCutoffFrequency and XAudio2CutoffFrequencyToRadians helper functions for converting between hertz and radian frequencies.
CPU cycles are recorded using . Use to convert these values.
\t\n| Note |
|---|
| This only counts cycles on the CPU on which XAudio2 is running. |
| Windows |
|---|
| The delay reported is a variable value equal to the rough distance between the last sample submitted to the driver by XAudio2 and the sample currently playing. The following factors can affect the delay: playing multichannel audio on a hardware-accelerated device; the type of audio device (WavePci, WaveCyclic, or WaveRT); and, to a lesser extent, audio hardware implementation. |
| Xbox 360 |
|---|
| The delay reported is a fixed value, which is normally 1,024 samples (21.333 ms at 48 kHz). If XOverrideSpeakerConfig has been called using the XAUDIOSPEAKERCONFIG_LOW_LATENCY flag, the delay reported is 512 samples (10.667 ms at 48 kHz). |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| Number of source voices decoding XMA data. |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| A voice can use more than one XMA stream. |
If pSends is not
Setting SendCount to 0 is useful for certain effects such as volume meters or file writers that don't generate any audio output to pass on to another voice.
If needed, a voice will perform a single sample rate conversion, from the voice's input sample rate to the input sample rate of the voice's output voices. Because only one sample rate conversion will be performed, all the voice's output voices must have the same input sample rate. If the input sample rates of the voice and its output voices are the same, no sample rate conversion is performed.
\t\nFor all encoded formats, including constant bit rate (CBR) formats such as adaptive differential pulse code modulation (ADPCM), SamplesPlayed is expressed in terms of decoded samples. For pulse code modulation (PCM) formats, SamplesPlayed is expressed in terms of either input or output samples. There is a one-to-one mapping from input to output for PCM formats.
If a client needs to get the correlated positions of several voices?that is, to know exactly which sample of a particular voice is playing when a specified sample of another voice is playing?it must make the
| Value | Description |
|---|---|
| Enables matrix coefficient table calculation.? | |
| Enables delay time array calculation (stereo only).? | |
| Enables low pass filter (LPF) direct-path coefficient calculation.? | |
| Enables LPF reverb-path coefficient calculation.? | |
| Enables reverb send level calculation.? | |
| Enables Doppler shift factor calculation.? | |
| Enables emitter-to-listener interior angle calculation.? | |
| Fills the center channel with silence. This flag allows you to keep a 6-channel matrix so you do not have to remap the channels, but the center channel will be silent. This flag is only valid if you also set | |
| Applies an equal mix of all source channels to a low frequency effect (LFE) destination channel. It only applies to matrix calculations with a source that does not have an LFE channel and a destination that does have an LFE channel. This flag is only valid if you also set |
For a detailed explanation of sound cones see Sound Cones.
\t\nThe following members must be initialized before passing this structure to the
pMatrixCoefficients
pDelayTimes
SrcChannelCount
DstChannelCount
The following members are returned by passing this structure to the
pMatrixCoefficients
pDelayTimes
LPFDirectCoefficient
LPFReverbCoefficient
ReverbLevel
DopplerFactor
EmitterToListenerAngle
EmitterToListenerDistance
EmitterVelocityComponent
ListenerVelocityComponent
| Note |
|---|
| For pMatrixCoefficients and pDelayTimes, |
The parameter type
X3DAudio uses a left-handed Cartesian coordinate system, with values on the x-axis increasing from left to right, on the y-axis from bottom to top, and on the z-axis from near to far. Azimuths are measured clockwise from a given reference direction.
For user-defined distance curves, the distance field of the first point must be 0.0f and the distance field of the last point must be 1.0f.
If an emitter moves beyond a distance of (CurveDistanceScaler ? 1.0f), the last point on the curve is used to compute the volume output level. The last point is determined by the following:
Inner Radius and Inner Radius Angle.pPoints[PointCount-1].DSPSetting)
InnerRadius is used to specify an area of smooth transition around the origin point as a sound travels directly through, above or below the listener. Elevation is accounted for by specifying an InnerRadiusAngle, whereby a sound whose elevation increases or decreases, will eventually start to bleed the sound into more than just two speakers.
When Inner Radius and Inner Radius Angle are not used, emitters are audible in the two closest speakers to their current position/orientation (or, if directly on a line with one speaker's defined angle, solely from that one speaker).
Inner Radius and Inner Radius Angle have no effect on emitters positioned outside of the cones they describe. Inside of the cone, they will gradually cause the sound to bleed into the opposite speakers, until the sound will be equally heard in all speakers when the emitter is at the same position as (or directly above or below) the listener.
\t\nWhen distance is greater than CurveDistanceScaler ? 1.0f, the amplification factor is (CurveDistanceScaler ? 1.0f)/distance. At a distance of CurveDistanceScaler ? 2.0f, the sound will be at half volume or -6 dB, at a distance of CurveDistanceScaler ? 4.0f, the sound will be at one quarter volume or -12 dB, and so on.
pVolumeCurve and pLFECurve are independent of each other. pVolumeCurve does not affect LFE channel volume.
pVolumeCurve and pLFECurve are independent of each other. pLFECurve does not affect non LFE channel volume.
The parameter type
A listener's front and top vectors must be orthonormal. To be considered orthonormal, a pair of vectors must have a magnitude of 1 +- 1x10-5 and a dot product of 0 +- 1x10-5.
\t\nThis metadata can be used to implement optimizations that require knowledge of a stream buffer's contents. \t\n For example, XAPOs that always produce silent output from silent input can check the flag on the input stream buffer \t\n to determine if any signal processing is necessary. If silent, the XAPO can simply set the flag on the output \t\n stream buffer to silent and return, thus averting the work of processing silent data.
Likewise, XAPOs that receive valid input data, but generate silence (for any reason), may set the \t\n output stream buffer's flag accordingly, rather than writing silent samples to the buffer.
These flags represent what should be assumed is in the respective buffer. \t\n The flags may not reflect what is actually stored in memory.\t\n For example, the
The created XAPO will have a reference count of 1. Client code should call IUnknown::Release after passing the XAPO to XAudio2 to allow XAudio2 to dispose of the XAPO when it is no longer needed. Use
Echo only supports FLOAT32 audio formats.
\t\nEach band ranges from FrequencyCenterN - (BandwidthN / 2) to FrequencyCenterN + (BandwidthN / 2).
\t\nOnce locked, the input and output configuration and any other locked parameters remain constant until \t\n UnLockForProcess is called. After an XAPO is locked, further calls to LockForProcess have no effect until the UnLockForProcess function is called.
An XAPO indicates what specific formats it supports through its implementation of the \t\n IsInputFormatSupported and \t\n IsOutputFormatSupported methods. An XAPO should assert the input and \t\n output configurations are supported and that any required effect-specific initialization is complete. The \t\n IsInputFormatSupported, \t\n IsOutputFormatSupported, and \t\n Initialize methods should be used as necessary before calling this method.
Because Process is a nonblocking method, all internal memory buffers required for \t\n Process should be allocated in LockForProcess.
Process is never called before LockForProcess returns successfully.
LockForProcess is called directly by XAudio2 and should not be called by the client code.
\t\nOnce locked, the input and output configuration and any other locked parameters remain constant until \t\n UnLockForProcess is called. After an XAPO is locked, further calls to LockForProcess have no effect until the UnLockForProcess function is called.
An XAPO indicates what specific formats it supports through its implementation of the \t\n IsInputFormatSupported and \t\n IsOutputFormatSupported methods. An XAPO should assert the input and \t\n output configurations are supported and that any required effect-specific initialization is complete. The \t\n IsInputFormatSupported, \t\n IsOutputFormatSupported, and \t\n Initialize methods should be used as necessary before calling this method.
Because Process is a nonblocking method, all internal memory buffers required for \t\n Process should be allocated in LockForProcess.
Process is never called before LockForProcess returns successfully.
LockForProcess is called directly by XAudio2 and should not be called by the client code.
\t\nReturns
Returns
The
Returns
The
Returns
The contents of pData are defined by a given XAPO. Immutable parameters (constant for the lifetime of the XAPO) should be set in this method. Once initialized, an XAPO cannot be initialized again. An XAPO should be initialized before passing it to XAudio2 as part of an effect chain.
| Note |
|---|
| XAudio2 does not call this method, it should be called by the client before passing the XAPO to XAudio2. |
Constant and locked parameters such as the input and output formats remain unchanged. Variables set by
For example, an effect with delay should zero out its delay line during this method, but should not reallocate anything as the XAPO remains locked with a constant input and output configuration.
XAudio2 only calls this method if the XAPO is locked.
This method is called from the realtime thread and should not block.
\t\nReturns
Once locked, the input and output configuration and any other locked parameters remain constant until \t\n UnLockForProcess is called. After an XAPO is locked, further calls to LockForProcess have no effect until the UnLockForProcess function is called.
An XAPO indicates what specific formats it supports through its implementation of the \t\n IsInputFormatSupported and \t\n IsOutputFormatSupported methods. An XAPO should assert the input and \t\n output configurations are supported and that any required effect-specific initialization is complete. The \t\n IsInputFormatSupported, \t\n IsOutputFormatSupported, and \t\n Initialize methods should be used as necessary before calling this method.
Because Process is a nonblocking method, all internal memory buffers required for \t\n Process should be allocated in LockForProcess.
Process is never called before LockForProcess returns successfully.
LockForProcess is called directly by XAudio2 and should not be called by the client code.
\t\nUnlocking an XAPO instance allows it to be reused with\t\n different input and output formats.\t\n
\t\n| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
Implementations of this function should not block, as the function is called from the realtime audio processing thread.
All code that could cause a delay, such as format validation and memory allocation, should be put in the
For in-place processing, the pInputProcessParameters parameter will not necessarily be the same as pOutputProcessParameters. Rather, their pBuffer members will point to the same memory.
Multiple input and output buffers may be used with in-place XAPOs, though the input buffer count must equal the output buffer count. For in-place processing when multiple input and output buffers are used, the XAPO may assume the number of input buffers equals the number of output buffers.
In addition to writing to the output buffer, as appropriate, an XAPO is responsible for setting the output stream's buffer flags and valid frame count.
When IsEnabled is
When writing a Process method, it is important to note XAudio2 audio data is interleaved, which means data from each channel is adjacent for a particular sample number. For example, if there was a 4-channel wave playing into an XAudio2 source voice, the audio data would be a sample of channel 0, a sample of channel 1, a sample of channel 2, a sample of channel 3, and then the next sample of channels 0, 1, 2, 3, and so on.
\t\nReturns the number of input frames required.
XAudio2 calls this method to determine what size input buffer an XAPO requires to generate\t\n the given number of output frames. This method only needs to be called once while an XAPO is locked.\t\n CalcInputFrames is only called by XAudio2 if the XAPO is locked.
This function should not block, because it may be called from the realtime audio processing thread.
\t\nReturns the number of output frames that will be produced.
XAudio2 calls this method to determine how large of an output buffer an XAPO will require for a \t\n certain number of input frames. CalcOutputFrames is only called by XAudio2 if the XAPO is locked.
This function should not block, because it may be called from the realtime audio processing thread.
\t\n XAPO instances are passed to XAudio2 as
XAPO instances are passed to XAudio2 as
The data in pParameters is completely effect-specific and determined by the implementation of the
SetParameters can only be called on the real-time audio processing thread; no synchronization between SetParameters and the
The data in pParameters is completely effect-specific and determined by the implementation of the
Unlike SetParameters, XAudio2 does not call this method on the realtime audio processing thread. Thus, the XAPO must protect variables shared with
XAudio2 calls this method from the
This method may block and should never be called from the realtime audio processing thread instead get the current parameters from CXAPOParametersBase::BeginProcess.
\t\nAlthough the format and maximum size values of a particular stream buffer are constant, as defined by the XAPO_LOCKFORPROCESS_PARAMETERS structure, the actual memory address of the stream buffer is permitted to change. For constant-bit-rate (CBR) XAPOs, ValidFrameCount is constant and is always equal to the corresponding XAPO_LOCKFORPROCESS_PARAMETERS.MaxFrameCount for this buffer.
| Note |
|---|
| Only constant-bit-rate XAPOs are currently supported. |
This structure is used by the
The specific mapping of button to game function varies depending on the game type.
The constant XINPUT_GAMEPAD_TRIGGER_THRESHOLD may be used as the value which bLeftTrigger and bRightTrigger must be greater than to register as pressed. This is optional, but often desirable. Xbox 360 Controller buttons do not manifest crosstalk.
\t\n#define0x00000001\t\n #define 0x00000002\t\n #define 0x00000004\t\n #define 0x00000008\t\n #define 0x00000010\t\n #define 0x00000020\t\n #define 0x00000040\t\n #define 0x00000080\t\n #define 0x0100\t\n #define 0x0200\t\n #define 0x1000\t\n #define 0x2000\t\n #define 0x4000\t\n #define 0x8000
Bits that are set but not defined above are reserved, and their state is undefined.
| Value | Description |
|---|---|
| Limit input event fetch to the gamepad.? |
If the function succeeds, the return value is
If no new keys have been pressed, the return value is
If the controller is not connected or the user has not activated it, the return value is
If the function fails, the return value is an error code defined in Winerror.h. The function does not use SetLastError to set the calling thread's last-error code.
Wireless controllers are not considered active upon system startup, and calls to any of the XInput functions before a wireless controller is made active return
If the function succeeds, the return value is
If the controller is not connected, the return value is
If the function fails, the return value is an error code defined in Winerror.h. The function does not use SetLastError to set the calling thread's last-error code.
If the function successfully retrieves the device IDs for render and capture, the return code is
If there is no headset connected to the controller, the function also retrieves
If the controller port device is not physically connected, the function returns
If the function fails, it returns a valid Win32 error code.
Use of legacy DirectSound is not recommended, and DirectSound is not available for Modern applications.
\t\nIf the function succeeds, the return value is
If the controller is not connected, the return value is
If the function fails, the return value is an error code defined in Winerror.h. The function does not use SetLastError to set the calling thread's last-error code.
When
| Value | Description |
|---|---|
| Limit query to devices of Xbox 360 Controller type.? |
Any value of dwflags other than the above or 0 is illegal and will result in an error break when debugging.
If the function succeeds, the return value is
If the controller is not connected, the return value is
If the function fails, the return value is an error code defined in Winerror.h. The function does not use SetLastError to set the calling thread's last-error code.
If the function succeeds, the return value is
This function is meant to be called when an application gains or loses focus (such as via WM_ACTIVATEAPP). Using this function, you will not have to change the XInput query loop in your application as neutral data will always be reported if XInput is disabled.
In a controller that supports vibration effects:
Passing
Passing TRUE will pass the last vibration request (even if it is 0) sent to
| Value | Description |
|---|---|
| The device is not connected.? | |
| The device is a wired device and does not have a battery.? | |
| The device has an alkaline battery.? | |
| The device has a nickel metal hydride battery.? | |
| The device has an unknown battery type.? |
| Value |
|---|
The SubType member indicates the specific subtype of controller present. Games may detect the controller subtype and tune their handling of controller input or output based on subtypes that are well suited to their game genre. For example, a car racing game might check for the presence of a wheel controller to provide finer control of the car being driven. However, titles must not disable or ignore a device based on its subtype. Subtypes not recognized by the game or for which the game is not specifically tuned should be treated as a standard Xbox 360 Controller (
Older XUSB Windows drivers report incomplete capabilities information, particularly for wireless devices. The latest XUSB Windows driver provides full support for wired and wireless devices, and more complete and accurate capabilties flags.
\t\nFuture devices may return HID codes and virtual key values that are not supported on current devices, and are currently undefined. Applications should ignore these unexpected values.
A virtual-key code is a byte value that represents a particular physical key on the keyboard, not the character or characters (possibly none) that the key can be mapped to based on keyboard state. The keyboard state at the time a virtual key is pressed modifies the character reported. For example, VK_4 might represent a \"4\" or a \"$\", depending on the state of the SHIFT key.
A reported keyboard event includes the virtual key that caused the event, whether the key was pressed or released (or is repeating), and the state of the keyboard at the time of the event. The keyboard state includes information about whether any CTRL, ALT, or SHIFT keys are down.
If the keyboard event represents an Unicode character (for example, pressing the \"A\" key), the Unicode member will contain that character. Otherwise, Unicode will contain the value zero.
The valid virtual-key (VK_xxx) codes are defined in XInput.h. In addition to codes that indicate key presses, the following codes indicate controller input.
| Value | Description |
|---|---|
| A button? | |
| B button? | |
| X button? | |
| Y button? | |
| Right shoulder button? | |
| Left shoulder button? | |
| Left trigger? | |
| Right trigger? | |
| Directional pad up? | |
| Directional pad down? | |
| Directional pad left? | |
| Directional pad right? | |
| START button? | |
| BACK button? | |
| Left thumbstick click? | |
| Right thumbstick click? | |
| Left thumbstick up? | |
| Left thumbstick down? | |
| Left thumbstick right? | |
| Left thumbstick left? | |
| Left thumbstick up and left? | |
| Left thumbstick up and right? | |
| Left thumbstick down and right? | |
| Left thumbstick down and left? | |
| Right thumbstick up? | |
| Right thumbstick down? | |
| Right thumbstick right? | |
| Right thumbstick left? | |
| Right thumbstick up and left? | |
| Right thumbstick up and right? | |
| Right thumbstick down and right? | |
| Right thumbstick down and left? |
The dwPacketNumber member is incremented only if the status of the controller has changed since the controller was last polled.
\t\nThe left motor is the low-frequency rumble motor. The right motor is the high-frequency rumble motor. The two motors are not the same, and they create different vibration effects.
\t\nstart + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing s = det([o_2 - o_1, d_2, d_1 x d_2]) / ||d_1 x d_2||^2\n t = det([o_2 - o_1, d_1, d_1 x d_2]) / ||d_1 x d_2||^2\n Where o_1 is the position of the first ray, o_2 is the position of the second ray,\n d_1 is the normalized direction of the first ray, d_2 is the normalized direction\n of the second ray, det denotes the determinant of a matrix, x denotes the cross\n product, [ ] denotes a matrix, and || || denotes the length or magnitude of a vector.\n start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing Driver type options.
\t\nThe driver type is required when calling
The driver type is unknown.
A hardware driver, which implements Direct3D features in hardware. This is the primary driver that you should use in your Direct3D applications because it provides the best performance. A hardware driver uses hardware acceleration (on supported hardware) but can also use software for parts of the pipeline that are not supported in hardware. This driver type is often referred to as a hardware abstraction layer or HAL.
A reference driver, which is a software implementation that supports every Direct3D feature. A reference driver is designed for accuracy rather than speed and as a result is slow but accurate. The rasterizer portion of the driver does make use of special CPU instructions whenever it can, but it is not intended for retail applications; use it only for feature testing, demonstration of functionality, debugging, or verifying bugs in other drivers. This driver is installed by the DirectX SDK. This driver may be referred to as a REF driver, a reference driver or a reference rasterizer.
A
A software driver, which is a driver implemented completely in software. The software implementation is not intended for a high-performance application due to its very slow performance.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature levels 9_1 through level 10.1 with a high performance software implementation. For information about limitations creating a WARP device on certain feature levels, see Limitations Creating WARP and Reference Devices. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide.
Describes the set of features targeted by a Direct3D device.
\t\nFor an overview of the capabilities of each feature level, see Overview For Each Feature Level.
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
\t\nTargets features supported by feature level 9.1 including shader model 2.
Targets features supported by feature level 9.2 including shader model 2.
Targets features supported by feature level 9.3 including shader model 2.0b.
Targets features supported by Direct3D 10.0 including shader model 4.
Targets features supported by Direct3D 10.1 including shader model 4.
Targets features supported by Direct3D 11.0 including shader model 5.
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
\t\nUse the
The following diagram shows the various primitive types for a geometry shader object.
\t\nValues that identify the type of resource to be viewed as a shader resource.
\t\nA
The type is unknown.
The resource is a buffer.
The resource is a 1D texture.
The resource is an array of 1D textures.
The resource is a 2D texture.
The resource is an array of 2D textures.
The resource is a multisampling 2D texture.
The resource is an array of multisampling 2D textures.
The resource is a 3D texture.
The resource is a cube texture.
The resource is an array of cube textures.
The resource is an extended buffer.
Creates a buffer.
\t\nNumber of bytes in the blob.
The address of a reference to the ID3DBlob interface that is used to retrieve the buffer.
Returns one of the following Direct3D 10 Return Codes.
The latest D3dcompiler_nn.dll contains the
This interface is used to return arbitrary length data.
\t\nAn
The ID3DBlob interface is type defined in the D3DCommon.h header file as a
Blobs can be used as a data buffer, storing vertex, adjacency, and material information during mesh optimization and loading operations. Also, these objects are used to return object code and error messages in APIs that compile vertex, geometry and pixel shaders.
\t\nGet a reference to the data.
\t\nReturns a reference.
Get the size.
\t\nThe size of the data, in bytes.
Get a reference to the data.
\t\nGet the size.
\t\nDefines a shader macro.
\t\nYou can use shader macros in your shaders. The
Shader_Macros[1] = { \"zero\", \"0\" };\t\n The following shader or effect creation functions take an array of shader macros as an input parameter:
The macro name.
The macro definition.
The \t\n
The \t\n
The \t\n
The \t\n
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous \t\n IMoniker::BindToStorage operation and for receiving asynchronous notifications. See \t\n URL Monikers for more information. The following table compares the behavior of asynchronous \t\n
The \t\n
The \t\n
The Read method reads a specified number of bytes from the stream object into memory, starting at the current seek reference.
\t\nA reference to the buffer which the stream data is read into.
The number of bytes of data to read from the stream object.
A reference to a ULONG variable that receives the actual number of bytes read from the stream object.
Note??The number of bytes read may be zero.
This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek reference by the actual number of bytes read.
The number of bytes actually read is also returned in the pcbRead parameter.
Notes to CallersThe actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream.
The application should handle both a returned error and
The Write method writes a specified number of bytes into the stream object starting at the current seek reference.
\t\nA reference to the buffer that contains the data that is to be written to the stream. A valid reference must be provided for this parameter even when cb is zero.
The number of bytes of data to attempt to write into the stream. This value can be zero.
A reference to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this reference to
If the seek reference is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek reference and writes the specified bytes starting at the seek reference. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.
With a zero byte count and a seek reference past the end of the stream, this method does not create the fill bytes to increase the stream to the seek reference. In this case, you must call the \t\n
The pcbWritten parameter can have a value even if an error occurs.
In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.
\t\n The \t\n
The \t\n
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous \t\n IMoniker::BindToStorage operation and for receiving asynchronous notifications. See \t\n URL Monikers for more information. The following table compares the behavior of asynchronous \t\n
The Seek method changes the seek reference to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek reference.
\t\nThe displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek reference (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.
A reference to the location where this method writes the value of the new seek reference from the beginning of the stream.
You can set this reference to
You can also use this method to obtain the current value of the seek reference by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek reference is not changed. The current seek reference is returned in the plibNewPosition parameter.
\t\nThe SetSize method changes the size of the stream object.
\t\nSpecifies the new size of the stream as a number of bytes.
This method can return one of the following values.
The size of the stream object was successfully changed.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The stream size is not changed because there is no space left on the storage device.
The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD data type of libNewSize must be 0. If it is nonzero, this parameter is not valid.
The object has been invalidated by a revert operation above it in the transaction tree.
If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size.
The seek reference is not affected by the change in stream size.
Calling
The CopyTo method copies a specified number of bytes from the current seek reference in the stream to the current seek reference in another stream.
\t\nA reference to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
The number of bytes to copy from the source stream.
A reference to the location where this method writes the actual number of bytes written to the destination. You can set this reference to
A reference to the location where this method writes the actual number of bytes read from the source. You can set this reference to
The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek reference in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using \t\n
The destination stream can be a clone of the source stream created by calling the \t\n
If
If
To copy the remainder of the source from the current seek reference, specify the maximum large integer value for the cb parameter. If the seek reference is the beginning of the stream, this operation copies the entire stream.
\t\nThe Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode,
Controls how the changes for the stream object are committed. See the
This method can return one of the following values.
Changes to the stream object were successfully committed to the parent level.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The commit operation failed due to lack of space on the storage device.
The object has been invalidated by a revert operation above it in the transaction tree.
The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see \t\n
If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.
The
The Revert method discards all changes that have been made to a transacted stream since the last \t\n
This method can return one of the following values.
The stream was successfully reverted to its previous version.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The Revert method discards changes made to a transacted stream since the last commit operation.
\t\nThe LockRegion method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
\t\nInteger that specifies the byte offset for the beginning of the range.
Integer that specifies the length of the range, in bytes, to be restricted.
Specifies the restrictions being requested on accessing the range.
This method can return one of the following values.
The specified range of bytes was locked.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
Locking is not supported at all or the specific type of lock requested is not supported.
Requested lock is supported, but cannot be granted because of an existing lock.
The object has been invalidated by a revert operation above it in the transaction tree.
The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.
Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the \t\n
Any region locked with
Since the type of locking supported is optional and can vary in different implementations of \t\n
The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.
Notes to ImplementersSupport for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.
\t\n The Stat method retrieves the \t\n
The Clone method creates a new stream object with its own seek reference that references the same bytes as the original stream.
\t\nWhen successful, reference to the location of an
The Clone method creates a new stream object for accessing the same bytes but using a separate seek reference. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.
The initial setting of the seek reference in the cloned stream instance is the same as the current setting of the seek reference in the original stream at the time of the clone operation.
\t\n The \t\n
start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing start + (end - start) * amount\n Passing