https://github.com/oguzeroglu/texturemerger
A lightweight library that creates a Texture Atlas from Three.js textures
https://github.com/oguzeroglu/texturemerger
game-development texture threejs webgl
Last synced: 9 months ago
JSON representation
A lightweight library that creates a Texture Atlas from Three.js textures
- Host: GitHub
- URL: https://github.com/oguzeroglu/texturemerger
- Owner: oguzeroglu
- License: mit
- Created: 2020-04-10T09:54:27.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-06-30T02:37:14.000Z (over 3 years ago)
- Last Synced: 2025-04-03T21:07:54.860Z (11 months ago)
- Topics: game-development, texture, threejs, webgl
- Language: JavaScript
- Homepage:
- Size: 267 KB
- Stars: 88
- Watchers: 5
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TextureMerger
TextureMerger is a lightweight client-side Javascript library that generates a [texture atlas](https://en.wikipedia.org/wiki/Texture_atlas) from provided Three.js textures and calculates the UV coordinates for each texture inside the atlas.
TextureMerger produces power-of-two textures, so the atlas generated by TextureMerger [can be compressed](https://en.wikipedia.org/wiki/Texture_compression).
Ported from [TextureMerger class](https://github.com/oguzeroglu/ROYGBIV/blob/master/js/handler/TextureMerger.js) of [ROYGBIV Engine](https://github.com/oguzeroglu/ROYGBIV).
## What can you do with it?
You can pack your textures into one big texture, share the texture uniform across different meshes to gain performance. You can also pack different textures of a single mesh (emissive texture, displacement texture etc.) into a one texture for only one mesh.
## Example
Check out [this live example](https://oguzeroglu.github.io/TextureMerger/example/example.html).
In this example a single Texture Atlas is shared by 4 different meshes, however each of these meshes look like they have a separate texture mapped.
## Usage
### Include the library in your HTML
```HTML
```
### Merge your Textures
```Javascript
var texture1, texture2, texture3; // Both instances of THREE.Texture
loadTextures(); // Your texture loading logic
var textureMerger = new TextureMerger({
texture1: texture1,
texture2: texture2,
texture3: texture3
});
var atlas = textureMerger.mergedTexture;
var ranges = textureMerger.ranges;
console.log(ranges);
```
Prints:
```Javascript
{
texture1: {startU: 0, endU: 0.25, startV: 1, endV: 0.6},
texture2: {startU: ..., endU: ..., startV: ..., endV: ...},
texture3: {startU: ..., endU: ..., startV: ..., endV: ...}
}
```
### In your shader
**Note**: Instead of doing the calculation in the shader, you can directly modify the original UV values of geometry as well. In this case, you don't have to write custom shaders. Live demo also uses this approach.
Pass textureMerger.mergedTexture to your shader as a Texture uniform. Pass the range of related texture as an attribute or uniform.
For **gl.POINTS**
```GLSL
float coordX = ((gl_PointCoord.x) * (endU - startU)) + startU;
float coordY = ((1.0 - gl_PointCoord.y) * (endV - startV)) + startV;
vec4 textureColor = texture2D(texture, vec2(coordX, coordY));
```
For the rest:
```GLSL
// affine transformation on original UV of a vertex
float coordX = (uv.x * (endU - startU) + startU);
float coordY = (uv.y * (startV - endV) + endV);
vec4 textureColor = texture2D(texture, vec2(coordX, coordY));
```
## Prevent Texture Bleeding
Texture Bleeding is a common problem for visual applications that rely on Texture Atlases. In order to overcome this problem you can use [Half-texel edge correction method](http://drilian.com/2008/11/25/understanding-half-pixel-and-half-texel-offsets/):
In your vertex shader:
```GLSL
// Instead of the original uvCoordinates, pass the return value
// of this function to your Fragment Shader.
// uvCoordinates: [startU, startV, endU, endV]
vec4 fixTextureBleeding(vec4 uvCoordinates){
// TEXTURE_SIZE is the size of each Atlas entry.
// For instance if you created a Texture Atlas from 128x128
// textures, TEXTURE_SIZE would be 128.
float offset = 0.5 / float(TEXTURE_SIZE);
return vec4(uvCoordinates[0] + offset, uvCoordinates[1] - offset, uvCoordinates[2] - offset, uvCoordinates[3] + offset);
}
```
## License
TextureMerger uses MIT license.