Texture Struct Reference

An SDL_GPUTexture and the metadata describing it. More...

#include <Texture.h>

Inheritance diagram for Texture:

Public Member Functions
Texture *	initWithDevice (Texture *self, RenderDevice *device, const SDL_GPUTextureCreateInfo *info, const void *pixels)
	Initializes this Texture, creating its SDL_GPUTexture and optionally uploading pixel data.
Texture *	initWithSurface (Texture *self, RenderDevice *device, SDL_Surface *surface, SDL_GPUTextureUsageFlags usage, bool generateMipmaps)
	Initializes this Texture from an SDL_Surface, uploading its pixels immediately.
void	setName (Texture *self, const char *name)
	Assigns a debug label to this texture, visible in GPU capture tools.
void *	downloadPixels (const Texture *self)
	Downloads mip level 0, layer 0 of this texture to a newly allocated buffer.
Class *	_Texture (void)
	The Texture archetype.

Data Fields
Object	object
	The superclass.
SDL_GPUTexture *	texture
	The underlying SDL texture.
SDL_GPUTextureFormat	format
	The pixel format.
SDL_Size	size
	The texture dimensions in pixels.
SDL_GPUTextureType	type
	The texture type (2D, cube, 3D, array).
SDL_GPUTextureUsageFlags	usage
	The usage flags the texture was created with.
Uint32	layerCountOrDepth
	The depth (3D) or layer count (array/cube), or 1.
Uint32	numLevels
	The number of mip levels.
SDL_GPUSampleCount	sampleCount
	The MSAA sample count.
ident	data
	User data.

Protected Attributes
TextureInterface *	interface
	The interface.

Detailed Description

An SDL_GPUTexture and the metadata describing it.

Texture owns its underlying SDL_GPUTexture and releases it in dealloc, so a Texture is freed with release like any other Objectively object — there is no separate device-level release call:

Texture *texture = $(renderDevice, createTexture, &info, pixels);
// ... use texture->texture, texture->size, texture->format ...
release(texture);

The metadata fields are populated at initialization from the SDL_GPUTextureCreateInfo and are immutable thereafter.

Member Function Documentation

_Texture()

Class * _Texture

(

void

)

The Texture archetype.

Returns

The Texture Class.

downloadPixels()

void * downloadPixels

(

const Texture *

self

)

Downloads mip level 0, layer 0 of this texture to a newly allocated buffer.

Blocks until the download completes (records a copy pass, submits it with a fence, and waits on that fence), so this is not suited to per-frame use. The returned buffer is tightly packed in self's native format and sized per SDL_CalculateGPUTextureFormatSize; the caller is responsible for interpreting the pixel format and freeing the buffer with free.

Parameters

self	The Texture.

Returns

A newly allocated buffer of downloaded pixel data. GPU_Asserts on failure.

initWithDevice()

Texture * initWithDevice	(	Texture *	self,
		RenderDevice *	device,
		const SDL_GPUTextureCreateInfo *	info,
		const void *	pixels
	)

Initializes this Texture, creating its SDL_GPUTexture and optionally uploading pixel data.

This is the designated initializer. When pixels is non-NULL, a temporary upload transfer buffer is allocated, pixels is copied into it, a copy pass is recorded and submitted, so the texture is GPU-resident before returning. Only mip level 0 is uploaded. The upload size is computed with SDL_CalculateGPUTextureFormatSize, so block-compressed formats (BCn, ASTC, …) are handled correctly; pixels must be tightly packed for info's format.

Parameters

self	The Texture.
device	The RenderDevice used to create and release the texture. Retained.
info	Texture creation parameters (format, type, dimensions, usage, etc.).
pixels	Initial tightly-packed pixel data to upload, or NULL to leave the texture uninitialised.

Returns

The initialized Texture, or NULL on failure.

initWithSurface()

Texture * initWithSurface	(	Texture *	self,
		RenderDevice *	device,
		SDL_Surface *	surface,
		SDL_GPUTextureUsageFlags	usage,
		bool	generateMipmaps
	)

Initializes this Texture from an SDL_Surface, uploading its pixels immediately.

Converts surface to SDL_PIXELFORMAT_RGBA32 if needed, derives the dimensions from the surface, and uploads as SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM. The surface's row pitch is respected, so padded rows (alignment, or a sub-surface of an atlas) upload correctly. The surface is neither modified nor freed.

Parameters

self	The Texture.
device	The RenderDevice used to create and release the texture. Retained.
surface	The source surface. Must not be NULL.
usage	Texture usage flags (e.g. SDL_GPU_TEXTUREUSAGE_SAMPLER).
mipmaps	If true, a full mip chain is allocated (level count derived from the surface's smaller dimension) and generated after the base level upload; this adds SDL_GPU_TEXTUREUSAGE_COLOR_TARGET to usage, since mipmap generation is a blit. If false, only mip level 0 exists, matching prior behavior.

Returns

The initialized Texture, or NULL on failure.

setName()

void setName	(	Texture *	self,
		const char *	name
	)

Assigns a debug label to this texture, visible in GPU capture tools.

Parameters

self	The Texture.
name	A null-terminated debug name string.

Field Documentation

data

ident Texture::data

User data.

format

SDL_GPUTextureFormat Texture::format

The pixel format.

interface

TextureInterface* Texture::interface

protected

The interface.

layerCountOrDepth

Uint32 Texture::layerCountOrDepth

The depth (3D) or layer count (array/cube), or 1.

numLevels

Uint32 Texture::numLevels

The number of mip levels.

object

Object Texture::object

The superclass.

sampleCount

SDL_GPUSampleCount Texture::sampleCount

The MSAA sample count.

size

SDL_Size Texture::size

The texture dimensions in pixels.

texture

SDL_GPUTexture* Texture::texture

The underlying SDL texture.

type

SDL_GPUTextureType Texture::type

The texture type (2D, cube, 3D, array).

usage

SDL_GPUTextureUsageFlags Texture::usage

The usage flags the texture was created with.

---

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

• Sources/ObjectivelyGPU/Texture.h
• Sources/ObjectivelyGPU/Texture.c