Package jme3tools.optimize

Class TextureAtlas

java.lang.Object
jme3tools.optimize.TextureAtlas
public class TextureAtlas extends Object
TextureAtlas allows combining multiple textures to one texture atlas.

After the TextureAtlas has been created with a certain size, textures can be added for freely chosen "map names". The textures are automatically placed on the atlas map and the image data is stored in a byte array for each map name. Later each map can be retrieved as a Texture to be used further in materials.

The first map name used is the "master map" that defines new locations on the atlas. Secondary textures (other map names) have to reference a texture of the master map to position the texture on the secondary map. This is necessary as the maps share texture coordinates and thus need to be placed at the same location on both maps.

The helper methods that work with Geometry objects handle the DiffuseMap or ColorMap as the master map and additionally handle NormalMap and SpecularMap as secondary maps.

The textures are referenced by their asset key name and for each texture the location inside the atlas is stored. A texture with an existing key name is never added more than once to the atlas. You can access the information for each texture or geometry texture via helper methods.

The TextureAtlas also allows you to change the texture coordinates of a mesh or geometry to point at the new locations of its texture inside the atlas (if the texture exists inside the atlas).

Note that models that use texture coordinates outside the 0-1 range (repeating/wrapping textures) will not work correctly as their new coordinates leak into other parts of the atlas and thus display other textures instead of repeating the texture.

Also note that textures are not scaled and the atlas needs to be large enough to hold all textures. All methods that allow adding textures return false if the texture could not be added due to the atlas being full. Furthermore secondary textures (normal, specular maps etc.) have to be the same size as the main (e.g. DiffuseMap) texture.

Usage examples

Create one geometry out of several geometries that are loaded from a j3o file: 
 Node scene = assetManager.loadModel("Scenes/MyScene.j3o");
 Geometry geom = TextureAtlas.makeAtlasBatch(scene);
 rootNode.attachChild(geom);
Create a texture atlas and change the texture coordinates of one geometry: 
 Node scene = assetManager.loadModel("Scenes/MyScene.j3o");
 //either auto-create from node:
 TextureAtlas atlas = TextureAtlas.createAtlas(scene);
 //or create manually by adding textures or geometries with textures
 TextureAtlas atlas = new TextureAtlas(1024,1024);
 atlas.addTexture(myTexture, "DiffuseMap");
 atlas.addGeometry(myGeometry);
 //create material and set texture
 Material mat = new Material(mgr, "Common/MatDefs/Light/Lighting.j3md");
 mat.setTexture("DiffuseMap", atlas.getAtlasTexture("DiffuseMap"));
 //change one geometry to use atlas, apply texture coordinates and replace material.
 Geometry geom = scene.getChild("MyGeometry");
 atlas.applyCoords(geom);
 geom.setMaterial(mat);

  • Constructor Details

    • TextureAtlas

      public TextureAtlas(int width, int height)

  • Method Details

    • addGeometry

      public boolean addGeometry(Geometry geometry)
      Add a geometries DiffuseMap (or ColorMap), NormalMap and SpecularMap to the atlas.
      Parameters:
      geometry - the Geometry to be added (not null)
      Returns:
      false if the atlas is full.

    • addTexture

      public boolean addTexture(Texture texture, String mapName)
      Add a texture for a specific map name
      Parameters:
      texture - A texture to add to the atlas.
      mapName - A freely chosen map name that can be later retrieved as a Texture. The first map name supplied will be the master map.
      Returns:
      false if the atlas is full.

    • addTexture

      public void addTexture(Texture texture, String mapName, Texture masterTexture)
      Add a texture for a specific map name at the location of another existing texture on the master map.
      Parameters:
      texture - A texture to add to the atlas.
      mapName - A freely chosen map name that can be later retrieved as a Texture.
      masterTexture - The master texture for determining the location, it has to exist in tha master map.

    • addTexture

      public void addTexture(Texture texture, String mapName, String sourceTextureName)
      Add a texture for a specific map name at the location of another existing texture (on the master map).
      Parameters:
      texture - A texture to add to the atlas.
      mapName - A freely chosen map name that can be later retrieved as a Texture.
      sourceTextureName - Name of the master map used for the location.

    • getAtlasTile

      public TextureAtlas.TextureAtlasTile getAtlasTile(Texture texture)
      Get the TextureAtlasTile for the given Texture
      Parameters:
      texture - The texture to retrieve the TextureAtlasTile for.
      Returns:
      the atlas tile

    • getAtlasTexture

      public Texture getAtlasTexture(String mapName)
      Creates a new atlas texture for the given map name.
      Parameters:
      mapName - the desired name
      Returns:
      the atlas texture

    • applyCoords

      public boolean applyCoords(Geometry geom)
      Applies the texture coordinates to the given geometry if its DiffuseMap or ColorMap exists in the atlas.
      Parameters:
      geom - The geometry to change the texture coordinate buffer on.
      Returns:
      true if texture has been found and coords have been changed, false otherwise.

    • applyCoords

      public boolean applyCoords(Geometry geom, int offset, Mesh outMesh)
      Applies the texture coordinates to the given output mesh if the DiffuseMap or ColorMap of the input geometry exist in the atlas.
      Parameters:
      geom - The geometry to change the texture coordinate buffer on.
      offset - Target buffer offset.
      outMesh - The mesh to set the coords in (can be same as input).
      Returns:
      true if texture has been found and coords have been changed, false otherwise.

    • createAtlas

      public static TextureAtlas createAtlas(Spatial root, int atlasSize)
      Create a texture atlas for the given root node, containing DiffuseMap, NormalMap and SpecularMap.
      Parameters:
      root - The rootNode to create the atlas for.
      atlasSize - The size of the atlas (width and height).
      Returns:
      Null if the atlas cannot be created because not all textures fit.

    • makeAtlasBatch

      public static Geometry makeAtlasBatch(Spatial spat, AssetManager mgr, int atlasSize)
      Creates one geometry out of the given root spatial and merges all single textures into one texture of the given size.
      Parameters:
      spat - The root spatial of the scene to batch
      mgr - An asset manager that can be used to create the material.
      atlasSize - A size for the atlas texture, it has to be large enough to hold all single textures.
      Returns:
      A new geometry that uses the generated texture atlas and merges all meshes of the root spatial, null if the atlas cannot be created because not all textures fit.