com.badlogic.gdx.graphics.g2d

Class PixmapPacker

java.lang.Object

com.badlogic.gdx.graphics.g2d.PixmapPacker

All Implemented Interfaces:

Disposable

public class PixmapPacker
extends Object
implements Disposable

Packs Pixmap instances into one more more PixmapPacker.Page instances to generate an atlas of Pixmap instances. Provides means to directly convert the pixmap atlas to a TextureAtlas. The packer supports padding and border pixel duplication, specified during construction. The packer supports incremental inserts and updates of TextureAtlases generated with this class.

All methods except getPage(String) and getPages() are thread safe. The methods #generateTextureAtlas(TextureFilter, TextureFilter, boolean) and #updateTextureAtlas(TextureAtlas, TextureFilter, TextureFilter, boolean) need to be called on the rendering thread, all other methods can be called from any thread.

One-off usage:

 // 512x512 pixel pages, RGB565 format, 2 pixels of padding, border duplication
 PixmapPacker packer = new PixmapPacker(512, 512, Format.RGB565, 2, true);
 packer.pack("First Pixmap", pixmap1);
 packer.pack("Second Pixmap", pixmap2);
 TextureAtlas atlas = packer.generateTextureAtlas(TextureFilter.Nearest, TextureFilter.Nearest);
 

Note that you should not dispose the packer in this usage pattern. Instead, dispose the TextureAtlas if no longer needed. Incremental usage:

 // 512x512 pixel pages, RGB565 format, 2 pixels of padding, no border duplication
 PixmapPacker packer = new PixmapPacker(512, 512, Format.RGB565, 2, false);
 TextureAtlas incrementalAtlas = new TextureAtlas();
 
 // potentially on a separate thread, e.g. downloading thumbnails
 packer.pack("thumbnail", thumbnail);
 
 // on the rendering thread, every frame
 packer.updateTextureAtlas(incrementalAtlas, TextureFilter.Linear, TextureFilter.Linear);
 
 // once the atlas is no longer needed, make sure you get the final additions. This might
 // be more elaborate depending on your threading model.
 packer.updateTextureAtlas(incrementalAtlas, TextureFilter.Linear, TextureFilter.Linear);
 incrementalAtlas.dispose();
 

Pixmap-only usage:

 PixmapPacker packer = new PixmapPacker(512, 512, Format.RGB565, 2, true);
 packer.pack("First Pixmap", pixmap1);
 packer.pack("Second Pixmap", pixmap2);
 
 // do something interesting with the resulting pages
 for (Page page : packer.getPages()) {
 }
 
 // dispose of the packer in this case
 packer.dispose();
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	PixmapPacker.Page

Constructor Summary

Constructors

Constructor and Description
PixmapPacker(int width, int height, Pixmap.Format format, int padding, boolean duplicateBorder) Creates a new ImagePacker which will insert all supplied images into a width by height image.

Method Summary

Methods

Modifier and Type	Method and Description
void	dispose() Disposes all resources, including Pixmap instances for the pages created so far.
boolean	duplicateBorder()
TextureAtlas	generateTextureAtlas(Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps) Generates a new TextureAtlas from the Pixmap instances inserted so far.
int	getPadding()
PixmapPacker.Page	getPage(String name)
int	getPageHeight()
int	getPageIndex(String name) Returns the index of the page containing the given packed rectangle.
Array<PixmapPacker.Page>	getPages()
int	getPageWidth()
Rectangle	getRect(String name)
Rectangle	pack(String name, Pixmap image) Inserts the given Pixmap.
void	updateTextureAtlas(TextureAtlas atlas, Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps) Updates the given TextureAtlas, adding any new Pixmap instances packed since the last call to this method.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PixmapPacker

public PixmapPacker(int width,
            int height,
            Pixmap.Format format,
            int padding,
            boolean duplicateBorder)

Creates a new ImagePacker which will insert all supplied images into a width by height image. padding specifies the minimum number of pixels to insert between images. border will duplicate the border pixels of the inserted images to avoid seams when rendering with bi-linear filtering on.

Parameters:

width - the width of the output image

height - the height of the output image

padding - the number of padding pixels

duplicateBorder - whether to duplicate the border

Method Detail

pack

public Rectangle pack(String name,
             Pixmap image)

Inserts the given Pixmap. You can later on retrieve the images position in the output image via the supplied name and the method getRect(String).

Parameters:

name - the name of the image

image - the image

Returns:

Rectangle describing the area the pixmap was rendered to or null.

Throws:

RuntimeException - in case the image did not fit due to the page size being to small or providing a duplicate name

getPages

public Array<PixmapPacker.Page> getPages()

Returns:

the PixmapPacker.Page instances created so far. This method is not thread safe!

getRect

public Rectangle getRect(String name)

Parameters:

name - the name of the image

Returns:

the rectangle for the image in the page it's stored in or null

getPage

public PixmapPacker.Page getPage(String name)

Parameters:

name - the name of the image

Returns:

the page the image is stored in or null

getPageIndex

public int getPageIndex(String name)

Returns the index of the page containing the given packed rectangle.

Parameters:

name - the name of the image

Returns:

the index of the page the image is stored in or -1

dispose

public void dispose()

Disposes all resources, including Pixmap instances for the pages created so far. These page Pixmap instances are shared with any TextureAtlas generated or updated by either #generateTextureAtlas(TextureFilter, TextureFilter, boolean) or #updateTextureAtlas(TextureAtlas, TextureFilter, TextureFilter, boolean). Do not call this method if you generated or updated a TextureAtlas, instead dispose the TextureAtlas.

Specified by:

dispose in interface Disposable

generateTextureAtlas

public TextureAtlas generateTextureAtlas(Texture.TextureFilter minFilter,
                                Texture.TextureFilter magFilter,
                                boolean useMipMaps)

Generates a new TextureAtlas from the Pixmap instances inserted so far.

Parameters:

minFilter -

magFilter -

Returns:

the TextureAtlas

updateTextureAtlas

public void updateTextureAtlas(TextureAtlas atlas,
                      Texture.TextureFilter minFilter,
                      Texture.TextureFilter magFilter,
                      boolean useMipMaps)

Updates the given TextureAtlas, adding any new Pixmap instances packed since the last call to this method. This can be used to insert Pixmap instances on a separate thread via pack(String, Pixmap) and update the TextureAtlas on the rendering thread. This method must be called on the rendering thread.

getPageWidth

public int getPageWidth()

getPageHeight

public int getPageHeight()

getPadding

public int getPadding()

duplicateBorder

public boolean duplicateBorder()