This is an overview of Tangram's styling system. For a complete technical reference of the custom style-creation system, see styles, and for all the technical details of drawing with those styles, see draw.
Draw styles are referenced in two places in the scene file: when defining custom styles and again in draw groups.
Tangram currently has five built-in base draw styles: polygons, lines, points, text, and raster. Each draw style displays data in a different way, and some of them require specific data types and properties.
For each base draw style, blend mode combo styles are also available with the naming pattern "blend_base", eg translucent_polygons, overlay_lines etc. For more information see blend.
The polygons draw style tessellates and extrudes vector shapes into 3D geometry. It requires polygonal data. See polygons.
The lines draw style can turn either polygonal or line data into lines. See lines.
The points draw style draws a filled circle at the location of the data point. It can work with point data, lines, or polygons. Points will "collide" with each other, with only the winner being drawn, determined by the priority draw parameter.
[JS only] Only points from the same datasource will collide with each other.
Technically, this draw style creates a small quad, which is then colored with a default shader which draws a dot. This behavior can be overridden with either a custom shader or a texture.
See points.
The text draw style draws text labels at a given point. It can work with point, line, or polygon data. When used with lines, the label will be drawn along the line. When used with polygons, the label will be drawn at the polygon's centroid. Text labels will "collide" with each other, with only the winner being drawn, determined by the priority draw parameter.
[JS only] Only text elements from the same datasource will collide with each other.
See text.
The raster draw style draws one tile-sized square per tile and paints it with the appropriate tile from a Raster data source. See raster.
These built-in draw styles are used as the foundation for all custom styling in Tangram. When writing an inline style under a layer, they are referenced in draw groups, in one of two ways:
A draw group with a custom name may reference a style by name with the style parameter:
roads:
draw:
my_style:
style: polygons
color: blueOr, if a draw group is named for one of the draw styles, the style parameter may be omitted:
roads:
draw:
polygons:
color: blue
lines:
color: redBy defining multiple draw groups the same feature may be drawn using multiple styles simultaneously:
roads:
draw:
polygons:
color: blue
lines:
color: redWhen defining a custom style, the built-in draw groups are explicitly referenced under the new style name with the base parameter:
styles:
buildings:
base: polygonsIn this way, custom styles may "extend" the behavior or the built-in draw styles.
The polygons draw style requires a datasource containing coordinates connected by lines into a "closed" shape. If the lines of the polygon start and stop at different places, it is an "open" shape, and the polygons draw style can't use it. But if a sequence of lines connects back onto its own starting point, it is considered "closed", and can be extruded into a 3D shape.
Styles which are extensions of the polygons draw style can take the following parameters:
Draw groups which use the polygons draw style must specify, at minimum, the following parameters in order to be drawn:
The lines style requires a datasource containing connected coordinates. Thus it can accept either linear or polygonal input data. It draws a rectangle along each line segment, and can optionally draw special join and cap styles.
Styles which are extensions of the lines draw style can take the following parameters:
Draw groups which use the lines draw style must specify, at minimum, the following parameters in order to be drawn:
The points draw style is used to draw dots or sprites at points of interest. It also builds a rectangle at a point, and can be colored in a variety of ways:
- with a special shader designed to draw a circle
- with a
texture - with a
spritefrom atexture
If the point is used to draw a dot, the size and color of this circle can be specified in the scene file with the size and color parameters.
points and text have a special relationship, which is useful for creating custom labels and icons. They will also collide with each other – the "winner" is drawn and the "loser" is not, as determined by the priority draw parameter.
[JS only] Only points and text elements from the same datasource will collide with each other.
Draw groups which use the points draw style must specify, at minimum, the following parameters in order to be drawn:
The text style is similar to the sprites style, in that it builds a rectangle at a point. However, instead of being colored with a custom texture, this style builds its own texture, containing text.
The content of the text is based on the text_source parameter. The style of the text is specified by the font parameters.
Styles which are extensions of the text style can take the following special parameters:
font: Sets font's typeface, style, size, color, and outline.text_source: Determines label text, defaults to the feature'snameproperty.priority: Sets the priority of the label relative to other labels and points/sprites.align: Controls text alignment.anchor: Controls text's relative positioning.offset: Controls text's position offset.text_wrap: Sets number of characters before text wraps to multiple lines.repeat_distance: Sets the distance beyond which label text may repeat.repeat_group: Optional grouping mechanism for fine-grained control over text repetition.collide: Sets whether label collides with other labels or points/sprites.move_into_tile: Increases number of labels that will display, by moving some to fit within tile bounds (JS-only)
These parameters are described in the draw entry.
Draw groups which use the text draw style must specify, at minimum, the following parameters in order to be drawn:
The raster style renders Raster data sources, such as traditional raster tiles.
Note that Raster sources can also be used by other styles, by "attaching" the sources to the styles with the rasters parameter. See the Rasters Overview.
The mix parameter copies the properties of the named style (or styles) to a new style. In this way, new styles can be "forked" from existing styles.
This allows styles to be made which vary only slightly from each other, without having to manually duplicate everything else in the style code. It also allows a style to act as a "base" or "foundation" style, to be mixed into others.
The following example creates a style named "geo2" by copying all the properties of the "geo" style:
styles:
geo:
base: polygon
geo2:
mix: geoThese two styles are identical.
Once you've mixed in a style, you can add or modify any properties you like.
For example, you could create a new style called styleB that "inherits from" an existing style called styleA, and then adds custom shader blocks:
styleB:
mix: styleA
shaders:
blocks:
color: ...Or you could mix in an existing style, but disable lighting:
fancy-but-no-lighting:
base: fancy
lighting: falseYou can even modify the mix'ed-in style's base. For example, if you have a polygon-based style with custom shader blocks that you want to apply to lines instead, you can create a line-based version like this:
fancy-lines:
mix: fancy-polygons
base: lines # change the base to linesNote that in this case, any properties which were special to the polygons draw style will still be copied, but will be ignored by the renderer.
The mix parameter can also be given a list of styles – this makes it possible to mix multiple effects together, e.g. to apply both the windows and halftone effects simultaneously:
halftone-windows:
mix: [ windows, halftone ]Styles in a list will be copied in the order listed – so if a property is common to multiple named styles, styles named last in the list will take precedence.
styles:
custom:
mix: [styleA, styleB, styleC]Here, styleC's properties will override any it has in common with the other listed styles.