IDirect3DDevice9::StretchRect Method

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.

Syntax

HRESULT StretchRect(      

    IDirect3DSurface9 *pSourceSurface,
    CONST RECT *pSourceRect,
    IDirect3DSurface9 *pDestSurface,
    CONST RECT *pDestRect,
    D3DTEXTUREFILTERTYPE Filter
);

Parameters

pSourceSurface

[in] Pointer to the source surface. See IDirect3DSurface9.

pSourceRect

[in] Pointer to the source rectangle. A NULL for this parameter causes the entire source surface to be used.

pDestSurface

[in] Pointer to the destination surface. See IDirect3DSurface9.

pDestRect

[in] Pointer to the destination rectangle. A NULL for this parameter causes the entire destination surface to be used.

Filter

[in] Filter type. Allowable values are D3DTEXF_NONE, D3DTEXF_POINT, or D3DTEXF_LINEAR. For more information, see D3DTEXTUREFILTERTYPE.

Return Value

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.

Remarks

General Restrictions

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 Restrictions

IDirect3DDevice9::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 Restrictions

Depth 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.