IDirect3DMobileDevice::StretchRect

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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.

Syntax

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

Parameters

  • 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 Value

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

Source formats

Texture

 

Render target texture

 

Render target

 

Off-screen plain

Direct3D Mobile Driver (stretching)

  Destination formats

 

Texture

Source formats

Texture

 

Render target texture

 

Render target

 

Off-screen plain

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

Header d3dm.h
Library D3dm.lib, D3dmguid.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

IDirect3DMobileDevice
IDirect3DMobileSurface
D3DMTEXTUREFILTERTYPE
D3DM Values
D3DMCAPS
IDirect3DMobile::CheckDeviceMultiSampleType
IDirect3DMobileDevice::CopyRects
IDirect3DMobileDevice::UpdateTexture
IDirect3DMobileDevice::CreateDepthStencilSurface

Concepts

IDirect3DMobile::CheckDeviceFormatConversion