class DirectXContext in Tinman.AddOns.DirectX

Abstract base class for implementations of the IGraphicsContext interface that make use of DirectX.

abstract class	DirectXContext	extends	GraphicsContext
		base of	DirectX11Context
			DirectX9Context

Remarks

When using the RegisterShaderEffects method, the following files are used:

• 'ShaderEffectName.fx'
  HLSL effect file (source code).
• 'ShaderEffectName.{tag}'
  HLSL effect file (compiled binary).

where ShaderEffectName will be used as the shader effect name (case-sensitive) that must be passed to ShaderEffect. The global variables and techniques of the effect are exposed via the IShaderEffect interface. The following behaviour is applied when loading/compiling a shader effect:

• Only the '*.fx' file exists in the source directory:
  The effect is compiled and the corresponding '*.{tag}' file is written into the binary directory. If the binary directory is not writeable, a warning is logged and the '*.{tag}' file is not written.
• Both '*.fx' and '*.{tag} files exist in the source resp. binary directory:
  The effect is recompiled, if any of its source code files (effect file + includes) have been modified. On success, the corresponding '*.{tag}' file is updated and the recompiled effect replaces the previous effect. If the binary directory is not writeable, a warning is logged and the '*.{tag}' file is not updated.
• Only the '*.{tag}' file exists in the binary directory:
  The effect is loaded. The binary directory can be read-only.

The placeholder {tag} depicts the DirectX version, i.e. dx9 for DirectX 9 and dx11 for DirectX 11. When compiling the shader effect, the upper-case placeholder tag is provided as a preprocessor macro, e.g. DX11.

Public / Attributes

Cache

Returns the shared ResourceCache object for this graphics context.

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

DebugDisableShaderOptimization

Tell the shader effect compiler to do full optimization (false) or to skip optimization (true)?

public static field	DebugDisableShaderOptimization
type	bool

Remarks:

Defaults to false.

See also:

IGraphicsContext.RegisterShaderEffects

DebugEnableLogOutput

Enable additional debug-level log output?

public static field	DebugEnableLogOutput
type	bool

Remarks:

Defaults to false.

FrameTime

The GPU time that has been spent for the last frame.

public property	FrameTime { get }
type	float32
value	[>=0]	The spent time, in milliseconds.
inherited	GraphicsContext.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.

Graphics

Returns the shared Graphics object for this graphics context.

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

IsNearAtZero

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.
inherited	GraphicsContext.IsNearAtZero

LifecycleState

Returns the lifecycle state of this object.

public override property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Initializable.LifecycleState

Name

Human readable name of this graphics context.

public property	Name { get }
type	string
value	[not-empty]	The graphics context name.
inherited	GraphicsContext.Name

NativeHandle

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.
inherited	GraphicsContext.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.

public abstract property	PrimitiveRenderer { get }
type	IPrimitiveRenderer
value	[not-null]	The IPrimitiveRenderer object.
inherited	GraphicsContext.PrimitiveRenderer

RenderTargetCount

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

public property	RenderTargetCount { get }
type	int32
value	[1..4]	The number of render targets.
inherited	GraphicsContext.RenderTargetCount

See also:

IGraphicsContext.SetRenderTarget

ShaderEffectNames

Returns the names of all shader effects.

public property	ShaderEffectNames { get }
type	string[]
value	[not-null]	The list of shader effect names.
inherited	GraphicsContext.ShaderEffectNames

See also:

IGraphicsContext.ShaderEffect

Size

The 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.
inherited	GraphicsContext.Size

Remarks:

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

TextureFactory

Returns the ITextureFactory for this graphics context.

public abstract property	TextureFactory { get }
type	ITextureFactory
value	[not-null]	The ITextureFactory object.
inherited	GraphicsContext.TextureFactory

Public / Methods

AcquireTry

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.

Begin

Begins an access to this object.

public virtual method	Begin ()
inherited	GraphicsContext.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

Clear

Clears 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.
inherited	GraphicsContext.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.

CreateGeometryBuffer

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		[not-null]	The instance buffer.
inherited	GraphicsContext.CreateGeometryBuffer

See also:

IGraphicsContext.SetGeometryBuffer

CreateIndexBuffer

Creates 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		[not-null]	The IIndexBuffer object.
inherited	GraphicsContext.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		[not-null]	The IIndexBuffer object.
inherited	GraphicsContext.CreateIndexBuffer

CreateRenderTarget

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		[not-null]	The render target.
inherited	GraphicsContext.CreateRenderTarget

See also:

IGraphicsContext.ValidateRenderTargetFormat
IGraphicsContext.SetRenderTarget

CreateSwapChain

Creates 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		[not-null]	The render target for the created swap chain.
inherited	GraphicsContext.CreateSwapChain

Remarks:

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

• A8_R8_G8_B8
• D24_S8
• MultiSample
• Srgb

See also:

IGraphicsContext.SetRenderTarget

---

Creates a swap chain render target for the given window.

[OwnerReturn]
public abstract method	CreateSwapChain (IntPtr windowHandle, Vec2I clientSize)
type	ISwapChain
params	windowHandle		The HWND window handle.
	clientSize		The swap chain size, in pixels.
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:

• A8_R8_G8_B8
• D24_S8
• MultiSample
• Srgb

CreateTextureCube

Creates 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		[not-null]	The ITexture2D object.
inherited	GraphicsContext.CreateTextureCube

See also:

ITextureFactory.ValidateTextureFormat

Exceptions:

• TinmanException:
  If format is not supported.

CreateVertexBuffer

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.
inherited	GraphicsContext.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		[not-null]	The IVertexBuffer object.
inherited	GraphicsContext.CreateVertexBuffer

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]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

End

Ends the current access to this object.

public virtual method	End ()
inherited	GraphicsContext.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

Initialize

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

ReadPixels

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.
inherited	GraphicsContext.ReadPixels

RegisterShaderEffects

Scans the given directory for shader effect files and registers them in this graphics context.

public override sealed 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	GraphicsContext.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.ShaderEffect

SetClip

Sets the clip rectangle on the current render target.

[BeginEnd]
public abstract method	SetClip (Box2I value)
params	value		The clip rectangle.
inherited	GraphicsContext.SetClip

SetGeometryBuffer

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.
inherited	GraphicsContext.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.

SetRenderTarget

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.
inherited	GraphicsContext.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.CreateRenderTarget
IGraphicsContext.CreateSwapChain
IGraphicsContext.RenderTargetCount

SetViewport

Sets the viewport rectangle on the current render target.

[BeginEnd]
public abstract method	SetViewport (Box2I value)
params	value		The viewport rectangle.
inherited	GraphicsContext.SetViewport

ShaderEffect

Returns a shader effect by its name.

public method	ShaderEffect (string name)
type	IShaderEffect
params	name	[not-empty]	The shader effect name.
returns		[not-null]	The shader effect object.
inherited	GraphicsContext.ShaderEffect

Remarks:

The lookup scheme for shader source code or shader binaries is up to the implementing class.

See also:

IGraphicsContext.ShaderEffectNames

Validate

Checks 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.
inherited	GraphicsContext.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).

ValidateRenderTargetFormat

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.
inherited	GraphicsContext.ValidateRenderTargetFormat

See also:

IGraphicsContext.CreateRenderTarget

Protected / Attributes

renderTargetCount

The maximum number of simultaneous render targets, in the range [1..4].

protected field	renderTargetCount
type	int32
inherited	GraphicsContext.renderTargetCount

Remarks:

This field must be initialized by subclasses during construction.

Protected / Constructors

DirectXContext

Creates a new instance of DirectXContext.

protected constructor	DirectXContext (string name, int64 magic, string tag)
params	name	[not-empty]	The graphics context name.
	magic		Magic value for compiled shader effects.
	tag	[not-empty]	The filename suffix tag for compiled shader effects.

Protected / Methods

AssertBegun

protected method	AssertBegun (string source)
params	source
inherited	GraphicsContext.AssertBegun

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method	DisposeManaged ()
overrides	GraphicsContext.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.

DisposeUnmanaged

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.

DoInitialize

Performs initialization.

protected override method	DoInitialize ()
inherited	GraphicsContext.DoInitialize

Remarks:

Overriding methods must call the DoInitialize method of their base class. The base call should be the first statement.

Initialized

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

RegisterShaderEffect

Register a new shader effect.

protected method	RegisterShaderEffect ([Owner] IShaderEffect effect)
params	effect	[not-null]	The effect.
inherited	GraphicsContext.RegisterShaderEffect

Remarks:

This method should only be called from within RegisterShaderEffects.

RegisterShaderEffects_Add

protected abstract method	RegisterShaderEffects_Add (string name, [Owner] IntPtr handle)
params	name
	handle

RegisterShaderEffects_Compile

protected abstract method	RegisterShaderEffects_Compile (Path directory, ShaderEffectCompileInfo effect)
params	directory
	effect

TimestampQuery

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.
inherited	GraphicsContext.TimestampQuery

TimestampQueryCancel

Cancels the pending GPU queries by calling TimestampQuery as necessary.

protected method	TimestampQueryCancel ()
inherited	GraphicsContext.TimestampQueryCancel

Remarks:

This method should be called by subclassed during disposal.

Logging

Logger

The logger object of this class.

public static readonly field	Logger
type	ILogger