Optional alpha parameter for draw groups

[bcamper]

This PR adds a new alpha parameter inside several draw group contexts. It allows the scene author to set only the alpha channel of a color, independently of the RGB channels.

Use cases where this is helpful include:

• Modifying the alpha for named CSS colors
• Modifying the alpha channel in a sub-layer, which can simplify complex layer trees or help with cases where you may be importing/overriding another style, or applying "themes" that change the underlying base colors
• Using a feature property to set the color, but then modifying only the alpha (note, this was not easily achievable before in cases where a feature property might contain a hex or CSS named color), e.g. use transit line colors encoded in tiles, but draw lines at 75% opacity

Syntax

• Applies to the following styles in draw groups, where the alpha parameter, if present, will override the alpha channel set by the corresponding color parameter:
  • polygons:
    • polygon fill color: color
    • example:

    translucent_polygons:
      color: red
      alpha: 0.5 # red polygon with 50% opacity
    

  • lines:
    • line fill color: color
    • outline color (inside outline block): color
    • example:

   overlay_lines:
     color: function() { return feature.colour_name; }
     alpha: 0.75 # color by a feature property but set 75% opacity
  

  • points:
    • point fill color: color
    • outline color (inside outline block): color
    • font fill/stroke for attached labels as described below, inside a text block
    • example:

    # points with a 25% opacity yellow fill, and a 50% opacity blue outline
    points:
      color: yellow
      alpha: 0.25
      outline:
        color: blue
        alpha: 0.5
        width: 4px
    

  • text
    • font fill color (inside font block): fill
    • font stroke color (inside font.stroke block): color
    • example:

    text:
      font:
        fill: black
        alpha: 0.5 # black fill with 50 opacity%
        stroke: { color: red, alpha: 0.25 } # red stroke with 25% opacity
    

• alpha values can be set by:
  • Single value: alpha: 0.5
  • Zoom interpolated values: alpha: [[14, 0.5], [16, 1]] (fade in opacity from z14-16)
  • JS function: alpha: function(){ return feature.height/200; } (set building opacity by height)
• In cases where a color value is required, the alpha parameter has no effect if no color is specified. In cases where a default color applies, the alpha parameter will modify the default color if no color is specified.
• The alpha parameter inherits through sub-layers like any other draw parameter, and does not need to be defined at the same depth as a color it modifies; it will modify the nearest ancestor layer where color is defined.

  depth1:
    draw:
      points: { color: red, alpha: 0.5} # these features render w/color [1, 0, 0, 0.5]
  
    depth2:
      draw:
        points: { alpha: 0.25 } # these features render w/color [1, 0, 0, 0.25]
  

• As with other parameters, it is not additive or compounding across layers: in the example, any features rendered at depth2 will have 25% alpha (no interaction with the 50% value from the parent layer).
• If a sub-layer sets alpha: null, it un-sets any value set by an ancestor layer. The color's alpha channel returns to its original, unmodified value.

  depth1:
    draw:
      points: { color: red, alpha: 0.5} # these features render w/color [1, 0, 0, 0.5]
  
    depth2:
      draw:
        points: { alpha: null } # these features render w/full opacity, color [1, 0, 0, 1]
  

• NOTE: for polygons and lines, alpha channel is only applicable for appropriate blend modes (translucent, overlay, etc.), and is not intended to be used with the default opaque blending.

[bcamper]

It's possible the alpha support for font fill and stroke is overkill, though it led to me having some fun with fonts... :D

[bcamper]

cc @matteblair @meetar @sensescape @burritojustice @nvkelso @tallytalwar for comment.

[meetar]

@bcamper Looks great from here! Couple of questions about the PR description:

In cases where a color value is required, the alpha parameter has no effect if no color is specified.

This is because nothing will draw, correct? So this line is clarifying that there won't be some kind of default color applied in order to apply an alpha to it.

If a sub-layer sets alpha: null, it un-sets any value set by an ancestor layer. The color's alpha channel returns to its original, unmodified value.

Are there cases where the "original unmodifed value" could be something other than 1.0?

[bcamper]

@meetar:

In cases where a color value is required, the alpha parameter has no effect if no color is specified.

This is because nothing will draw, correct? So this line is clarifying that there won't be some kind of default color applied in order to apply an alpha to it.

Yep, that's right, feel free to help clarify the language if you have suggestions.

If a sub-layer sets alpha: null, it un-sets any value set by an ancestor layer. The color's alpha channel returns to its original, unmodified value.

Are there cases where the "original unmodifed value" could be something other than 1.0?

For sure! Any time color sets an alpha already, like this:

depth1:
  draw:
    points:
      color: [1, 0, 0, 0.25] # renders at 25% opacity

  depth2:
    draw:
      points:
        alpha: 0.5 # overrides color, renders at 50% opacity

    depth3:
      draw:
        points:
          alpha: null # back to the original 25% opacity

I should have put in an example where it is very explicitly overriding, even at one level, like:

  draw:
    points:
      color: [1, 0, 0, 0.25]
      alpha: 0.5 # overrides color, features will render w/50% opacity

Basically, whenever alpha is present, it overrides the color alpha. All the other behavior, including the alpha: null "un-set", falls out of the regular draw group and import merging (because an explicitly set null gets merged on top of others, like any other value).

[meetar]

LGTM! 👍

[matteblair]

Looks good! I don't see any problems implementing this in Tangram ES too.

[tallytalwar]

Again, 👏 on the great description @bcamper. Sorry couldn't jump on this before. But looks good to me too.