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 pixmaps into one or more pages 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. How bin packing is performed can be customized via PixmapPacker.PackStrategy.

All methods can be called from any thread unless otherwise noted.

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, false);
 packer.dispose();
 // ...
 atlas.dispose();
 

With this usage pattern, disposing the packer will not dispose any pixmaps used by the texture atlas. The texture atlas must also be disposed when no longer needed. Incremental texture atlas usage:

 // 512x512 pixel pages, RGB565 format, 2 pixels of padding, no border duplication
 PixmapPacker packer = new PixmapPacker(512, 512, Format.RGB565, 2, false);
 TextureAtlas atlas = new TextureAtlas();
 
 // potentially on a separate thread, e.g. downloading thumbnails
 packer.pack("thumbnail", thumbnail);
 
 // on the rendering thread, every frame
 packer.updateTextureAtlas(atlas, TextureFilter.Linear, TextureFilter.Linear, false);
 
 // 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(atlas, TextureFilter.Linear, TextureFilter.Linear, false);
 // ...
 atlas.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()) {
        // ...
 }
 
 packer.dispose();
 

Author:

mzechner, Nathan Sweet, Rob Rendell

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PixmapPacker.GuillotineStrategy Does bin packing by inserting to the right or below previously packed rectangles.
static interface	PixmapPacker.PackStrategy Choose the page and location for each rectangle.
static class	PixmapPacker.Page
static class	PixmapPacker.PixmapPackerRectangle
static class	PixmapPacker.SkylineStrategy Does bin packing by inserting in rows.

Constructor Summary

Constructors

Constructor and Description
PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder) Uses PixmapPacker.GuillotineStrategy.
PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder, boolean stripWhitespaceX, boolean stripWhitespaceY, PixmapPacker.PackStrategy packStrategy) Creates a new ImagePacker which will insert all supplied pixmaps into one or more pageWidth by pageHeight pixmaps using the specified strategy.
PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder, PixmapPacker.PackStrategy packStrategy) Uses PixmapPacker.GuillotineStrategy.

Method Summary

Modifier and Type	Method and Description
void	dispose() Disposes any pixmap pages which don't have a texture.
TextureAtlas	generateTextureAtlas(Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps) Generates a new TextureAtlas from the pixmaps inserted so far.
boolean	getDuplicateBorder()
boolean	getPackToTexture()
int	getPadding()
PixmapPacker.Page	getPage(String name)
Pixmap.Format	getPageFormat()
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)
Color	getTransparentColor()
Rectangle	pack(Pixmap image) Inserts the pixmap without a name.
Rectangle	pack(String name, Pixmap image) Inserts the pixmap.
void	setDuplicateBorder(boolean duplicateBorder)
void	setPackToTexture(boolean packToTexture) If true, when a pixmap is packed to a page that has a texture, the portion of the texture where the pixmap was packed is updated using glTexSubImage2D.
void	setPadding(int padding)
void	setPageFormat(Pixmap.Format pageFormat)
void	setPageHeight(int pageHeight)
void	setPageWidth(int pageWidth)
void	setTransparentColor(Color color) Sets the default color of the whole PixmapPacker.Page when a new one created.
void	sort(Array<Pixmap> images) Sorts the images to the optimzal order they should be packed.
void	updatePageTextures(Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps) Calls updateTexture for each page.
void	updateTextureAtlas(TextureAtlas atlas, Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps) Updates the TextureAtlas, adding any new Pixmap instances packed since the last call to this method.
void	updateTextureAtlas(TextureAtlas atlas, Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps, boolean useIndexes) Updates the TextureAtlas, adding any new Pixmap instances packed since the last call to this method.
void	updateTextureRegions(Array<TextureRegion> regions, Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps) Calls updateTexture for each page and adds a region to the specified array for each page texture.

Methods inherited from class java.lang.Object

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

Constructor Detail

PixmapPacker

public PixmapPacker(int pageWidth,
                    int pageHeight,
                    Pixmap.Format pageFormat,
                    int padding,
                    boolean duplicateBorder)

Uses PixmapPacker.GuillotineStrategy.

See Also:

PixmapPacker#PixmapPacker(int, int, Format, int, boolean, boolean, boolean, PackStrategy)

PixmapPacker

public PixmapPacker(int pageWidth,
                    int pageHeight,
                    Pixmap.Format pageFormat,
                    int padding,
                    boolean duplicateBorder,
                    PixmapPacker.PackStrategy packStrategy)

Uses PixmapPacker.GuillotineStrategy.

See Also:

PixmapPacker#PixmapPacker(int, int, Format, int, boolean, boolean, boolean, PackStrategy)

PixmapPacker

public PixmapPacker(int pageWidth,
                    int pageHeight,
                    Pixmap.Format pageFormat,
                    int padding,
                    boolean duplicateBorder,
                    boolean stripWhitespaceX,
                    boolean stripWhitespaceY,
                    PixmapPacker.PackStrategy packStrategy)

Creates a new ImagePacker which will insert all supplied pixmaps into one or more pageWidth by pageHeight pixmaps using the specified strategy.

Parameters:

padding - the number of blank pixels to insert between pixmaps.

duplicateBorder - duplicate the border pixels of the inserted images to avoid seams when rendering with bi-linear filtering on.

stripWhitespaceX - strip whitespace in x axis

stripWhitespaceY - strip whitespace in y axis

Method Detail

sort

public void sort(Array<Pixmap> images)

Sorts the images to the optimzal order they should be packed. Some packing strategies rely heavily on the images being sorted.

pack

public Rectangle pack(Pixmap image)

Inserts the pixmap without a name. It cannot be looked up by name.

See Also:

pack(String, Pixmap)

pack

public Rectangle pack(String name,
                      Pixmap image)

Inserts the pixmap. If name was not null, you can later retrieve the image's position in the output image via getRect(String).

Parameters:

name - If null, the image cannot be looked up by name.

Returns:

Rectangle describing the area the pixmap was rendered to.

Throws:

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

getPages

public Array<PixmapPacker.Page> getPages()

Returns:

the PixmapPacker.Page instances created so far. If multiple threads are accessing the packer, iterating over the pages must be done only after synchronizing on the packer.

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 any pixmap pages which don't have a texture. Page pixmaps that have a texture will not be disposed until their texture is disposed.

Specified by:

dispose in interface Disposable

generateTextureAtlas

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

Generates a new TextureAtlas from the pixmaps inserted so far. After calling this method, disposing the packer will no longer dispose the page pixmaps.

updateTextureAtlas

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

Updates the 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. After calling this method, disposing the packer will no longer dispose the page pixmaps. Has useIndexes on by default so as to keep backwards compatibility

updateTextureAtlas

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

Updates the 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. After calling this method, disposing the packer will no longer dispose the page pixmaps.

updateTextureRegions

public void updateTextureRegions(Array<TextureRegion> regions,
                                 Texture.TextureFilter minFilter,
                                 Texture.TextureFilter magFilter,
                                 boolean useMipMaps)

Calls updateTexture for each page and adds a region to the specified array for each page texture.

updatePageTextures

public void updatePageTextures(Texture.TextureFilter minFilter,
                               Texture.TextureFilter magFilter,
                               boolean useMipMaps)

Calls updateTexture for each page.

getPageWidth

public int getPageWidth()

setPageWidth

public void setPageWidth(int pageWidth)

getPageHeight

public int getPageHeight()

setPageHeight

public void setPageHeight(int pageHeight)

getPageFormat

public Pixmap.Format getPageFormat()

setPageFormat

public void setPageFormat(Pixmap.Format pageFormat)

getPadding

public int getPadding()

setPadding

public void setPadding(int padding)

getDuplicateBorder

public boolean getDuplicateBorder()

setDuplicateBorder

public void setDuplicateBorder(boolean duplicateBorder)

getPackToTexture

public boolean getPackToTexture()

setPackToTexture

public void setPackToTexture(boolean packToTexture)

If true, when a pixmap is packed to a page that has a texture, the portion of the texture where the pixmap was packed is updated using glTexSubImage2D. Note if packing many pixmaps, this may be slower than reuploading the whole texture. This setting is ignored if getDuplicateBorder() is true.

getTransparentColor

public Color getTransparentColor()

See Also:

setTransparentColor(Color color)

setTransparentColor

public void setTransparentColor(Color color)

Sets the default color of the whole PixmapPacker.Page when a new one created. Helps to avoid texture bleeding or to highlight the page for debugging.

See Also:

Page#Page(PixmapPacker packer)