Texture Atlas Extension

The TexAtlasComponent of this extension manages a texture atlas that can be accessed from shaders. It is designed to be incorporated into Cogs materials so that the atlas can be draped over different geometries.

Specifying a source

The path property specifies the path template used for fetching tiles. Its syntax matches that of TileJSON 3.0.0's tile endpoint syntax, that is, the terms {x}, {y}, and {z} are replaced with corresponding integers, while the rest is interpreted verbatim.

Specifying the mapping

The domain of the map is assumed by a rectangle specified by domainMin and domainMax. The base tile has the domain [0,0]x[1,1].

The image of the map into world space is specified by:

• projection: Specifies how to interpret the coefficients array.
• coefficients: Specifies the world-space geometry of the map according to the given projection value:
  • For the WorldSpaceBilinear projection, coefficents should be the four world space corners ordered as [0,0], [1,0], [0,1], [1, 1].

Note that, for simplicity reasons, it is assumed that a tile is only visible at one place. This usually poses few problems except:

• The width or height of the domain exceeds 1, i.e. domain is set up as multiple copies of the base map. Just please don't.
• Your map spans a boundary of the base tile (typically the seam along the date line), then the base tile is two places on the screen. The fix is to bump minLevel to e.g. 1 so that the base tile is split into parts that is only visible once.

Specifying the elevation

Even though the map can be sampled at any elevation, the elevation has to be provided. This elevation is used to calculate refinement and culling of tiles, and providing the wrong elevation might give strange refinement and culling behaviour.

By enabling the debyugBox property, wireframe outlines of the actual tile geometry are rendered, which will reveal a wrong elevation.

Specifying the range of map level to use

The system will automatically pick a base level from the size of the domain so that that a tile will roughly match the domain size. This level is then subjected to minLevel and maxLevel to pin it to a certain range.

Since the system picks the base level, there should rarely be any need to explicitly set minLevel.

The maxLevel will in addition to restricting the base level also be a limit for the tile refinement.

Specifying refinement tolerance

The property tolerance specifies the desired tile texel width if the screen had the width of 1 (i.e. the actual screen size is factored out).

Integration

Material shader

A material can use up to four texture atlases at the same time. Each atlas has an index member that specifies which 'slot' this atlas occupies.

The shader that want's to look up the atlas include the file TexAtlasLookup.es30.glsl, which defines bool texAtlasLookup<N>(out vec4 color, in vec2 pos) for each active atlas slot <N>.

This function is passed an engine coord position and returns true if the atlas contain any data for this position, and in that case, the color output variable has been populated.

Client code

The client code must populate the materialInstances array with all material instances that use an atlas. Then the system will update the required material properties, variants, and textures.

Example

Cogs demo number 115 contains a full example of setting this up.