ImageAtlas Struct Reference

Packs many Images into one sheet, backed by one Texture. More...

#include <ImageAtlas.h>

Inheritance diagram for ImageAtlas:

Public Member Functions
Class *	_ImageAtlas (void)
AtlasImage *	addImage (ImageAtlas *self, Image *image)
	Adds the given Image to this atlas.
AtlasImage *	addImageWithName (ImageAtlas *self, const char *name, Image *image)
	Adds the given Image to this atlas, registered under name for ImageAtlas::imageWithName.
AtlasImage *	addImageWithResourceName (ImageAtlas *self, const char *name, float pixelDensity)
	Loads the Image Resource by the given name and adds it to this atlas.
bool	compile (ImageAtlas *self)
	Packs every added Image into a new sheet.
AtlasImage *	imageWithName (const ImageAtlas *self, const char *name)
ImageAtlas *	init (ImageAtlas *self)
	Initializes this ImageAtlas.
void	renderDeviceWillReset (ImageAtlas *self)
	Releases this atlas' Texture ahead of a RenderDevice reset.
Texture *	texture (ImageAtlas *self, RenderDevice *device)
	Resolves the sheet's Texture, creating it on the given device if necessary.

Data Fields
unsigned	generation
	Incremented by every ImageAtlas::addImageWithName and ImageAtlas::compile, so that anything derived from this atlas' contents or layout can tell when it is stale.
Image *	image
	The compiled sheet, or NULL until ImageAtlas::compile.
Array *	images
	The AtlasImages, in the order added.
int	maxSize
	The largest sheet dimension ImageAtlas::compile will attempt.
Object	object
	The superclass.

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

Detailed Description

Packs many Images into one sheet, backed by one Texture.

The Renderer merges consecutive draws that share a Texture into one draw call, so a UI whose images all come from one atlas draws in a handful of calls rather than one per View. Add Images, then compile: every AtlasImage learns where its pixels landed, and the sheet's Texture is created on first request and shared by every View that draws from it.

Packing is by shelves: images are sorted by height, then laid out left to right in rows, onto the smallest power-of-two square that holds them, up to maxSize. There is no padding: the Renderer samples without mipmaps, so there are no mip levels to bleed across.

Definition at line 49 of file ImageAtlas.h.

Member Function Documentation

_ImageAtlas()

Class * _ImageAtlas

(

void

)

Definition at line 324 of file ImageAtlas.c.

                         {
  static Class *clazz;
  static Once once;
 
  do_once(&once, {
    clazz = _initialize(&(const ClassDef) {
      .name = "ImageAtlas",
      .superclass = _Object(),
      .instanceSize = sizeof(ImageAtlas),
      .interfaceSize = sizeof(ImageAtlasInterface),
      .initialize = initialize,
    });
  });
 
  return clazz;
}

addImage()

AtlasImage * addImage	(	ImageAtlas *	self,
		Image *	image
	)

Adds the given Image to this atlas.

Parameters

self	The ImageAtlas.
image	The Image. Its surface is shared with the returned AtlasImage.

Returns

The AtlasImage, owned by this atlas. Its rect is not valid until the next ImageAtlas::compile.

Definition at line 59 of file ImageAtlas.c.

                                                            {
 
  assert(image);
  assert(!$((Object *) image, isKindOfClass, _AtlasImage()));
 
  AtlasImage *atlasImage = $(alloc(AtlasImage), initWithImage, self, image);
  assert(atlasImage);
 
  $(self->images, addObject, atlasImage);
  release(atlasImage);
 
  return atlasImage;
}

addImageWithName()

AtlasImage * addImageWithName	(	ImageAtlas *	self,
		const char *	name,
		Image *	image
	)

Adds the given Image to this atlas, registered under name for ImageAtlas::imageWithName.

Names are unique: registering a name again replaces the mapping, while the previously registered AtlasImage remains in the atlas.

Parameters

self	The ImageAtlas.
name	The name.
image	The Image. Its surface is shared with the returned AtlasImage.

Returns

The AtlasImage, owned by this atlas. Its rect is not valid until the next ImageAtlas::compile.

Definition at line 96 of file ImageAtlas.c.

                                                                                      {
 
  assert(name);
 
  AtlasImage *atlasImage = $(self, addImage, image);
 
  $(self->names, setObjectForKeyPath, atlasImage, name);
  self->generation++;
 
  return atlasImage;
}

addImageWithResourceName()

AtlasImage * addImageWithResourceName	(	ImageAtlas *	self,
		const char *	name,
		float	pixelDensity
	)

Loads the Image Resource by the given name and adds it to this atlas.

Parameters

self	The ImageAtlas.
name	The Resource name.

Returns

The AtlasImage, owned by this atlas, or NULL if the Resource was not found.

Definition at line 77 of file ImageAtlas.c.

                                                                                                    {
 
  AtlasImage *atlasImage = NULL;
 
  Image *image = $$(Image, imageWithResourceName, name, pixelDensity);
  if (image) {
    atlasImage = $(self, addImage, image);
    release(image);
  } else {
    MVC_LogError("Image %s not found\n", name);
  }
 
  return atlasImage;
}

compile()

bool compile

(

ImageAtlas *

self

)

Packs every added Image into a new sheet.

Every AtlasImage's rect is reassigned, and the previous sheet and Texture are released, so a View drawing from this atlas MUST read rect and ImageAtlas::texture at draw time rather than caching either. Compiling repacks everything from scratch, so add all Images first and compile once.

Parameters

self	The ImageAtlas.

Returns

true if every Image fit within maxSize, false otherwise.

Definition at line 170 of file ImageAtlas.c.

                                      {
 
  self->generation++;
 
  const size_t count = self->images->count;
  if (count == 0) {
    return true;
  }
 
  AtlasImage **images = calloc(count, sizeof(AtlasImage *));
  assert(images);
 
  SDL_Rect *rects = calloc(count, sizeof(SDL_Rect));
  assert(rects);
 
  size_t area = 0;
  int size = 1;
 
  for (size_t i = 0; i < count; i++) {
    images[i] = $(self->images, objectAtIndex, i);
 
    const SDL_Surface *surface = images[i]->image.surface;
    area += (size_t) surface->w * (size_t) surface->h;
    size = max(size, max(surface->w, surface->h));
  }
 
  qsort(images, count, sizeof(AtlasImage *), compareImages);
 
  size = max(size, (int) ceil(sqrt((double) area)));
 
  int sheetSize = 1;
  while (sheetSize < size) {
    sheetSize <<= 1;
  }
 
  bool packed = false;
  while (sheetSize <= self->maxSize) {
    if (pack(images, rects, count, sheetSize)) {
      packed = true;
      break;
    }
    sheetSize <<= 1;
  }
 
  if (packed) {
 
    for (size_t i = 0; i < count; i++) {
      images[i]->rect = rects[i];
    }
 
    SDL_Surface *sheet = SDL_CreateSurface(sheetSize, sheetSize, SDL_PIXELFORMAT_RGBA32);
    assert(sheet);
 
    SDL_FillSurfaceRect(sheet, NULL, 0);
 
    for (size_t i = 0; i < count; i++) {
 
      const AtlasImage *image = images[i];
      const SDL_Surface *surface = image->image.surface;
      const size_t pitch = surface->w * SDL_BYTESPERPIXEL(surface->format);
 
      for (int y = 0; y < surface->h; y++) {
        memcpy((Uint8 *) sheet->pixels + (image->rect.y + y) * sheet->pitch + image->rect.x * SDL_BYTESPERPIXEL(sheet->format),
               (const Uint8 *) surface->pixels + y * surface->pitch,
               pitch);
      }
    }
 
    release(self->image);
    self->image = $$(Image, imageWithSurface, sheet);
    assert(self->image);
 
    SDL_DestroySurface(sheet);
 
    self->texture = release(self->texture);
 
  } else {
    MVC_LogError("%zu images (%zu texels) do not fit within %dx%d\n", count, area, self->maxSize, self->maxSize);
  }
 
  free(rects);
  free(images);
 
  return packed;
}

imageWithName()

AtlasImage * imageWithName	(	const ImageAtlas *	self,
		const char *	name
	)

Parameters

self	The ImageAtlas.
name	The name.

Returns

The AtlasImage registered under name via ImageAtlas::addImageWithName, or NULL.

Definition at line 112 of file ImageAtlas.c.

                                                                           {
 
  assert(name);
 
  return $(self->names, objectForKeyPath, name);
}

init()

ImageAtlas * init

(

ImageAtlas *

self

)

Initializes this ImageAtlas.

Parameters

self	The ImageAtlas.

Returns

The initialized ImageAtlas, or NULL on error.

Definition at line 260 of file ImageAtlas.c.

                                          {
 
  self = (ImageAtlas *) super(Object, self, init);
  if (self) {
 
    self->images = $$(Array, array);
    assert(self->images);
 
    self->names = $$(Dictionary, dictionary);
    assert(self->names);
 
    self->maxSize = IMAGE_ATLAS_MAX_SIZE;
  }
 
  return self;
}

renderDeviceWillReset()

void renderDeviceWillReset

(

ImageAtlas *

self

)

Releases this atlas' Texture ahead of a RenderDevice reset.

An ImageAtlas is not a View, so nothing calls this on its behalf: every View that draws from an atlas MUST forward its own View::renderDeviceWillReset here. The call is idempotent, so shared atlases are fine.

Parameters

self	The ImageAtlas.

Definition at line 281 of file ImageAtlas.c.

                                                    {
  self->texture = release(self->texture);
}

texture()

Texture * texture	(	ImageAtlas *	self,
		RenderDevice *	device
	)

Resolves the sheet's Texture, creating it on the given device if necessary.

Parameters

self	The ImageAtlas.
device	The RenderDevice.

Returns

The Texture, owned by this atlas, or NULL if the atlas has not been compiled.

Definition at line 289 of file ImageAtlas.c.

                                                                {
 
  assert(device);
 
  if (self->texture == NULL && self->image) {
    self->texture = $(device, createTextureFromSurface, self->image->surface, SDL_GPU_TEXTUREUSAGE_SAMPLER, false);
    assert(self->texture);
  }
 
  return self->texture;
}

Field Documentation

generation

unsigned ImageAtlas::generation

Incremented by every ImageAtlas::addImageWithName and ImageAtlas::compile, so that anything derived from this atlas' contents or layout can tell when it is stale.

Definition at line 66 of file ImageAtlas.h.

image

Image* ImageAtlas::image

The compiled sheet, or NULL until ImageAtlas::compile.

Definition at line 71 of file ImageAtlas.h.

images

Array* ImageAtlas::images

The AtlasImages, in the order added.

Definition at line 76 of file ImageAtlas.h.

interface

ImageAtlasInterface* ImageAtlas::interface[0]

protected

The interface type.

Definition at line 60 of file ImageAtlas.h.

maxSize

int ImageAtlas::maxSize

The largest sheet dimension ImageAtlas::compile will attempt.

Sheets are power-of-two squares, so this SHOULD be a power of two; a value that is not rounds down to one. Defaults to IMAGE_ATLAS_MAX_SIZE, which every SDL_GPU backend supports.

Definition at line 90 of file ImageAtlas.h.

object

Object ImageAtlas::object

The superclass.

Definition at line 54 of file ImageAtlas.h.

---

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

• Sources/ObjectivelyMVC/ImageAtlas.h
• Sources/ObjectivelyMVC/ImageAtlas.c