class EE::Graphics::TexturePacker

Overview

The Texture Packer class is used to create new Texture Atlases. Atlases can be created indicating the texture atlas size and adding textures to the atlases. More…

#include <texturepacker.hpp>

class TexturePacker {
public:
    // construction

    TexturePacker();

    TexturePacker(
        const Uint32& maxWidth,
        const Uint32& maxHeight,
        const Float& pixelDensity = 1,
        const bool& forcePowOfTwo = true,
        const bool& scalableSVG = false,
        const Uint32& pixelBorder = 2,
        const Texture::Filter& textureFilter = Texture::Filter::Linear,
        const bool& allowChilds = false,
        const bool& allowFlipping = false
    );
    ~TexturePacker();

    // methods

    static TexturePacker* New();

    static TexturePacker* New(
        const Uint32& maxWidth,
        const Uint32& maxHeight,
        const Float& pixelDensity = 1,
        const bool& forcePowOfTwo = true,
        const bool& scalableSVG = false,
        const Uint32& pixelBorder = 2,
        const Texture::Filter& textureFilter = Texture::Filter::Linear,
        const bool& allowChilds = false,
        const bool& allowFlipping = false
    );

    bool addTexture(const std::string& TexturePath);
    bool addImage(Image* Img, const std::string& Name);
    bool addTexturesPath(std::string TexturesPath);
    Int32 packTextures();
    void save(const std::string& Filepath, const Image::SaveType& Format = Image::SaveType::SAVE_TYPE_PNG, const bool& KeepExtensions = false);
    void close();

    void setOptions(
        const Uint32& maxWidth,
        const Uint32& maxHeight,
        const Float& pixelDensity = 1,
        const bool& forcePowOfTwo = true,
        const bool& scalableSVG = false,
        const Uint32& pixelBorder = 2,
        const Texture::Filter& textureFilter = Texture::Filter::Linear,
        const bool& allowChilds = false,
        const bool& allowFlipping = false
    );

    const Int32& getWidth() const;
    const Int32& getHeight() const;
    const std::string& getFilepath() const;
};

Detailed Documentation

The Texture Packer class is used to create new Texture Atlases. Atlases can be created indicating the texture atlas size and adding textures to the atlases.

Construction

TexturePacker()

Creates a new texture packer ( you will need to call SetOptions before adding any texture or image ).

TexturePacker(
    const Uint32& maxWidth,
    const Uint32& maxHeight,
    const Float& pixelDensity = 1,
    const bool& forcePowOfTwo = true,
    const bool& scalableSVG = false,
    const Uint32& pixelBorder = 2,
    const Texture::Filter& textureFilter = Texture::Filter::Linear,
    const bool& allowChilds = false,
    const bool& allowFlipping = false
)

Creates a new texture packer indicating the maximum size of the texture atlas.

Parameters:

maxWidth	The maximum width that the texture atlas will use.
maxHeight	The maximum height that the texture atlas will use.
pixelDensity	Indicates the device pixel density that represents the resources that will the packer pack.
textureFilter	Indicates with texture filter should be used when the texture of the atlas is loaded.
forcePowOfTwo	Indicates that if the max with and height must be adjusted to fit a power of two texture.
scalableSVG	True if SVG images are scaled to the packer PixelDensity
pixelBorder	Indicates how many pixels will be added to separate one image to another in the texture atlas. Usefull to avoid artifacts when rendered scaled TextureRegions. Use at least 1 pixel to separate images if you will scale any TextureRegion.
allowChilds	When enabled if the atlas does not have enough space left in the image to put more resources it will create a new image atlas and add the rest of the images in that images, repeating this process recursivelly until using all source images.
allowFlipping	Indicates if the images can be flipped inside the texture atlas. This is not compatible with eepp ( since it can’t flip the textures back to the original orientation ). So avoid it for eepp.

Methods

static TexturePacker* New(
    const Uint32& maxWidth,
    const Uint32& maxHeight,
    const Float& pixelDensity = 1,
    const bool& forcePowOfTwo = true,
    const bool& scalableSVG = false,
    const Uint32& pixelBorder = 2,
    const Texture::Filter& textureFilter = Texture::Filter::Linear,
    const bool& allowChilds = false,
    const bool& allowFlipping = false
)

Creates a new instance of the texture packer indicating the maximum size of the texture atlas.

Parameters:

maxWidth	The maximum width that the texture atlas will use.
maxHeight	The maximum height that the texture atlas will use.
pixelDensity	Indicates the device pixel density that represents the resources that will the packer pack.
textureFilter	Indicates with texture filter should be used when the texture of the atlas is loaded.
forcePowOfTwo	Indicates that if the max with and height must be adjusted to fit a power of two texture.
scalableSVG	True if SVG images are scaled to the packer PixelDensity
pixelBorder	Indicates how many pixels will be added to separate one image to another in the texture atlas. Usefull to avoid artifacts when rendered scaled TextureRegions. Use at least 1 pixel to separate images if you will scale any TextureRegion.
allowChilds	When enabled if the atlas does not have enough space left in the image to put more resources it will create a new image atlas and add the rest of the images in that images, repeating this process recursivelly until using all source images.
allowFlipping	Indicates if the images can be flipped inside the texture atlas. This is not compatible with eepp ( since it can’t flip the textures back to the original orientation ). So avoid it for eepp.

bool addTexture(const std::string& TexturePath)

Adds a image/texture from its path to the texture atlas.

Parameters:

TexturePath

The image path.

bool addImage(Image* Img, const std::string& Name)

Adds a image to the texture atlas. The image instance must remain in memory until the texture atlas is saved.

bool addTexturesPath(std::string TexturesPath)

Adds a directory with images. It will try to add all the images inside that directory to the texture atlas.

Int32 packTextures()

After adding all the images that will be used to create the texture atlas. Packing the textures will generate the texture atlas information ( it will fit the images inside the texture atlas, etc ).

Returns:

The amount of pixels used for the new image or the total area used. 0 means it failed.

void save(const std::string& Filepath, const Image::SaveType& Format = Image::SaveType::SAVE_TYPE_PNG, const bool& KeepExtensions = false)

Save the texture atlas to a file, in the indicated format. If PackTexture() has not been called, it will be called automatically by the function ( so you don’t need to call it ).

Parameters:

Filepath	The path were it will be saved the new texture atlas.
Format	The image format of the new texture atlas.
KeepExtensions	Indicates if the extensions of the image files must be saved. Usually you want to find the TextureRegions by its name without extension, but this can be changed here.

void close()

Clear all the textures added

void setOptions(
    const Uint32& maxWidth,
    const Uint32& maxHeight,
    const Float& pixelDensity = 1,
    const bool& forcePowOfTwo = true,
    const bool& scalableSVG = false,
    const Uint32& pixelBorder = 2,
    const Texture::Filter& textureFilter = Texture::Filter::Linear,
    const bool& allowChilds = false,
    const bool& allowFlipping = false
)

First of all you need to set at least the max dimensions of the texture atlas. If the instance of the texture packer was created without indicating this data, this must be called before adding any texture or image.

Parameters:

maxWidth	The maximum width that the texture atlas will use.
maxHeight	The maximum height that the texture atlas will use.
pixelDensity	Indicates the device pixel density that represents the resources that will the packer pack.
textureFilter	Indicates with texture filter should be used when the texture of the atlas is loaded.
forcePowOfTwo	Indicates that if the max with and height must be adjusted to fit a power of two texture.
scalableSVG	True if SVG images are scaled to the packer PixelDensity
pixelBorder	Indicates how many pixels will be added to separate one image to another in the texture atlas. Usefull to avoid artifacts when rendered scaled TextureRegions. Use at least 1 pixel to separate images if you will scale any TextureRegion.
allowChilds	When enabled if the atlas does not have enough space left in the image to put more resources it will create a new image atlas and add the rest of the images in that images, repeating this process recursivelly until using all source images.
allowFlipping	Indicates if the images can be flipped inside the texture atlas. This is not compatible with eepp ( since it can’t flip the textures back to the original orientation ). So avoid it for eepp.

const Int32& getWidth() const

Returns:

The texture atlas to generate width.

const Int32& getHeight() const

Returns:

The texture atlas to generate height

const std::string& getFilepath() const

Returns:

If the texture atlas has already been saved, returns the file path to the texture atlas.