Main interface for BufferUploads More...

#include <IBufferUploads.h>

Inheritance diagram for BufferUploads::IManager:

Public Member Functions
Upload Data to an existing transaction
virtual void	UpdateData (TransactionID id, DataPacket *rawData, const PartialResource &=PartialResource())=0
	Use UpdateData to change the data within an existing object More...

Begin and End transactions
virtual TransactionID	Transaction_Begin (const BufferDesc &desc, DataPacket *initialisationData=nullptr, TransactionOptions::BitField flags=0)=0
	Begin a new transaction More...

virtual TransactionID	Transaction_Begin (intrusive_ptr< ResourceLocator > &locator, TransactionOptions::BitField flags=0)=0
	Begin a new transaction More...

virtual void	Transaction_End (TransactionID id)=0
	Ends a transaction More...

virtual void	Transaction_Validate (TransactionID id)=0
	Validates a transaction More...

Immediate creation
virtual intrusive_ptr< ResourceLocator >	Transaction_Immediate (const BufferDesc &desc, DataPacket *initialisationData=nullptr, const PartialResource &=PartialResource())=0
	Create a new buffer synchronously More...

Transaction management
virtual void	AddRef (TransactionID id)=0
	Add extra ref count to transaction More...

virtual bool	IsCompleted (TransactionID id)=0
	Checks for completion More...

virtual intrusive_ptr< ResourceLocator >	GetResource (TransactionID id)=0
	Gets the resource from a completed transaction More...

Resource references
virtual void	Resource_Validate (const ResourceLocator &locator)=0
	Read back data from a resource More...

virtual intrusive_ptr< DataPacket >	Resource_ReadBack (const ResourceLocator &locator)=0
	Read back data from a resource More...

Frame management
virtual void	Update (RenderCore::IThreadContext &immediateContext)=0
	Called every frame to update uploads More...

Utilities, profiling & debugging
virtual void	Flush ()=0
	Stalls until all work queues are empty More...

virtual CommandListMetrics	PopMetrics ()=0
	Gets performance metrics More...

virtual size_t	ByteCount (const BufferDesc &desc) const =0
	Returns the size of a buffer More...

virtual PoolSystemMetrics	CalculatePoolMetrics () const =0
	Returns metrics about pool memory More...

virtual void	FramePriority_Barrier ()=0
	Sets a barrier for frame priority operations More...

Event queue
typedef uint32	EventListID

virtual EventListID	EventList_GetLatestID ()=0

virtual void	EventList_Get (EventListID id, Event_ResourceReposition &begin, Event_ResourceReposition &end)=0

virtual void	EventList_Release (EventListID id)=0

Detailed Description

Main interface for BufferUploads

BufferUploads::IManager is used as the main interface for uploading data to the GPU. Normal usage involves creating a transaction, waiting for the transaction to complete, and then ending the transaction.

Use BufferUploads::CreateManager() to create a new manager object.

Buffer uploads can be used from a separate dll, or statically linked in.

Typical usage:

@code 
        BufferUploads::IManager& manager = ...;
        BufferUploads::BufferDesc desc = ...;
        intrusive_ptr<DataPacket> pkt = ...;
        auto uploadTransaction = manager.Transaction_Begin(desc, initialisationData);
            // later....
        if (manager.IsCompleted(uploadTransaction)) {
            _myResource = manager.GetResource(uploadTransaction);
            manager.Transaction_End(uploadTransaction);
        }
    \endcode

Member Function Documentation

virtual void BufferUploads::IManager::AddRef ( TransactionID id )

pure virtual

Add extra ref count to transaction

Adds another reference count to a transaction. Useful when a resource is getting cloned. Should be balanced with a call to Transaction_End

See also: Transaction_End

Implemented in BufferUploads::Manager.

virtual size_t BufferUploads::IManager::ByteCount ( const BufferDesc & desc ) const

pure virtual

Returns the size of a buffer

Calculates the size of a buffer from a description. This can be used to estimate the amount of GPU memory that will be used.

Implemented in BufferUploads::Manager.

virtual PoolSystemMetrics BufferUploads::IManager::CalculatePoolMetrics ( ) const

pure virtual

Returns metrics about pool memory

Returns some profiling metrics related to the resource pooling buffers maintained by the system. Used by the BufferUploadDisplay for presenting profiling information.

Implemented in BufferUploads::Manager.

virtual void BufferUploads::IManager::Flush ( )

pure virtual

Stalls until all work queues are empty

Normally should only be used during shutdown and loading.

Implemented in BufferUploads::Manager.

virtual void BufferUploads::IManager::FramePriority_Barrier ( )

pure virtual

Sets a barrier for frame priority operations

Sets a barrier, which determines the "end of frame" point for frame priority operations. This will normally be called from the same thread that begins most upload operations.

Implemented in BufferUploads::Manager.

virtual intrusive_ptr<ResourceLocator> BufferUploads::IManager::GetResource ( TransactionID id )

pure virtual

Gets the resource from a completed transaction

After a transaction has been completed, get the resource with this method. Note that the reference count for the returned resource is incremented by one in this method. The caller must balance that with a call to Resource_Release().

Implemented in BufferUploads::Manager.

virtual bool BufferUploads::IManager::IsCompleted ( TransactionID id )

pure virtual

Checks for completion

Returns true iff the given transaction has been completed.

Implemented in BufferUploads::Manager.

virtual CommandListMetrics BufferUploads::IManager::PopMetrics ( )

pure virtual

Gets performance metrics

Gets the latest performance metrics. Internally the system maintains a queue of performance metrics. Every frame, a new set of metrics is pushed onto the queue (until the stack reaches it's maximum size). PopMetrics() will remove the next item from the queue. If there no more items, "_commitTime" will be 0.

Implemented in BufferUploads::Manager.

virtual intrusive_ptr<DataPacket> BufferUploads::IManager::Resource_ReadBack ( const ResourceLocator & locator )

pure virtual

Read back data from a resource

Read data back from a resource. Sometimes this may require copying data from the GPU onto the CPU. Note that this can have a significant effect on performance! If the resource is currently in use by the GPU, it can result in a store. Whenever possible, it's recommended to avoid using this method. It's provided for compatibility and debugging.

Implemented in BufferUploads::Manager.

virtual void BufferUploads::IManager::Resource_Validate ( const ResourceLocator & locator )

pure virtual

Read back data from a resource

Read data back from a resource. Sometimes this may require copying data from the GPU onto the CPU. Note that this can have a significant effect on performance! If the resource is currently in use by the GPU, it can result in a store. Whenever possible, it's recommended to avoid using this method. It's provided for compatibility and debugging.

Implemented in BufferUploads::Manager.

virtual TransactionID BufferUploads::IManager::Transaction_Begin	(	const BufferDesc &	desc,
		DataPacket *	initialisationData = `nullptr`,
		TransactionOptions::BitField	flags = `0`
	)

pure virtual

Begin a new transaction

Begin a new transaction, either by creating a new resource, or by attaching to an existing resource.

Implemented in BufferUploads::Manager.

virtual TransactionID BufferUploads::IManager::Transaction_Begin	(	intrusive_ptr< ResourceLocator > &	locator,
		TransactionOptions::BitField	flags = `0`
	)

pure virtual

Begin a new transaction

Begin a new transaction, either by creating a new resource, or by attaching to an existing resource.

Implemented in BufferUploads::Manager.

virtual void BufferUploads::IManager::Transaction_End ( TransactionID id )

pure virtual

Ends a transaction

Ends a transaction started with Transaction_Begin. Internally, this updates a reference count. So every call to Transaction_Begin must be balanced with a call to Transaction_End. Be sure to end all transactions before destroying the buffer uploads manager.

Implemented in BufferUploads::Manager.

virtual intrusive_ptr<ResourceLocator> BufferUploads::IManager::Transaction_Immediate	(	const BufferDesc &	desc,
		DataPacket *	initialisationData = `nullptr`,
		const PartialResource &	= `PartialResource()`
	)

pure virtual

Create a new buffer synchronously

Creates a new resource synchronously. All creating objects will execute in the current thread, and a new resource will be returned from the call. Use these methods when uploads can't be delayed.

Implemented in BufferUploads::Manager.

virtual void BufferUploads::IManager::Transaction_Validate ( TransactionID id )

pure virtual

Validates a transaction

This is a tool for debugging. Checks a transaction for common problems. Only implemented in _DEBUG builds. Errors will invoke an assert.

Implemented in BufferUploads::Manager.

virtual void BufferUploads::IManager::Update ( RenderCore::IThreadContext & immediateContext )

pure virtual

Called every frame to update uploads

Performs once-per-frame tasks. Normally called by the render device once per frame.

Implemented in BufferUploads::Manager.

virtual void BufferUploads::IManager::UpdateData	(	TransactionID	id,
		DataPacket *	rawData,
		const PartialResource &	= `PartialResource()`
	)

pure virtual

Use UpdateData to change the data within an existing object

Upload data for buffer uploads can be provided either to the Transaction_Begin call, or to UploadData. Use UploadData when you want to update an existing resource, or change the data that's already present.

Implemented in BufferUploads::Manager.

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

BufferUploads/IBufferUploads.h

Public Member Functions

Event queue

Detailed Description

Member Function Documentation