Derm.Render.BufferObject Class Reference

Data buffer object abstraction. More...

Inheritance diagram for Derm.Render.BufferObject:

Classes
struct	BufferHint
	Buffer allocation hints. More...
Public Types
enum	Source { Client, Server }
	Buffer object data source. More...
enum	UsageMode { Draw = 0, Read }
	Buffer object usage enumeration type definition. More...
enum	XferMode { Stream = 0, Static, Dynamic }
	Buffer object usage mode enumeration type definition. More...
Public Member Functions
	BufferObject (int type, UsageMode usage, XferMode xfer)
	Construct a BufferObject determining its type, data usage and transfer mode.
abstract void	AllocateOnClient (int items)
	Allocates BufferObject data on client.
void	Bind (RenderContext ctx)
	Bind this RenderBufferObject.
override void	Create (RenderContext ctx)
	Create this BufferObject.
override void	Delete (RenderContext ctx)
	Delete this BufferObject.
bool	IsMapped ()
	Check whether this RenderBufferObject data is mapped.
void	Map (RenderContext ctx, int mask)
	Map this BufferObject.
T	MapGet< T > (RenderContext ctx, Int64 offset)
void	MapSet< T > (RenderContext ctx, T value, Int64 offset)
void	Unbind (RenderContext ctx)
	Unbind this RenderBufferObject.
void	Unmap (RenderContext ctx)
	Unmap this RenderBufferObject data.
Protected Member Functions
int	GetMappedBufferMask ()
	Determine RenderBufferObject data mapping access mask.
void	ReleaseOnClient ()
	Release BufferObject data on client.
Protected Attributes
BufferHint	mBufferHint
	BufferObject hints.
int	mDataItemSize = 0
	BufferObject data item size.
int	mDataUsage
	RenderBufferObject data usage hint.
int	mType
	RenderBufferObject type.
Properties
Source	DataSource `[get]`
	BufferObject data source property.
BufferHint	Hints `[get, set]`
	BufferObject hints.
int	ItemsCount `[get, set]`
	Number of items included in this BufferObject.

Detailed Description

Data buffer object abstraction.

BufferObject collect data. This abstract class doesn't define the term of storage of the BufferObject, but it defines BufferObject interface. The BufferObject main characteristic is the location of the data buffer: client side or server side.

When data buffer is allocated on client memory, it can be accessed easily by application and it can be reallocated whenever required, but it cannot be used for rendering operations; infact the data buffer shall be allocated on server side before being used for rendering.

Once allocated on server side, the data buffer can be linked with shader inputs for rendering, but it cannot be accessed without synchornization with the graphic system, and each modification requires an update on the server side, which cost is linear with the data to be modified.

It shall be possible to manage BufferObject data with the following primitives:

Allocation of client memory (see AllocateOnClient).
Reallocation of actual client memory.
Release actual client memory (see ReleaseOnClient).
Allocation of client memory into server memory (see AllocateOnServer).
Fetch of actual server memory into client memory.
Release of server memory.

The actual data buffer location can be queried with the DataSource property. To allocate a BufferObject on server, the data buffer shall be allocated in client memory first, then it can be allocated on server.

When allocating a data buffer on server, a set of hints shall be defined in order to optimize data buffer usage by the graphic system. These hints can be determined by the usage mode (see UsageMode and the transfer mode (see XferMode); these hints aid the graphics system to manage correctly the buffer data, assuming the data buffer usage and the data buffer update frequency.

Note that data buffer hints cannot be changed once the buffer object is allocated on server side, indeed to change buffer data hints it's necessary to deallocate and reallocate data buffer on server side; in this case you should consider to refactor the application logic, because the cost of the buffer allocation could be more significant respect the enhancements derived by buffer hints.

You can note that BufferObject class doesn't define the concrete data allocation, and methods and properties which iteracts with the data buffer are declared as abstract. Infact this class shall be derived in order to allocate data buffers, generally using generic classes to allow flexibility in the data definition.

The main class for accessing to the BufferObject interface is the RenderBufferObject class (a generic one). Other specific BufferObject implementation shall derive from RenderBufferObject (see RenderBufferObject<T>. for more details).

The BufferObject is quite flexible. There are many ways to allocate data for a collection of BufferObject instances. Here is an overview of standard allocation methods:

Separate buffer: a BufferObject is allocated in a single buffer object, wich represents the unique BufferObject instance. This is the simplest way to allocate a BufferObject. Graphically the BufferObject data layout could be presented as: [IIIIIIIII...III].
Packed buffer: multiple BufferObject instances are allocated in a single buffer object, which represent the data of every BufferObject instance involved in data allocation. The data of each single BufferObject instance is accessed using an offset. Graphically the BufferObject data layout could be presented as: [IIIIIIIII...III JJJJJJJJJ...JJJ].
Interleaved buffer: multiple BufferObject instances are allocated in a single buffer object, which represent the data of every BufferObject instance involved in data allocation. The data of each single BufferObject instance is accessed using an offset and a stride. Graphically the BufferObject data layout could be presented as: [IJIJIJIJIJ...IJIJIJ].

Member Enumeration Documentation

enum Derm::Render::BufferObject::Source

Buffer object data source.

Enumerator:

Client

Buffer object data is specified by client (application).

When this data source is specified, the buffer object data is specified by client (application). Indeed the client is able to map buffer object data: in the case the usage is Draw, mapping is has read/write permissions, while in the case the usage is Read, mapping is read only..

Server

Buffer object data is specified by server (OpenGL implementation).

When this data source is specified, the buffer object data is specified by server (OpenGL implementation). Indeed the client is able to map buffer object data only in the case the usage is Read, which it has read only permissions. In the case usage is Draw, no mapping is allowed.

enum Derm::Render::BufferObject::UsageMode

Buffer object usage enumeration type definition.

Enumerator:

Draw

Buffer object data is used for drawing (application to GL).

The buffer object data contents will be used for drawing. The contents could be specified by client or server.

Read

Buffer object data is used for reading (GL to application).

The buffer object data contents will be used for reading. The contents could be specified by only server.

enum Derm::Render::BufferObject::XferMode

Buffer object usage mode enumeration type definition.

Enumerator:

Stream

Stream usage mode.

When selected with Usage.Draw, client/server specify once the buffer object data, which will be used few times for drawing. When selected with Usage.Read, server specify once the buffer object data, which will be used once for reading.

Static

Static usage mode.

When selected with Usage.Draw, client/server specify once the buffer object data, which will be used many times for drawing. When selected with Usage.Read, server specify once the buffer object data, which will be used many times for reading.

Dynamic

Dynamic usage mode.

When selected with Usage.Draw, client/server specify many times the buffer object data, which will be used many times for drawing. When selected with Usage.Read, server specify many times the buffer object data, which will be used many times for reading.

Constructor & Destructor Documentation

Derm.Render.BufferObject.BufferObject	(	int	type,
		UsageMode	usage,
		XferMode	xfer
	)

Construct a BufferObject determining its type, data usage and transfer mode.

Parameters:

type

The type could assume one of the values:

Derm.Gl.ARRAY_BUFFER
Derm.Gl.ELEMENT_ARRAY_BUFFER
Derm.Gl.PIXEL_PACK_BUFFER
Derm.Gl.PIXEL_UNPACK_BUFFER

usage

An UsageMode specifying the data buffer usage.

xfer

A XferMode specifying the data buffer transfer mode.

Member Function Documentation

abstract void Derm.Render.BufferObject.AllocateOnClient ( int items ) [pure virtual]

Allocates BufferObject data on client.

Parameters:

items

Number of items to (re)allocate. A System.Int32

This routine shall allocate a certain number of BufferObject items on client memory; default values for allocated data is defined by specific BufferObject item implementor.

In the case BufferObject as already allocated the data buffer, it is reallocated keeping already defined data.

Implemented in Derm.Render.PackedArrayBufferObject, and Derm.Render.RenderBufferObject< T >.

void Derm.Render.BufferObject.Bind ( RenderContext ctx )

Bind this RenderBufferObject.

override void Derm.Render.BufferObject.Create ( RenderContext ctx ) [virtual]

Create this BufferObject.

Parameters:

ctx

Implements Derm.Render.RenderObject.

override void Derm.Render.BufferObject.Delete ( RenderContext ctx ) [virtual]

Delete this BufferObject.

Parameters:

ctx

Implements Derm.Render.RenderObject.

int Derm.Render.BufferObject.GetMappedBufferMask ( ) [protected]

Determine RenderBufferObject data mapping access mask.

Returns:

It returns one of the following values:

Derm.Gl.READ_WRITE
Derm.Gl.READ_ONLY
Derm.Gl.WRITE_ONLY A System.Int32

The RenderBufferObject makes available its data to application whenever it is mapped; The map implementation requires an access mask. This routine determines the most efficient access mask determined by the RenderBufferObject Usage and UsageMode.

In the case the RenderBufferObject data source is Client,

bool Derm.Render.BufferObject.IsMapped ( )

Check whether this RenderBufferObject data is mapped.

Returns:

void Derm.Render.BufferObject.Map	(	RenderContext	ctx,
		int	mask
	)

Map this BufferObject.

Parameters:

	ctx	A RenderContext required for mapping this BufferObject.
	mask	A System.Int32 specifying the map access. It can be Gl.READ_ONLY, Gl.WRITE_ONLY, or Gl.READ_WRITE.

T Derm.Render.BufferObject.MapGet< T >	(	RenderContext	ctx,
		Int64	offset
	)

Type Constraints

T

:

struct

void Derm.Render.BufferObject.MapSet< T >	(	RenderContext	ctx,
		T	value,
		Int64	offset
	)

Type Constraints

T

:

struct

void Derm.Render.BufferObject.ReleaseOnClient ( ) [protected]

Release BufferObject data on client.

void Derm.Render.BufferObject.Unbind ( RenderContext ctx )

Unbind this RenderBufferObject.

void Derm.Render.BufferObject.Unmap ( RenderContext ctx )

Unmap this RenderBufferObject data.

Member Data Documentation

BufferHint Derm.Render.BufferObject.mBufferHint [protected]

BufferObject hints.

int Derm.Render.BufferObject.mDataItemSize = 0 [protected]

BufferObject data item size.

int Derm.Render.BufferObject.mDataUsage [protected]

RenderBufferObject data usage hint.

int Derm.Render.BufferObject.mType [protected]

RenderBufferObject type.

The RenderBufferObject could assume the values Derm.Gl.ARRAY_BUFFER, Derm.Gl.ELEMENT_ARRAY_BUFFER, Derm.Gl.PIXEL_PACK_BUFFER, or Derm.Gl.PIXEL_UNPACK_BUFFER.

Property Documentation

Source Derm.Render.BufferObject.DataSource [get]

BufferObject data source property.

BufferHint Derm.Render.BufferObject.Hints [get, set]

BufferObject hints.

BufferObject hints, specified at construction time. Hints cannot be changed after having allocated buffer on server.

int Derm.Render.BufferObject.ItemsCount [get, set]

Number of items included in this BufferObject.

Derm.Render.BufferObject Class Reference

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Properties

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

Property Documentation