A BufferObject describes a generic array of data used, for example, to describe the vertices in a Shape or data retrieved from a framebuffer. More...

#include "bufferobject.h"

Inheritance diagram for ion::gfx::BufferObject:

[legend]

Collaboration diagram for ion::gfx::BufferObject:

[legend]

Classes
struct	BufferSubData
	Specifies a destination byte range, read byte offset, and source BufferObject or DataContainer for BufferSubData and CopyBufferSubData. More...

struct	Spec

Public Types
enum	Changes { kDataChanged = kNumBaseChanges, kSubDataChanged, kNumChanges }
	Changes that affect the resource. More...

enum	ComponentType { kInvalid, kByte, kUnsignedByte, kShort, kUnsignedShort, kInt, kUnsignedInt, kFloat, kFloatMatrixColumn2, kFloatMatrixColumn3, kFloatMatrixColumn4 }
	The type of the components of a spec. More...

enum	Target { kArrayBuffer, kElementBuffer, kCopyReadBuffer, kCopyWriteBuffer }

enum	UsageMode { kDynamicDraw, kStaticDraw, kStreamDraw }

enum	BaseChanges { kLabelChanged, kResourceChanged, kNumBaseChanges }
	All ResourceHolders derived from this should start their own change enums from kNumBaseChanges. More...

Public Member Functions
	BufferObject ()
	Creates a BufferObject of type kArrayBuffer. More...

Target	GetTarget () const
	Gets the buffer target. More...

size_t	AddSpec (const ComponentType type, const size_t component_count, const size_t byte_offset)
	Describes an element of an arbitrary datatype to the BufferObject. More...

const Spec &	GetSpec (const size_t spec_index) const
	Gets the Spec at index spec_index. More...

size_t	GetSpecCount () const
	Gets the number of Specs in the BufferObject. More...

void	SetData (const base::DataContainerPtr &data, const size_t struct_size, const size_t count, UsageMode usage)
	Sets data container, the size of the structure in bytes, and the number of structures. More...

const base::DataContainerPtr &	GetData () const
	Gets the data container. More...

void	SetSubData (const math::Range1ui &byte_range, const base::DataContainerPtr &data)
	Marks that the specified byte range of the BufferObject's data should be updated with the passed data. More...

void	CopySubData (const BufferObjectPtr &src, const math::Range1ui &dst_byte_range, uint32 read_offset)
	Adds a byte range of data that should be copied from src to this BufferObject. More...

void	ClearSubData () const
	Clears the vector of sub-data. More...

const base::AllocVector < BufferSubData > &	GetSubData () const
	Returns all sub-data ranges; may be an empty vector. More...

void *	GetMappedPointer () const
	Returns the mapped data pointer of the buffer, which will be NULL if the buffer has not been mapped with Renderer::MapBufferObjectData(Range)(). More...

size_t	GetStructSize () const
	Gets the size of one structure, in bytes. More...

size_t	GetCount () const
	Gets the number of structs in the buffer. More...

UsageMode	GetUsageMode () const
	Gets the usage mode of the data. More...

void	SetResource (size_t index, ResourceKey key, ResourceBase *resource) const
	Sets the resource at the passed index and key. More...

ResourceBase *	GetResource (size_t index, ResourceKey key) const
	Returns the Resource at the given index and key, or NULL if no resource was previously set at that location. More...

int	GetResourceCount () const
	Returns the number of resources that this holder holds. More...

size_t	GetGpuMemoryUsed () const
	Returns the total amount of GPU memory used by this Holder's resource. More...

const std::string &	GetLabel () const
	Returns/sets the label of this. More...

void	SetLabel (const std::string &label)

void	AddReceiver (Notifier *receiver)
	Adds a Notifier to be notified. More...

void	RemoveReceiver (Notifier *receiver)
	Removes a Notifier to be notified. More...

size_t	GetReceiverCount () const
	Returns the number of Notifiers that will be notified. More...

const AllocatorPtr &	GetAllocator () const
	Returns the Allocator that was used for the instance. More...

const AllocatorPtr &	GetNonNullAllocator () const
	Return our allocator, or the default allocator if the instance was declared on the stack. More...

const AllocatorPtr &	GetAllocatorForLifetime (AllocationLifetime lifetime) const
	Convenience function that returns the Allocator to use to allocate an object with a specific lifetime. More...

void *	operator new (size_t size)
	The standard no-parameter new operator uses the default Allocator. More...

void *	operator new (size_t size, AllocationLifetime lifetime)
	This overloaded version of the new operator uses the AllocationManager's default Allocator for the specified lifetime. More...

void *	operator new (size_t size, const AllocatorPtr &allocator)
	This overloaded version of the new operator takes the Allocator to use directly as a parameter. More...

void *	operator new (size_t size, const AllocatorPtr &allocator, void *ptr)
	Special operator new for using placement new with Allocatables. More...

void *	operator new (size_t size, void *ptr)
	The placement new operator is defined conventionally. More...

void	operator delete (void *ptr)
	Define the delete operator to use specialized functions dealing with an Allocator. More...

void	operator delete (void *ptr, AllocationLifetime lifetime)
	Windows requires these (or it issues C4291 warnings). More...

void	operator delete (void *ptr, const AllocatorPtr &allocator)

void	operator delete (void ptr, void ptr2)
	The placement delete operator does nothing, as usual. More...

int	GetRefCount () const
	GetRefCount() is part of the interface necessary for SharedPtr. More...

Protected Types
typedef WeakReferentPtr< Notifier >	NotifierPtr

typedef AllocVector< NotifierPtr >	NotifierPtrVector

Protected Member Functions
	BufferObject (Target target)
	Creates a BufferObject with a particular target type. More...

	~BufferObject () override
	The destructor is protected because all base::Referent classes must have protected or private destructors. More...

void	OnChanged (int bit) const
	Forwards OnChanged to all resources. More...

const NotifierPtrVector &	GetReceivers () const
	Returns the set of Notifiers that will be notified. More...

void	Notify () const
	Notifies all contained Notifiers by calling their OnNotify(). More...

Friends
class	Renderer
	Allow the Renderer to map and unmap buffer data. More...

Detailed Description

A BufferObject describes a generic array of data used, for example, to describe the vertices in a Shape or data retrieved from a framebuffer.

It is a wrapper around a structure, but makes no assumptions about the structure itself, nor any assumptions about the input data (e.g. it assumes data is already in the correct format to send to the graphics card, and performs no normalization, clamping, etc.).

For the purposes of BufferObject a data structure is composed of elements defined by a Spec (e.g., int, vec2f, mat4), each Spec has an SpecType (e.g., int, float, float), and a certain number of components (e.g., 1, 2, 16). A spec may correspond to a shader attribute, a uniform, or some kind of pixel format, depending on how the buffer is used.

There are three possible usage modes that give OpenGL hints as to how the data should be stored (from the OpenGL ES documentation):

kDynamicDraw: The data store contents will be modified repeatedly and used many times.
kStaticDraw: The data store contents will be modified once and used many times.
kStreamDraw: The data store contents will be modified once and used at most a few times.

A BufferObject can be bound to two possible targets: a kElementBuffer or a kArrayBuffer. kElementBuffer means the data will be used as an element array defining indices, while kArrayBuffer means the data will be used for array data, such as vertices. BufferObjects are by default kArrayBuffers; see the IndexBuffer class for creating types of kElementBuffer to be used as index arrays.

After a buffer's data has been set through SetData(), callers can modify sub-ranges of data through SetSubData(), or update the entire buffer's data with another call to SetData().

Definition at line 67 of file bufferobject.h.

Member Typedef Documentation

typedef WeakReferentPtr<Notifier> ion::base::Notifier::NotifierPtr

protectedinherited

Definition at line 49 of file notifier.h.

typedef AllocVector<NotifierPtr> ion::base::Notifier::NotifierPtrVector

protectedinherited

Definition at line 50 of file notifier.h.

Member Enumeration Documentation

enum ion::gfx::ResourceHolder::BaseChanges

inherited

All ResourceHolders derived from this should start their own change enums from kNumBaseChanges.

Enumerator
kLabelChanged
kResourceChanged
kNumBaseChanges

Definition at line 56 of file resourceholder.h.

enum ion::gfx::BufferObject::Changes

Changes that affect the resource.

Enumerator
kDataChanged
kSubDataChanged
kNumChanges

Definition at line 70 of file bufferobject.h.

enum ion::gfx::BufferObject::ComponentType

The type of the components of a spec.

Enumerator
kInvalid
kByte
kUnsignedByte
kShort
kUnsignedShort
kInt
kUnsignedInt
kFloat
kFloatMatrixColumn2	These are necessary since each column of a matrix must be sent to OpenGL separately and we must know the number of components in each column.
kFloatMatrixColumn3
kFloatMatrixColumn4

Definition at line 77 of file bufferobject.h.

enum ion::gfx::BufferObject::Target

Enumerator
kArrayBuffer
kElementBuffer
kCopyReadBuffer
kCopyWriteBuffer

Definition at line 93 of file bufferobject.h.

enum ion::gfx::BufferObject::UsageMode

Enumerator
kDynamicDraw
kStaticDraw
kStreamDraw

Definition at line 100 of file bufferobject.h.

Constructor & Destructor Documentation

ion::gfx::BufferObject::BufferObject ( )

Creates a BufferObject of type kArrayBuffer.

Definition at line 28 of file bufferobject.cc.

ion::gfx::BufferObject::BufferObject ( Target target )

explicitprotected

Creates a BufferObject with a particular target type.

This constructor is protected so that only derived classes can set the target.

Definition at line 35 of file bufferobject.cc.

ion::gfx::BufferObject::~BufferObject ( )

overrideprotected

The destructor is protected because all base::Referent classes must have protected or private destructors.

Definition at line 42 of file bufferobject.cc.

References GetData().

Member Function Documentation

void ion::base::Notifier::AddReceiver ( Notifier * receiver )

inherited

Adds a Notifier to be notified.

Does nothing if the receiver is NULL or is already in the receiver vector.

Definition at line 25 of file notifier.cc.

size_t ion::gfx::BufferObject::AddSpec	(	const ComponentType	type,
		const size_t	component_count,
		const size_t	byte_offset
	)

Describes an element of an arbitrary datatype to the BufferObject.

An element is defined by its byte offset into the struct, its type, and the number of components it contains.

AddSpec() Returns a static index into the array of elements for this BufferObject. The returned value is a unique (for this BufferObject), static index into an array of Elements. The returned index is required by the Get() functions, below. If count is > 4, then returns an invalid index (base::kInvalidIndex). Since Specs are unique; attempting to add the same Spec twice has no effect and the original index of the identical Spec is returned.

Definition at line 46 of file bufferobject.cc.

References ion::port::ERROR, ion::base::kInvalidIndex, and LOG.

void ion::gfx::BufferObject::ClearSubData ( ) const

inline

Clears the vector of sub-data.

Definition at line 240 of file bufferobject.h.

void ion::gfx::BufferObject::CopySubData	(	const BufferObjectPtr &	src,
		const math::Range1ui &	dst_byte_range,
		uint32	read_offset
	)

inline

Adds a byte range of data that should be copied from src to this BufferObject.

read_offset specifies the byte offset within the src BufferObject data from which to copy the data. dst_byte_range specifies the destination range. The source and destination ranges should not overlap if src == this. Note that all subdatas in src are applied to to src before the copy to this BufferObject.

Definition at line 226 of file bufferobject.h.

References ion::base::SharedPtr< T >::Get().

const AllocatorPtr& ion::base::Allocatable::GetAllocator ( ) const

inlineinherited

Returns the Allocator that was used for the instance.

This will be NULL if the instance was declared on the stack or created with normal placement new.

Definition at line 68 of file allocatable.h.

References allocator_.

Referenced by ion::base::DataContainer::CreateAndCopy(), ion::text::DynamicFontImage::FindContainingImageDataIndex(), and ion::text::DynamicFontImage::FindImageDataIndex().

const AllocatorPtr& ion::base::Allocatable::GetAllocatorForLifetime ( AllocationLifetime lifetime ) const

inlineinherited

Convenience function that returns the Allocator to use to allocate an object with a specific lifetime.

Definition at line 78 of file allocatable.h.

References ion::base::Allocator::GetAllocatorForLifetime().

Referenced by ion::text::BasicBuilder::BuildVertexData(), ion::text::OutlineBuilder::BuildVertexData(), ion::gfxutils::ShaderManager::CreateShaderProgram(), ion::text::DynamicFontImage::FindContainingImageDataIndex(), ion::text::DynamicFontImage::FindImageDataIndex(), ion::gfx::Renderer::Renderer(), and ion::gfx::UpdateStateTable().

size_t ion::gfx::BufferObject::GetCount ( ) const

inline

Gets the number of structs in the buffer.

Definition at line 257 of file bufferobject.h.

const base::DataContainerPtr& ion::gfx::BufferObject::GetData ( ) const

inline

Gets the data container.

Definition at line 205 of file bufferobject.h.

References ion::base::SharedPtr< T >::Get().

Referenced by ~BufferObject().

size_t ion::gfx::ResourceHolder::GetGpuMemoryUsed ( ) const

inlineinherited

Returns the total amount of GPU memory used by this Holder's resource.

Definition at line 78 of file resourceholder.h.

const std::string& ion::gfx::ResourceHolder::GetLabel ( ) const

inlineinherited

Returns/sets the label of this.

Definition at line 89 of file resourceholder.h.

void* ion::gfx::BufferObject::GetMappedPointer ( ) const

inline

Returns the mapped data pointer of the buffer, which will be NULL if the buffer has not been mapped with Renderer::MapBufferObjectData(Range)().

Definition at line 250 of file bufferobject.h.

const AllocatorPtr& ion::base::Allocatable::GetNonNullAllocator ( ) const

inlineinherited

Return our allocator, or the default allocator if the instance was declared on the stack.

Definition at line 72 of file allocatable.h.

References allocator_, and ion::base::AllocationManager::GetNonNullAllocator().

size_t ion::base::Notifier::GetReceiverCount ( ) const

inherited

Returns the number of Notifiers that will be notified.

Definition at line 71 of file notifier.cc.

const Notifier::NotifierPtrVector & ion::base::Notifier::GetReceivers ( ) const

protectedinherited

Returns the set of Notifiers that will be notified.

Definition at line 77 of file notifier.cc.

int ion::base::Shareable::GetRefCount ( ) const

inlineinherited

GetRefCount() is part of the interface necessary for SharedPtr.

Definition at line 34 of file shareable.h.

Referenced by ion::base::Notifier::RemoveReceiver().

ResourceBase * ion::gfx::ResourceHolder::GetResource	(	size_t	index,
		ResourceKey	key
	)		const

inherited

Returns the Resource at the given index and key, or NULL if no resource was previously set at that location.

Definition at line 122 of file resourceholder.cc.

int ion::gfx::ResourceHolder::GetResourceCount ( ) const

inlineinherited

Returns the number of resources that this holder holds.

Note that this is not necessarily the number of indices that have non-NULL resources. This can be used as a fast trivial check to see if the holder has any resources.

Definition at line 73 of file resourceholder.h.

const BufferObject::Spec & ion::gfx::BufferObject::GetSpec ( const size_t spec_index ) const

Gets the Spec at index spec_index.

If spec_index is invalid, returns an InvalidReference.

Definition at line 69 of file bufferobject.cc.

References ion::port::ERROR, and LOG.

size_t ion::gfx::BufferObject::GetSpecCount ( ) const

inline

Gets the number of Specs in the BufferObject.

Definition at line 186 of file bufferobject.h.

size_t ion::gfx::BufferObject::GetStructSize ( ) const

inline

Gets the size of one structure, in bytes.

Definition at line 255 of file bufferobject.h.

const base::AllocVector<BufferSubData>& ion::gfx::BufferObject::GetSubData ( ) const

inline

Returns all sub-data ranges; may be an empty vector.

Definition at line 244 of file bufferobject.h.

Target ion::gfx::BufferObject::GetTarget ( ) const

inline

Gets the buffer target.

Definition at line 138 of file bufferobject.h.

UsageMode ion::gfx::BufferObject::GetUsageMode ( ) const

inline

Gets the usage mode of the data.

Definition at line 259 of file bufferobject.h.

void ion::base::Notifier::Notify ( ) const

protectedinherited

Notifies all contained Notifiers by calling their OnNotify().

Any receivers that have been destroyed will be removed from the vector of receivers.

Definition at line 81 of file notifier.cc.

References ion::base::SharedPtr< T >::Get().

void ion::gfx::ResourceHolder::OnChanged ( int bit ) const

inlineprotectedinherited

Forwards OnChanged to all resources.

Definition at line 326 of file resourceholder.h.

void ion::base::Allocatable::operator delete ( void * ptr )

inlineinherited

Define the delete operator to use specialized functions dealing with an Allocator.

Definition at line 109 of file allocatable.h.

void ion::base::Allocatable::operator delete	(	void *	ptr,
		AllocationLifetime	lifetime
	)

inlineinherited

Windows requires these (or it issues C4291 warnings).

Definition at line 112 of file allocatable.h.

void ion::base::Allocatable::operator delete	(	void *	ptr,
		const AllocatorPtr &	allocator
	)

inlineinherited

Definition at line 113 of file allocatable.h.

void ion::base::Allocatable::operator delete	(	void *	ptr,
		void *	ptr2
	)

inlineinherited

The placement delete operator does nothing, as usual.

Definition at line 118 of file allocatable.h.

void* ion::base::Allocatable::operator new ( size_t size )

inlineinherited

The standard no-parameter new operator uses the default Allocator.

Definition at line 84 of file allocatable.h.

void* ion::base::Allocatable::operator new	(	size_t	size,
		AllocationLifetime	lifetime
	)

inlineinherited

This overloaded version of the new operator uses the AllocationManager's default Allocator for the specified lifetime.

Definition at line 88 of file allocatable.h.

void* ion::base::Allocatable::operator new	(	size_t	size,
		const AllocatorPtr &	allocator
	)

inlineinherited

This overloaded version of the new operator takes the Allocator to use directly as a parameter.

If the Allocator pointer is NULL, this uses the default Allocator.

Definition at line 95 of file allocatable.h.

void* ion::base::Allocatable::operator new	(	size_t	size,
		const AllocatorPtr &	allocator,
		void *	ptr
	)

inlineinherited

Special operator new for using placement new with Allocatables.

Definition at line 100 of file allocatable.h.

void* ion::base::Allocatable::operator new	(	size_t	size,
		void *	ptr
	)

inlineinherited

The placement new operator is defined conventionally.

Definition at line 105 of file allocatable.h.

void ion::base::Notifier::RemoveReceiver ( Notifier * receiver )

inherited

Removes a Notifier to be notified.

Does nothing if the receiver is NULL or not in the set of receivers.

Definition at line 38 of file notifier.cc.

References ion::base::Shareable::GetRefCount().

Referenced by ion::gfx::AttributeArray::~AttributeArray().

void ion::gfx::BufferObject::SetData	(	const base::DataContainerPtr &	data,
		const size_t	struct_size,
		const size_t	count,
		UsageMode	usage
	)

inline

Sets data container, the size of the structure in bytes, and the number of structures.

The DataContainer will only be destroyed when the last client ReferentPtr to the DataContainer goes away and the BufferObject is destroyed or a new DataContainer is set with SetData(). data may be NULL in which case the BufferObject is sized to struct_size * count, but its contents are undefined and it is expected that the BufferObject will be populated later with SetSubData().

Definition at line 195 of file bufferobject.h.

References ion::base::SharedPtr< T >::Get().

void ion::gfx::ResourceHolder::SetLabel ( const std::string & label )

inlineinherited

Definition at line 90 of file resourceholder.h.

void ion::gfx::ResourceHolder::SetResource	(	size_t	index,
		ResourceKey	key,
		ResourceBase *	resource
	)		const

inherited

Sets the resource at the passed index and key.

The size of the internal vector is automatically managed so that it has the smallest possible size.

Definition at line 51 of file resourceholder.cc.

References DCHECK, DCHECK_EQ, ion::gfx::ResourceBase::GetKey(), and ion::gfx::ResourceBase::OnChanged().

void ion::gfx::BufferObject::SetSubData	(	const math::Range1ui &	byte_range,
		const base::DataContainerPtr &	data
	)

inline

Marks that the specified byte range of the BufferObject's data should be updated with the passed data.

This function is only meaningful if SetData() has already been used, and may be called multiple times to update multiple byte ranges.

Definition at line 211 of file bufferobject.h.

References ion::base::SharedPtr< T >::Get().

Friends And Related Function Documentation

friend class Renderer

friend

Allow the Renderer to map and unmap buffer data.

Definition at line 369 of file bufferobject.h.

The documentation for this class was generated from the following files:

gfx/bufferobject.h
gfx/bufferobject.cc

Classes

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation