linsyking/elm-canvas/2.0.0

NOTE: the latest version is 4.4.0

Rerouted (regenerated, verified). Same repository and tag, but GitHub now builds the zip with different bytes, so it no longer matches the SHA-1 package.elm-lang.org recorded. The Lamdera package server serves a copy recovered from https://github.com/linsyking/elm-canvas.

What we checked: Rebuilt with git archive from commit 8a2e082db001 of https://github.com/linsyking/elm-canvas (zip prefix linsyking-elm-canvas-8a2e082/, America/Los_Angeles times): the zip is byte-identical to the one package.elm-lang.org recorded, SHA-1 161e76f3d17c5bd6e93cefb51e57639cdb8559da.

The Lamdera compiler uses this copy and prints a one-line notice saying so. elm itself fails to download this version.

Details · package.elm-lang.org's zip: https://github.com/linsyking/elm-canvas/zipball/2.0.0/

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 : Float
, y0 : Float
, x1 : Float
, y1 : Float
}

Linear gradient definition.

  • x0, y0: top left corner of the gradient
  • x1, y1: bottom right corner of the gradient
type alias RadialGradient =
{ x0 : Float
, y0 : Float
, rad0 : Float
, x1 : Float
, y1 : Float
, rad1 : Float
}

Radial gradient definition.

  • x0, y0: top left corner of the gradient
  • x1, y1: bottom right corner of the gradient
  • rad0: inner radius of the gradient
  • rad1: outer radius of the gradient
fillLinear : LinearGradient -> List ( Float, Color ) -> Setting

Fill with linear gradient.

  • x0, y0: top left corner of the gradient
  • x1, y1: bottom right corner of the gradient
  • stops: ( offset, color )
    • offset is a float number from 0 to 1, so the horizontal position of the stop
    • where color is the Color of given stop (from avh4/elm-color)
fillRadial : RadialGradient -> List ( Float, Color ) -> Setting

Fill with radial gradient.

  • x0, y0: top left corner of the gradient
  • x1, y1: bottom right corner of the gradient
  • rad0: inner radius of the gradient
  • rad1: outer radius of the gradient
  • stops: ( offset, color )
    • offset is a float number from 0 to 1, so the horizontal position of the stop
    • where color is the Color of given stop (from avh4/elm-color)
strokeLinear : LinearGradient -> List ( Float, Color ) -> Setting

Stroke with linear gradient.

  • x0, y0: top left corner of the gradient
  • x1, y1: bottom right corner of the gradient
  • stops: ( offset, color )
    • offset is a float number from 0 to 1, so the horizontal position of the stop
    • where color is the Color of given stop (from avh4/elm-color)
strokeRadial : RadialGradient -> List ( Float, Color ) -> Setting

Stroke with radial gradient.

  • x0, y0: top left corner of the gradient
  • x1, y1: bottom right corner of the gradient
  • rad0: inner radius of the gradient
  • rad1: outer radius of the gradient
  • stops: ( offset, color )
    • offset is a float number from 0 to 1, so the horizontal position of the stop
    • where color is the Color of given stop (from avh4/elm-color)

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 -> Setting

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

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

Record with the settings for a shadow.

  • blur: Amount of blur for the shadow
  • color: Color of the shadow (from avh4/elm-color)
  • offset: ( xOffset, yOffset )

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 -> 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 ]
= Rotate Float
| Scale Float Float
| Translate Float Float
| ApplyMatrix
{ m11 : Float
, m12 : Float
, m21 : Float
, m22 : Float
, dx : Float
, dy : 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 : Float -> 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 : 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 : Float -> 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
  • x
    • Scaling factor in the horizontal direction.
  • y
    • Scaling factor in the vertical direction.

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

{ m11 : Float
, m12 : Float
, m21 : Float
, m22 : Float
, dx : Float
, dy : Float
}

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.

  • m11
    • Horizontal scaling.
  • m12
    • Horizontal skewing.
  • m21
    • Vertical skewing.
  • m22
    • Vertical scaling.
  • dx
    • Horizontal moving.
  • dy
    • Vertical moving.

Filter

Filters are powerful when you want to add visual effects to your renderable objects.

filter : String -> Setting

Specify a filter applied on the renderable object.

You can use functions like blur, brightness, contrast and so on to apply the filters.

The property is a string, so you can choose your filters like this:

"<filter-function1> [<filter-function2] [<filter-functionN]"

See the MDN docs for more information and examples.

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 : Float -> 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 : Bool -> 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.

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
= 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.