Package com.badlogic.gdx.graphics.g2d
Class PixmapPacker
- java.lang.Object
-
- com.badlogic.gdx.graphics.g2d.PixmapPacker
-
- All Implemented Interfaces:
Disposable
public class PixmapPacker extends java.lang.Object implements Disposable
Packspixmaps
into one or morepages
to generate an atlas of pixmap instances. Provides means to directly convert the pixmap atlas to aTextureAtlas
. 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 viaPixmapPacker.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();
-
-
Nested Class Summary
Nested Classes Modifier and Type Class 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 Description PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder)
PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder, boolean stripWhitespaceX, boolean stripWhitespaceY, PixmapPacker.PackStrategy packStrategy)
Creates a new PixmapPacker which will insert all supplied pixmaps into one or morepageWidth
bypageHeight
pixmaps using the specified strategy.PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder, PixmapPacker.PackStrategy packStrategy)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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 newTextureAtlas
from the pixmaps inserted so far.boolean
getDuplicateBorder()
boolean
getPackToTexture()
int
getPadding()
PixmapPacker.Page
getPage(java.lang.String name)
Pixmap.Format
getPageFormat()
int
getPageHeight()
int
getPageIndex(java.lang.String name)
Returns the index of the page containing the given packed rectangle.Array<PixmapPacker.Page>
getPages()
int
getPageWidth()
Rectangle
getRect(java.lang.String name)
Color
getTransparentColor()
Rectangle
pack(Pixmap image)
Inserts the pixmap without a name.Rectangle
pack(java.lang.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 defaultcolor
of the wholePixmapPacker.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)
CallsupdateTexture
for each page.void
updateTextureAtlas(TextureAtlas atlas, Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps)
Updates theTextureAtlas
, adding any newPixmap
instances packed since the last call to this method.void
updateTextureAtlas(TextureAtlas atlas, Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps, boolean useIndexes)
Updates theTextureAtlas
, adding any newPixmap
instances packed since the last call to this method.void
updateTextureRegions(Array<TextureRegion> regions, Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps)
CallsupdateTexture
for each page and adds a region to the specified array for each page texture.
-
-
-
Constructor Detail
-
PixmapPacker
public PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder)
-
PixmapPacker
public PixmapPacker(int pageWidth, int pageHeight, Pixmap.Format pageFormat, int padding, boolean duplicateBorder, PixmapPacker.PackStrategy 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 PixmapPacker which will insert all supplied pixmaps into one or morepageWidth
bypageHeight
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 axisstripWhitespaceY
- 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(java.lang.String name, Pixmap image)
Inserts the pixmap. If name was not null, you can later retrieve the image's position in the output image viagetRect(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(java.lang.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(java.lang.String name)
- Parameters:
name
- the name of the image- Returns:
- the page the image is stored in or null
-
getPageIndex
public int getPageIndex(java.lang.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 interfaceDisposable
-
generateTextureAtlas
public TextureAtlas generateTextureAtlas(Texture.TextureFilter minFilter, Texture.TextureFilter magFilter, boolean useMipMaps)
Generates a newTextureAtlas
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 theTextureAtlas
, adding any newPixmap
instances packed since the last call to this method. This can be used to insert Pixmap instances on a separate thread viapack(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 theTextureAtlas
, adding any newPixmap
instances packed since the last call to this method. This can be used to insert Pixmap instances on a separate thread viapack(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)
CallsupdateTexture
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)
CallsupdateTexture
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 ifgetDuplicateBorder()
is true.
-
getTransparentColor
public Color getTransparentColor()
- See Also:
setTransparentColor(Color color)
-
setTransparentColor
public void setTransparentColor(Color color)
Sets the defaultcolor
of the wholePixmapPacker.Page
when a new one created. Helps to avoid texture bleeding or to highlight the page for debugging.- See Also:
Page(PixmapPacker packer)
-
-