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

interface IGraphicsContext in Tinman.AddOns.Rendering

Base interface for classes that provide a graphics context.

interface IGraphicsContext extends IBeginEnd
  INativeHandle
  base of GraphicsContext

Remarks

Rendering with a graphics context is performed as follows:

  1. Call Validate:
    1. true: The graphics context is valid, continue with 3.
    2. false: The graphics context has become invalid, continue with 2.
  2. Reset the graphics context:
    1. Dispose all resources, e.g.:
      IIndexBuffer s, IVertexBuffer s, ITexture2D s, ITextureCube s, IRenderTarget s.
    2. Call Validate. The method will return true if the graphics context is valid again.
    3. Recreate all resources.
  3. Call Begin
  4. Use SetRenderTarget to perform rendering for each IRenderTarget resp. ISwapChain.
  5. Call End
  6. Call Present for each swap chain.

Attributes

Cache

Returns the shared ResourceCache object for this graphics context.

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

FrameTime

The GPU time that has been spent for the last frame.

property FrameTime { get }
type float32
value [>=0] The spent time, in milliseconds.

Remarks:

The last frame is defined as the sequence of render calls made between Begin and End. The frame time is measured for the most recent frame that has been finished by the GPU, i.e. measuring frame time will never stall the pipeline.

Graphics

Returns the shared Graphics object for this graphics context.

[OwnerReturn]
property Graphics { get }
type Graphics
value [not-null] The shared graphics object.

IsNearAtZero

Is the near-clipping plane mapped to 0 in clip-space (true), or is it mapped to -1 (false)?

property IsNearAtZero { get }
type bool
value The mapping behaviour for the near-clipping plane.

LifecycleState

Returns the lifecycle state of this object.

property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited ILifecycleState.LifecycleState

Name

Human readable name of this graphics context.

property Name { get }
type string
value [not-empty] The graphics context name.

NativeHandle

Returns the raw handle value of the native resource that is contained in this object.

property NativeHandle { get }
type IntPtr
value The raw handle value.
inherited INativeHandle.NativeHandle

Remarks:

The documentation of the implementing class will contain information on how to interpret the raw handle value.

PrimitiveRenderer

Returns the IPrimitiveRenderer for this graphics context.

property PrimitiveRenderer { get }
type IPrimitiveRenderer
value [not-null] The IPrimitiveRenderer object.

RenderTargetCount

The number of render targets that can be used simultaneously during rendering.

property RenderTargetCount { get }
type int32
value [1..4] The number of render targets.

See also:

SetRenderTarget

ShaderEffectNames

Returns the names of all shader effects.

property ShaderEffectNames { get }
type string[]
value [not-null] The list of shader effect names.

See also:

ShaderEffect

Size

The pixel size of the render targets that have been specified by the most recent call to SetRenderTarget.

property Size { get }
type Vec2I
value The render target size, in pixels.

Remarks:

If no render target is bound to index 0, Zero is returned.

TextureFactory

Returns the ITextureFactory for this graphics context.

property TextureFactory { get }
type ITextureFactory
value [not-null] The ITextureFactory object.

Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method AcquireTry ()
type IDisposable
returns this if a new strong reference has been acquired, null if this object is already being disposed.
inherited IDisposable.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.

method Begin ()
inherited 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 pixels to the given values on the render targets that have been specified by the most recent call to SetRenderTarget.

[BeginEnd]
method Clear (RenderTargetClearFlags flags, int64 color = 0, float32 depth = 1, int32 stencil = 0)
params flags Flags that depict the buffers to clear.
  color The color (see Colors) to clear to.
  depth The depth value to clear to.
  stencil The stencil value to clear to.

Remarks:

An implementation can choose to either clear all pixels (e.g. Direct3D 10/11), or to clear only those that are inside of the current viewport rectangle (e.g. Direct3D 9). This behaviour is not exposed, so the Clear method should only be called after SetRenderTarget and before SetViewport.

Passing Depth and/or Stencil with the flags parameter when there is no depth/stencil buffer (see D24_S8) can make the Clear method fail silently.

CreateGeometryBuffer

Creates a buffer for drawing geometry.

[OwnerReturn]
method CreateGeometryBuffer ([Owner] IVertexBuffer vertices, [Owner] IIndexBuffer indices = null, [Owner] IVertexBuffer instances = null)
type IGeometryBuffer
params vertices [not-null] The vertex buffer that holds geometry data.
  indices The index buffer or null. Defaults to null.
  instances The vertex buffer that holds instance data or null. Defaults to null.
returns [not-null] The instance buffer.

See also:

SetGeometryBuffer

CreateIndexBuffer

Creates a dynamic IIndexBuffer object (i.e. CanSetIndices returns true).

[OwnerReturn]
method CreateIndexBuffer (int32 capacity)
type IIndexBuffer
params capacity [>0] The capacity of the index buffer, in vertex indices.
returns [not-null] The IIndexBuffer object.

Creates a static IIndexBuffer object (i.e. CanSetIndices returns false).

[OwnerReturn]
method CreateIndexBuffer (int32[] indices, int32 offset = 0, int32 count = 0)
type IIndexBuffer
params indices [not-null] The index buffer content.
  offset [>=0] Offset to first vertex index in indices. Defaults to 0.
  count [>=0] Total number of vertex indices. If 0, all remaining vertex indices will be used. Defaults to 0.
returns [not-null] The IIndexBuffer object.

CreateRenderTarget

Creates a new off-screen render target.

[OwnerReturn]
method CreateRenderTarget (int32 width, int32 height, RenderTargetFormat format)
type IRenderTarget
params width [>0] Width of render target, in pixels.
  height [>0] Height of render target, in pixels.
  format The render target format.
returns [not-null] The render target.

See also:

ValidateRenderTargetFormat
SetRenderTarget

CreateSwapChain

Creates a swap chain render target for the given window.

[OwnerReturn]
method CreateSwapChain (IApplicationWindow window)
type ISwapChain
params window [not-null] The target window.
returns [not-null] The render target for the created swap chain.

Remarks:

When the swap chain render target is created, the following format flags are used:

See also:

SetRenderTarget

CreateTextureCube

Creates a dynamic ITextureCube object (i.e. CanSetTexels returns true).

[OwnerReturn]
method CreateTextureCube (int32 size, TextureFormat format, int32 mipmaps = 1, bool srgb = true)
type ITextureCube
params size [>0] The texture size, in texels.
  format [not-null] The texture format (will be returned by Format).
  mipmaps [>=0] The number of mipmap levels (including the full-resolution level). If 0 the number of levels will be inferred from size. Defaults to 1.
  srgb The sRGB behaviour of the created texture (see IsSrgb). Defaults to true.
returns [not-null] The ITexture2D object.

See also:

ITextureFactory.ValidateTextureFormat

Exceptions:

CreateVertexBuffer

Creates a static IVertexBuffer object (i.e. CanLockBuffer returns false).

[OwnerReturn]
method CreateVertexBuffer (VertexElements format, ByteBuffer content)
type IVertexBuffer
params format [not-null] The vertex buffer format.
  content [not-null] The vertex buffer contents.

Remarks:

The capacity (see Capacity) of the returned vertex buffer is equal to floor(BS/VS), where BS is the buffer size (see Remaining) and VS is the vertex size (see Size).

Creates a dynamic IVertexBuffer object (i.e. CanLockBuffer returns true).

[OwnerReturn]
method CreateVertexBuffer (int32 capacity, VertexElements format)
type IVertexBuffer
params capacity [>0] The capacity of the vertex buffer, in vertices.
  format [not-null] The vertex format.
returns [not-null] The IVertexBuffer object.

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]
method Dispose ()
inherited IDisposable.Dispose

Remarks:

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

End

Ends the current access to this object.

method End ()
inherited 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

ReadPixels

Obtains a snapshot of the given render target.

method ReadPixels (int32 renderTargetIndex = 0)
type ColorBuffer
params renderTargetIndex [0..RenderTargetCount-1] The render target index.
returns The snapshot pixels or null if no render target is bound to the given index.

RegisterShaderEffects

Scans the given directory for shader effect files and registers them in this graphics context.

method RegisterShaderEffects (Path source, Path binary)
params source [not-null] The directory that holds shader effect source code files.
  binary [not-null] The directory that holds shader effect binary files.

Remarks:

Only the given directories are scanned for shader effect files. Subdirectories are not scanned.

Please refer to the documentation of the implementing class for details on which files are used to represent shader effect files.

The source and binary parameters may point to the same directory.

See also:

ShaderEffect

SetClip

Sets the clip rectangle on the current render target.

[BeginEnd]
method SetClip (Box2I value)
params value The clip rectangle.

SetGeometryBuffer

Sets the geometry buffers to use for drawing geometry.

[BeginEnd]
method SetGeometryBuffer (IGeometryBuffer geometryBuffer = null, int32 firstInstance = 0, int32 instanceCount = -1)
params geometryBuffer The geometry buffer to use or null to clear all buffer bindings. Defaults to null.
  firstInstance [>=0] Index of first instance to draw. Will be ignored if geometry is not instanced. Defaults to 0.
  instanceCount [>=-1] Total number of instances to draw. Set to -1 to draw all instances in geometryBuffer. Will be ignored if geometry is not instanced. Defaults to -1.

Remarks:

If Instances is not null, the cartesian product of the vertices and instances in geometryBuffer is used to draw instanced geometry: Each vertex in Vertices that is referenced by subsequent calls to IPrimitiveRenderer is duplicated instanceCount times; instance data from Instances is appended to the vertex data, which is then consumed by GPU shaders.

The firstInstance and instanceCount parameters choose the range of instances that will be used by subsequent calls to IPrimitiveRenderer. If Instances is null, these parameters are ignored.

SetRenderTarget

Sets the render target to use for subsequent draw calls.

[BeginEnd]
method SetRenderTarget (IRenderTarget renderTarget0 = null, IRenderTarget renderTarget1 = null, IRenderTarget renderTarget2 = null, IRenderTarget renderTarget3 = null, bool keepDepthStencil = false)
params renderTarget0 The render target to use at color index 0. Defaults to null.
  renderTarget1 The render target to use at color index 1. Defaults to null.
  renderTarget2 The render target to use at color index 2. Defaults to null.
  renderTarget3 The render target to use at color index 3. Defaults to null.
  keepDepthStencil Keep current depth/stencil buffer, in case that none of the given render targets has a depth/stencil buffer? Defaults to false.

Remarks:

Setting the render target will also reset the viewport (see SetViewport) and clip rectangle (see SetClip) to the render target size (see Size).

Setting all render targets to null will restore the previous render targets, i.e. the ones that have been set in the current Begin/End cycle by the before last call to SetRenderTarget with at least one non-null renderTarget* parameter.

Render target arguments with color indices greater than or equal to RenderTargetCount will be skipped silently.

The render targets are probed for a depth/stencil buffer, from color index 0 to 3. The first non-null buffer will be used. If none of the render targets has a buffer, depth/stencil buffer will be disabled, unless keepDepthStencil is true.

See also:

CreateRenderTarget
CreateSwapChain
RenderTargetCount

SetViewport

Sets the viewport rectangle on the current render target.

[BeginEnd]
method SetViewport (Box2I value)
params value The viewport rectangle.

ShaderEffect

Returns a shader effect by its name.

method ShaderEffect (string name)
type IShaderEffect
params name [not-empty] The shader effect name.
returns [not-null] The shader effect object.

Remarks:

The lookup scheme for shader source code or shader binaries is up to the implementing class.

See also:

ShaderEffectNames

Validate

Checks if this graphics context is still valid.

method Validate ()
type bool
returns true if the graphics context is valid, false if it has become invalid.

Remarks:

Once a graphics context has become invalid, it must be detached from the application and all graphics resources have to be re-created (e.g. via GraphicsContextDetach and GraphicsContextAttach).

ValidateRenderTargetFormat

Checks if the given render target format is supported by this graphics context.

method ValidateRenderTargetFormat (RenderTargetFormat format)
type bool
params format The render target format.
returns true if CreateRenderTarget will succeed, false if it will fail.

See also:

CreateRenderTarget

Extensions

AspectRatio

Returns the aspect ratio of the screen.

method AspectRatio ()
type float32
returns The aspect ratio (width divided by height).

LoadTextureCube

Loads an ITextureCube resource.

[OwnerReturn]
method LoadTextureCube (Path path)
type ITextureCube
params path [not-null] The file path.
returns The ITextureCube object.

SetGeometryBuffer

Sets the geometry buffers to use for drawing geometry.

method SetGeometryBuffer (IGeometryBuffer geometryBuffer, RangeI instances)
params geometryBuffer The geometry buffer to use or null.
  instances The range of instances to draw. Will be ignored if geometry is not instanced.

Remarks:

If Instances is not null, the cartesian product of the vertices and instances in geometryBuffer is used to draw instanced geometry: Each vertex in Vertices that is referenced by subsequent calls to IPrimitiveRenderer is duplicated Length times; instance data from Instances is appended to the vertex data, which is then consumed by GPU shaders.

The instances parameter chooses the range of instances that will be used by subsequent calls to IPrimitiveRenderer. If Instances is null, this parameter is ignored.

Tinman 3D SDK v1.0 | info@tinman3d.com | Copyright © 2012 - 2017 Matthias Englert, Fulda (Germany)