helins.canvas — io.helins/canvas 2.0.0-beta0

cljs

An more idiomatic access to the Canvas API.

Aims to be particularly minimalistic and close to the original thing (cf. README).

Functions producing side effects are organized in a fluid interface. In other words, they return the given context or standalone path and can conveniently be be chained using ->.

Shape drawing functions, such as line or arc, can be applied both to contexts as well as standalone paths produced by path.

Functions prefixed with path- only apply to standalone paths and mimick other functions applying only to contexts. For instance, path-stroke is the sibling of stroke.

alpha cljs

(alpha ctx)

(alpha ctx percent)

Gets or sets the alpha (transparency) value that is applied to shapes and images before they are drawn onto the canvas.

Cf. .globalAlpha

arc cljs

(arc path x y radius angle-start angle-end)

(arc path x y radius angle-start angle-end anti-clockwise?)

Adds a circular arc to the current sub-path.

Cf. .arc()

arc-ctrl cljs

(arc-ctrl path x-1 y-1 x-2 y-2 radius)

Adds a circular arc to the current sub-path, using the given control points and radius.

The arc is automatically connected to the path's latest point with a straight line, if necessary for the specified parameters.

Commonly used for making rounded corners.

Cf. .arcTo

begin cljs

(begin ctx)

(begin ctx x y)

Starts a new path by emptying the list of sub-paths. Call this method when you want to create a new path.

Cf. .beginPath()

bezier-1 cljs

(bezier-1 path x-cp y-cp x-end y-end)

(bezier-1 path x-start y-start x-cp y-cp x-end y-end)

Adds a quadratic Bézier curve (1 control point) to the current sub-path. It requires two points: the first one is a control point and the second one is the end point. The starting point is the latest point in the current path, which can be changed using move before creating the quadratic Bézier curve.

Cf. .quadraticCurveTo()

bezier-2 cljs

(bezier-2 path x-cp-1 y-cp-1 x-cp-2 y-cp-2 x-end y-end)

(bezier-2 path x-start y-start x-cp-1 y-cp-1 x-cp-2 y-cp-2 x-end y-end)

Adds a cubic Bézier curve (2 control points) to the current sub-path. It requires three points: the first two are control points and the third one is the end point. The starting point is the latest point in the current path, which can be changed using move before creating the Bézier curve.

Cf. .bezierCurveTo()

clear cljs

(clear ctx x y width height)

Erases the pixels in a rectangular area by setting them to transparent black.

Cf. .clearRect()

clip cljs

(clip ctx)

(clip ctx fill-rule)

Turns the current path into the current clipping region. It replaces any previous clipping region.

fill-rule is non-nilable.

Cf. .clip()

close cljs

(close ctx)

Attempts to add a straight line from the current point to the start of the current sub-path.

If the shape has already been closed or has only one point, this function does nothing.

Cf. .closePath()

color-fill cljs

(color-fill ctx)

(color-fill ctx color)

Gets or sets the color, gradient, or pattern to use inside shapes. The default style is #000 (black).

Cf. .fillStyle

color-shadow cljs

(color-shadow ctx)

(color-shadow ctx color)

Gets or sets the color of shadows.

Be aware that the shadow's rendered opacity will be affected by the opacity of the color set by color-fill when filling, and of the color set by color-stroke when stroking.

Cf. .shadowColor

color-stroke cljs

(color-stroke ctx)

(color-stroke ctx color)

Gets or sets the color, gradient, or pattern to use for the strokes (outlines) around shapes. The default is #000 (black).

Cf. .strokeStyle

composite-op cljs

(composite-op ctx)

(composite-op ctx type)

Gets or sets the type of compositing operation to apply when drawing new shapes.

Cf. .globalCompositeOperation

contains? cljs

(contains? ctx x y)

Reports whether or not the specified point is inside the area contained by the stroking of a path (initialized by begin).

Cf. .isPointInStroke()

deg->rad cljs

(deg->rad deg)

Converts degrees to radians.

ellipse cljs

(ellipse path x y radius-x radius-y rotation angle-start angle-end)

(ellipse path
         x
         y
         radius-x
         radius-y
         rotation
         angle-start
         angle-end
         anti-clockwise?)

Adds an elliptical arc to the current sub-path.

Cf. .ellipse()

encloses? cljs

(encloses? ctx x y)

(encloses? ctx x y fill-rule)

Reports whether or not the specified point is contained in the current path.

Cf. .isPointInPath()

fill cljs

(fill ctx)

(fill ctx fill-rule)

Fills the current path with with the color set by color-fill.

Cf. .fill()

font cljs

(font ctx)

(font ctx new-font)

Gets or sets the current text style to use when drawing text. This string uses the same syntax as a CSS font specifier.

Cf. .font Font specifier

grad-linear cljs

(grad-linear ctx x-1 y-1 x-2 y-2 color-stops)

Creates a gradient along the line connecting two given coordinates which can be assigned using color-fill and/or color-stroke.

color-stops is a vector of [percent color].

Cf. .createLinearGradient()

grad-radial cljs

(grad-radial ctx x-1 y-1 radius-1 x-2 y-2 radius-2 color-stops)

Creates a radial gradient using the size and coordinates of two circles which can be assigned using color-fill and/or color-stroke.

color-stops is a vector of [percent color].

Cf. .createRadialGradient()

high-dpi cljs

(high-dpi ctx)

Adapts a context and its underlying canvas to high DPI screens by scaling the image in order to avoid otherwise pixelated drawings.

Modifies the scale properties of the transformation matrix.

Cf. matrix

line cljs

(line path x y)

(line path x-1 y-1 x-2 y-2)

Adds a straight line to the current sub-path by connecting the sub-path's last point to the specified (x, y) coordinates.

Cf. .line()

line-cap cljs

(line-cap ctx)

(line-cap ctx cap)

Gets or sets the shape used to draw the end points of lines.

Cf. .lineCap

line-dash cljs

(line-dash ctx)

(line-dash ctx segments)

(line-dash ctx segments offset)

Gets or sets the line dash pattern used when stroking lines.

If needed, also sets the offset.

segments is a JS array of numbers that specify distances to alternately draw a line and a gap (in coordinate space units)

Arity 1 returns [current-dash current-offset].

Cf. .lineDashOffset .setLineDash()

line-join cljs

(line-join ctx)

(line-join ctx join)

Gets or sets the shape used to join two line segments where they meet.

This property has no effect wherever two connected segments have the same direction, because no joining area will be added in this case.

Degenerate segments with a length of zero (i.e., with all endpoints and control points at the exact same position) are also ignored.

Cf. .lineJoin

line-width cljs

(line-width ctx)

(line-width ctx width)

Gets or sets the thickness of lines.

Cf. .lineWidth

matrix cljs

(matrix ctx)

(matrix ctx m)

(matrix ctx a b c d e f)

Gets (a copy) or sets the transformation matrix.

Cf. .getTransform() .setTransform()

matrix-mult cljs

(matrix-mult ctx a b c d e f)

Multiplies the current transformation matrix by the given arguments.

Allows to scale, rotate, translate (move), and skew the context.

Cf. .transform()

miter-limit cljs

(miter-limit ctx)

(miter-limit ctx limit)

Gets or sets the miter limit ratio.

Cf. .miterLimit

move cljs

(move path x y)

Begins a new sub-path at the point specified by the given (x, y) coordinates.

Cf. .moveTo

on-frame cljs

(on-frame f)

Invokes f everytime the next frame it is time to draw a frame with the current timestamp. Aims for 60 frames per second.

There are 2 ways for cancelling it: either call the returned function (no arguments) or return a falsy value from f.

paste cljs

(paste ctx src x-dest y-dest)

(paste ctx src x-dest y-dest width-dest height-dest)

(paste ctx src x-src y-src width-src height-src x-dest y-dest width height)

Provides different ways to draw an image onto the canvas.

Cf. .drawImage()

path cljs

(path)

(path source)

Returns a new path object which can be reused in order to improve performance.

Just like a context, it can be used with shape drawing functions such as line and functions prefixed with path-.

source is either an existing path which will be copied or an SVG string path.

Cf. Path2D

path-clip cljs

(path-clip ctx path)

(path-clip ctx path fill-rule)

Just like clip, but clips the given path.

fill-rule is non-nilable.

path-contains? cljs

(path-contains? ctx path x y)

Just like contains?, but in reference to the given path.

path-encloses? cljs

(path-encloses? ctx path x y)

(path-encloses? ctx path x y fill-rule?)

Just like encloses?, but in reference to the given path.

path-fill cljs

(path-fill ctx path)

(path-fill ctx path fill-rule)

Just like fill, but fills the given path.

path-stroke cljs

(path-stroke ctx path)

Just like stroke, but strokes the given path.

pattern cljs

(pattern ctx src)

(pattern ctx src repeat)

Creates a pattern using the specified image and repetition which can be assigned using color-fill and/or color-stroke.

Cf. .createPattern()

rect cljs

(rect path x y width height)

Adds a rectangle to the current path.

Cf. .rect

rect-fill cljs

(rect-fill ctx x y width height)

Draws a rectangle that is filled according to the color set by color-fill

This method draws directly to the canvas without modifying the current path.

Cf. .fillRect()

rect-stroke cljs

(rect-stroke ctx x y width height)

Draws a rectangle that is stroked (outlined).

This method draws directly to the canvas without modifying the current path.

Cf. stroke .strokeRect()

rotate cljs

(rotate ctx radians)

Adds a rotation to the transformation matrix.

Cf. .rotate()

scale cljs

(scale ctx x y)

Adds a scaling transformation to the canvas units horizontally and/or vertically.

By default, one unit on the canvas is exactly one pixel. A scaling transformation modifies this behavior. For instance, a scaling factor of 0.5 results in a unit size of 0.5 pixels; shapes are thus drawn at half the normal size. Similarly, a scaling factor of 2.0 increases the unit size so that one unit becomes two pixels; shapes are thus drawn at twice the normal size.

Cf. .scale()

scale-x cljs

(scale-x ctx x)

Like scale, but only for the X axis.

scale-y cljs

(scale-y ctx y)

Like scale, but only for the Y axis.

shadow cljs

(shadow ctx blur x-offset y-offset)

(shadow ctx blur x-offset y-offset color)

Shorthand calling shadow-blur, shadow-x, [[shaddow-y]], and if needed, color-shadow.

shadow-blur cljs

(shadow-blur ctx)

(shadow-blur ctx blur)

Gets or sets the amount of blur applied to shadows. The default is 0 (no blur).

Cf. .shadowBlur

shadow-x cljs

(shadow-x ctx)

(shadow-x ctx x-offset)

Gets or sets the distance that shadows will be offset horizontally.

Cf. .shadowOffsetX

shadow-y cljs

(shadow-y ctx)

(shadow-y ctx y-offset)

Gets or sets the distance that shadows will be offset vertically.

Cf. .shadowOffsetY

smoothing? cljs

(smoothing? ctx)

(smoothing? ctx enabled?)

Gets or sets whether scaled images are smoothed (true, default) or not (false).

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.

Cf. .imageSmoothingEnabled

stroke cljs

(stroke ctx)

Strokes (outlines) the current path according to the color set by color-stroke and line related settings such as line-width.

Strokes are aligned to the center of a path; in other words, half of the stroke is drawn on the inner side, and half on the outer side.

The stroke is drawn using the non-zero winding rule, which means that path intersections will still get filled.

Cf. .stroke()

style-pop cljs

(style-pop ctx)

Restores the most recently saved canvas state by popping the top entry in the drawing state stack.

If there is no saved state, this method does nothing.

Cf. style-save .restore()

style-save cljs

(style-save ctx)

Saves the entire state of the canvas (that is related to any styling) by pushing the current state onto a stack.

Cf. style-pop .save()

subspace clj/s macro

(subspace [ctx] & forms)

The transformation matrix is saved at the beginning of the macro and restored at the end so that any spatial transformations are forgotten.

Specially useful when drawing standalone paths which typically require translation.

Cf. matrix path

text-align cljs

(text-align ctx)

(text-align ctx align)

Gets or sets the current text alignment used when drawing text.

The alignment is relative to the x value of the text-fill function. For example, if textAlign is "center", then the text's left edge will be at x - (textWidth / 2).

Cf. .textAlign

text-baseline cljs

(text-baseline ctx)

(text-baseline ctx baseline)

Gets or sets the current text baseline used when drawing text.

Cf. .textBaseline

text-fill cljs

(text-fill ctx x y text)

(text-fill ctx x y text max-width)

Draws a text string at the specified coordinates, filling the string's characters with the current fillStyle. An optional parameter allows specifying a maximum width for the rendered text, which the user agent will achieve by condensing the text or by using a lower font size.

This function draws directly to the canvas without modifying the current path.

The text is rendered using the font and text layout configuration as defined by font, text-align, and text-baseline.

Cf. [[ŧext-stroke]] .fillText()

text-metrics cljs

(text-metrics ctx text)

text-stroke cljs

(text-stroke ctx x y text)

(text-stroke ctx x y text max-width)

Strokes — that is, draws the outlines of — the characters of a text string at the specified coordinates. An optional parameter allows specifying a maximum width for the rendered text, which the user agent will achieve by condensing the text or by using a lower font size.

This function draws directly to the canvas without modifying the current path.

Cf. text-fill .strokeText()

translate cljs

(translate ctx x y)

Adds a translation transformation to the current matrix.

Cf. .translate()

translate-x cljs

(translate-x ctx x)

Like translate but only for the X axis.

translate-y cljs

(translate-y ctx y)

Like translate but only for the Y axis.