IDirect3DMobileDevice::StretchRect (Windows CE 5.0)

Article
09/14/2012

This method allows you to copy a rectangular region of a source surface to a rectangular region of a destination surface. If the rectangles are not the same size, the method applies a filtering algorithm that you can specify as one of the methods parameters. If the surfaces are not the same color format, the pixel color values are converted as well.

HRESULT StretchRect(  IDirect3DMobileSurface* pSourceSurface,  CONST RECT* pSourceRect,  IDirect3DMobileSurface* pDestSurface,  CONST RECT* pDestRect,  D3DMTEXTUREFILTERTYPE Filter);

Parameters

pSourceSurface
[in] Pointer to an IDirect3DMobileSurface interface that represents the source surface.
pSourceRect
[in] Pointer to a RECT structure that represents the source rectangle. A NULL for this parameter causes the entire source surface to be used.
pDestSurface
[in] Pointer to an IDirect3DMobileSurface interface that represents the destination surface. For stretching operations, the destination surface must be a render target or a render target texture. See the tables in the Remarks section.
pDestRect
[in] Pointer to a RECT structure that represents the destination rectangle. A NULL for this parameter causes the entire destination surface to be used.
Filter
[in] Filter type. Allowable values are D3DMTEXF_NONE, D3DMTEXF_POINT, or D3DMTEXF_LINEAR (see D3DMTEXTUREFILTERTYPE).

Return Values

If the method succeeds, the return value is D3DM_OK (see D3DM Values).

If the method fails, the return value can be D3DMERR_INVALIDCALL (see D3DMERR Values).

When calling IDirect3DMobileDevice::StretchRect method in a debug configuration the Direct3D Mobile middleware does a significant amount of checking on the input parameters. The following list describes conditions that will cause the method to fail.

The source and destination surfaces are the same.
The given filtering algorithm is not supported in the TextureFilterCaps member of the D3DMCAPS structure.
Stretching or shrinking is involved and either surface has a DXTn compressed format.
The source surface is multisampled, meaning that is was created with the MultiSampleType parameter of IDirect3DMobile::CheckDeviceMultiSampleType method set to a value other than D3DMMULTISAMPLE_NONE.

In release builds, the results for passing invalid parameters are undefined.

Remarks

Using IDirect3DMobileDevice::StretchRect to load texture maps is not recommended because it does not make direct use of the system's internal table of dirty rectangles. Instead, use IDirect3DMobileDevice::CopyRects or IDirect3DMobileDevice::UpdateTexture .

General Restrictions

There are many restrictions as to which surface combinations are valid for IDirect3DMobileDevice::StretchRect. Factors include driver support, and whether the operation will result in stretching or shrinking. The following tables show these restrictions.

Direct3D Mobile Driver (no stretching)

		Destination formats
		Texture	RT texture	RT	Off-screen plain
Source formats	Texture	No	Yes	Yes	No
	Render target texture	No	Yes	Yes	No
	Render target	No	Yes	Yes	No
	Off-screen plain	No	Yes	Yes	Yes

Direct3D Mobile Driver (stretching)

		Destination formats
		Texture	RT texture	RT	Off-screen plain
Source formats	Texture	No	Yes	Yes	No
	Render target texture	No	Yes	Yes	No
	Render target	No	Yes	Yes	No
	Off-screen plain	No	Yes	Yes	No

IDirect3DMobileDevice::StretchRect requires that both the source and destination surfaces be D3DPOOL_VIDEOMEM surfaces.

If filtering is specified, IDirect3DMobileDevice::StretchRect will fail unless the driver sets the appropriate flags in D3DMCAPS. If D3DMTEXF_NONE is specified, the driver chooses 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. The color conversion is derived directly from the driver. You call the IDirect3DMobile::CheckDeviceFormatConversion method to determine whether the driver supports a particular format conversion

Depth and Stencil Restrictions

Depth and stencil surfaces can be copied using IDirect3DMobileDevice::StretchRect with the following restrictions.

Because both the source and destination surfaces must be plain depth stencil surfaces (not textures), they must be created with IDirect3DMobileDevice::CreateDepthStencilSurface.
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 must point to rectangles that cover the whole surface.

IDirect3DMobileDevice::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.

Requirements

OS Versions: Windows CE 5.0 and later.
Header: D3dm.h.
Link Library: D3dm.lib, D3dmguid.lib.

Share via