Abstract base class for IGraphicsContext implementations.
abstract class
|
GraphicsContext
|
implements
|
IGraphicsContext
|
||
extends
|
Initializable
|
||||
base of
|
DirectXContext
|
These protected fields must be initialized by subclasses in the constructor:
Returns the shared ResourceCache object for this graphics context.
public
property
|
Cache
{
get
}
|
||
type
|
ResourceCache
|
||
value
|
|
The shared resource cache. | |
implements
|
IGraphicsContext.Cache
|
The GPU time that has been spent for the last frame.
public
property
|
FrameTime
{
get
}
|
||
type
|
float32
|
||
value
|
|
The spent time, in milliseconds. | |
implements
|
IGraphicsContext.FrameTime
|
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.
Returns the shared Graphics object for this graphics context.
[OwnerReturn]
|
||||
public
property
|
Graphics
{
get
}
|
|||
type
|
Graphics
|
|||
value
|
|
The shared graphics object. | ||
implements
|
IGraphicsContext.Graphics
|
Is
the
near-clipping
plane
mapped
to
0
in
clip-space
(true
),
or
is
it
mapped
to
-1
(false
)?
public
property
|
IsNearAtZero
{
get
}
|
||
type
|
bool
|
||
value
|
The mapping behaviour for the near-clipping plane. | ||
implements
|
IGraphicsContext.IsNearAtZero
|
Returns the lifecycle state of this object.
public
override
property
|
LifecycleState
{
get
}
|
||
type
|
LifecycleState
|
||
value
|
The lifecycle state. | ||
inherited
|
Initializable.LifecycleState
|
Human readable name of this graphics context.
public
property
|
Name
{
get
}
|
||
type
|
string
|
||
value
|
|
The graphics context name. | |
implements
|
IGraphicsContext.Name
|
Returns the raw handle value of the native resource that is contained in this object.
public
abstract
property
|
NativeHandle
{
get
}
|
||
type
|
IntPtr
|
||
value
|
The raw handle value. | ||
implements
|
INativeHandle.NativeHandle
|
Remarks:
The documentation of the implementing class will contain information on how to interpret the raw handle value.
Returns the IPrimitiveRenderer for this graphics context.
public
abstract
property
|
PrimitiveRenderer
{
get
}
|
||
type
|
IPrimitiveRenderer
|
||
value
|
|
The IPrimitiveRenderer object. | |
implements
|
IGraphicsContext.PrimitiveRenderer
|
The number of render targets that can be used simultaneously during rendering.
public
property
|
RenderTargetCount
{
get
}
|
||
type
|
int32
|
||
value
|
|
The number of render targets. | |
implements
|
IGraphicsContext.RenderTargetCount
|
See also:
IGraphicsContext.SetRenderTargetReturns the names of all shader effects.
public
property
|
ShaderEffectNames
{
get
}
|
||
type
|
string[]
|
||
value
|
|
The list of shader effect names. | |
implements
|
IGraphicsContext.ShaderEffectNames
|
See also:
IGraphicsContext.ShaderEffectThe pixel size of the render targets that have been specified by the most recent call to SetRenderTarget.
public
property
|
Size
{
get
}
|
||
type
|
Vec2I
|
||
value
|
The render target size, in pixels. | ||
implements
|
IGraphicsContext.Size
|
Remarks:
If
no
render
target
is
bound
to
index
0
,
Zero
is
returned.
Returns the ITextureFactory for this graphics context.
public
abstract
property
|
TextureFactory
{
get
}
|
||
type
|
ITextureFactory
|
||
value
|
|
The ITextureFactory object. | |
implements
|
IGraphicsContext.TextureFactory
|
Acquires a strong reference to this disposable object.
[OwnerReturn, ThreadSafe]
|
||||
public
method
|
AcquireTry
()
|
|||
type
|
IDisposable
|
|||
returns
|
this
if
a
new
strong
reference
has
been
acquired,
null
if
this
object
is
already
being
disposed.
|
|||
inherited
|
Disposable.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.
Begins an access to this object.
public
virtual
method
|
Begin
()
|
||
implements
|
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:
BeginEndClears pixels to the given values on the render targets that have been specified by the most recent call to SetRenderTarget.
[BeginEnd]
|
||||
public
abstract
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. | |||
implements
|
IGraphicsContext.Clear
|
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.
Creates a buffer for drawing geometry.
[OwnerReturn]
|
||||
public
abstract
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
|
|
The instance buffer. | ||
implements
|
IGraphicsContext.CreateGeometryBuffer
|
See also:
IGraphicsContext.SetGeometryBufferCreates
a
dynamic
IIndexBuffer
object
(i.e.
CanSetIndices
returns
true
).
[OwnerReturn]
|
||||
public
abstract
method
|
CreateIndexBuffer
(int32 capacity)
|
|||
type
|
IIndexBuffer
|
|||
params
|
capacity
|
[>0]
|
The capacity of the index buffer, in vertex indices. | |
returns
|
|
The IIndexBuffer object. | ||
implements
|
IGraphicsContext.CreateIndexBuffer
|
Creates
a
static
IIndexBuffer
object
(i.e.
CanSetIndices
returns
false
).
[OwnerReturn]
|
||||
public
abstract
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
|
|
The IIndexBuffer object. | ||
implements
|
IGraphicsContext.CreateIndexBuffer
|
Creates a new off-screen render target.
[OwnerReturn]
|
||||
public
abstract
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
|
|
The render target. | ||
implements
|
IGraphicsContext.CreateRenderTarget
|
See also:
IGraphicsContext.ValidateRenderTargetFormatCreates a swap chain render target for the given window.
[OwnerReturn]
|
||||
public
abstract
method
|
CreateSwapChain
(IApplicationWindow window)
|
|||
type
|
ISwapChain
|
|||
params
|
window
|
[not-null]
|
The target window. | |
returns
|
|
The render target for the created swap chain. | ||
implements
|
IGraphicsContext.CreateSwapChain
|
Remarks:
When the swap chain render target is created, the following format flags are used:
See also:
IGraphicsContext.SetRenderTargetCreates
a
dynamic
ITextureCube
object
(i.e.
CanSetTexels
returns
true
).
[OwnerReturn]
|
||||
public
abstract
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
|
|
The ITexture2D object. | ||
implements
|
IGraphicsContext.CreateTextureCube
|
See also:
ITextureFactory.ValidateTextureFormatExceptions:
Creates
a
static
IVertexBuffer
object
(i.e.
CanLockBuffer
returns
false
).
[OwnerReturn]
|
||||
public
abstract
method
|
CreateVertexBuffer
(VertexElements format,
ByteBuffer content)
|
|||
type
|
IVertexBuffer
|
|||
params
|
format
|
[not-null]
|
The vertex buffer format. | |
content
|
[not-null]
|
The vertex buffer contents. | ||
implements
|
IGraphicsContext.CreateVertexBuffer
|
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]
|
||||
public
abstract
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
|
|
The IVertexBuffer object. | ||
implements
|
IGraphicsContext.CreateVertexBuffer
|
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]
|
||||
public
method
|
Dispose
()
|
|||
inherited
|
Disposable.Dispose
|
Remarks:
The Dispose method silently returns if the object has already been disposed.
Ends the current access to this object.
public
virtual
method
|
End
()
|
||
implements
|
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:
BeginEndInitializes the object, if necessary
public
method
|
Initialize
()
|
||
inherited
|
Initializable.Initialize
|
Remarks:
The Initialize method returns silently if the object is already in the state Initialized.
Obtains a snapshot of the given render target.
public
abstract
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.
|
||
implements
|
IGraphicsContext.ReadPixels
|
Scans the given directory for shader effect files and registers them in this graphics context.
public
abstract
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. | |
implements
|
IGraphicsContext.RegisterShaderEffects
|
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:
IGraphicsContext.ShaderEffectSets the clip rectangle on the current render target.
[BeginEnd]
|
||||
public
abstract
method
|
SetClip
(Box2I value)
|
|||
params
|
value
|
The clip rectangle. | ||
implements
|
IGraphicsContext.SetClip
|
Sets the geometry buffers to use for drawing geometry.
[BeginEnd]
|
||||
public
abstract
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 .
|
||
implements
|
IGraphicsContext.SetGeometryBuffer
|
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.
Sets the render target to use for subsequent draw calls.
[BeginEnd]
|
||||
public
virtual
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 .
|
|||
implements
|
IGraphicsContext.SetRenderTarget
|
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:
IGraphicsContext.CreateRenderTargetSets the viewport rectangle on the current render target.
[BeginEnd]
|
||||
public
abstract
method
|
SetViewport
(Box2I value)
|
|||
params
|
value
|
The viewport rectangle. | ||
implements
|
IGraphicsContext.SetViewport
|
Returns a shader effect by its name.
public
method
|
ShaderEffect
(string name)
|
||
type
|
IShaderEffect
|
||
params
|
name
|
[not-empty]
|
The shader effect name. |
returns
|
|
The shader effect object. | |
implements
|
IGraphicsContext.ShaderEffect
|
Remarks:
The lookup scheme for shader source code or shader binaries is up to the implementing class.
See also:
IGraphicsContext.ShaderEffectNamesChecks if this graphics context is still valid.
public
abstract
method
|
Validate
()
|
||
type
|
bool
|
||
returns
|
true
if
the
graphics
context
is
valid,
false
if
it
has
become
invalid.
|
||
implements
|
IGraphicsContext.Validate
|
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).
Checks if the given render target format is supported by this graphics context.
public
abstract
method
|
ValidateRenderTargetFormat
(RenderTargetFormat format)
|
||
type
|
bool
|
||
params
|
format
|
The render target format. | |
returns
|
true
if
CreateRenderTarget
will
succeed,
false
if
it
will
fail.
|
||
implements
|
IGraphicsContext.ValidateRenderTargetFormat
|
See also:
IGraphicsContext.CreateRenderTargetThe maximum number of simultaneous render targets, in the range [1..4].
protected
field
|
renderTargetCount
|
||
type
|
int32
|
Remarks:
This field must be initialized by subclasses during construction.
Creates a new instance of GraphicsContext.
protected
constructor
|
GraphicsContext
(string name,
bool isNearAtZero)
|
||
params
|
name
|
[not-empty]
|
The graphics context name (see Name). |
isNearAtZero
|
The value for IsNearAtZero. |
protected
method
|
AssertBegun
(string source)
|
||
params
|
source
|
Computes the estimated memory consumption of a render target.
[Pure]
|
||||
protected
static
method
|
ComputeRenderTargetMemoryConsumption
(int32 width,
int32 height,
RenderTargetFormat format)
|
|||
type
|
int32
|
|||
params
|
width
|
[>0]
|
Width of render target, in pixels. | |
height
|
[>0]
|
Height of render target, in pixels. | ||
format
|
The render target format. | |||
returns
|
|
The estimated memory consumption. |
Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.
protected
override
method
|
DisposeManaged
()
|
||
overrides
|
Disposable.DisposeManaged
|
Remarks:
This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.
Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.
The DisposeManaged method is called before the DisposeUnmanaged method.
Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.
protected
virtual
method
|
DisposeUnmanaged
()
|
||
inherited
|
Disposable.DisposeUnmanaged
|
Remarks:
Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.
The DisposeUnmanaged method is called after the DisposeManaged method.
Performs initialization.
protected
override
method
|
DoInitialize
()
|
||
overrides
|
Initializable.DoInitialize
|
Remarks:
Overriding methods must call the DoInitialize method of their base class. The base call should be the first statement.
This method is called when this object has been initialized completely, i.e. after the DoInitialize call and just before returning from Initialize.
[EmptyBody]
|
||||
protected
virtual
method
|
Initialized
()
|
|||
inherited
|
Initializable.Initialized
|
Register a new shader effect.
protected
method
|
RegisterShaderEffect
([Owner]
IShaderEffect effect)
|
||
params
|
effect
|
[not-null]
|
The effect. |
Remarks:
This method should only be called from within RegisterShaderEffects.
Performs a GPU query for the frametime in milliseconds.
protected
abstract
method
|
TimestampQuery
(int32 command)
|
||
type
|
float32
|
||
params
|
command
|
The
query
command
to
perform:
0 :
begin
new
query.
1 :
end
running
query.
2 :
poll
query
result.
|
|
returns
|
<
0 :
failure
>=
0 :
success.
|
Cancels the pending GPU queries by calling TimestampQuery as necessary.
protected
method
|
TimestampQueryCancel
()
|
Remarks:
This method should be called by subclassed during disposal.
The logger object of this class.
public
static
readonly
field
|
Logger
|
||
type
|
ILogger
|