IGraphicsContext
Description
- Derived from
- Extended by
-
GraphicsContext abstract
Base interface for classes that provide a graphics context.
Rendering with a graphics context is performed as follows:
-
Call Validate:
-
true
: The graphics context is valid, continue with 3. -
false
: The graphics context has become invalid, continue with 2.
-
-
Reset the graphics context:
-
Dispose all resources:
IGpuBuffer, IGeometryBuffer, IGraphicsFence, IGraphicsTimer, IRenderEffect, IRenderTarget, ITexture -
Call Validate. The method will return
true
if the graphics context is valid again. -
Recreate all resources.
-
-
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. -
Use SetRenderTarget to perform rendering for each IRenderTarget resp. ISwapChain.
-
Call IBeginEnd.End
-
Call ISwapChain.Present for each swap chain.
There are several types of GPU resources that can be created with a graphics context:
-
Resources with IResource.AccessPattern = ResourceAccessPattern.Static, created by:
ITextureFactory.CreateTexture2DStatic
IBufferFactory.CreateIndexBufferStatic
IBufferFactory.CreateStructuredBufferStatic
IBufferFactory.CreateVertexBufferStatic -
Resources with IResource.AccessPattern = ResourceAccessPattern.Dynamic, created by:
ITextureFactory.CreateTexture2D
CreateTextureCube
IBufferFactory.CreateIndexBuffer
IBufferFactory.CreateStructuredBuffer
IBufferFactory.CreateVertexBuffer -
Resources with IResource.AccessPattern = ResourceAccessPattern.Mappable, created by:
ITextureFactory.CreateTexture2D
IBufferFactory.CreateIndexBuffer
IBufferFactory.CreateStructuredBuffer
IBufferFactory.CreateVertexBuffer
Public / Methods
CanCreateRenderEffect
Checks if this IGraphicsContext is capable of creating an instance of IRenderEffectBase for the given render effect parameters.
CanCreateSwapChain
Checks if this IGraphicsContext is capable of creating an instance of ISwapChain for the given native window.
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.
- See also
ClearRenderTarget
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
Creates a new graphics fence object.
- RenderException
-
If a graphics subsystem error has occurred.
CreateGeometryBuffer
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.
- See also
CreateRenderEffect
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
Creates a new off-screen render target.
- RenderException
-
If a graphics subsystem error has occurred.
CreateSwapChain
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.
- See also
CreateTextureCube
Creates an ITextureCube with ResourceAccessPattern.Dynamic access.
- RenderException
-
If a graphics subsystem error has occurred.
CreateTimer
Creates a new graphics timer object.
- RenderException
-
If a graphics subsystem error has occurred.
ReadPixels
Obtains a snapshot of the given render target.
- RenderException
-
If a graphics subsystem error has occurred.
RegisterRenderEffectFactory
Registers the given render effect factory.
- RenderException
-
If a graphics subsystem error has occurred.
SetGeometryBuffer
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
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
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
Restores the backed-up render targets and the depth/stencil buffer.
Calls to SetRenderTargetBackup and SetRenderTargetRestore must be balanced and may be nested.
Validate
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).
Public / Attributes
Graphics
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).
- See also
IsNearAtZero
Is the near-clipping plane mapped to 0
in clip-space (true
), or is it mapped to -1
(false
)?
RenderTargetCount
The number of render targets that can be used simultaneously during rendering.
- See also
Size
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.
Viewport
The pixel size of the current viewport that has been specified by the most recent call to SetViewport.
Extensions
LoadTextureCube
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
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
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.