Device.Clear(ClearFlags,Color,Single,Int32,Rectangle[]) Method (Microsoft.DirectX.Direct3D)

Article
11/06/2009

Clears the viewport or a set of rectangles in the viewport to a specified RGBA color, clears the depth buffer, and erases the stencil buffer.

Definition

Visual Basic Public Sub Clear( _
    ByVal flags As ClearFlags, _
    ByVal color As Color, _
    ByVal zdepth As Single, _
    ByVal stencil As Integer, _
    ByVal rect() As Rectangle _
)

C# public void Clear(
    ClearFlags flags,
    Color color,
    float zdepth,
    int stencil,
    Rectangle[] rect
);

C++ public:
void Clear(
    ClearFlags flags,
    Color color,
    float zdepth,
    int stencil,
    array<Rectangle>^ rect
);

JScript public function Clear(
    flags : ClearFlags,
    color : Color,
    zdepth : float,
    stencil : int,
    rect : Rectangle[]
);

Parameters

flags Microsoft.DirectX.Direct3D.ClearFlags
Flags that indicate which surfaces to clear. This parameter can be any combination of the following flags, but at least one flag must be used.
ClearFlags.Stencil: Clears the stencil buffer to the value in the stencil parameter.
ClearFlags.Target: Clears the render target to the color in the color parameter.
ClearFlags.ZBuffer: Clears the depth buffer to the value in the Z parameter.

color System.Drawing.Color
A Color object that represents the color to which the render target surface is cleared.

zdepth System.Single
New z value that this method stores in the depth buffer. This parameter can be in the range of 0.0 through 1.0 (for z-based or w-based depth buffers). A value of 0.0 represents the nearest distance to the viewer; a value of 1.0 represents the farthest distance.

stencil System.Int32
Integer value to store in each stencil-buffer entry. This parameter can be in the range of 0 through 2n-1, where n is the bit depth of the stencil buffer.

rect System.Drawing.Rectangle[]
Array of Rectangle structures that describe the rectangles to clear. To clear the entire surface, set a rectangle to the dimensions of the rendering target. Each rectangle uses screen coordinates that correspond to points on the render target surface. Coordinates are clipped to the bounds of the viewport rectangle.

Remarks

This method fails if the ZBuffer or Stencil flags are specified when the render target does not have an attached depth buffer. Similarly, the method fails if the Stencil flag is specified when the depth-buffer format does not contain stencil buffer information.

Exceptions

InvalidCallException

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

Visual Basic	Public Sub Clear( _ ByVal flags As ClearFlags, _ ByVal color As Color, _ ByVal zdepth As Single, _ ByVal stencil As Integer, _ ByVal rect() As Rectangle _ )
C#	public void Clear( ClearFlags flags, Color color, float zdepth, int stencil, Rectangle[] rect );
C++	public: void Clear( ClearFlags flags, Color color, float zdepth, int stencil, array<Rectangle>^ rect );
JScript	public function Clear( flags : ClearFlags, color : Color, zdepth : float, stencil : int, rect : Rectangle[] );

flags	Microsoft.DirectX.Direct3D.ClearFlags Flags that indicate which surfaces to clear. This parameter can be any combination of the following flags, but at least one flag must be used. ClearFlags.Stencil: Clears the stencil buffer to the value in the stencil parameter. ClearFlags.Target: Clears the render target to the color in the color parameter. ClearFlags.ZBuffer: Clears the depth buffer to the value in the Z parameter.
color	System.Drawing.Color A Color object that represents the color to which the render target surface is cleared.
zdepth	System.Single New z value that this method stores in the depth buffer. This parameter can be in the range of 0.0 through 1.0 (for z-based or w-based depth buffers). A value of 0.0 represents the nearest distance to the viewer; a value of 1.0 represents the farthest distance.
stencil	System.Int32 Integer value to store in each stencil-buffer entry. This parameter can be in the range of 0 through 2n-1, where n is the bit depth of the stencil buffer.
rect	System.Drawing.Rectangle[] Array of Rectangle structures that describe the rectangles to clear. To clear the entire surface, set a rectangle to the dimensions of the rendering target. Each rectangle uses screen coordinates that correspond to points on the render target surface. Coordinates are clipped to the bounds of the viewport rectangle.

Device.Clear(ClearFlags,Color,Single,Int32,Rectangle[]) Method (Microsoft.DirectX.Direct3D)

Additional resources