IGraphicsContext

Description

interface Tinman.Engine.Rendering.IGraphicsContext

Derived from

IBeginEnd
INativeHandle

Extended by

GraphicsContext abstract

Base interface for classes that provide a graphics context.

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 IBeginEnd.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 GpuUpdateFlag.NoOverwrite), use a IGraphicsFence.

  4. Use SetRenderTarget to perform rendering for each IRenderTarget resp. ISwapChain.

  5. Call IBeginEnd.End

  6. Call ISwapChain.Present for each swap chain.

There are several types of GPU resources that can be created with a graphics context:

Public / Methods

CanCreateRenderEffect


[OwnerReturn]
public method CanCreateRenderEffect → (1)

parameters in : RenderEffectParameters

[not-null]
The render effect parameters object.

returns → bool

false iff CreateRenderEffect returns null,
true otherwise.

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

CanCreateSwapChain


public method CanCreateSwapChain → (1)

window in : INativeWindow

[not-null]
The native window.

returns → bool

true if CreateSwapChain will succeed and return a ISwapChain object,
false if it will fail.

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

ClearCache


public method ClearCache → ()

Requests to clear the graphics resource cache.

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

ClearRenderTarget


[BeginEnd]
public method ClearRenderTarget → (4)

flags in : RenderTargetClearFlags

Flags that depict the buffers to clear.

color opt : int64 = 0

The color (see Colors) to clear to.

depth opt : float32 = 1

The depth value to clear to.

stencil opt : int32 = 0

The stencil value to clear to.

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

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


[OwnerReturn]
public method CreateFence → ()

returns → IGraphicsFence

The graphics fence object.

Creates a new graphics fence object.

RenderException

If a graphics subsystem error has occurred.

CreateGeometryBuffer


[OwnerReturn]
public method CreateGeometryBuffer → (3)

vertices in : IVertexBuffer

[not-null]
The vertex buffer that holds geometry data.

indices opt : IIndexBuffer = null

The index buffer or null.

instances opt : IVertexBuffer = null

The vertex buffer that holds instance data or null.

returns → IGeometryBuffer

The instance buffer.

Creates a buffer for drawing geometry.

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

RenderException

If a graphics subsystem error has occurred.

CreateRenderEffect


[OwnerReturn]
public method CreateRenderEffect → (1)

parameters in : RenderEffectParameters

[not-null]
The render effect parameters object.

returns → IRenderEffectBase

The IRenderEffectBase object or null if the given parameters in object is not applicable to this factory.

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

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

RenderException

If a graphics subsystem error has occurred.

CreateRenderTarget


[OwnerReturn]
public method CreateRenderTarget → (6)

width in : int32

[>0]
Width of render target, in pixels.

height in : int32

[>0]
Height of render target, in pixels.

format in : RenderTargetFormat

The render target format.

color opt : int64 = 0

The default color (see Colors) to clear to.

depth opt : float32 = 1

The default depth value to clear to.

stencil opt : int32 = 0

The default stencil value to clear to.

returns → IRenderTarget

The render target.

Creates a new off-screen render target.

RenderException

If a graphics subsystem error has occurred.

CreateSwapChain


[OwnerReturn]
public method CreateSwapChain → (1)

window in : INativeWindow

[not-null]
The target window.

returns → ISwapChain

The render target for the created swap chain.

Creates a swap chain render target for the given window.

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

RenderException

If a graphics subsystem error has occurred.

CreateTextureCube


[OwnerReturn]
public method CreateTextureCube → (4)

size in : int32

[>0]
The texture size, in texels.

format in : TextureFormat

[not-null]
The texture format (will be returned by ITexture.Format).

mipmaps opt : int32 = 1

[>=0]
The number of mipmap levels (including the full-resolution level). If 0 the number of levels will be inferred from size in.

srgb opt : bool = true

The sRGB behaviour of the created texture (see ITexture.IsSrgb).

returns → ITextureCube

The ITexture2D object.

RenderException

If a graphics subsystem error has occurred.

CreateTimer


[OwnerReturn]
public method CreateTimer → ()

returns → IGraphicsTimer

The graphics timer object.

Creates a new graphics timer object.

RenderException

If a graphics subsystem error has occurred.

ReadPixels


public method ReadPixels → (2)

renderTargetIndex opt : int32 = 0

[0..IGraphicsContext.RenderTargetCount-1]
The render target index.

alpha opt : bool = true

Read alpha channel?

returns → ColorBuffer

The snapshot pixels or null if no render target is bound to the given index.

Obtains a snapshot of the given render target.

RenderException

If a graphics subsystem error has occurred.

RegisterRenderEffectFactory


public method RegisterRenderEffectFactory → (1)

factory in : IRenderEffectFactory

[not-null]
The render effect factory to register.

Registers the given render effect factory.

RenderException

If a graphics subsystem error has occurred.

SetClip


[BeginEnd]
public method SetClip → (1)

value in : Box2I

The clip rectangle.

Sets the clip rectangle on the current render target.

SetGeometryBuffer


[BeginEnd]
public method SetGeometryBuffer → (3)

geometryBuffer opt : IGeometryBuffer = null

The geometry buffer to use or null to clear all buffer bindings.

firstInstance opt : int32 = 0

[>=0]
Index of first instance to draw. Will be ignored if geometry is not instanced.

instanceCount opt : int32 = -1

[>=-1]
Total number of instances to draw. Set to -1 to draw all instances in geometryBuffer opt. Will be ignored if geometry is not instanced. Defaults to -1.

Sets the geometry buffers to use for drawing geometry.

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

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

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

SetRenderTarget


[BeginEnd]
public method SetRenderTarget → (1)

renderTargets in : RenderTargets

The render targets to set.

Sets the render targets for subsequent draw calls.

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 IRenderTarget.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 IRenderTarget.Finish method for each used render target.

SetRenderTargetBackup


[BeginEnd]
public method SetRenderTargetBackup → ()

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

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

SetRenderTargetRestore


[BeginEnd]
public method SetRenderTargetRestore → ()

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

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

SetViewport


[BeginEnd]
public method SetViewport → (1)

value in : Box2I

The viewport rectangle.

Sets the viewport rectangle on the current render target.

Validate


public method Validate → ()

returns → bool

true if the graphics context is valid, false if it has become invalid.

Checks if this graphics context is still valid.

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 IApplication.GraphicsContextDetach and IApplication.GraphicsContextAttach).

ValidateRenderTargetFormat


public method ValidateRenderTargetFormat → (1)

format in : RenderTargetFormat

The render target format.

returns → bool

true if CreateRenderTarget will succeed, false if it will fail.

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

Public / Attributes

BufferFactory


public attribute BufferFactory → (get)

value : IBufferFactory

[not-null]
The IBufferFactory object.

Returns the IBufferFactory for this graphics context.

Cache


public attribute Cache → (get)

value : ResourceCache

[not-null]
The shared resource cache. Will be the same object as Graphics.Cache of Graphics.

Returns the shared ResourceCache object for this graphics context.

DeviceInfo


public attribute DeviceInfo → (get)

value : string

[not-null]
The graphics device description name.

Returns a human readable description of the underlying graphics device.

Graphics


[OwnerReturn]
public attribute Graphics → (get)

value : Graphics

[not-null]
The shared graphics object.

Returns the shared Graphics object for this graphics context.

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 Graphics.ScreenSize).

IsNearAtZero


public attribute IsNearAtZero → (get)

value : bool

The mapping behaviour for the near-clipping plane.

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

MeshDispatcher


public attribute MeshDispatcher → (get)

value : IMeshDispatcher

The IMeshDispatcher object or null iff this graphics context does not support mesh rendering work.

Returns the IMeshDispatcher for this graphics context.

Name


public attribute Name → (get)

value : string

[not-empty]
The graphics context name.

Human readable name of this graphics context.

PrimitiveRenderer


public attribute PrimitiveRenderer → (get)

value : IPrimitiveRenderer

[not-null]
The IPrimitiveRenderer object.

Returns the IPrimitiveRenderer for this graphics context.

RenderTargetCount


public attribute RenderTargetCount → (get)

value : int32

[>=1]
The number of render targets.

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

ShaderRepository


public attribute ShaderRepository → (get)

value : Path

[not-null]
The shader repository path.

Returns the path to the shader repository.

Size


public attribute Size → (get)

value : Vec2I

The render target size, in pixels.

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

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

TextureFactory


public attribute TextureFactory → (get)

value : ITextureFactory

[not-null]
The ITextureFactory object.

Returns the ITextureFactory for this graphics context.

Viewport


public attribute Viewport → (get)

value : Vec2I

The pixel size of the viewport.

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

WorkDispatcher


public attribute WorkDispatcher → (get)

value : IWorkDispatcher

The IWorkDispatcher object or null iff this graphics context does not support general-purpose computational work.

Returns the IWorkDispatcher for this graphics context.

Extensions

LoadTextureCube


[OwnerReturn]
public static method LoadTextureCube → (1)

path in : Path

[not-null]
The file path.

returns → ITextureCube

The ITextureCube object.

Loads an ITextureCube resource.

RenderException

If a graphics subsystem error has occurred.

IOException

If an I/O error has occurred.

ValidatingException

If the image reader has reported an error, for example because of an unsupported file format feature.

SetGeometryBuffer


public static method SetGeometryBuffer → (2)

geometryBuffer in : IGeometryBuffer

The geometry buffer to use or null.

instances in : RangeI

The range of instances to draw. Will be ignored if geometry is not instanced.

Sets the geometry buffers to use for drawing geometry.

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

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

SetRenderTarget


[BeginEnd]
public static method SetRenderTarget → (1)

renderTarget in : IRenderTarget

[not-null]
The render target to set.

Sets the render target for subsequent draw calls.

Setting the render target will also reset the viewport (see IGraphicsContext.SetViewport) and clip rectangle (see IGraphicsContext.SetClip) to the size of the given render target (see IRenderTarget.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.

SystemInfo


public static method SystemInfo → (1)

columns opt : int32 = 100

[>0]
Maximum number of text column.

returns → string

The system information dump.

Collects textual information about this graphics context.