|Microsoft DirectX 9.0|
Copy 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.
IDirect3DSurface9 *pSourceSurface, CONST RECT *pSourceRect, IDirect3DSurface9 *pDestSurface, CONST RECT *pDestRect, D3DTEXTUREFILTERTYPE Filter );
- [in] Pointer to the source surface. See IDirect3DSurface9.
- [in] Pointer to the source rectangle. A NULL for this parameter causes the entire source surface to be used.
- [in] Pointer to the destination surface. See IDirect3DSurface9.
- [in] Pointer to the destination rectangle. A NULL for this parameter causes the entire destination surface to be used.
- [in] Filter type. Allowable values are D3DTEXF_NONE, D3DTEXF_POINT, or D3DTEXF_LINEAR. For more information, see D3DTEXTUREFILTERTYPE.
If the method succeeds, the return value is D3D_OK.
If the method fails, the return value can be
D3DERR_INVALIDCALL The method call is invalid. For example, a method's parameter may have an invalid value.
There are many restrictions as to which surface combinations are valid for IDirect3DDevice9::StretchRect. Factors include whether the driver is a Microsoft?DirectX?9.0 driver or older, and whether the operation will result in stretching/shrinking. Since applications are not expected to recognize if the driver is a DirectX 9.0 driver or not, Microsoft Direct3D?will automatically set a new D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES cap in the D3DDEVCAPS2 structure for DirectX 9.0-level drivers and above.
DirectX 8.x 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.x 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
DirectX 9.0 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
DirectX 9.0 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
IDirect3DDevice9::StretchRect requires that both the source and destination surfaces must be D3DPOOL_DEFAULT surfaces.
If filtering is specified, IDirect3DDevice9::StretchRect will fail unless the driver sets the appropriate StretchRectFilterCaps in D3DCAPS9. If D3DTEXF_NONE is specified, the driver will choose a filtering algorithm.
The stretch operation supports color-space conversion from YUV to high-precision RGBA only. Stretching between rectangles on the same surface is not supported. Use IDirect3D9::CheckDeviceFormatConversion to test the hardware for color conversion support because software emulation for the conversion is not supported.
Texture RestrictionsIDirect3DDevice9::StretchRect will work for a texture surface (or a cube texture surface) only for DirectX 9.0 drivers (drivers that set D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES).
Depth and Stencil RestrictionsDepth and stencil surfaces can be copied using IDirect3DDevice9::StretchRect with the following restrictions.
- Both the source and destination surfaces must be created with IDirect3DDevice9::CreateDepthStencilSurface, because they must be plain depth stencil surfaces (not textures).
- Both surfaces must be the same format (no format conversion).
- No stretching or shrinking is allowed.
- Subrectangle copies are not allowed. The entire surface must be copied. In other words, pSourceRect and pDestRect must be NULL, or point to rectangles that cover the whole surface.
- StretchRect cannot be called inside of IDirect3DDevice9::BeginScene/IDirect3DDevice9::EndScene pairs.
- The source or destination surface can't be a mip level of a texture (cube texture) created with D3DUSAGE_DEPTHSTENCIL.
- Neither of the surfaces can be created as "discardable."
- Drivers must set D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES. See D3DDEVCAPS2.
IDirect3DDevice9::StretchRect will fail for any of the following:
- If pSourceSurface and pDestSurface are the same.
- If stretching or shrinking is involved and either surface has a DXTn compressed format.
- If the source surface is multisampled (created with MultiSampleType != D3DMULTISAMPLE_NONE).
- If the destination surface is an off-screen plain surface but the source is not. If the destination surface is an off-screen plain surface and stretching is involved.