This is the technical documentation for Tangram's textures block. For the JS-only draw-level parameter, see texture. 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

When a texture is defined in the top-level textures element, it is declared with 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

Outside of the textures element, a new texture may be defined inline by providing a URL instead of a texture name:

# defining a new texture inline
styles:
    rock:
        base: polygons
        material:
            normal:
                texture: images/rock.jpg
                mapping: uv

These textures will use the default parameters described below. To use custom parameters for a texture, you must declare it in the textures element.

If a texture is provided for a lines style, the texture is repeated across the line, with the width of the texture matching the width of the line, and the texture y coordinate scaled to match the aspect ratio of the image (its height over its width).

draw group texture parameter

Textures may also be assigned, re-assigned, or un-assigned per draw group with Tangram-JS only – see texture.

texture parameters

url

Optional string, though either url or element is required (JS-only. This element is required for ES). Specifies the path to a texture source file. No default.

URLs can be absolute or relative.

textures:
    ghost:
        url: demos/images/ghost.png
textures:
    ghost:
        url: http://ghostimages.com/ghost.png

density

Optional number. Default is 1.

Indicates the intended native pixel density of the texture, to allow the texture to be drawn correctly at various display densities. The number is effectively used as a devisor when calculating display pixels.

This is specifically useful when style rules don't explicitly define the size of a sprite.

textures:
    pois:
        url: pois.png
        density: 2 # authored at 2x resolution
        sprites:
            # define sprites: [x origin, y origin, width, height]
            airport: [0, 0, 64, 64]
            ...

In the example above, the sprite will be drawn as a 32-pixel square.

element

[JS-only] Optional string, though either url or element is required. Specifies a CSS element selector string. No default.

This parameter allows an HTML element to be used as the source of the texture, as identified by a CSS selector string.

For example, this canvas element:

<canvas class='awesome-texture'>

Can be referenced as:

textures:
    awesome-texture:
        element: .awesome-texture

You can also reference an element by id, but the use of # in CSS means the YAML must be quoted so it's not interpreted as a YAML comment:

<canvas id='texture-id'>

textures:
    awesome-texture:
        element: '#texture-id' # no comment!

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.

textures:
    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.

For using sprites in draw styles, see sprite.

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.

textures:
    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]

For using sprites in draw styles, see sprite.