public class TextureAtlas
extends java.lang.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);
| Modifier and Type | Class and Description |
|---|---|
class |
TextureAtlas.TextureAtlasTile |
| Constructor and Description |
|---|
TextureAtlas(int width,
int height) |
| Modifier and Type | Method and Description |
|---|---|
boolean |
addGeometry(Geometry geometry)
Add a geometries DiffuseMap (or ColorMap), NormalMap and SpecularMap to the atlas.
|
boolean |
addTexture(Texture texture,
java.lang.String mapName)
Add a texture for a specific map name
|
void |
addTexture(Texture texture,
java.lang.String mapName,
java.lang.String sourceTextureName)
Add a texture for a specific map name at the location of another existing texture (on the master map).
|
void |
addTexture(Texture texture,
java.lang.String mapName,
Texture masterTexture)
Add a texture for a specific map name at the location of another existing texture on the master map.
|
boolean |
applyCoords(Geometry geom)
Applies the texture coordinates to the given geometry
if its DiffuseMap or ColorMap exists in the atlas.
|
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.
|
static TextureAtlas |
createAtlas(Spatial root,
int atlasSize)
Create a texture atlas for the given root node, containing DiffuseMap, NormalMap and SpecularMap.
|
Texture |
getAtlasTexture(java.lang.String mapName)
Creates a new atlas texture for the given map name.
|
TextureAtlas.TextureAtlasTile |
getAtlasTile(Texture texture)
Get the
TextureAtlasTile for the given Texture |
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.
|
public boolean addGeometry(Geometry geometry)
geometry - the Geometry to be added (not null)public boolean addTexture(Texture texture, java.lang.String mapName)
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.public void addTexture(Texture texture, java.lang.String mapName, Texture masterTexture)
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.public void addTexture(Texture texture, java.lang.String mapName, java.lang.String sourceTextureName)
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.public TextureAtlas.TextureAtlasTile getAtlasTile(Texture texture)
TextureAtlasTile for the given Texturetexture - The texture to retrieve the TextureAtlasTile for.public Texture getAtlasTexture(java.lang.String mapName)
mapName - the desired namepublic boolean applyCoords(Geometry geom)
geom - The geometry to change the texture coordinate buffer on.public boolean applyCoords(Geometry geom, int offset, Mesh outMesh)
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).public static TextureAtlas createAtlas(Spatial root, int atlasSize)
root - The rootNode to create the atlas for.atlasSize - The size of the atlas (width and height).public static Geometry makeAtlasBatch(Spatial spat, AssetManager mgr, int atlasSize)
spat - The root spatial of the scene to batchmgr - 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.