styles.md

This is the technical documentation for Tangram's styles object. For a conceptual overview of the styling system, see the Styles Overview.

####styles The styles element is an optional top-level element in the scene file. It takes only one kind of element, a named style object.

Styles defined under this element can be referenced by name inside a draw group with the style parameter.

styles:
    buildings-style:
        base: polygons
        shaders: ...

buildings:
    draw:
        polygons:
            style: buildings-style

style name

Required string, can be anything. No default.

A custom style must specify either a base or mix parameter, or both.

Defines a new custom style.

styles:
    buildings:
        base: polygons

style parameters

####base Optional string, naming one of the built-in draw styles. No default.

Defines the expected input geometry of the custom style, which determines what other kinds of parameters the style can take. Tangram's built-in styles are polygons, lines, points, and text. No default.

styles:
    geo:
        base: polygons
    icons:
        base: points

For more, see the Styles Overview.

####mix Optional string or list, naming one or more custom styles. No default.

Copies properties from other custom styles.

styles:
    geo-variant:
        mix: geo

Can also be used to combine multiple styles:

styles:
    custom:
        mix: [styleA, styleB, styleC]

For more, see the Styles Overview.

####animated Optional boolean, true or false. When true, the renderer will attempt to redraw the style every frame.

styles:
    water:
        base: polygons
        animated: true

####blend Optional string, one of add, multiply, overlay, or inlay. The points and text draw styles have a default blend value of overlay – the polygons and lines draw styles have no default, and no blending will be applied to them if this parameter is not specified.

When set, features drawn with this style will be composited into the scene using the method specified, for a transparent effect.

The overlay and inlay blend modes apply traditional transparency using the alpha channel. Features drawn with overlay will be appear on top of the scene (irrespective of the order property), similar to a heads-up display. This is useful for compositing labels on top of the scene. inlay will cause features to be interwoven into the scene at an appropriate depth, according to their order value. To illustrate the difference: a street label drawn with overlay will be visible over any geometry covering the street, such as a nearby building, while a label drawn with inlay will display behind the building (but will still be partially visible where it is not covered by the building).

add and multiply apply Photoshop-filter-like operations: features composited with add will tend to accumulate toward white, and multiply will tend to acculumate toward black.

styles:
    glass:
        base: polygons
        blend: multiply

####lighting Optional string, one of fragment, vertex, or false. Sets the lighting type of the style. Default is fragment.

• fragment: lighting will be calculated once per pixel.
• vertex: lighting will be calculated once per vertex, and values between vertices will be interpolated.
• false: lighting will not be calculated.

styles:
    flat_polygons:
        base: polygons
        lighting: false

####texture Optional URL, texture object, or named texture on the "points" draw style. No default.

Assigns a texture for use as the color of the point.

styles:
    ghosts:
        base: points
        texture: images/ghost.png

For more, see textures#texture.

####texcoords Optional boolean, true or false. When true, the geometry will be assigned texture coordinates, for use with texture objects in combination with the mapping parameter – for more, see textures.

styles:
    monsters:
        base: points
        texcoords: true

####shaders Optional string. Begins the shaders definition object. For more on materials, see the shaders technical reference.

styles:
    buildings:
        base: polygons
        shaders:
            blocks:
            ...

####material Optional parameter. Starts a material definition block. For more on materials, see the materials technical reference.

styles:
    landuse:
        base: polygons
        material:
            ...

####url Optional URL. Imports a style definition from a URL. The URL should point to a YAML file that includes one or more style definitions, in the same format they appear under the top-level styles element in the scene file.

styles:
    halftone:
        url: halftone.yaml

In halftone.yaml:

halftone:
    base: polygons
    ...