textures.md

This is the technical documentation for Tangram's textures block. For an overview of the ways textures can be used by Tangram, see the Materials Overview.

##textures The textures element is an optional top-level element in the scene file. It has only one kind of sub-element: a named texture object.

textures:
    pois:
        url: demos/images/marker.png
    brick:
        url: demos/images/brick.jpg

####texture Optional _named texture, URL, or texture object. No default.

A texture object may be defined either in the top-level textures element or inline.

When defined in the top-level textures element, it is declared as a texture name which allows it to be referenced by name in other texture parameters, including in styles and materials definitions:

# here we define and name the texture
textures:
    pois:
        url: images/poi_icons_18@2x.png

# here we reference the above texture
styles:
    pois-style:
        base: points
        texture: pois

A texture object may also be defined inline, anywhere a texture parameter may be specified:

# defining a texture 
styles:
    rock:
        base: polygons
        material:
            normal:
                texture:
                    url: rock.jpg
                mapping: uv

# defining a texture inline in the texture parameter of a style based on points
styles:
    animals-style:
        base: points
        texture:
            url: path/to/image.png
            filtering: mipmap
            sprites:
                bunny: [0, 0, 32, 32]
                fox: [0, 32, 32, 32]

Whether defined in the textures element or inline, at a minimum, a URL must be passed:

textures:
    ghost:
        url: images/ghost.png

styles:
    points:
        texture: images/ghost.png

texture parameters

####url Required string. Defines the path to an image file. No default.

URLs can be absolute or relative.

    ghost:
        url: demos/images/ghost.png

    ghost:
        url: http://ghostimages.com/ghost.png

filtering

Optional string, one of linear, nearest, or mipmap. Defaults to linear.

Sets the filtering mode for the texture, which determines quality at various zoom levels.

    ghost:
        url: demos/images/ghost.png
        filtering: mipmap

sprites

Optional parameter. Defines the start of a sprites block.

sprites take only one kind of parameter: the sprite name. Any number of sprites may be defined.

sprite name

Required string. Can be anything. No default.

Defines an area of a texture to be used as an individual sprite, as [x origin, y origin, width, height] in pixels.

    pois:
        url: demos/images/poi_icons_32.png
        filtering: mipmap
        sprites:
            airport: [0, 0, 32, 32]
            restaurant: [0, 777, 32, 32]
            cafe: [0, 814, 32, 32]
            museum: [0, 518, 32, 32]