Copies the contents of a source surface to a destination surface and may rotate the contents.
[in] A pointer to a DXGI_DDI_ARG_BLT structure that describes the parameters of a bit-block transfer (bitblt).
This function returns one of the following values.
The bitblt was successfully performed.
The driver detected that the graphics adapter was removed. Therefore, the driver did not complete the bitblt operation. If the driver does not notice the adapter-removal condition, the driver is not required to return this error code.
The Microsoft Direct3D runtime might set the Flags member of the DXGI_DDI_ARG_BLT structure that the pBltData parameter points to in such a way as to require the BltDXGI function to perform a bit-block transfer (bitblt) operation that resolves multi-sampled resources, performs color-format conversion, and performs a stretch or shrink all at once. However, the Direct3D runtime will never set the Flags member of DXGI_DDI_ARG_BLT to zero (that is, no flags set) together with the DXGI_DDI_MODE_ROTATION_IDENTITY value set in the Rotate member of DXGI_DDI_ARG_BLT (that is, to indicate no rotation) to perform a straight memory copy operation. Instead, unless both resources are multi-sampled, the Direct3D runtime calls the driver's ResourceCopy or ResourceCopyRegion function to perform a straight memory copy operation.
The quality of the stretch or shrink that the user-mode display driver performs must be as good as the stretch or shrink that a bilinear filter performs.
The Direct3D runtime will call the driver's BltDXGI function infrequently. That is, the runtime should call BltDXGI no more than once or twice per frame because the runtime uses BltDXGI primarily to support a presentation.
When the runtime calls BltDXGI for a presentation, the runtime sets the Present bit-field flag in the Flags member of DXGI_DDI_ARG_BLT. The runtime sets the Present bit-field flag to inform the driver that there are extra requirements for the bitblt and that extra synchronization may be necessary (for example, the runtime might need to perform extra synchronization in computer configurations that contain two graphics adapters that each handle separate parts of the display). When the Present bit-field flag is set, the driver should perform a copy operation from an application's back buffers to the shared surface of the Desktop Window Manager (DWM). Because synchronization for this type of copy operation is inexact, tearing artifacts should be the worst type of artifacts that a user experiences. For this type of copy operation, the driver should not use a multi-pass approach by first resolving into the destination surface and then color converting the results in-place because the possible artifacts would be much worse.
If the driver supports returning DXGI_DDI_ERR_UNSUPPORTED during the creation of a primary surface (that is, returning DXGI_DDI_ERR_UNSUPPORTED from a call to its CreateResource(D3D10) function with the D3D10_DDI_BIND_PRESENT flag set in the BindFlags member of D3D10DDIARG_CREATERESOURCE along with the pPrimaryDesc member of D3D10DDIARG_CREATERESOURCE set to non-NULL), the driver must also support rotation during a copy operation. If the driver never returns DXGI_DDI_ERR_UNSUPPORTED from a call to its CreateResource(D3D10) function, the runtime will never pass the DXGI_DDI_MODE_ROTATION_ROTATE90, DXGI_DDI_MODE_ROTATION_ROTATE180, or DXGI_DDI_MODE_ROTATION_ROTATE270 value to the Rotate member of DXGI_DDI_ARG_BLT. Therefore, in this situation, the driver's BltDXGI function is not required to support rotation.
The runtime sets a value in the Rotate member of DXGI_DDI_ARG_BLT to indicate the number of degrees to rotate counter-clockwise the contents of the source before the driver copies the contents to the destination. Rotation is specified in increments of 90 degrees.
Note When the driver's BltDXGI function copies sRGB-formatted content from a source surface to a non-sRGB destination surface, the driver should copy the sRGB content unchanged (that is, the driver should not perform the sRGB to linear conversion).
The BltDXGI function always uses a whole source subresource (versus some sub-rectangular area) to perform the bitblt operation. In addition, the source is a D3D10DDIRESOURCE_TEXTURE2D representation (specified in the ResourceDimension member of D3D10DDIARG_CREATERESOURCE when the source is created in a call to the user-mode display driver's CreateResource(D3D10) function). When the runtime sets the Resolve bitfield in the Flags member of DXGI_DDI_ARG_BLT, the source is a multi-sampled resource. The source resource is restricted to a resource in which the D3D10_DDI_BIND_PRESENT flag was set in the BindFlags member of D3D10DDIARG_CREATERESOURCE. The format of the source (specified in the Format member of D3D10DDIARG_CREATERESOURCE) is restricted to display mode formats, specified by the following values from the DXGI_FORMAT enumeration:
DXGI_FORMAT_B8G8R8A8_UNORM (See Note below.)
Note If the driver supports the source format DXGI_FORMAT_B8G8R8A8_UNORM, these restrictions apply:
- When the driver performs a bitblt operation from a floating-point format to an integer format such as BGRA8888, it must implicitly encode gamma into the results.
- Conversely, when the driver performs a bitblt operation from an integer format to a floating-point format, it must implicitly remove gamma encoding from the results.
The destination is also a D3D10DDIRESOURCE_TEXTURE2D representation. The format of the destination is also restricted to display mode formats. The destination resource is restricted to a resource that is bound as a render target (D3D10_DDI_BIND_RENDER_TARGET set in the BindFlags member of D3D10DDIARG_CREATERESOURCE).
Beginning in Windows 8, if the driver must create a stereo back buffer, it should set members of the D3D10DDIARG_CREATERESOURCE or D3D11DDIARG_CREATERESOURCE structure, respectively, pointed to by the pCreateResource parameter of the CreateResource(D3D10) or CreateResource(D3D11) functions, as follows:
- Set the ArraySize member to a value of 2.
- Set the D3D10_DDI_BIND_PRESENT flag value in the BindFlags member.
Additionally, to support stereo presentation, the BltDXGI function must allow any values for the DstSubresource and SrcSubresource members of the DXGI_DDI_ARG_BLT structure that are within the range of the source and destination resources.
|Available in Windows Vista and later versions of the Windows operating systems.|