Class RenderTarget

Namespace

SharpDX.Direct2D1

Assembly

SharpDX.Direct2D1.dll

[Guid("2cd90694-12e2-11dc-9fed-001143a055f9")]
public class RenderTarget : Resource

Inheritance

object

Resource

RenderTarget

Derived

BitmapRenderTarget

DeviceContext

DeviceContextRenderTarget

WicRenderTarget

WindowRenderTarget

Inherited Members

Resource.Factory

Constructors

RenderTarget(Factory, Surface, RenderTargetProperties)

Creates a render target that draws to a DirectX Graphics Infrastructure (DXGI) surface.

public RenderTarget(Factory factory, Surface dxgiSurface, RenderTargetProperties properties)

Parameters

factory Factory

an instance of Factory

dxgiSurface Surface

The DXGI surface to bind this render target to

properties RenderTargetProperties

The rendering mode, pixel format, remoting options, DPI information, and the minimum DirectX support required for hardware rendering. For information about supported pixel formats, see {{Supported Pixel Formats and Alpha Modes}}.

Remarks

To write to a Direct3D surface, you obtain an SharpDX.DXGI.Surface and pass it to the {{CreateDxgiSurfaceRenderTarget}} method to create a DXGI surface render target; you can then use the DXGI surface render target to draw 2-D content to the DXGI surface. A DXGI surface render target is a type of RenderTarget. Like other Direct2D render targets, you can use it to create resources and issue drawing commands. The DXGI surface render target and the DXGI surface must use the same DXGI format. If you specify the {{DXGI_FORMAT_UNKOWN}} format when you create the render target, it will automatically use the surface's format.The DXGI surface render target does not perform DXGI surface synchronization. To work with Direct2D, the Direct3D device that provides the SharpDX.DXGI.Surface must be created with the D3D10_CREATE_DEVICE_BGRA_SUPPORT flag.For more information about creating and using DXGI surface render targets, see the {{Direct2D and Direct3D Interoperability Overview}}.When you create a render target and hardware acceleration is available, you allocate resources on the computer's GPU. By creating a render target once and retaining it as long as possible, you gain performance benefits. Your application should create render targets once and hold onto them for the life of the application or until the render target's {{EndDraw}} method returns the {{D2DERR_RECREATE_TARGET}} error. When you receive this error, you need to recreate the render target (and any resources it created).

RenderTarget(nint)

public RenderTarget(nint nativePtr)

Parameters

nativePtr nint

Fields

DefaultStrokeWidth

Default stroke width used for all methods that are not explicitly using it. Default is set to 1.0f.

public const float DefaultStrokeWidth = 1

Field Value

float

Properties

AntialiasMode

Retrieves or sets the current antialiasing mode for nontext drawing operations.

public AntialiasMode AntialiasMode { get; set; }

Property Value

AntialiasMode

DotsPerInch

Get or sets the dots per inch (DPI) of the render target.

public Size2F DotsPerInch { get; set; }

Property Value

Size2F

Remarks

This method specifies the mapping from pixel space to device-independent space for the render target. If both dpiX and dpiY are 0, the factory-read system DPI is chosen. If one parameter is zero and the other unspecified, the DPI is not changed. For WindowRenderTarget, the DPI defaults to the most recently factory-read system DPI. The default value for all other render targets is 96 DPI.

MaximumBitmapSize

Gets the maximum size, in device-dependent units (pixels), of any one bitmap dimension supported by the render target.

public int MaximumBitmapSize { get; }

Property Value

int

Remarks

This method returns the maximum texture size of the Direct3D device.

Note??The software renderer and WARP devices return the value of 16 megapixels (16*1024*1024). You can create a Direct2D texture that is this size, but not a Direct3D texture that is this size.?

PixelFormat

Retrieves the pixel format and alpha mode of the render target.

public PixelFormat PixelFormat { get; }

Property Value

PixelFormat

PixelSize

Returns the size of the render target in device pixels.

public Size2 PixelSize { get; }

Property Value

Size2

Size

Returns the size of the render target in device-independent pixels.

public Size2F Size { get; }

Property Value

Size2F

StrokeWidth

Get or set the default stroke width used for all methods that are not explicitly using it. Default is set to 1.0f.

public float StrokeWidth { get; set; }

Property Value

float

TextAntialiasMode

Gets or sets the current antialiasing mode for text and glyph drawing operations.

public TextAntialiasMode TextAntialiasMode { get; set; }

Property Value

TextAntialiasMode

TextRenderingParams

Retrieves or sets the render target's current text rendering options.

public RenderingParams TextRenderingParams { get; set; }

Property Value

RenderingParams

Remarks

If the settings specified by textRenderingParams are incompatible with the render target's text antialiasing mode (specified by SetTextAntialiasMode), subsequent text and glyph drawing operations will fail and put the render target into an error state.

Transform

Gets or sets the current transform of the render target.

public RawMatrix3x2 Transform { get; set; }

Property Value

RawMatrix3x2

Methods

BeginDraw()

Initiates drawing on this render target.

public void BeginDraw()

Remarks

Drawing operations can only be issued between a BeginDraw and EndDraw call.

BeginDraw and EndDraw are used to indicate that a render target is in use by the Direct2D system. Different implementations of RenderTarget might behave differently when BeginDraw is called. An BitmapRenderTarget may be locked between BeginDraw/EndDraw calls, a DXGI surface render target might be acquired on BeginDraw and released on EndDraw, while an WindowRenderTarget may begin batching at BeginDraw and may present on EndDraw, for example.

The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.

After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an SharpDX.Result indicating the success of the operations and, optionally, the tag state of the render target at the time the error occurred. The EndDraw method always succeeds: it should not be called twice even if a previous EndDraw resulted in a failing SharpDX.Result.

If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate SharpDX.Result and error information when EndDraw is called.

Clear(RawColor4?)

Clears the drawing area to the specified color.

public void Clear(RawColor4? clearColor)

Parameters

clearColor RawColor4?

The color to which the drawing area is cleared, or null for transparent black.

Remarks

Direct2D interprets the clearColor as straight alpha (not premultiplied). If the render target's alpha mode is D2D1_ALPHA_MODE_IGNORE, the alpha channel of clearColor is ignored and replaced with 1.0f (fully opaque).

If the render target has an active clip (specified by PushAxisAlignedClip), the clear command is applied only to the area within the clip region.

DrawBitmap(Bitmap, RawRectangleF, float, BitmapInterpolationMode)

Draws the specified bitmap after scaling it to the size of the specified rectangle.

public void DrawBitmap(Bitmap bitmap, RawRectangleF destinationRectangle, float opacity, BitmapInterpolationMode interpolationMode)

Parameters

bitmap Bitmap

The bitmap to render.

destinationRectangle RawRectangleF

The size and position, in device-independent pixels in the render target's coordinate space, of the area to which the bitmap is drawn; NULL to draw the selected portion of the bitmap at the origin of the render target. If the rectangle is specified but not well-ordered, nothing is drawn, but the render target does not enter an error state.

opacity float

A value between 0.0f and 1.0f, inclusive, that specifies an opacity value to apply to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. The default value is 1.0f.

interpolationMode BitmapInterpolationMode

The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is Linear.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawBitmap}}) failed, check the result returned by the EndDraw() or Flush() methods.

DrawBitmap(Bitmap, RawRectangleF?, float, BitmapInterpolationMode, RawRectangleF?)

Draws the specified bitmap after scaling it to the size of the specified rectangle.

public void DrawBitmap(Bitmap bitmap, RawRectangleF? destinationRectangle, float opacity, BitmapInterpolationMode interpolationMode, RawRectangleF? sourceRectangle)

Parameters

bitmap Bitmap

The bitmap to render.

destinationRectangle RawRectangleF?

The size and position, in device-independent pixels in the render target's coordinate space, of the area to which the bitmap is drawn. If the rectangle is not well-ordered, nothing is drawn, but the render target does not enter an error state.

opacity float

A value between 0.0f and 1.0f, inclusive, that specifies the opacity value to be applied to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. Default is 1.0f.

interpolationMode BitmapInterpolationMode

The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is D2D1_BITMAP_INTERPOLATION_MODE_LINEAR.

sourceRectangle RawRectangleF?

The size and position, in device-independent pixels in the bitmap's coordinate space, of the area within the bitmap to draw; null to draw the entire bitmap.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawBitmap) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

DrawBitmap(Bitmap, float, BitmapInterpolationMode)

Draws the specified bitmap after scaling it to the size of the specified rectangle.

public void DrawBitmap(Bitmap bitmap, float opacity, BitmapInterpolationMode interpolationMode)

Parameters

bitmap Bitmap

The bitmap to render.

opacity float

A value between 0.0f and 1.0f, inclusive, that specifies an opacity value to apply to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. The default value is 1.0f.

interpolationMode BitmapInterpolationMode

The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is Linear.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawBitmap}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawBitmap(Bitmap, float, BitmapInterpolationMode, RawRectangleF)

Draws the specified bitmap after scaling it to the size of the specified rectangle.

public void DrawBitmap(Bitmap bitmap, float opacity, BitmapInterpolationMode interpolationMode, RawRectangleF sourceRectangle)

Parameters

bitmap Bitmap

The bitmap to render.

opacity float

A value between 0.0f and 1.0f, inclusive, that specifies an opacity value to apply to the bitmap; this value is multiplied against the alpha values of the bitmap's contents. The default value is 1.0f.

interpolationMode BitmapInterpolationMode

The interpolation mode to use if the bitmap is scaled or rotated by the drawing operation. The default value is Linear.

sourceRectangle RawRectangleF

The size and position, in device-independent pixels in the bitmap's coordinate space, of the area within the bitmap to be drawn; NULL to draw the entire bitmap.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawBitmap}}) failed, check the result returned by the EndDraw() or Flush(out long, out long) methods.

DrawEllipse(Ellipse, Brush)

Draws the outline of the specified ellipse using the specified stroke style.

public void DrawEllipse(Ellipse ellipse, Brush brush)

Parameters

ellipse Ellipse

The position and radius of the ellipse to draw, in device-independent pixels.

brush Brush

The brush used to paint the ellipse's outline.

Remarks

The {{DrawEllipse}} method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawEllipse(Ellipse, Brush, float)

Draws the outline of the specified ellipse using the specified stroke style.

public void DrawEllipse(Ellipse ellipse, Brush brush, float strokeWidth)

Parameters

ellipse Ellipse

The position and radius of the ellipse to draw, in device-independent pixels.

brush Brush

The brush used to paint the ellipse's outline.

strokeWidth float

The thickness of the ellipse's stroke. The stroke is centered on the ellipse's outline.

Remarks

The {{DrawEllipse}} method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawEllipse(Ellipse, Brush, float, StrokeStyle)

Draws the outline of the specified ellipse using the specified stroke style.

public void DrawEllipse(Ellipse ellipse, Brush brush, float strokeWidth, StrokeStyle strokeStyle)

Parameters

ellipse Ellipse

The position and radius of the ellipse to draw, in device-independent pixels.

brush Brush

The brush used to paint the ellipse's outline.

strokeWidth float

The width of the stroke, in device-independent pixels. The value must be greater than or equal to 0.0f. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.

strokeStyle StrokeStyle

The style of stroke to apply to the ellipse's outline, or null to paint a solid stroke.

Remarks

The DrawEllipse method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawEllipse) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

DrawGeometry(Geometry, Brush)

Draws the outline of the specified geometry.

public void DrawGeometry(Geometry geometry, Brush brush)

Parameters

geometry Geometry

The geometry to draw.

brush Brush

The brush used to paint the geometry's stroke.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawGeometry(Geometry, Brush, float)

Draws the outline of the specified geometry.

public void DrawGeometry(Geometry geometry, Brush brush, float strokeWidth)

Parameters

geometry Geometry

The geometry to draw.

brush Brush

The brush used to paint the geometry's stroke.

strokeWidth float

The thickness of the geometry's stroke. The stroke is centered on the geometry's outline.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawGeometry(Geometry, Brush, float, StrokeStyle)

Draws the outline of the specified geometry using the specified stroke style.

public void DrawGeometry(Geometry geometry, Brush brush, float strokeWidth, StrokeStyle strokeStyle)

Parameters

geometry Geometry

The geometry to draw.

brush Brush

The brush used to paint the geometry's stroke.

strokeWidth float

The width of the stroke, in device-independent pixels. The value must be greater than or equal to 0.0f. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.

strokeStyle StrokeStyle

The style of stroke to apply to the geometry's outline, or null to paint a solid stroke.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGeometry) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

DrawGlyphRun(RawVector2, GlyphRun, Brush, MeasuringMode)

Draws the specified glyphs.

public void DrawGlyphRun(RawVector2 baselineOrigin, GlyphRun glyphRun, Brush foregroundBrush, MeasuringMode measuringMode)

Parameters

baselineOrigin RawVector2

The origin, in device-independent pixels, of the glyphs' baseline.

glyphRun GlyphRun

The glyphs to render.

foregroundBrush Brush

The brush used to paint the specified glyphs.

measuringMode MeasuringMode

A value that indicates how glyph metrics are used to measure text when it is formatted. The default value is DWRITE_MEASURING_MODE_NATURAL.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawGlyphRun) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

DrawLine(RawVector2, RawVector2, Brush)

Draws a line between the specified points.

public void DrawLine(RawVector2 point0, RawVector2 point1, Brush brush)

Parameters

point0 RawVector2

The start point of the line, in device-independent pixels.

point1 RawVector2

The end point of the line, in device-independent pixels.

brush Brush

The brush used to paint the line's stroke.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawLine(RawVector2, RawVector2, Brush, float)

Draws a line between the specified points.

public void DrawLine(RawVector2 point0, RawVector2 point1, Brush brush, float strokeWidth)

Parameters

point0 RawVector2

The start point of the line, in device-independent pixels.

point1 RawVector2

The end point of the line, in device-independent pixels.

brush Brush

The brush used to paint the line's stroke.

strokeWidth float

A value greater than or equal to 0.0f that specifies the width of the stroke. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawLine(RawVector2, RawVector2, Brush, float, StrokeStyle)

Draws a line between the specified points using the specified stroke style.

public void DrawLine(RawVector2 point0, RawVector2 point1, Brush brush, float strokeWidth, StrokeStyle strokeStyle)

Parameters

point0 RawVector2

The start point of the line, in device-independent pixels.

point1 RawVector2

The end point of the line, in device-independent pixels.

brush Brush

The brush used to paint the line's stroke.

strokeWidth float

The width of the stroke, in device-independent pixels. The value must be greater than or equal to 0.0f. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.

strokeStyle StrokeStyle

The style of stroke to paint, or null to paint a solid line.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawLine) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

DrawRectangle(RawRectangleF, Brush)

Draws the outline of a rectangle that has the specified dimensions.

public void DrawRectangle(RawRectangleF rect, Brush brush)

Parameters

rect RawRectangleF

The dimensions of the rectangle to draw, in device-independent pixels.

brush Brush

The brush used to paint the rectangle's stroke.

Remarks

When this method fails, it does not return an error code. To determine whether a drawing method (such as {{DrawRectangle}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) method.

DrawRectangle(RawRectangleF, Brush, float)

Draws the outline of a rectangle that has the specified dimensions and stroke style.

public void DrawRectangle(RawRectangleF rect, Brush brush, float strokeWidth)

Parameters

rect RawRectangleF

The dimensions of the rectangle to draw, in device-independent pixels.

brush Brush

The brush used to paint the rectangle's stroke.

strokeWidth float

A value greater than or equal to 0.0f that specifies the width of the rectangle's stroke. The stroke is centered on the rectangle's outline.

Remarks

When this method fails, it does not return an error code. To determine whether a drawing method (such as {{DrawRectangle}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) method.

DrawRectangle(RawRectangleF, Brush, float, StrokeStyle)

Draws the outline of a rectangle that has the specified dimensions and stroke style.

public void DrawRectangle(RawRectangleF rect, Brush brush, float strokeWidth, StrokeStyle strokeStyle)

Parameters

rect RawRectangleF

The dimensions of the rectangle to draw, in device-independent pixels.

brush Brush

The brush used to paint the rectangle's stroke.

strokeWidth float

The width of the stroke, in device-independent pixels. The value must be greater than or equal to 0.0f. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.

strokeStyle StrokeStyle

The style of stroke to paint, or null to paint a solid stroke.

Remarks

When this method fails, it does not return an error code. To determine whether a drawing method (such as DrawRectangle) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush method.

DrawRoundedRectangle(RoundedRectangle, Brush)

Draws the outline of the specified rounded rectangle.

public void DrawRoundedRectangle(RoundedRectangle roundedRect, Brush brush)

Parameters

roundedRect RoundedRectangle

The dimensions of the rounded rectangle to draw, in device-independent pixels.

brush Brush

The brush used to paint the rounded rectangle's outline.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawRoundedRectangle}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawRoundedRectangle(RoundedRectangle, Brush, float)

Draws the outline of the specified rounded rectangle.

public void DrawRoundedRectangle(RoundedRectangle roundedRect, Brush brush, float strokeWidth)

Parameters

roundedRect RoundedRectangle

The dimensions of the rounded rectangle to draw, in device-independent pixels.

brush Brush

The brush used to paint the rounded rectangle's outline.

strokeWidth float

The width of the rounded rectangle's stroke. The stroke is centered on the rounded rectangle's outline. The default value is 1.0f.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawRoundedRectangle}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawRoundedRectangle(RoundedRectangle, Brush, float, StrokeStyle)

Draws the outline of the specified rounded rectangle using the specified stroke style.

public void DrawRoundedRectangle(RoundedRectangle roundedRect, Brush brush, float strokeWidth, StrokeStyle strokeStyle)

Parameters

roundedRect RoundedRectangle

The dimensions of the rounded rectangle to draw, in device-independent pixels.

brush Brush

The brush used to paint the rounded rectangle's outline.

strokeWidth float

The width of the rounded rectangle's stroke. The stroke is centered on the rounded rectangle's outline. The default value is 1.0f.

strokeStyle StrokeStyle

The style of the rounded rectangle's stroke, or NULL to paint a solid stroke. The default value is NULL.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawRoundedRectangle}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawRoundedRectangle(ref RoundedRectangle, Brush, float, StrokeStyle)

Draws the outline of the specified rounded rectangle using the specified stroke style.

public void DrawRoundedRectangle(ref RoundedRectangle roundedRect, Brush brush, float strokeWidth, StrokeStyle strokeStyle)

Parameters

roundedRect RoundedRectangle

The dimensions of the rounded rectangle to draw, in device-independent pixels.

brush Brush

The brush used to paint the rounded rectangle's outline.

strokeWidth float

The width of the stroke, in device-independent pixels. The value must be greater than or equal to 0.0f. If this parameter isn't specified, it defaults to 1.0f. The stroke is centered on the line.

strokeStyle StrokeStyle

The style of the rounded rectangle's stroke, or null to paint a solid stroke. The default value is null.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawRoundedRectangle) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

DrawText(string, TextFormat, RawRectangleF, Brush)

Draws the specified text using the format information provided by an TextFormat object.

public void DrawText(string text, TextFormat textFormat, RawRectangleF layoutRect, Brush defaultForegroundBrush)

Parameters

text string

A reference to an array of Unicode characters to draw.

textFormat TextFormat

An object that describes formatting details of the text to draw, such as the font, the font size, and flow direction.

layoutRect RawRectangleF

The size and position of the area in which the text is drawn.

defaultForegroundBrush Brush

The brush used to paint the text.

Remarks

To create an TextFormat object, create an Factory and call its {{CreateTextFormat}} method. This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawText}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawText(string, TextFormat, RawRectangleF, Brush, DrawTextOptions)

Draws the specified text using the format information provided by an TextFormat object.

public void DrawText(string text, TextFormat textFormat, RawRectangleF layoutRect, Brush defaultForegroundBrush, DrawTextOptions options)

Parameters

text string

A reference to an array of Unicode characters to draw.

textFormat TextFormat

An object that describes formatting details of the text to draw, such as the font, the font size, and flow direction.

layoutRect RawRectangleF

The size and position of the area in which the text is drawn.

defaultForegroundBrush Brush

The brush used to paint the text.

options DrawTextOptions

A value that indicates whether the text should be snapped to pixel boundaries and whether the text should be clipped to the layout rectangle. The default value is None, which indicates that text should be snapped to pixel boundaries and it should not be clipped to the layout rectangle.

Remarks

To create an TextFormat object, create an Factory and call its {{CreateTextFormat}} method. This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawText}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawText(string, TextFormat, RawRectangleF, Brush, DrawTextOptions, MeasuringMode)

Draws the specified text using the format information provided by an TextFormat object.

public void DrawText(string text, TextFormat textFormat, RawRectangleF layoutRect, Brush defaultForegroundBrush, DrawTextOptions options, MeasuringMode measuringMode)

Parameters

text string

A reference to an array of Unicode characters to draw.

textFormat TextFormat

An object that describes formatting details of the text to draw, such as the font, the font size, and flow direction.

layoutRect RawRectangleF

The size and position of the area in which the text is drawn.

defaultForegroundBrush Brush

The brush used to paint the text.

options DrawTextOptions

A value that indicates whether the text should be snapped to pixel boundaries and whether the text should be clipped to the layout rectangle. The default value is None, which indicates that text should be snapped to pixel boundaries and it should not be clipped to the layout rectangle.

measuringMode MeasuringMode

A value that indicates how glyph metrics are used to measure text when it is formatted. The default value is DWRITE_MEASURING_MODE_NATURAL.

Remarks

To create an TextFormat object, create an Factory and call its {{CreateTextFormat}} method. This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{DrawText}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawText(string, int, TextFormat, RawRectangleF, Brush, DrawTextOptions, MeasuringMode)

Draws the specified text using the format information provided by an TextFormat object.

public void DrawText(string text, int stringLength, TextFormat textFormat, RawRectangleF layoutRect, Brush defaultFillBrush, DrawTextOptions options, MeasuringMode measuringMode)

Parameters

text string

No documentation.

stringLength int

No documentation.

textFormat TextFormat

No documentation.

layoutRect RawRectangleF

No documentation.

defaultFillBrush Brush

No documentation.

options DrawTextOptions

No documentation.

measuringMode MeasuringMode

No documentation.

Remarks

To create an TextFormat object, create an Factory and call its CreateTextFormat method.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawText) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

DrawTextLayout(RawVector2, TextLayout, Brush)

Draws the formatted text described by the specified TextLayout object.

public void DrawTextLayout(RawVector2 origin, TextLayout textLayout, Brush defaultForegroundBrush)

Parameters

origin RawVector2

The point, described in device-independent pixels, at which the upper-left corner of the text described by textLayout is drawn.

textLayout TextLayout

The formatted text to draw. Any drawing effects that do not inherit from Resource are ignored. If there are drawing effects that inherit from ID2D1Resource that are not brushes, this method fails and the render target is put in an error state.

defaultForegroundBrush Brush

The brush used to paint any text in textLayout that does not already have a brush associated with it as a drawing effect (specified by the SetDrawingEffect(ComObject, TextRange) method).

Remarks

When drawing the same text repeatedly, using the DrawTextLayout method is more efficient than using the {{DrawText}} method because the text doesn't need to be formatted and the layout processed with each call. This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawTextLayout) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

DrawTextLayout(RawVector2, TextLayout, Brush, DrawTextOptions)

Draws the formatted text described by the specified TextLayout object.

public void DrawTextLayout(RawVector2 origin, TextLayout textLayout, Brush defaultFillBrush, DrawTextOptions options)

Parameters

origin RawVector2

No documentation.

textLayout TextLayout

No documentation.

defaultFillBrush Brush

No documentation.

options DrawTextOptions

No documentation.

Remarks

When drawing the same text repeatedly, using the DrawTextLayout method is more efficient than using the DrawText method because the text doesn't need to be formatted and the layout processed with each call.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as DrawTextLayout) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

EndDraw()

Ends drawing operations on the render target and indicates the current error state and associated tags.

public void EndDraw()

Remarks

Drawing operations can only be issued between a {{BeginDraw}} and EndDraw call.BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of RenderTarget might behave differently when {{BeginDraw}} is called. An BitmapRenderTarget may be locked between BeginDraw/EndDraw calls, a DXGI surface render target might be acquired on BeginDraw and released on EndDraw, while an WindowRenderTarget may begin batching at BeginDraw and may present on EndDraw, for example. The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of {{BeginDraw}}/EndDraw. After {{BeginDraw}} is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the {{Flush}} method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an HRESULT indicating the success of the operations and, optionally, the tag state of the render target at the time the error occurred. The EndDraw method always succeeds: it should not be called twice even if a previous EndDraw resulted in a failing HRESULT. If EndDraw is called without a matched call to {{BeginDraw}}, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate HRESULT and error information when EndDraw is called.

EndDraw(out long, out long)

Ends drawing operations on the render target and indicates the current error state and associated tags.

public void EndDraw(out long tag1, out long tag2)

Parameters

tag1 long

When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.

tag2 long

When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.

Remarks

Drawing operations can only be issued between a BeginDraw and EndDraw call.

BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of RenderTarget might behave differently when BeginDraw is called. An BitmapRenderTarget may be locked between BeginDraw/EndDraw calls, a DXGI surface render target might be acquired on BeginDraw and released on EndDraw, while an WindowRenderTarget may begin batching at BeginDraw and may present on EndDraw, for example.

The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.

After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an SharpDX.Result indicating the success of the operations and, optionally, the tag state of the render target at the time the error occurred. The EndDraw method always succeeds: it should not be called twice even if a previous EndDraw resulted in a failing SharpDX.Result.

If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate SharpDX.Result and error information when EndDraw is called.

FillEllipse(Ellipse, Brush)

Paints the interior of the specified ellipse.

public void FillEllipse(Ellipse ellipse, Brush brush)

Parameters

ellipse Ellipse

The position and radius, in device-independent pixels, of the ellipse to paint.

brush Brush

The brush used to paint the interior of the ellipse.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillEllipse) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

FillGeometry(Geometry, Brush)

Paints the interior of the specified geometry.

public void FillGeometry(Geometry geometry, Brush brush)

Parameters

geometry Geometry

The geometry to paint.

brush Brush

The brush used to paint the geometry's interior.

Remarks

If the opacityBrush parameter is not NULL, the alpha value of each pixel of the mapped opacityBrush is used to determine the resulting opacity of each corresponding pixel of the geometry. Only the alpha value of each color in the brush is used for this processing; all other color information is ignored. The alpha value specified by the brush is multiplied by the alpha value of the geometry after the geometry has been painted by brush. When this method fails, it does not return an error code. To determine whether a drawing operation (such as FillGeometry) failed, check the result returned by the EndDraw() or Flush() method.

FillGeometry(Geometry, Brush, Brush)

Paints the interior of the specified geometry.

public void FillGeometry(Geometry geometry, Brush brush, Brush opacityBrush)

Parameters

geometry Geometry

The geometry to paint.

brush Brush

The brush used to paint the geometry's interior.

opacityBrush Brush

The opacity mask to apply to the geometry, or null for no opacity mask. If an opacity mask (the opacityBrush parameter) is specified, brush must be an BitmapBrush that has its x- and y-extend modes set to D2D1_EXTEND_MODE_CLAMP. For more information, see the Remarks section.

Remarks

If the opacityBrush parameter is not null, the alpha value of each pixel of the mapped opacityBrush is used to determine the resulting opacity of each corresponding pixel of the geometry. Only the alpha value of each color in the brush is used for this processing; all other color information is ignored. The alpha value specified by the brush is multiplied by the alpha value of the geometry after the geometry has been painted by brush.

When this method fails, it does not return an error code. To determine whether a drawing operation (such as FillGeometry) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush method.

FillMesh(Mesh, Brush)

Paints the interior of the specified mesh.

public void FillMesh(Mesh mesh, Brush brush)

Parameters

mesh Mesh

The mesh to paint.

brush Brush

The brush used to paint the mesh.

Remarks

The current antialias mode of the render target must be D2D1_ANTIALIAS_MODE_ALIASED when FillMesh is called. To change the render target's antialias mode, use the SetAntialiasMode method.

FillMesh does not expect a particular winding order for the triangles in the Mesh; both clockwise and counter-clockwise will work.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillMesh) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

FillOpacityMask(Bitmap, Brush, OpacityMaskContent)

Applies the opacity mask described by the specified bitmap to a brush and uses that brush to paint a region of the render target.

public void FillOpacityMask(Bitmap opacityMask, Brush brush, OpacityMaskContent content)

Parameters

opacityMask Bitmap

The opacity mask to apply to the brush. The alpha value of each pixel in the region specified by sourceRectangle is multiplied with the alpha value of the brush after the brush has been mapped to the area defined by destinationRectangle.

brush Brush

The brush used to paint the region of the render target specified by destinationRectangle.

content OpacityMaskContent

The type of content the opacity mask contains. The value is used to determine the color space in which the opacity mask is blended.

Remarks

For this method to work properly, the render target must be using the Aliased antialiasing mode. You can set the antialiasing mode by calling the SharpDX.Direct2D1.RenderTarget.SetAntialiasMode(SharpDX.Direct2D1.AntialiasMode) method. This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{FillOpacityMask}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

FillOpacityMask(Bitmap, Brush, OpacityMaskContent, RawRectangleF?, RawRectangleF?)

Applies the opacity mask described by the specified bitmap to a brush and uses that brush to paint a region of the render target.

public void FillOpacityMask(Bitmap opacityMask, Brush brush, OpacityMaskContent content, RawRectangleF? destinationRectangle, RawRectangleF? sourceRectangle)

Parameters

opacityMask Bitmap

No documentation.

brush Brush

No documentation.

content OpacityMaskContent

No documentation.

destinationRectangle RawRectangleF?

No documentation.

sourceRectangle RawRectangleF?

No documentation.

Remarks

For this method to work properly, the render target must be using the D2D1_ANTIALIAS_MODE_ALIASED antialiasing mode. You can set the antialiasing mode by calling the ID2D1RenderTarget::SetAntialiasMode method.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillOpacityMask) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

FillRectangle(RawRectangleF, Brush)

Paints the interior of the specified rectangle.

public void FillRectangle(RawRectangleF rect, Brush brush)

Parameters

rect RawRectangleF

The dimension of the rectangle to paint, in device-independent pixels.

brush Brush

The brush used to paint the rectangle's interior.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRectangle) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

FillRoundedRectangle(RoundedRectangle, Brush)

Paints the interior of the specified rounded rectangle.

public void FillRoundedRectangle(RoundedRectangle roundedRect, Brush brush)

Parameters

roundedRect RoundedRectangle

The dimensions of the rounded rectangle to paint, in device-independent pixels.

brush Brush

The brush used to paint the interior of the rounded rectangle.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as {{FillRoundedRectangle}}) failed, check the result returned by the EndDraw(out long, out long) or Flush(out long, out long) methods.

FillRoundedRectangle(ref RoundedRectangle, Brush)

Paints the interior of the specified rounded rectangle.

public void FillRoundedRectangle(ref RoundedRectangle roundedRect, Brush brush)

Parameters

roundedRect RoundedRectangle

The dimensions of the rounded rectangle to paint, in device-independent pixels.

brush Brush

The brush used to paint the interior of the rounded rectangle.

Remarks

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as FillRoundedRectangle) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

Flush()

Executes all pending drawing commands.

public void Flush()

Remarks

This command does not flush the device that is associated with the render target. Calling this method resets the error state of the render target.

Flush(out long, out long)

Executes all pending drawing commands.

public void Flush(out long tag1, out long tag2)

Parameters

tag1 long

When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.

tag2 long

When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.

Remarks

This command does not flush the Direct3D device context that is associated with the render target.

Calling this method resets the error state of the render target.

GetTags(out long, out long)

Gets the label for subsequent drawing operations.

public void GetTags(out long tag1, out long tag2)

Parameters

tag1 long

When this method returns, contains the first label for subsequent drawing operations. This parameter is passed uninitialized. If null is specified, no value is retrieved for this parameter.

tag2 long

When this method returns, contains the second label for subsequent drawing operations. This parameter is passed uninitialized. If null is specified, no value is retrieved for this parameter.

Remarks

If the same address is passed for both parameters, both parameters receive the value of the second tag.

IsSupported(ref RenderTargetProperties)

Indicates whether the render target supports the specified properties.

public RawBool IsSupported(ref RenderTargetProperties renderTargetProperties)

Parameters

renderTargetProperties RenderTargetProperties

The render target properties to test.

Returns

RawBool

TRUE if the specified render target properties are supported by this render target; otherwise, SharpDX.Result.False.

Remarks

This method does not evaluate the DPI settings specified by the renderTargetProperties parameter.

PopAxisAlignedClip()

Removes the last axis-aligned clip from the render target. After this method is called, the clip is no longer applied to subsequent drawing operations.

public void PopAxisAlignedClip()

Remarks

A PushAxisAlignedClip/PopAxisAlignedClip pair can occur around or within a PushLayer/PopLayer pair, but may not overlap. For example, a PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip sequence is valid, but a PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer sequence is not.

PopAxisAlignedClip must be called once for every call to PushAxisAlignedClip.

For an example, see How to Clip with an Axis-Aligned Clip Rectangle.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopAxisAlignedClip) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

PopLayer()

Stops redirecting drawing operations to the layer that is specified by the last PushLayer call.

public void PopLayer()

Remarks

A PopLayer must match a previous PushLayer call.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PopLayer) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

PushAxisAlignedClip(RawRectangleF, AntialiasMode)

Specifies a rectangle to which all subsequent drawing operations are clipped.

public void PushAxisAlignedClip(RawRectangleF clipRect, AntialiasMode antialiasMode)

Parameters

clipRect RawRectangleF

The size and position of the clipping area, in device-independent pixels.

antialiasMode AntialiasMode

The antialiasing mode that is used to draw the edges of clip rects that have subpixel boundaries, and to blend the clip with the scene contents. The blending is performed once when the PopAxisAlignedClip method is called, and does not apply to each primitive within the layer.

Remarks

The clipRect is transformed by the current world transform set on the render target. After the transform is applied to the clipRect that is passed in, the axis-aligned bounding box for the clipRect is computed. For efficiency, the contents are clipped to this axis-aligned bounding box and not to the original clipRect that is passed in.

The following diagrams show how a rotation transform is applied to the render target, the resulting clipRect, and a calculated axis-aligned bounding box.

1. Assume the rectangle in the following illustration is a render target that is aligned to the screen pixels.

2. Apply a rotation transform to the render target. In the following illustration, the black rectangle represents the original render target and the red dashed rectangle represents the transformed render target.

3. After calling PushAxisAlignedClip, the rotation transform is applied to the clipRect. In the following illustration, the blue rectangle represents the transformed clipRect.

4. The axis-aligned bounding box is calculated. The green dashed rectangle represents the bounding box in the following illustration. All contents are clipped to this axis-aligned bounding box.

Note??If rendering operations fail or if PopAxisAlignedClip is not called, clip rects may cause some artifacts on the render target. PopAxisAlignedClip can be considered a drawing operation that is designed to fix the borders of a clipping region. Without this call, the borders of a clipped area may be not antialiased or otherwise corrected.?

The PushAxisAlignedClip and PopAxisAlignedClip must match. Otherwise, the error state is set. For the render target to continue receiving new commands, you can call Flush to clear the error.

A PushAxisAlignedClip and PopAxisAlignedClip pair can occur around or within a PushLayer and PopLayer, but cannot overlap. For example, the sequence of PushAxisAlignedClip, PushLayer, PopLayer, PopAxisAlignedClip is valid, but the sequence of PushAxisAlignedClip, PushLayer, PopAxisAlignedClip, PopLayer is invalid.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushAxisAlignedClip) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

PushLayer(ref LayerParameters, Layer)

Adds the specified layer to the render target so that it receives all subsequent drawing operations until PopLayer is called.

public void PushLayer(ref LayerParameters layerParameters, Layer layer)

Parameters

layerParameters LayerParameters

No documentation.

layer Layer

No documentation.

Remarks

The PushLayer method allows a caller to begin redirecting rendering to a layer. All rendering operations are valid in a layer. The location of the layer is affected by the world transform set on the render target.

Each PushLayer must have a matching PopLayer call. If there are more PopLayer calls than PushLayer calls, the render target is placed into an error state. If Flush is called before all outstanding layers are popped, the render target is placed into an error state, and an error is returned. The error state can be cleared by a call to EndDraw.

A particular Layer resource can be active only at one time. In other words, you cannot call a PushLayer method, and then immediately follow with another PushLayer method with the same layer resource. Instead, you must call the second PushLayer method with different layer resources.

This method doesn't return an error code if it fails. To determine whether a drawing operation (such as PushLayer) failed, check the result returned by the ID2D1RenderTarget::EndDraw or ID2D1RenderTarget::Flush methods.

RestoreDrawingState(DrawingStateBlock)

Sets the render target's drawing state to that of the specified DrawingStateBlock.

public void RestoreDrawingState(DrawingStateBlock drawingStateBlock)

Parameters

drawingStateBlock DrawingStateBlock

No documentation.

SaveDrawingState(DrawingStateBlock)

Saves the current drawing state to the specified DrawingStateBlock.

public void SaveDrawingState(DrawingStateBlock drawingStateBlock)

Parameters

drawingStateBlock DrawingStateBlock

No documentation.

SetTags(long, long)

Specifies a label for subsequent drawing operations.

public void SetTags(long tag1, long tag2)

Parameters

tag1 long

A label to apply to subsequent drawing operations.

tag2 long

A label to apply to subsequent drawing operations.

Remarks

The labels specified by this method are printed by debug error messages. If no tag is set, the default value for each tag is 0.

TryEndDraw(out long, out long)

Ends drawing operations on the render target and indicates the current error state and associated tags.

public Result TryEndDraw(out long tag1, out long tag2)

Parameters

tag1 long

When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.

tag2 long

When this method returns, contains the tag for drawing operations that caused errors or 0 if there were no errors. This parameter is passed uninitialized.

Returns

Result

If the method succeeds, it returns SharpDX.Result.Ok. Otherwise, it returns an SharpDX.Result error code and sets tag1 and tag2 to the tags that were active when the error occurred.

Remarks

Drawing operations can only be issued between a BeginDraw and EndDraw call.

BeginDraw and EndDraw are use to indicate that a render target is in use by the Direct2D system. Different implementations of RenderTarget might behave differently when BeginDraw is called. An BitmapRenderTarget may be locked between BeginDraw/EndDraw calls, a DXGI surface render target might be acquired on BeginDraw and released on EndDraw, while an WindowRenderTarget may begin batching at BeginDraw and may present on EndDraw, for example.

The BeginDraw method must be called before rendering operations can be called, though state-setting and state-retrieval operations can be performed even outside of BeginDraw/EndDraw.

After BeginDraw is called, a render target will normally build up a batch of rendering commands, but defer processing of these commands until either an internal buffer is full, the Flush method is called, or until EndDraw is called. The EndDraw method causes any batched drawing operations to complete, and then returns an SharpDX.Result indicating the success of the operations and, optionally, the tag state of the render target at the time the error occurred. The EndDraw method always succeeds: it should not be called twice even if a previous EndDraw resulted in a failing SharpDX.Result.

If EndDraw is called without a matched call to BeginDraw, it returns an error indicating that BeginDraw must be called before EndDraw. Calling BeginDraw twice on a render target puts the target into an error state where nothing further is drawn, and returns an appropriate SharpDX.Result and error information when EndDraw is called.

Operators

explicit operator RenderTarget(nint)

public static explicit operator RenderTarget(nint nativePtr)

Parameters

nativePtr nint

Returns

RenderTarget