Device.StretchRectangle Method

Language:

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

Definition

Visual Basic Public Sub StretchRectangle( _
    ByVal sourceSurface As Surface, _
    ByVal sourceRectangle As Rectangle, _
    ByVal destSurface As Surface, _
    ByVal destRectangle As Rectangle, _
    ByVal filter As TextureFilter _
)

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

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

JScript public function StretchRectangle(
    sourceSurface : Surface,
    sourceRectangle : Rectangle,
    destSurface : Surface,
    destRectangle : Rectangle,
    filter : TextureFilter
);

Visual Basic	Public Sub StretchRectangle( _ ByVal sourceSurface As Surface, _ ByVal sourceRectangle As Rectangle, _ ByVal destSurface As Surface, _ ByVal destRectangle As Rectangle, _ ByVal filter As TextureFilter _ )
C#	public void StretchRectangle( Surface sourceSurface, Rectangle sourceRectangle, Surface destSurface, Rectangle destRectangle, TextureFilter filter );
C++	public: void StretchRectangle( Surface^ sourceSurface, Rectangle sourceRectangle, Surface^ destSurface, Rectangle destRectangle, TextureFilter filter );
JScript	public function StretchRectangle( sourceSurface : Surface, sourceRectangle : Rectangle, destSurface : Surface, destRectangle : Rectangle, filter : TextureFilter );

Parameters

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

sourceRectangle System.Drawing.Rectangle
A Rectangle object that represents the source rectangle. If set to null, the entire source surface is used.

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

destRectangle System.Drawing.Rectangle
A Rectangle object that represents the destination rectangle. If set to null, the entire destination surface is used.

filter Microsoft.DirectX.Direct3D.TextureFilter
Filter type. Allowable values are None, 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.

General Restrictions

There are many restrictions on which surface combinations are valid for Device.StretchRectangle. Factors include whether the driver is part of Microsoft DirectX 9.0 or an earlier version, and whether the operation will result in stretching or shrinking. Since applications are not expected to recognize whether the driver is a DirectX 9.0 driver, Microsoft Direct3D automatically sets a new value in the DeviceCaps.CanStretchRectangleFromTextures property for drivers from DirectX 9.0 and later.

The following tables show the possible surface combinations.

DirectX 9.0 driver (no stretching)

Destination format

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

DirectX 9.0 driver (stretching)

Destination format

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 No

Device.StretchRectangle requires that both source and destination surfaces be Pool.Default surfaces.

If filtering is specified, Device.StretchRectangle fails unless the driver sets Caps.StretchRectangleFilterCaps. If TextureFilter.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. To test the hardware for color conversion, use Manager.CheckDeviceFormatConversion, because software emulation for the conversion is not supported.

Texture Restrictions

Device.StretchRectangle works for a texture surface or cube texture surface only for DirectX 9.0 drivers (those that set DeviceCaps.CanStretchRectangleFromTextures).

Depth and Stencil Restrictions

Depth and stencil surfaces can be copied using Device.StretchRectangle with the following restrictions.

Because both source and destination surfaces must be plain depth stencil surfaces and not textures, they must be created with Device.CreateDepthStencilSurface.

Both surfaces must be of the same format; that is, no format conversion is allowed.

No stretching or shrinking is allowed.

Subrectangle copies are not allowed. The entire surface must be copied; that is, sourceRectangle and destRectangle must be null or must point to rectangles that cover the whole surface.

Device.StretchRectangle cannot be called inside of a Device.BeginScene ... Device.EndScene pair.

The source or destination surface cannot be a mip level of a texture or cube texture created with Usage.DepthStencil.

Neither of the surfaces can be created with their Discard values set to true.

Drivers must set DeviceCaps.CanStretchRectangleFromTextures.

Device.StretchRectangle will fail in any of the following situations.

The sourceSurface and destSurface parameters are the same.

Stretching or shrinking is involved and either surface has a DXTn compressed format.

The destination surface is an off-screen plain surface, but the source is not.

The destination surface is an off-screen plain surface, and stretching is involved.

Exceptions

InvalidCallException The method call is invalid. For example, a method's parameter might contain an invalid value.

	Destination format
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

	Destination format
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	No

Feedback? Please provide us with your comments on this topic.
For more help, visit the DirectX Developer Center

sourceSurface	Microsoft.DirectX.Direct3D.Surface A Surface object that represents the source surface.
sourceRectangle	System.Drawing.Rectangle A Rectangle object that represents the source rectangle. If set to null, the entire source surface is used.
destSurface	Microsoft.DirectX.Direct3D.Surface A Surface object that represents the destination surface.
destRectangle	System.Drawing.Rectangle A Rectangle object that represents the destination rectangle. If set to null, the entire destination surface is used.
filter	Microsoft.DirectX.Direct3D.TextureFilter Filter type. Allowable values are None, Point, or Linear. For more information, see TextureFilter.