Device.StretchRectangle Method

Article
10/15/2009

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

Copies the contents of the source rectangle to the destination rectangle.

Namespace: Microsoft.WindowsMobile.DirectX.Direct3D
Assembly: Microsoft.WindowsMobile.DirectX (in Microsoft.WindowsMobile.DirectX.dll)

Syntax

'Declaration
Public Sub StretchRectangle ( _
    sourceSurface As Surface, _
    sourceRectangle As Rectangle, _
    destSurface As Surface, _
    destRectangle As Rectangle, _
    filter As TextureFilter _
)
'Usage
Dim instance As Device
Dim sourceSurface As Surface
Dim sourceRectangle As Rectangle
Dim destSurface As Surface
Dim destRectangle As Rectangle
Dim filter As TextureFilter

instance.StretchRectangle(sourceSurface, _
    sourceRectangle, destSurface, destRectangle, _
    filter)

public void StretchRectangle(
    Surface sourceSurface,
    Rectangle sourceRectangle,
    Surface destSurface,
    Rectangle destRectangle,
    TextureFilter filter
)

public:
void StretchRectangle(
    Surface^ sourceSurface, 
    Rectangle sourceRectangle, 
    Surface^ destSurface, 
    Rectangle destRectangle, 
    TextureFilter filter
)

member StretchRectangle : 
        sourceSurface:Surface * 
        sourceRectangle:Rectangle * 
        destSurface:Surface * 
        destRectangle:Rectangle * 
        filter:TextureFilter -> unit

Parameters

sourceSurface
Type: Microsoft.WindowsMobile.DirectX.Direct3D.Surface
A Surface object that represents the source surface.

sourceRectangle
Type: System.Drawing.Rectangle
A Rectangle object that represents the source rectangle. If nulla null reference (Nothing in Visual Basic), the entire source surface is used.

destSurface
Type: Microsoft.WindowsMobile.DirectX.Direct3D.Surface
A Surface object that represents the destination surface.

destRectangle
Type: System.Drawing.Rectangle
A Rectangle object that represents the destination rectangle. If nulla null reference (Nothing in Visual Basic), the entire destination surface is used.

filter
Type: Microsoft.WindowsMobile.DirectX.Direct3D.TextureFilter
Filter type. The allowable values are Point or Linear. For more information see TextureFilter.

Remarks

The source rectangle can be stretched and filtered by the copy. This method is often used to change the aspect ratio of a video stream.

If the operation results in stretching or shrinking, not all surface combinations are valid for StretchRectangle. Other factors include the types of surfaces involved and their formats.

The following table shows valid surface destination format combinations:

Source format	Texture	RT Texture	RT	Off-screen plain
Texture	No	Yes	Yes	No
RT texture	No	Yes	Yes	No
RT	No	Yes	Yes	No
Off-screen plain	No	Yes	Yes	Yes, but only with no stretching

If filtering is specified, StretchRectangle fails unless the driver sets StretchRectangleFilterCaps. If None is specified, the driver chooses a filtering algorithm.

You can use depth stencil surfaces in StretchRectangle calls, provided there is no stretching or shrinking occurring in the call. The following restrictions also apply to DepthStencil surfaces when being copied with a StretchRectangle call:

Both surfaces must be of the same format with no format conversion.
No stretching or shrinking is allowed.
Only the entire surface can be copied. Sub-rectangle copies are not allowed.

Applications should use CopyRects or UpdateTexture rather than StretchRectangle to load texture maps, because they were designed to use internal information and dirt rectangle tables.

Stretching between rectangles on the same surface is not supported. To test the hardware for color conversion, use the CheckDeviceFormatConversion method of a Manager because software emulation for the conversion is not supported. This method also indicates whether stretching between surfaces of the same format is supported. Stretching or shrinking is not supported if either of the surfaces has a DXTn compressed format. The source surface must not be multisampled.

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Platforms

Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Compact Framework

Supported in: 3.5, 2.0