# gtec-texture-packer **Repository Path**: githubmap/gtec-texture-packer ## Basic Information - **Project Name**: gtec-texture-packer - **Description**: No description available - **Primary Language**: Unknown - **License**: BSD-3-Clause - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2023-12-01 - **Last Updated**: 2025-04-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Texture Packer A texture atlas generation tool that helps create complex texture atlases. ## Why With the new DPI aware UI framework we have a lot requirements to the atlas and font generation and are more likely to modify and experiment with the atlas content. So having better tools for the generation will save a lot of time. ## Features * Texture atlas creation from a input xml * Trim support (global and per element override) * Shape padding (global and per element override) * Border padding * Duplicate detection * Per element DPI tagging * Smart image addition * Add elements to atlas * Add folder * Add angle code font * License file support * Create a merged license file for atlases. * Warn about missing licenses for atlas images. * Supports both normal and pre-multiplied image output * Writes * Atlas image: png * Binary texture atlas: bta * Basic font kerning: fbk * Bitmap fonts format: nbf, jsonBitmapFont * AtlasFlavor support * Validate that texture atlases created for various resolutions (flavors) contain the same images and meta data, so errors can be detected during creation instead of at runtime when selecting the resolution. * Build and version control friendly output: * All output files should be deterministic given the same input. * Will never overwrite a file if no changes were made. * Default settings are read from a config file * The default configuration is created like this: * Set the hard-coded configuration * If a configuration file exist next to the executable we apply the changes from that. * We then look for a configuration file next to the command file and if that is not found we search for the nearest configuration file in all parent directories and if one is found we apply its changes. ## Configuration ### TexturePackerConfig Configures all settings used for pacing Name | Description ---------------------|------------------------- Version | Current "1" DefaultCompany | The default company to associate with written atlases (for encoders that support it). This can be overridden per atlas. ```xml ... ``` #### CreateAtlasConfig Configures all settings used for creating texture atlases. Name | Description ---------------------|------------------------- OutputAtlasFormat | Set the default atlas format. Can be: *bta3, bta4, bta4C#* ```xml ... ``` ##### AtlasConfig Name | Description ---------------------|------------------------- TransparencyMode | Set the transparency mode. Can be: *normal, pre-multiply* ```xml ... ``` ###### ElementConfig Name | Description ----------------------|------------------------- DefaultDpi | The default dpi for atlases that don't specify their dpi. Trim | enable/disable image trim. Trim removes transparent pixels around the sprite, but the image appears to have its original size when they are used. TrimMargin | The minimum number of transparent pixels to leave around a trimmed sprite (default: 1 as leaving one will create nicer aliasing for most use cases). TransparencyThreshold | The first alpha value that is considered non transparent (default: 1). ShapePadding | The number of pixels of padding that should be added around images to prevent texture bleeding. BorderPadding | The number of pixels that should be kept free at the border of the texture. ```xml ``` ###### LayoutConfig Name | Description ---------------------|------------------------- AllowRotation | Set to false as its not fully supported at the moment. Allows the texture packer to rotate the elements. ```xml ``` ###### TextureConfig Name | Description ---------------------|------------------------- MaxSize | The maximum allowed texture size PixelFormat | **Not supported yet.** Defaults to *R8G8B8A8* SizeRestrictions | *any*=any size, *pow2*=power to texture, *pow2square*=square power 2. ```xml ``` ##### AddBitmapFontConfig Name | Description ---------------------|------------------------- OutputFontFormat | The default bitmap font output format (default: *nbf*) ```xml ``` #### LicenseConfig Name | Description ------------------------|------------------------- File | The name of the license file. If empty license file support are disabled. Type | The type of the license file: *nxpJson, unknown*. Unknown is considered a binary blob without merge support. AllowMasterFileCreation | Allows the texture packer to created a merged license master file for atlases. RequiredForAllContent | If true a license file must be present in all directories used to create a texture atlas. ```xml ``` ## Commands ### AtlasFlavors Verify that all atlases created under it contain the exact same names, elements and meta data. This is useful to ensure that a various resolutions of atlases contain the exact same things making it safer to assume that its safe to switch between resolutions. Can contain the following child elements: Child elements | Description ---------------------|------------------------- CreateAtlas | (optional) Add a atlas flavor. ```xml ... ``` ### CreateAtlas Create a texture atlas Name | Description ---------------------|------------------------- Name | The unique name of the atlas and its a possible sub folder to output to. If the name ends with *number*_dpi it will be interpreted as setting the DefaultDpi for the atlas. For example Test_480dpi will set the DefaultDpi to 480. If the DefaultDpi attribute is specified as well and its a different value its considered a error. DefaultDpi | (optional) Override the default dpi. OutputAtlasFormat | (optional) Override the default atlas output format. License | (optional) Override all found licenses with the supplied one SourcePath | (optional) Set a path that will be added to all 'relative sub command paths' (defaults to empty) TransparencyMode | (optional) Override the default transparency mode. Can be: *normal, premultiply*. ```xml ... ``` #### CreateAtlas sub commands ##### AtlasConfig override A specific AtlasConfig can be added here which will override the one from the configuration file. If its present there can only be one and it must be the first sub command! ##### AddFolder Add all image files from given folder to the atlas. There can be zero to N of these. Name | Description ---------------------|------------------------- Path | The relative folder path (will be combined with the atlas source path) DefaultDpi | (optional) Override the default dpi for all images in the folder Can contain the following child elements: Child elements | Description ---------------------|------------------------- ElementConfig | (optional) Must be the first child. Overrides the default settings with the supplied ones (unset config elements will use the current default). Folder | (optional) Customize a sub folder added by AddFolder. (must come before any File tags) File | (optional) Customize a entry added by AddFolder. ```xml ... ``` ###### Folder Customize all files under the given folder which was added by *AddFolder* Name | Description ---------------------|------------------------- Path | The relative name of the element to modify (must exist in the folder). Can contain the following child elements: Child elements | Description ---------------------|------------------------- ElementConfig | (optional) Must be the first child. Overrides the default settings with the supplied ones (unset config elements will use the current default). ```xml ... ``` ###### File Customize a file added by *AddFolder* Name | Description ---------------------|------------------------- Path | The relative name of the element to modify (must exist in the folder). Can contain the following child elements: Child elements | Description ---------------------|------------------------- ElementConfig | (optional) Must be the first child. Overrides the default settings with the supplied ones (unset config elements will use the current default). AddAnchor | (optional) Add a number of anchor points as meta data. AddNineSlice | (optional) Add nine slice information. AddComplexPatch | (optional) Add complex patch information (experimental). ```xml ... ``` ##### AddBitmapFont Add a bitmap font to the atlas. There can be zero to N of these. Name | Description ---------------------|------------------------- OutputFontFormat | (optional) Override the default font output format: *fbk, nbf, jsonBitmapFont, nbfC#*. Multiple formats can be specified here to produce multiple output file. Example: fbk,nbf. Path | The relative font file path (will be combined with the atlas source path) Type | The type of the font bitmap data. It can be: bitmap, sdf. DefaultDpi | (optional) Override the default dpi for all font characters. LineSpacingPx | (optional) Force the given line-spacing MeasureChar | (optional) Measure the given char, this is used in conjunction with 'MeasureHeightPx' MeasureHeightPx | (optional) The expected height of the 'MeasureChar' if 'MeasureChar' is set. Can contain the following child elements: Child elements | Description ---------------------|------------------------- ElementConfig | (optional) Must be the first child. Overrides the default settings with the supplied ones (unset config elements will use the current default). ```xml ``` ##### AddImage Add a single image to the atlas. There can be zero to N of these. Name | Description ---------------------|------------------------- Path | The relative image path (will be combined with the atlas source path). If the path ends with *number*_dpi it will be interpreted as setting the dpi for the image. For example Test_480dpi.png will set the dpi to 480. If the Dpi attribute is specified as well and its a different value its considered a error. Dpi | (optional) Set the dpi for the added image TargetPath | (optional) Override the default scheme. **Not implemented.** The relative target path name (will be combined with the atlas source path) Can contain the following child elements: Child elements | Description ---------------------|------------------------- ElementConfig | (optional) Must be the first child. Overrides the default settings with the supplied ones (unset config elements will use the current default). AddAnchor | (optional) Add a number of anchor points as meta data. AddNineSlice | (optional) Add nine slice information. AddComplexPatch | (optional) Add complex patch information (experimental). ```xml ``` ###### AddAnchor Add anchor information for the image, this is additional meta data that can be associated with a image. Name | Description ---------------------|------------------------- Position | The position of the anchor in pixels. This can either be one point of a array of points. ```xml ``` ###### AddNineSlice Customize a image entry by adding nine-slice information (not compatible with the ".9" filename tag) Name | Description ---------------------|------------------------- NineSlice | The nine slice to apply. It must fit inside the image) ContentMargin | The nine slice content margin to apply It can be larger than the actual image as its only applied to the content put inside the nine-slice element. ```xml ``` ###### AddComplexPatch Customize a image entry by adding patch information (not compatible with the ".9" filename tag). This is a experimental new sprite type. Name | Description ---------------------|---------------------------------- SliceX | Horizontal slice points. SliceY | Vertical slice points. ContentSliceX | Horizontal content slice points. ContentSliceY | Vertical content slice points. Flags | Patch flags: MirrorX (mirrors the x slices), MirrorY (mirrors the y slices). Normal slice points describe how to slice the sprite and each slice point can be tagged with various flags. Example: ```xml ``` The slice point flags are: Flag|Description ----|----------- t |slice is transparent s |slice can be scaled The content slice point flags are: Flag|Description ----|----------- c |content slice ## Examples ### Example config file ```xml ``` ## Example command file ```xml ``` This creates the following atlases (if run with the example config file as well): * Atlas: UIAtlas/UIAtlas_160dpi * Texture atlas file: ```UIAtlas/UIAtlas_160dpi.png``` * Binary texture atlas ```UIAtlas/UIAtlas_160dpi.bta``` * Binary font info ```UIAtlas/UIAtlas_160dpi_Font.nbf``` * Merged license file ```UIAtlas/License.json``` (this will be a merge of all licenses in the atlas) * Atlas: UIAtlas/UIAtlas_320dpi * Texture atlas file: ```UIAtlas/UIAtlas_320dpi.png``` * Binary texture atlas ```UIAtlas/UIAtlas_320dpi.bta``` * Binary font info ```UIAtlas/UIAtlas_320dpi_Font.nbf``` * Merged license file ```UIAtlas/License.json``` (this will be a merge of all licenses in the atlas) * Atlas: UIAtlas/UIAtlas_480dpi * Texture atlas file: ```UIAtlas/UIAtlas_480dpi.png``` * Binary texture atlas ```UIAtlas/UIAtlas_480dpi.bta``` * Binary font info ```UIAtlas/UIAtlas_480dpi_Font.nbf``` * Merged license file ```UIAtlas/License.json``` (this will be a merge of all licenses in the atlas) * Atlas: UIAtlas/UIAtlas_640dpi * Texture atlas file: ```UIAtlas/UIAtlas_640dpi.png``` * Binary texture atlas ```UIAtlas/UIAtlas_640dpi.bta``` * Binary font info ```UIAtlas/UIAtlas_640dpi_Font.nbf``` * Merged license file ```UIAtlas/License.json``` (this will be a merge of all licenses in the atlas) * Atlas: *Font/NormalAtlas/FontAtlas* * Texture atlas file: ```Font/NormalAtlas/FontAtlas.png``` * Binary texture atlas ```Font/NormalAtlas/FontAtlas.bta``` * Binary font info ```Font/NormalAtlas/FontAtlas_Font.nbf``` * Merged license file ```Font/NormalAtlas/License.json``` (this will be a merge of all licenses in the atlas) * Atlas: *Font/SdfAtlas/FontAtlas* * Texture atlas file: ```Font/SdfAtlas/FontAtlas.png``` * Binary texture atlas ```Font/SdfAtlas/FontAtlas.bta``` * Binary font info ```Font/SdfAtlas/FontAtlas_Font.nbf``` * Merged license file ```Font/SdfAtlas/License.json``` (this will be a merge of all licenses in the atlas) * Atlas: *Magic* * Texture atlas file: ```Magic.png``` * Binary texture atlas ```Magic.bta``` * Merged license file ```License.json``` (this will be a merge of all licenses in the atlas) It also validates that the atlases UIAtlas/UIAtlas_160dpi, UIAtlas/UIAtlas_320dpi, Atlas: UIAtlas/UIAtlas_480dpi and UIAtlas/UIAtlas_640dpi contains the same image resources (same image path name) and the same meta data for each entry. ## License BSD-3 Clause "New" or "Revised" License