Device.StretchRectangle(Surface,Rectangle,Surface,Rectangle,TextureFilter) Method (Microsoft.DirectX.Direct3D)

  • Article

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

Definition

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

Parameters

sourceSurface Microsoft.DirectX.Direct3D.Surface
A Surface object that represents the source surface.
sourceRectangle System.Drawing.Rectangle
A RectangleLeave Site 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 RectangleLeave Site 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.