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

Can​Create​Render​Effect


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.

Can​Create​Swap​Chain


public method CanCreateSwapChain → (1)

window in : INativeWindow

[not-null]
The native window.

returns → bool

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

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

Clear​Cache


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.

Clear​Render​Target


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

Create​Fence


[OwnerReturn]
public method CreateFence → ()

returns → IGraphicsFence

The graphics fence object.

Creates a new graphics fence object.

RenderException

If a graphics subsystem error has occurred.

Create​Geometry​Buffer


[OwnerReturn]
public method CreateGeometryBuffer → (3)

vertices in : IVertexBuffer own

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

indices opt : IIndexBuffer own = null

The index buffer or null.

instances opt : IVertexBuffer own = 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 infrequently 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.

Create​Render​Effect


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

Create​Render​Target


[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 clear color (see Colors).

depth opt : float32 = 1

The default clear depth value.

stencil opt : int32 = 0

The default clear stencil value.

returns → IRenderTarget

The render target.

Creates a new off-screen render target.

A render target may have a color buffer (see IRenderTarget.HasColor), a depth buffer (see IRenderTarget.HasDepth) or both. The content of a newly created render target is undefined. The color opt, depth opt and stencil opt parameters give a hint regarding the default values that will be used for clearing the render target with ClearRenderTarget. Some graphics APIs provide high-performance clears when the default values are used.

RenderException

If a graphics subsystem error has occurred.

Create​Swap​Chain


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

The content of a newly created swap chain is undefined, its default clear color is transparent black and its depth/stencil value is zero.

RenderException

If a graphics subsystem error has occurred.

Create​Texture​Cube


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

Create​Timer


[OwnerReturn]
public method CreateTimer → ()

returns → IGraphicsTimer

The graphics timer object.

Creates a new graphics timer object.

RenderException

If a graphics subsystem error has occurred.

Get​Render​Target


public method GetRenderTarget → ()

returns → RenderTargets

The current render target set.

Returns the current set of render targets.

The returned RenderTargets value represents the most recent value that has been passed to SetRenderTarget and will not capture the render targets that have been specified by external code.

Read​Pixels


[BeginEnd]
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.

Register​Render​Effect​Factory


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.

Set​Clip


[BeginEnd]
public method SetClip → (1)

value in : Box2I

The clip rectangle.

Sets the clip rectangle on the current render target.

Set​Geometry​Buffer


[BeginEnd]
public method SetGeometryBuffer → (3)

geometryBuffer opt : IGeometryBuffer = null

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

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.

firstInstance opt : int32 = 0

[>=0]
Index of first instance to draw. Will be ignored if geometry is not instanced. If IPrimitiveRenderer.CanUseZeroInstance is false, this index must be zero, otherwise no primitives will be drawn.

Sets the geometry buffers to use for drawing geometry.

This method should be called with default arguments to clear the geometry buffer bindings, after the rendering work has been submitted. Not doing so can potentially lead to incompatible combinations of active render effect pass (see IRenderEffectBase.Pass) and current geometry buffer. Although this is not an error, it might produce warning log messages for some APIs.

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.

Set​Render​Target


[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 bounds of the render target set (see RenderTargets.Size). The screen bounds of the shared Graphics object will also be set, by calling Graphics.Fullscreen.

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

Set​Render​Target​Backup


[BeginEnd]
public method SetRenderTargetBackup → ()

Backs up the current render target set (see GetRenderTarget), the current viewport (see Viewport), the current clip rectangle (see Clip) and the bounds of the shared Graphics object (see Graphics.Bounds).

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

Set​Render​Target​Restore


[BeginEnd]
public method SetRenderTargetRestore → ()

Restores the backed-up render target set, viewport, clip rectangle and graphics bounds.

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

Set​Viewport


[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).

Validate​Render​Target​Format


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.

Implementations usually need to perform render API calls in order to determine render target format support, which may include creation of dummy resources. However, implementations will cache validation results for each format in value, to avoid unnecessary work at runtime.

Wait


public method Wait → ()

returns → bool

true if the GPU has finished all submitted work,
false if the GPU is still busy.

Waits up to 250 ms for the GPU to finish its work.

This method is not intended to be used for synchronizing with the GPU during real-time rendering, for which IGraphicsFence objects should be used. Instead, this method is a helper for trivial cases, for example waiting for the GPU to finish before taking a screenshot.

Public / Attributes

Buffer​Factory


[Constant]
public attribute BufferFactory → (get)

value : IBufferFactory

[not-null]
The IBufferFactory object.

Returns the IBufferFactory for this graphics context.

Cache


[Constant]
public attribute Cache → (get)

value : ResourceCache

The shared resource cache or null iff Graphics is null. Will be the same object as Graphics.Cache of Graphics.

Returns the shared ResourceCache object for this graphics context.

Clip


public attribute Clip → (get)

value : Box2I

The pixel bounds of the clip rectangle.

The pixel bounds of the current clip rectangle that has been specified by the most recent call to SetClip.

Device​Info


[Constant]
public attribute DeviceInfo → (get)

value : string

[not-null]
The graphics device description name.

Returns a human readable description of the underlying graphics device.

Graphics


[Constant] [OwnerReturn]
public attribute Graphics → (get)

value : Graphics

The shared graphics object or null iff ShaderRepository is Path.Unknown.

Returns the shared Graphics object for this graphics context.

The returned Graphics may only be used between calls to IBeginEnd.Begin and IBeginEnd.End of IGraphicsContext, which surround the separate calls to IBeginEnd.Begin and IBeginEnd.End of Graphics.

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

Is​Cubemap​Seamless


[Constant]
public attribute IsCubemapSeamless → (get)

value : bool

true if seamless cubemap filtering is supported,
false if cubemap filtering is not seamless.

Is seamless filtering across cubemap faces performed for ITextureCube objects?

Is​Multi​Sample


[Constant]
public attribute IsMultiSample → (get)

value : bool

true if this graphics context uses multi-sampling,
false if not.

Does this graphics context use multi-sampling?

Is​Near​At​Zero


[Constant]
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)?

Mesh​Dispatcher


[Constant]
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.

The methods of IMeshDispatcher may only be used within calls to IBeginEnd.Begin and IBeginEnd.End.

Name


[Constant]
public attribute Name → (get)

value : string

[not-empty]
The graphics context name.

Human readable name of this graphics context.

Primitive​Renderer


[Constant]
public attribute PrimitiveRenderer → (get)

value : IPrimitiveRenderer

[not-null]
The IPrimitiveRenderer object.

Returns the IPrimitiveRenderer for this graphics context.

The methods of IPrimitiveRenderer may only be used within calls to IBeginEnd.Begin and IBeginEnd.End.

Render​Target​Count


[Constant]
public attribute RenderTargetCount → (get)

value : int32

[1..8]
The number of color render targets.

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

The optional depth/stencil render target may always be used during rendering and is not included in this count.

Shader​Repository


[Constant]
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.

Texture​Factory


[Constant]
public attribute TextureFactory → (get)

value : ITextureFactory

[not-null]
The ITextureFactory object.

Returns the ITextureFactory for this graphics context.

Viewport


public attribute Viewport → (get)

value : Box2I

The pixel bounds of the viewport rectangle.

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

Work​Dispatcher


[Constant]
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.

The methods of IWorkDispatcher may only be used within calls to IBeginEnd.Begin and IBeginEnd.End.

Extensions

Create​Render​Target


[OwnerReturn]
public static method CreateRenderTarget → (5)

size in : Vec2I

Size 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.

A render target may have a color buffer (see IRenderTarget.HasColor), a depth buffer (see IRenderTarget.HasDepth) or both.

RenderException

If a graphics subsystem error has occurred.

Load​Texture​Cube


[OwnerReturn]
public static method LoadTextureCube → (1)

path in : Path

[not-null]
The file path.

returns → ITextureCube

The ITextureCube object.

Loads a 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.

Set​Geometry​Buffer


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. If IPrimitiveRenderer.CanUseZeroInstance is false, RangeI.Start must be zero, otherwise no primitives will be drawn.

Sets the geometry buffers to use for drawing geometry.

This method should be called with default arguments to clear the geometry buffer bindings, after the rendering work has been submitted. Not doing so can potentially lead to incompatible combinations of active render effect pass (see IRenderEffectBase.Pass) and current geometry buffer. Although this is not an error, it might produce warning log messages for some APIs.

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.

Set​Render​Target


[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 color and/or depth buffer of the given render target will be used.

System​Info


public static method SystemInfo → (1)

columns opt : int32 = 100

[>0]
Maximum number of text columns.

returns → string

The system information dump.

Collects textual information about this graphics context.