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

interface IGraphicsContext in Tinman.Engine.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:
      IGpuBuffer, IGeometryBuffer, IGraphicsFence, IGraphicsTimer, IRenderEffect, IRenderTarget, ITexture
    2. Call Validate. The method will return true if the graphics context is valid again.
    3. Recreate all resources.
  3. Call Begin:
    The GPU may still be busy with processing commands of the previous frame. To wait for the GPU to finish (for example when using NoOverwrite), use a IGraphicsFence.
  4. Use SetRenderTarget to perform rendering for each IRenderTarget resp. ISwapChain.
  5. Call End
  6. Call Present for each swap chain.
There are several types of GPU resources that can be created with a graphics context:

Attributes

BufferFactory

Returns the IBufferFactory for this graphics context.

property BufferFactory { get }
type IBufferFactory
value [not-null] The IBufferFactory object.

Cache

Returns the shared ResourceCache object for this graphics context.

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

See also:

ClearCache

DeviceInfo

Returns a human readable description of the underlying graphics device.

property DeviceInfo { get }
type string
value [not-null] The graphics device description name.

Graphics

Returns the shared Graphics object for this graphics context.

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

Remarks:

The bounds of the shared Graphics object are set automatically to the bounds of the current render target. If the graphics context is not active or if no render target has been set, the bounds of the Graphics object will be empty, i.e. the screen size will be zero (see ScreenSize).

See also:

IRenderable.Render
IRenderable2D.Render2D

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.

IsSoleOwnership

Will this object be disposed upon the next call to Dispose?

[ThreadSafe]
property IsSoleOwnership { get }
type bool
value true if the object will be disposed when Dispose is called,
false if the object will not be disposed, because some other code is still holding shared ownership (see AcquireThrow).
inherited IDisposable.IsSoleOwnership

LifecycleState

Returns the lifecycle state of this object.

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

MeshDispatcher

Returns the IMeshDispatcher for this graphics context.

property MeshDispatcher { get }
type IMeshDispatcher
value The IMeshDispatcher object or null iff this graphics context does not support mesh rendering work.

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] The number of render targets.

See also:

SetRenderTarget

ShaderRepository

Returns the path to the shader repository.

property ShaderRepository { get }
type Path
value [not-null] The shader repository path.

See also:

IGraphicsContextFactory.ShaderRepository

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.

Viewport

The pixel size of the current viewport that has been specified by the most recent call to SetViewport.

property Viewport { get }
type Vec2I
value The pixel size of the viewport.

WorkDispatcher

Returns the IWorkDispatcher for this graphics context.

property WorkDispatcher { get }
type IWorkDispatcher
value The IWorkDispatcher object or null iff this graphics context does not support general-purpose computational work.

Extensions

LoadTextureCube

Loads an ITextureCube resource.

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

Exceptions:

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.

SetRenderTarget

Sets the render target for subsequent draw calls.

[BeginEnd]
method SetRenderTarget (IRenderTarget renderTarget)
params renderTarget [not-null] The render target to set.

Remarks:

Setting the render target will also reset the viewport (see SetViewport) and clip rectangle (see SetClip) to the size of the given render target (see Size). The screen size of the shared Graphics object will be set accordingly, too.

The depth/stencil buffer of the given render target will be used.

See also:

CreateRenderTarget
CreateSwapChain
RenderTargetCount
SetRenderTargetBackup
SetRenderTargetRestore

SystemInfo

Collects textual information about this graphics context.

method SystemInfo (int32 columns = 100)
type string
params columns [>0] Maximum number of text column.
returns [not-null] The system information dump.

Methods

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
method AcquireBase ()
type IDisposable
returns The strong reference to this disposable object or null iff this object is no longer valid.
inherited IDisposable.AcquireBase

Remarks:

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

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

Using this method usually requires type casting. Subclasses may additionally implement IDisposableGeneric, in order to provide some syntactic sugar for that.

AcquireThrow

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
method AcquireThrow ()
type IDisposable
returns [not-null] The strong reference to this disposable object.
inherited IDisposable.AcquireThrow

Remarks:

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

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

Exceptions:

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

CanCreateRenderEffect

Checks if this IGraphicsContext is capable of creating an instance of IRenderEffectBase for the given render effect parameters.

[OwnerReturn]
method CanCreateRenderEffect (RenderEffectParameters parameters)
type bool
params parameters [not-null] The render effect parameters object.
returns false iff CreateRenderEffect returns null,
true otherwise.

CanCreateSwapChain

Checks if this IGraphicsContext is capable of creating an instance of ISwapChain for the given native window.

method CanCreateSwapChain (INativeWindow window)
type bool
params window [not-null] The native window.
returns true if CreateSwapChain will succeed and return a ISwapChain object,
false if it will fail.

ClearCache

Requests to clear the graphics resource cache.

method ClearCache ()

Remarks:

The graphics resource cache will be cleared upon the next call to End when there are no pending resource loading jobs (see IsLoading). Before clearing the cache, the method waits for the GPU to finish all pending work.

See also:

Cache

ClearRenderTarget

Clears pixels to the given values on the render targets that have been specified by the most recent call to SetRenderTarget.

[BeginEnd]
method ClearRenderTarget (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 ClearRenderTarget method should only be called after SetRenderTarget and before SetViewport.

CreateFence

Creates a new graphics fence object.

[OwnerReturn]
method CreateFence ()
type IGraphicsFence
returns [not-null] The graphics fence object.

Exceptions:

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.

Remarks:

Geometry buffers should be created once and then re-used over many frames. Creating new geometry buffers frequently can have significant impact on performance.

See also:

SetGeometryBuffer

Exceptions:

CreateRenderEffect

Creates an instance of IRenderEffectBase for the given render effect parameters.

[OwnerReturn]
method CreateRenderEffect (RenderEffectParameters parameters)
type IRenderEffectBase
params parameters [not-null] The render effect parameters object.
returns The IRenderEffectBase object or null if the given parameters object is not applicable to this factory.

Remarks:

The documentation of the concrete implementation class of parameters depicts the render effect interface that will be implemented by the returned object.

Exceptions:

CreateRenderTarget

Creates a new off-screen render target.

[OwnerReturn]
method CreateRenderTarget (int32 width, int32 height, RenderTargetFormat format, int64 color = 0, float32 depth = 1, int32 stencil = 0)
type IRenderTarget
params width [>0] Width of render target, in pixels.
  height [>0] Height of render target, in pixels.
  format The render target format.
  color The default color (see Colors) to clear to.
  depth The default depth value to clear to.
  stencil The default stencil value to clear to.
returns [not-null] The render target.

See also:

ValidateRenderTargetFormat
SetRenderTarget

Exceptions:

CreateSwapChain

Creates a swap chain render target for the given window.

[OwnerReturn]
method CreateSwapChain (INativeWindow 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

Exceptions:

CreateTextureCube

Creates an ITextureCube with Dynamic access.

[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:

CreateTimer

Creates a new graphics timer object.

[OwnerReturn]
method CreateTimer ()
type IGraphicsTimer
returns [not-null] The graphics timer object.

Exceptions:

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.

Implementing methods must not throw any exceptions.

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, bool alpha = true)
type ColorBuffer
params renderTargetIndex [0..RenderTargetCount-1] The render target index.
  alpha Read alpha channel?
returns The snapshot pixels or null if no render target is bound to the given index.

Exceptions:

RegisterRenderEffectFactory

Registers the given render effect factory.

method RegisterRenderEffectFactory (IRenderEffectFactory factory)
params factory [not-null] The render effect factory to register.

Exceptions:

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:

This method should be called to clear all geometry buffers bindings after all rendering work has been done.

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 targets for subsequent draw calls.

[BeginEnd]
method SetRenderTarget (RenderTargets renderTargets)
params renderTargets The render targets to set.

Remarks:

Setting the render targets will also reset the viewport (see SetViewport) and clip rectangle (see SetClip) to the size of the first render target (see Size). The screen size of the shared Graphics object will be set accordingly, too.

The depth/stencil buffer of the first render target will be used.

The calling code is responsible for handling the required calls the Finish method for each used render target.

See also:

CreateRenderTarget
CreateSwapChain
RenderTargetCount
SetRenderTargetBackup
SetRenderTargetRestore

SetRenderTargetBackup

Backs up the current render targets and the current depth/stencil buffer.

[BeginEnd]
method SetRenderTargetBackup ()

Remarks:

Calls to SetRenderTargetBackup and SetRenderTargetRestore must be balanced and may be nested.

See also:

SetRenderTargetRestore

SetRenderTargetRestore

Restores the backed-up render targets and the depth/stencil buffer.

[BeginEnd]
method SetRenderTargetRestore ()

Remarks:

Calls to SetRenderTargetBackup and SetRenderTargetRestore must be balanced and may be nested.

See also:

SetRenderTargetBackup

SetViewport

Sets the viewport rectangle on the current render target.

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

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
Tinman 3D SDK v1.0 | info@tinman3d.com | Copyright © 2012 - 2022 Matthias Englert, Fulda (Germany)