shamansir / elm-canvas / Canvas.Settings.Advanced

Advanced rendering settings

The following are settings that you can apply, to create very specific and custom effects.

Gradient

The gradient setting allows you to use linear or radial gradients for fill or stroke.


type alias LinearGradient =
{ x0 : Basics.Float
, y0 : Basics.Float
, x1 : Basics.Float
, y1 : Basics.Float 
}

Linear gradient definition.


type alias RadialGradient =
{ x0 : Basics.Float
, y0 : Basics.Float
, rad0 : Basics.Float
, x1 : Basics.Float
, y1 : Basics.Float
, rad1 : Basics.Float 
}

Radial gradient definition.

fillLinear : LinearGradient -> List ( Basics.Float, Color ) -> Canvas.Internal.Canvas.Setting

Fill with linear gradient.

fillRadial : RadialGradient -> List ( Basics.Float, Color ) -> Canvas.Internal.Canvas.Setting

Fill with radial gradient.

strokeLinear : LinearGradient -> List ( Basics.Float, Color ) -> Canvas.Internal.Canvas.Setting

Stroke with linear gradient.

strokeRadial : RadialGradient -> List ( Basics.Float, Color ) -> Canvas.Internal.Canvas.Setting

Stroke with radial gradient.

Shadows

The shadow setting allows you to create a shadow for a renderable, similar to what the box-shadow CSS does to HTML elements.

A word of caution, shadows have a non-trivial performance cost, so use them wisely.

shadow : Shadow -> Canvas.Internal.Canvas.Setting

Specify a shadow to be rendered. See the Shadow type alias to know what parameters to pass.


type alias Shadow =
{ blur : Basics.Float
, color : Color
, offset : ( Basics.Float
, Basics.Float ) 
}

Record with the settings for a shadow.

Transforms: scaling, rotating, translating, and matrix transformations

Transforms are very useful as they allow you to manipulate the rendering via a transformation matrix, allowing you to translate, scale, rotate and skew the rendering context easily. They can be a bit of an advanced topic, but they are powerful and can be very useful.

When using transforms, keep in mind you are working on the global coordinate system, since it very hard to know what the center of your shape is to give sensible defaults.

transform : List Transform -> Canvas.Internal.Canvas.Setting

Specify the transform matrix to apply when drawing. You do so by applying transforms in order, like translate, rotate, or scale, but you can also use applyMatrix and set the matrix yourself manually if you know what you are doing.

shapes
    [ transform [ rotate (degrees 50) ] ]
    [ rect ( 40, 40 ) 20 20 ]


type Transform
    = Rotate Basics.Float
    | Scale Basics.Float Basics.Float
    | Translate Basics.Float Basics.Float
    | ApplyMatrix ({ m11 : Basics.Float, m12 : Basics.Float, m21 : Basics.Float, m22 : Basics.Float, dx : Basics.Float, dy : Basics.Float })

Type of transform to apply to the matrix, to be used in transform. See the functions below to learn how to create transforms.

translate : Basics.Float -> Basics.Float -> Transform

Adds a translation transformation by moving the canvas and its origin x units horizontally and y units vertically on the grid.

More information and examples on the MDN docs

translate x y

rotate : Basics.Float -> Transform

Adds a rotation to the transformation matrix. The angle argument represents a clockwise rotation angle and is expressed in radians. Use the core function degrees to make it easier to represent the rotation.

rotate (degrees 90)

The rotation center point is always the canvas origin. To change the center point, we will need to move the canvas by using the translate transform before rotating. For example, a very common use case to rotate from a specific point in the canvas, maybe the center of your renderable, would be done by translating to that point, rotating, and then translating back, if you want to apply more transformations. Like this:

transform
    [ translate x y
    , rotate rotation
    , translate -x -y

    {- Other transforms -}
    ]

See the MDN docs for more information and examples.

scale : Basics.Float -> Basics.Float -> Transform

Adds a scaling transformation to the canvas units by x horizontally and by y vertically.

By default, one unit on the canvas is exactly one pixel. If we apply, for instance, a scaling factor of 0.5, the resulting unit would become 0.5 pixels and so shapes would be drawn at half size. In a similar way setting the scaling factor to 2.0 would increase the unit size and one unit now becomes two pixels. This results in shapes being drawn twice as large.

scale x y

Note: You can use scale -1 1 to flip the context horizontally and scale 1 -1 to flip it vertically.

More information and examples in the MDN docs

applyMatrix : { m11 : Basics.Float, m12 : Basics.Float, m21 : Basics.Float, m22 : Basics.Float, dx : Basics.Float, dy : Basics.Float } -> Transform

Multiplies the current transformation with the matrix described by the arguments of this method. You are able to scale, rotate, move and skew the context.

Alpha, image smoothing and global composite mode

Finally, there are a couple of other settings that you can use to create interesting visual effects:

alpha : Basics.Float -> Canvas.Internal.Canvas.Setting

Specifies the alpha value that is applied before renderables are drawn onto the canvas. The value is in the range from 0.0 (fully transparent) to 1.0 (fully opaque). The default value is 1.0. Values outside the range, including Infinity and NaN will not be set and alpha will remain default.

imageSmoothing : Basics.Bool -> Canvas.Internal.Canvas.Setting

Specify if scaled images are smoothed (default) or not.

This property is useful for games and other apps that use pixel art. When enlarging images, the default resizing algorithm will blur the pixels. Set this property to false to retain the pixels' sharpness.

compositeOperationMode : GlobalCompositeOperationMode -> Canvas.Internal.Canvas.Setting

Specify the type of compositing operation to apply when drawing new entities, where type is a GlobalCompositeOperationMode identifying which of the compositing or blending mode operations to use.

See GlobalCompositeOperationMode below for more information.

compositeOperationMode Screen


type GlobalCompositeOperationMode
    = SourceOver
    | SourceIn
    | SourceOut
    | SourceAtop
    | DestinationOver
    | DestinationIn
    | DestinationOut
    | DestinationAtop
    | Lighter
    | Copy
    | Xor
    | Multiply
    | Screen
    | Overlay
    | Darken
    | Lighten
    | ColorDodge
    | ColorBurn
    | HardLight
    | SoftLight
    | Difference
    | Exclusion
    | Hue
    | Saturation
    | Color
    | Luminosity

Type of compositing operation, identifying which of the compositing or blending mode operations to use. See the chapter Compositing from the Canvas Tutorial.

For more information and pictures of what each mode does, see the MDN docs.