TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class Graphics in Tinman.AddOns.Rendering

The Graphics class provides methods for performing pixel-perfect 2D drawing.

sealed class Graphics extends Disposable
  implements IBeginEnd

Remarks

Pixel coordinates always refer to the center of a pixel, e.g. the pixel coordinates (0|0) refer to the center of the top-left pixel in the viewport. The center of the lower-right pixel is at (ScreenWidth-1|ScreenHeight-1). Names of method parameters that take pixel coordinates have the 'pixel' prefix (e.g. 'pixelX').

Screen coordinates refer to the whole viewport: the screen coordinates (0|0) refer to the top-left corner of the top-left pixel in the viewport. The lower-right corner of the lower-right pixel is at (ScreenWidth|ScreenHeight). Names of method parameters that take screen coordinates have the 'screen' prefix (e.g. 'screenX').

Public / Constants

NullResource

An IResourceHandle that always returns null.

public static readonly field NullResource
type IResourceHandle

Public / Attributes

Bounds

The bounds of this graphics object on the render target(s) of the graphics context.

public property Bounds { get set }
type Box2I
value The bounds, in pixel coordinates.

Cache

The shared resource cache of this Graphics instance.

public property Cache { get }
type ResourceCache
value [not-null] The shared resource cache.

Remarks:

Resources that have been obtained via Get will be disposed when this Graphics object is disposed.

Clip

Returns the current clip rectangle.

public property Clip { get }
type Box2I
value The clip rectangle, in pixel coordinates.

Context

Returns the graphics context.

public property Context { get }
type IGraphicsContext
value [not-null] The graphics context.

LifecycleState

Returns the lifecycle state of this object.

public virtual property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited Disposable.LifecycleState

Loader

The shared resource loader of this Graphics instance.

public property Loader { get }
type ResourceLoader
value [not-null] The shared resource loader.

ScreenHeight

Returns the screen height.

public property ScreenHeight { get }
type int32
value [>0] The screen height, in pixels.

ScreenSize

Returns the screen size.

public property ScreenSize { get }
type Vec2I
value The screen size, in pixels.

ScreenWidth

Returns the screen width.

public property ScreenWidth { get }
type int32
value [>0] The screen width, in pixels.

SimpleFont

Returns a PixelFont object that has been created using the DrawChar method of the ColorBuffer class.

public property SimpleFont { get }
type PixelFont
value [not-null] The simple font.

Remarks:

This font does not require any external resources and is thus always available.

Public / Constructors

Graphics

Creates a new instance of Graphics.

public constructor Graphics (IGraphicsContext context)
params context [not-null] The graphics context to use.

Remarks:

The shader effect 'Tinman.Graphics' must have been registered with the given graphics context before a Graphics object can be created.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method AcquireTry ()
type IDisposable
returns this if a new strong reference has been acquired, null if this object is already being disposed.
inherited Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Begin

Begins an access to this object.

public method Begin ()
implements IBeginEnd.Begin

Remarks:

See the documentation of the class which implements this interface for details on the operations that must be wrapped in Begin and End calls.

See also:

BeginEnd

Clear

Clears the current clip rectangle to the given color.

[BeginEnd]
public method Clear (int64 color)
params color The color to clear to.

ComputeAnchorX

Computes the position for the given anchor.

[Pure]
public static method ComputeAnchorX (Anchor anchor, int32 pixelRight, int32 pixelLeft = 0)
type int32
params anchor The anchor type.
  pixelRight Pixel coordinate of right edge.
  pixelLeft Pixel coordinate of left edge. Defaults to 0.
returns The anchor pixel X-coordinate.

ComputeAnchorY

Computes the position for the given anchor.

[Pure]
public static method ComputeAnchorY (Anchor anchor, int32 pixelBottom, int32 pixelTop = 0, int32 pixelBaseline = 0)
type int32
params anchor The anchor type.
  pixelBottom Pixel coordinate of bottom edge.
  pixelTop Pixel coordinate of top edge. Defaults to 0.
  pixelBaseline Pixel coordinate of baseline. Defaults to 0.
returns The anchor pixel Y-coordinate.

CreateBitmap

Creates a new image resource.

[OwnerReturn]
public method CreateBitmap (int32 width, int32 height, BitmapFlags flags = BitmapFlags.Default)
type Bitmap
params width [>0] The image width, in pixels.
  height [>0] The image height, in pixels.
  flags The image flags.
returns [not-null] The created image resource.

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method Dispose ()
inherited Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

DrawBitmap

Draws a bitmap image onto the screen.

[BeginEnd]
public method DrawBitmap (Bitmap bitmap, Vec2I pixel, Anchor anchor = Anchor.TopLeft, int64 color = Colors.White)
params bitmap [not-null] The image to draw.
  pixel Pixel coordinates of image anchor.
  anchor The image anchor to use. Defaults to TopLeft.
  color Image pixels will be modulated by this color (see Colors) value. Defaults to White.

Draws a bitmap image onto the screen.

[BeginEnd]
public method DrawBitmap (Bitmap bitmap, int32 pixelX, int32 pixelY, Anchor anchor = Anchor.TopLeft, int64 color = Colors.White)
params bitmap [not-null] The image to draw.
  pixelX Pixel X-coordinate of image anchor.
  pixelY Pixel Y-coordinate of image anchor.
  anchor The image anchor to use. Defaults to TopLeft.
  color Image pixels will be modulated by this color (see Colors) value. Defaults to White.

DrawBitmapOutline

Draws a bitmap image onto the screen.

[BeginEnd]
public method DrawBitmapOutline (Bitmap bitmap, int32 pixelX, int32 pixelY, Anchor anchor = Anchor.TopLeft, int64 color = Colors.Black)
params bitmap [not-null] The image to draw.
  pixelX Pixel X-coordinate of image anchor.
  pixelY Pixel Y-coordinate of image anchor.
  anchor The image anchor to use. Defaults to TopLeft.
  color Image pixels will be modulated by this color (see Colors) value. Defaults to Black.

DrawBitmapPart

Draws a bitmap image onto the screen.

[BeginEnd]
public method DrawBitmapPart (Bitmap bitmap, Box2I part, Vec2I pixel, Anchor anchor = Anchor.TopLeft, int64 color = Colors.White)
params bitmap [not-null] The image to draw.
  part The bitmap part to draw.
  pixel Pixel coordinates of image anchor.
  anchor The image anchor to use. Defaults to TopLeft.
  color Image pixels will be modulated by this color (see Colors) value. Defaults to White.

Draws a bitmap image onto the screen.

[BeginEnd]
public method DrawBitmapPart (Bitmap bitmap, int32 partX, int32 partY, int32 partWidth, int32 partHeight, int32 pixelX, int32 pixelY, Anchor anchor = Anchor.TopLeft, int64 color = Colors.White)
params bitmap [not-null] The image to draw.
  partX [0..bitmap.Width] X-coordinate of top-left bitmap pixel to draw.
  partY [0..bitmap.Height] Y-coordinate of top-left bitmap pixel to draw.
  partWidth [0..bitmap.Width-partX] Width of bitmap part to draw, in pixels.
  partHeight [0..bitmap.Height-partY] Height of bitmap part to draw, in pixels.
  pixelX Pixel X-coordinate of image anchor.
  pixelY Pixel Y-coordinate of image anchor.
  anchor The image anchor to use. Defaults to TopLeft.
  color Image pixels will be modulated by this color (see Colors) value. Defaults to White.

DrawBitmapStretch

Draws a bitmap image onto the screen.

[BeginEnd]
public method DrawBitmapStretch (Bitmap bitmap, int32 pixelX, int32 pixelY, int32 width, int32 height, Anchor anchor = Anchor.TopLeft, int64 color = Colors.White)
params bitmap [not-null] The image to draw.
  pixelX Pixel X-coordinate of image anchor.
  pixelY Pixel Y-coordinate of image anchor.
  width [>0] Width of image on screen.
  height [>0] Height of image on screen.
  anchor The image anchor to use. Defaults to TopLeft.
  color Image pixels will be modulated by this color (see Colors) value. Defaults to White.

DrawBitmapTransform

Draws a bitmap image onto the screen.

[BeginEnd]
public method DrawBitmapTransform (Bitmap bitmap, Mat3F transform, int32 pixelX, int32 pixelY, Anchor anchor = Anchor.TopLeft, int64 color = Colors.White)
params bitmap [not-null] The image to draw.
  transform The transformation matrix to apply (see remarks).
  pixelX Pixel X-coordinate of image anchor.
  pixelY Pixel Y-coordinate of image anchor.
  anchor The image anchor to use. Defaults to TopLeft.
  color Image pixels will be modulated by this color (see Colors) value. Defaults to White.

Remarks:

First the untransformed bitmap bounds are computed from the given image anchor. Then the given transformation matrix is applied to the corner vertices of the bitmap bounds. Finally, a textured quad is rendered using the transformed corner vertices.

DrawChar

Draws a character glyph onto the 2D canvas.

[BeginEnd]
public method DrawChar (PixelFont font, char c, int32 pixelX, int32 pixelY, int64 color, Anchor anchor = Anchor.TopLeft)
params font [not-null] The font to use.
  c The character to draw.
  pixelX Pixel X-coordinate of anchor point.
  pixelY Pixel Y-coordinate of anchor point.
  color The color to use (see Colors).
  anchor The anchor to use. Defaults to TopLeft.

See also:

PixelFont

DrawCircle

Draws a circle.

[BeginEnd]
public method DrawCircle (float32 pixelX, float32 pixelY, float32 radius, int64 colorBorder, int64 colorFill = 0)
params pixelX Pixel X-coordinate of circle center.
  pixelY Pixel Y-coordinate of circle center.
  radius Radius of circle, in pixel units.
  colorBorder Color (see Colors) of circle border or 0 for no border.
  colorFill Color (see Colors) of circle fill of 0 for no fill.

DrawLine

Draws a line segment, filling both endpoints.

[BeginEnd]
public method DrawLine (float32 pixelX1, float32 pixelY1, float32 pixelX2, float32 pixelY2, int64 color)
params pixelX1 Pixel X-coordinate of first point.
  pixelY1 Pixel Y-coordinate of first point.
  pixelX2 Pixel X-coordinate of second point.
  pixelY2 Pixel Y-coordinate of second point.
  color The color (see Colors) to use.

DrawLineHorizontal

Draws a horizontal line.

[BeginEnd]
public method DrawLineHorizontal (int32 pixelX, int32 pixelY, int32 length, int64 color)
params pixelX Pixel X-coordinate of first line endpoint.
  pixelY Pixel Y-coordinate of line.
  length Length of the line.
  color The color (see Colors) value to use.

DrawLineVertical

Draws a vertical line.

[BeginEnd]
public method DrawLineVertical (int32 pixelX, int32 pixelY, int32 length, int64 color)
params pixelX Pixel X-coordinate of line.
  pixelY Pixel Y-coordinate of first line endpoint.
  length Length of the line.
  color The color (see Colors) value to use.

DrawPolygon

Draws a simple polygon.

[BeginEnd]
public method DrawPolygon (int64 color, Vertex[] vertices, int32 first = 0, int32 count = -1)
params color Modulation color for the polygon vertex colors.
  vertices [not-null] The polygon vertices.
  first [0..vertices.Length] Index of first polygon vertex. Defaults to 0.
  count [-1..vertices.Length-first] Number of polygon vertices. If -1 all remaining vertices are used. Defaults to -1

Draws a simple polygon.

[BeginEnd]
public method DrawPolygon (Bitmap texture, Vertex[] vertices, int32 first = 0, int32 count = -1)
params texture [not-null] The texture image to use.
  vertices [not-null] The polygon vertices.
  first [0..vertices.Length] Index of first polygon vertex. Defaults to 0.
  count [-1..vertices.Length-first] Number of polygon vertices. If -1 all remaining vertices are used. Defaults to -1

Draws a simple polygon.

[BeginEnd]
public method DrawPolygon (ITexture2D texture, Vertex[] vertices, int32 first = 0, int32 count = -1)
params texture [not-null] The texture image to use.
  vertices [not-null] The polygon vertices.
  first [0..vertices.Length] Index of first polygon vertex. Defaults to 0.
  count [-1..vertices.Length-first] Number of polygon vertices. If -1 all remaining vertices are used. Defaults to -1

DrawPolyline

Draws a polyline.

[BeginEnd]
public method DrawPolyline (bool closed, int64 color, Vertex[] vertices, int32 first = 0, int32 count = -1)
params closed Connect the last vertex with the first vertex (i.e. draw a closed polyline)?
  color Modulation color for the polyline vertex colors.
  vertices [not-null] The polyline vertices.
  first [0..vertices.Length] Index of first polyline vertex. Defaults to 0.
  count [-1..vertices.Length-first] Number of polyline vertices. If -1 all remaining vertices are used. Defaults to -1

DrawPrimitive

Draws a batched 2D primitive.

[BeginEnd]
public method DrawPrimitive (Primitive primitive, int32 first, int32 count)
params primitive The primitive to draw.
  first [>=0] First vertex to draw (see remarks).
  count [>=0] Number of vertices to draw (see remarks).

Remarks:

If an index buffer has been specified to DrawPrimitivePrepare, the given first and count parameters refer to elements in the index buffer. Otherwise, they refer to vertices in the 2D vertex buffer.

See also:

DrawPrimitiveBuffer
DrawPrimitivePrepare

DrawPrimitiveBegin

Begins to render a 2D primitive which vertices are specified via the Vertex(...) method.

[BeginEnd]
public method DrawPrimitiveBegin (Primitive primitive, ITexture2D texture = null)
params primitive The primitive to render.
  texture The texture image to use. Defaults to null.

See also:

DrawPrimitiveEnd
DrawPrimitiveVertex

DrawPrimitiveBuffer

Creates a vertex buffer that can be used to draw batched 2D primitives.

[OwnerReturn]
public method DrawPrimitiveBuffer (int32 capacity)
type IVertexBuffer
params capacity [>0] The buffer capacity, in vertices.
returns [not-null] The vertex buffer for 2D primitives (see remarks).

Remarks:

The returned buffer has the following layout:

  1. Byte offset #0: Screen X-coordinate (32-bit floating point).
  2. Byte offset #4: Screen Y-coordinate (32-bit floating point).
  3. Byte offset #8: Depth coordinate (32-bit floating point).
  4. Byte offset #12: Color value (32-bit integer, A8R8G8B8).
  5. Byte offset #16: Texture U-coordinate (32-bit floating point).
  6. Byte offset #20: Texture V-coordinate (32-bit floating point).

See also:

DrawPrimitivePrepare
DrawPrimitive
Write

DrawPrimitiveEnd

Finishes rendering of the current 2D primitive.

[BeginEnd]
public method DrawPrimitiveEnd ()

See also:

DrawPrimitiveBegin
DrawPrimitiveVertex

DrawPrimitivePrepare

Prepares to render batched 2D primitives.

[BeginEnd]
public method DrawPrimitivePrepare (IGeometryBuffer geometryBuffer, ITexture2D texture = null)
params geometryBuffer [not-null] The geometry buffer (see DrawPrimitiveBuffer).
  texture Optional texture to use. Defaults to null.

See also:

DrawPrimitiveBuffer
DrawPrimitive

DrawPrimitiveVertex

Specifies the next vertex for the current 2D primitive.

[BeginEnd]
public method DrawPrimitiveVertex (Vertex v)
params v The vertex.

See also:

DrawPrimitiveBegin
DrawPrimitiveEnd

Specifies the next vertex for the current 2D primitive.

[BeginEnd]
public method DrawPrimitiveVertex (Vertex v, int64 color)
params v The vertex.
  color The color to multiply with Color.

See also:

DrawPrimitiveBegin
DrawPrimitiveEnd

Specifies the next vertex for the current 2D primitive.

[BeginEnd]
public method DrawPrimitiveVertex (float32 screenX, float32 screenY, int64 color)
params screenX Screen X-coordinate of vertex.
  screenY Screen Y-coordinate of vertex.
  color The diffuse vertex color (see Colors).

See also:

DrawPrimitiveBegin
DrawPrimitiveEnd

Specifies the next vertex for the current 2D primitive.

[BeginEnd]
public method DrawPrimitiveVertex (float32 x, float32 y, int64 color, float32 u, float32 v)
params x X-coordinate of vertex, in screen-space.
  y Y-coordinate of vertex, in screen-space.
  color The diffuse vertex color (see Colors).
  u Texture U-coordinate.
  v Texture V-coordinate.

See also:

DrawPrimitiveBegin
DrawPrimitiveEnd

DrawRectangle

Draws a rectangle.

[BeginEnd]
public method DrawRectangle (Box2I bounds, int64 colorBorder, int64 colorFill = 0)
params bounds The rectangle bounds, in pixel coordinates.
  colorBorder The border color (see Colors) to use or 0 for no border.
  colorFill The fill color (see Colors) to use or 0 for no fill.

Draws a rectangle.

[BeginEnd]
public method DrawRectangle (int32 pixelX, int32 pixelY, int32 width, int32 height, int64 colorBorder, int64 colorFill = 0)
params pixelX Pixel X-coordinate of top-left corner of rectangle.
  pixelY Pixel Y-coordinate of top-left corner of rectangle.
  width Width of rectangle, in pixels.
  height Height of rectangle, in pixels.
  colorBorder The border color (see Colors) to use or 0 for no border.
  colorFill The fill color (see Colors) to use or 0 for no fill.

DrawRoundRectangle

Draws a rectangle with round corners.

[BeginEnd]
public method DrawRoundRectangle (Box2I bounds, int32 round, int64 colorBorder, int64 colorFill = 0, Corner corners = Corner.All)
params bounds The rectangle bounds, in pixel coordinates.
  round Radius of round corners, in pixel units.
  colorBorder The border color (see Colors) to use or 0 for no border.
  colorFill The fill color (see Colors) to use or 0 for no fill.
  corners The round rectangle corners. Defaults to All.

Draws a rectangle with round corners.

[BeginEnd]
public method DrawRoundRectangle (int32 pixelX, int32 pixelY, int32 width, int32 height, int32 round, int64 colorBorder, int64 colorFill = 0, Corner corners = Corner.All)
params pixelX Pixel X-coordinate of top-left corner of rectangle.
  pixelY Pixel Y-coordinate of top-left corner of rectangle.
  width Width of rectangle, in pixels.
  height Height of rectangle, in pixels.
  round Radius of round corners, in pixel units.
  colorBorder The border color (see Colors) to use or 0 for no border.
  colorFill The fill color (see Colors) to use or 0 for no fill.
  corners The round rectangle corners. Defaults to All.

DrawShape

Draws the edges of the given vector shape (see EdgeAt).

[BeginEnd]
public method DrawShape (IShape shape, int64 colorBorder)
params shape [not-null] The vector shape.
  colorBorder The color to use for drawing the shape edges.

Draws the edges of the given vector shape (see EdgeAt).

[BeginEnd]
public method DrawShape (IShape shape, Mat3D transform, int64 colorBorder)
params shape [not-null] The vector shape.
  transform The transformation matrix from shape coordinates to screen coordinates.
  colorBorder The color to use for drawing the shape edges.

DrawString

Draws a pixel-perfect string onto the 2D canvas.

[BeginEnd]
public method DrawString (PixelFont font, string text, int32 pixelX, int32 pixelY, int64 color, Anchor anchor = Anchor.TopLeft)
params font [not-null] The font to use.
  text [not-null] The text to draw.
  pixelX Pixel X-coordinate of anchor point.
  pixelY Pixel Y-coordinate of anchor point.
  color The color (see Colors) to use.
  anchor The anchor to use. Defaults to TopLeft.

DrawStringOutline

Draws a pixel-perfect string onto the 2D canvas.

[BeginEnd]
public method DrawStringOutline (PixelFont font, string text, int32 pixelX, int32 pixelY, int64 textColor, Anchor anchor = Anchor.TopLeft, int64 outlineColor = Colors.Black & Colors.Opaque50)
params font [not-null] The font to use.
  text [not-null] The text to draw.
  pixelX Pixel X-coordinate of anchor point.
  pixelY Pixel Y-coordinate of anchor point.
  textColor The text color (see Colors) to use.
  anchor The anchor to use. Defaults to TopLeft.
  outlineColor The outline color (see Colors) to use. Defaults to semi-transparent black.

End

Ends the current access to this object.

public method End ()
implements IBeginEnd.End

Remarks:

See the documentation of the class which implements this interface for details on the operations that must be wrapped in Begin and End calls.

See also:

BeginEnd

FindAnchor

Finds the best anchor on a rectangle for the given screen direction.

[Pure]
public static method FindAnchor (Vec2D direction, bool baseline = true)
type Anchor
params direction Direction vector pointing towards a rectangle.
  baseline true uses Base as the rectangle bottom edge, false uses Bottom. Defaults to true.
returns The best anchor.

FlipAnchor

Flips the given anchor.

[Pure]
public static method FlipAnchor (Anchor anchor)
type Anchor
params anchor The anchor to flip.
returns The flipped anchor.

Fullscreen

Sets the Bounds of this Graphics object to full-screen (i.e. the size of the current render target, see Size).

public method Fullscreen ()
type Graphics
returns [not-null] this

LoadBitmapFrom

Loads an image resource from the given file.

[OwnerReturn]
public method LoadBitmapFrom (Path file, BitmapFlags flags = BitmapFlags.Default)
type Bitmap
params file [not-null] The file path.
  flags The image flags to apply when loading the image file.
returns [not-null] The loaded image resource.

Loads an image resource from the given image descriptor.

[OwnerReturn]
public method LoadBitmapFrom (IImage image, BitmapFlags flags = BitmapFlags.Default)
type Bitmap
params image [not-null] The image descriptor.
  flags The image flags to apply when loading the image file.
returns [not-null] The loaded image resource.

LoadFontFrom

Loads a font resource from the given file.

[OwnerReturn]
public method LoadFontFrom (Path file, Kerning kerning)
type PixelFont
params file [not-null] The file path.
  kerning The kerning parameters to use.
returns [not-null] The loaded font resource.

Remarks:

Additional metadata is encoded in the image file of the pixel font. Metadata values are encoded as compressed sRGB color channel values.

PopClip

Restores the most recent clip rectangle from the clip stack.

[BeginEnd]
public method PopClip ()

PopDepth

Restores the previous depth value.

[BeginEnd]
public method PopDepth ()

See also:

PushDepth

PushClip

Pushes the current clip rectangle onto the stack, intersects it with the given rectangle and sets the clip rectangle to the result.

[BeginEnd]
public method PushClip (Box2I bounds)
type bool
params bounds The bounds of the clip rectangle, in pixel coordinates.
returns true if the clip rectangle contains at least one screen pixel, false if it is empty.

See also:

PopClip

Pushes the current clip rectangle onto the clip stack and intersects it with the given rectangle.

[BeginEnd]
public method PushClip (int32 pixelX, int32 pixelY, int32 width, int32 height)
type bool
params pixelX Pixel X-coordinate of top-left corner of clip rectangle.
  pixelY Pixel Y-coordinate of top-left corner of clip rectangle.
  width [>=0] Width of clip rectangle, in pixels.
  height [>=0] Height of clip rectangle, in pixels.
returns true if the clip rectangle contains at least one screen pixel, false if it is empty.

PushDepth

Uses the given depth value for all subsequent 2D primitives.

[BeginEnd]
public method PushDepth (float32 depth)
params depth The depth value, in the range [0..1].

See also:

PopDepth

Translate

Translates all 2D rendering by the given amount.

[BeginEnd]
public method Translate (Vec2I pixel)
params pixel Translation amount, in pixels.

Translates all 2D rendering by the given amount.

[BeginEnd]
public method Translate (int32 pixelX, int32 pixelY)
params pixelX Horizontal translation amount, in pixels.
  pixelY Vertical translation amount, in pixels.

Write

Writes the given vertex to the specified buffer.

public static method Write (Vertex vertex, ByteBuffer buffer, float32 depth = 0)
params vertex The vertex to write.
  buffer [not-null] The target buffer.
  depth The screen depth value (see Graphics). Defaults to 0.

See also:

DrawPrimitiveBuffer