TransferBuffer Struct Reference

A CPU-accessible SDL_GPUTransferBuffer for staging data to or from the GPU. More...

#include <TransferBuffer.h>

Inheritance diagram for TransferBuffer:

Public Member Functions
TransferBuffer *	initWithDevice (TransferBuffer *self, RenderDevice *device, const SDL_GPUTransferBufferCreateInfo *info)
	Initializes this TransferBuffer, creating its SDL_GPUTransferBuffer.
void *	map (const TransferBuffer *self, bool cycle)
	Maps this transfer buffer into CPU-accessible memory for reading or writing.
void	unmap (const TransferBuffer *self)
	Unmaps this transfer buffer previously mapped with map.
void	write (const TransferBuffer *self, const void *data, Uint32 size, bool cycle)
	Writes size bytes of data into this transfer buffer.
Class *	_TransferBuffer (void)
	The TransferBuffer archetype.

Data Fields
Object	object
	The superclass.
SDL_GPUTransferBuffer *	buffer
	The underlying SDL transfer buffer.
Uint32	size
	The size of this transfer buffer, in bytes.

Protected Attributes
TransferBufferInterface *	interface [0]
	The interface type.

Detailed Description

A CPU-accessible SDL_GPUTransferBuffer for staging data to or from the GPU.

TransferBuffer owns its underlying SDL_GPUTransferBuffer and releases it in dealloc, so a TransferBuffer is freed with release like any other Objectively object. Its buffer field is the raw handle to embed in an SDL_GPUTransferBufferLocation or SDL_GPUTextureTransferInfo when calling CopyPass upload/download methods:

TransferBuffer *tbuf = $(renderDevice, createTransferBuffer,
  &(SDL_GPUTransferBufferCreateInfo) { .usage = SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD, .size = size });
 
$(copyPass, downloadBuffer, &src, &(SDL_GPUTransferBufferLocation) { .transfer_buffer = tbuf->buffer });
 
const void *data = $(tbuf, map, false);
...
$(tbuf, unmap);
release(tbuf);

Member Function Documentation

_TransferBuffer()

Class * _TransferBuffer

(

void

)

The TransferBuffer archetype.

Returns

The TransferBuffer Class.

initWithDevice()

TransferBuffer * initWithDevice	(	TransferBuffer *	self,
		RenderDevice *	device,
		const SDL_GPUTransferBufferCreateInfo *	info
	)

Initializes this TransferBuffer, creating its SDL_GPUTransferBuffer.

This is the designated initializer.

Parameters

self	The TransferBuffer.
device	The RenderDevice used to create, map, and release the transfer buffer. Retained.
info	Transfer buffer creation parameters (usage: upload or download, size).

Returns

The initialized TransferBuffer. GPU_Asserts on failure.

map()

void * map	(	const TransferBuffer *	self,
		bool	cycle
	)

Maps this transfer buffer into CPU-accessible memory for reading or writing.

Pass cycle = true to let the driver use a fresh buffer allocation (avoiding a pipeline stall) when the buffer is already in use by the GPU. Call unmap when done; the mapping must not be used after that.

Parameters

self	The TransferBuffer.
cycle	If true, the driver may cycle to a new backing allocation.

Returns

A CPU pointer to the mapped region. GPU_Asserts on failure.

unmap()

void unmap

(

const TransferBuffer *

self

)

Unmaps this transfer buffer previously mapped with map.

The CPU pointer returned by map must not be accessed after this call.

Parameters

self	The TransferBuffer.

write()

void write	(	const TransferBuffer *	self,
		const void *	data,
		Uint32	size,
		bool	cycle
	)

Writes size bytes of data into this transfer buffer.

Maps, copies and unmaps in one call, which is all that sourcing an upload from CPU data amounts to. Pass cycle = true when this buffer may still be in use by the GPU, as it will be for one held across frames.

Parameters

self	The TransferBuffer.
data	The data to write. Must hold at least size bytes.
size	The number of bytes to write. Must not exceed this buffer's size.
cycle	If true, the driver may cycle to a new backing allocation.

Field Documentation

buffer

SDL_GPUTransferBuffer* TransferBuffer::buffer

The underlying SDL transfer buffer.

interface

TransferBufferInterface* TransferBuffer::interface[0]

protected

The interface type.

object

Object TransferBuffer::object

The superclass.

size

Uint32 TransferBuffer::size

The size of this transfer buffer, in bytes.

---

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

• Sources/ObjectivelyGPU/TransferBuffer.h
• Sources/ObjectivelyGPU/TransferBuffer.c