pix 0.9: Reference Manual

::pix::ctxTop, Main, Index

NoteTop, Main, Index

This namespace provides a 2D API commonly used on the web. For more info, see: ContextRenderingContext2D

Struct Context:Top, Main, Index

imageimg
fillStylepaint
strokeStylepaint
globalAlphadouble
lineWidthdouble
miterLimitdouble
lineCapEnum LineCap
lineJoinEnum LineJoin
fontstring filePath to a .ttf or .otf file.
fontSizedouble
textAlignEnum HorizontalAlignment
textBaselineEnum BaselineAlignment

Enum BaselineAlignment:Top, Main, Index

CommandsTop, Main, Index

arc [::pix::ctx]Top, Main, Index

Adds a circular arc to the current sub-path.

arc context coordinates radius angleStart angleEnd ?ccw?
Parameters
contextctx
coordinatesA list {x y}
radiusDouble value
angleStartDouble value (radian)
angleEndDouble value (radian)
ccwBoolean value Optional, default false.
Return value

Nothing.

arcTo [::pix::ctx]Top, Main, Index

Adds a circular arc using the given control points and radius.

arcTo context coordinates1 coordinates2 radius
Parameters
contextctx
coordinates1A list {x1 y1}
coordinates2A list {x2 y2}
radiusDouble value
Return value

Nothing.

beginPath [::pix::ctx]Top, Main, Index

Starts a new path by emptying the list of sub-paths.

beginPath context
Parameters
contextctx
Description

Begin a new path by clearing any existing sub-paths in the context. This is typically used to start drawing a new shape or path.

Return value

Nothing.

bezierCurveTo [::pix::ctx]Top, Main, Index

Adds a cubic Bézier curve to the current sub-path.

bezierCurveTo context coordinates1 coordinates2 coordinates3
Parameters
contextctx
coordinates1A list {cp1x cp1y} (first control point)
coordinates2A list {cp2x cp2y} (second control point)
coordinates3A list {x y} (destination point)
Description

This operation requires three points: the first two are control points (cp1 and cp2), and the third one is the final destination point. The curve begins at the current pen position (which can be set using pix::ctx::moveTo).

Return value

Nothing.

circle [::pix::ctx]Top, Main, Index

Adds a circle to the current path.

circle context coordinates radius
Parameters
contextctx
coordinatesA list {cx cy}
radiusDouble value
Return value

Nothing.

clearRect [::pix::ctx]Top, Main, Index

Erases the pixels in a rectangular area.

clearRect context coordinates size
Parameters
contextctx
coordinatesA list {x y}
sizeA list {width height}
Return value

Nothing.

clip [::pix::ctx]Top, Main, Index

Sets the current path as the clipping region.

clip context ?path? ?windingRule?
Parameters
contextctx
pathpath object Optional, default "".
windingRuleEnum value Optional, default NonZero.
Description

The new clipping region is the intersection of the previous region and the current or provided path.

Return value

Nothing.

closePath [::pix::ctx]Top, Main, Index

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.

closePath context
Parameters
contextctx
Return value

Nothing.

destroy [::pix::ctx]Top, Main, Index

Destroy the ctx or all contexts if special word all is specified.

destroy value
Parameters
valuectx or string value.
Return value

Nothing.

drawImage [::pix::ctx]Top, Main, Index

Draws a source image onto the destination image.

drawImage context image options
Parameters
contextctx
imageimg
optionsSee description below:
Description

There are 3 ways to use this proc:

  1. simple destination:
    destinationXY A list destination coordinates {dX dY}.
  2. destination + size destination:
    destinationXY A list destination coordinates {dX dY}.
    destinationWH A list destination size {dW dH}.
  3. source + size source + destination + size destination:
    sourceXY A list source coordinates {sx sy}.
    sourceWH A list source size {sW sH}.
    destinationXY A list destination coordinates {dX dY}.
    destinationWH A list destination size {dW dH}.
Return value

Nothing.

ellipse [::pix::ctx]Top, Main, Index

Adds an ellipse to the current sub-path.

ellipse context coordinates radiusx radiusy
Parameters
contextctx
coordinatesA list {x y}
radiusxDouble value
radiusyDouble value
Return value

Nothing.

fill [::pix::ctx]Top, Main, Index

Fills the path with the current fillStyle.

fill context ?path? ?windingRule?
Parameters
contextctx
pathpath Optional, default "".
windingRuleEnum value Optional, default NonZero.
Description

If no path is specified, then call pix::ctx::fill $ctx with no arguments.

This will fill the current path with the current fillStyle. If no fillStyle has been set, it will default to Color(0.0, 0.0, 0.0, 1.0). If no path has been set, it will default to an empty path. If no winding rule has been set, it will default to NonZero.

Return value

Nothing.

fillCircle [::pix::ctx]Top, Main, Index

Draws a circle that is filled according to the current fillStyle

fillCircle context coordinates radius
Parameters
contextctx
coordinatesA list {cx cy}
radiusDouble value
Return value

Nothing.

fillEllipse [::pix::ctx]Top, Main, Index

Draws an ellipse that is filled according to the current fillStyle.

fillEllipse context coordinates radiusx radiusy
Parameters
contextctx
coordinatesA list {x y}
radiusxDouble value
radiusyDouble value
Return value

Nothing.

fillPath [::pix::ctx]Top, Main, Index

See img::fillPath procedure.

fillPath

fillPolygon [::pix::ctx]Top, Main, Index

Draws an n-sided regular polygon at (x, y) of size that is filled according to the current fillStyle.

fillPolygon context coordinates size sides
Parameters
contextctx
coordinatesA list {x y}
sizeDouble value
sidesInteger value
Return value

Nothing.

fillRect [::pix::ctx]Top, Main, Index

Draws a rectangle that is filled according to the current fillStyle.

fillRect context coordinates size
Parameters
contextctx
coordinatesA list {x y}
sizeA list {width height}
Return value

Nothing.

fillRoundedRect [::pix::ctx]Top, Main, Index

Draws a rounded rectangle that is filled according to the current fillStyle.

fillRoundedRect context coordinates size radius
Parameters
contextctx
coordinatesA list {x y}
sizeA list {width height}
radiusDouble value or list of {nw ne se sw}
Return value

Nothing.

fillStyle [::pix::ctx]Top, Main, Index

Fills current style.

fillStyle context value
Parameters
contextctx
valuepaint or string color
Return value

Nothing.

fillText [::pix::ctx]Top, Main, Index

Draws a text string at the specified coordinates, filling the string's characters with the current fillStyle.

fillText context text coordinates
Parameters
contextctx
textstring
coordinatesA list {x y}
Return value

Nothing.

font [::pix::ctx]Top, Main, Index

Sets font for current context.

font context filePath
Parameters
contextctx
filePathstring
Return value

Nothing.

fontSize [::pix::ctx]Top, Main, Index

Sets font size for current context.

fontSize context size
Parameters
contextctx
sizeDouble value
Return value

Nothing.

get [::pix::ctx]Top, Main, Index

Retrieves detailed information about the current context and returns it as a Tcl dictionary.

get context
Parameters
contextctx
Description

The dictionary includes:

Return value

A Tcl dictionary object that contains various properties (see above) of the context, which can be useful for introspection or debugging.

getImage [::pix::ctx]Top, Main, Index

Gets the image associated with the context.

getImage context
Parameters
contextctx
Return value

Image key as string.

getInfoStruct [::pix::ctx]Top, Main, Index

See ctx::get procedure.

getInfoStruct

getLineDash [::pix::ctx]Top, Main, Index

Gets line dash for current context.

getLineDash context
Parameters
contextctx
Return value

A list with current values.

getSize [::pix::ctx]Top, Main, Index

Gets the size of the image associated with the context.

getSize context
Parameters
contextctx
Return value

A Tcl dictionary object that contains the width and height of the image.

getTransform [::pix::ctx]Top, Main, Index

Gets matrix for current context.

getTransform context
Parameters
contextctx
Return value

A matrix as Tcl list.

globalAlpha [::pix::ctx]Top, Main, Index

Sets color alpha.

globalAlpha context alpha
Parameters
contextctx
alphaDouble value (0.0 to 1.0)
Description

This determines the transparency level of the drawing operations.

Return value

Nothing.

isPointInPath [::pix::ctx]Top, Main, Index

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

isPointInPath context coordinates ?path? ?windingRule?
Parameters
contextctx
coordinatesA list {x y}
pathpath Optional, default "".
windingRuleEnum value Optional, default NonZero.
Return value

A Tcl boolean value.

isPointInStroke [::pix::ctx]Top, Main, Index

Checks whether or not the specified point is inside the area contained by the stroking of a path.

isPointInStroke context coordinates ?path?
Parameters
contextctx
coordinatesA list {x y}
pathpath Optional, default "".
Return value

A Tcl boolean value.

lineCap [::pix::ctx]Top, Main, Index

Sets the style of the end caps for lines.

lineCap context enum
Parameters
contextctx
enumEnum value (ButtCap, RoundCap, or SquareCap)
Return value

Nothing.

lineJoin [::pix::ctx]Top, Main, Index

Parse the string as an enum value of type LineJoin and assign it to the lineJoin property of the context.

lineJoin context lineJoin
Parameters
contextctx
lineJoinEnum value
Description

The parseEnum function will raise an exception if the string is not a valid enum value.

Return value

Nothing.

lineTo [::pix::ctx]Top, Main, Index

Adds a straight line segment to the current sub-path from the current pen position to the specified coordinates.

lineTo context coordinates
Parameters
contextctx
coordinatesA Tcl list {x y}
Description

Calling this method multiple times allows you to chain multiple segments together. The actual lines will be rendered when calling pix::ctx::stroke.

Example:

pix::ctx::moveTo $ctx {10 10}
pix::ctx::lineTo $ctx {20 10}
pix::ctx::lineTo $ctx {20 20}
pix::ctx::lineTo $ctx {10 20}
pix::ctx::stroke $ctx
Return value

Nothing.

lineWidth [::pix::ctx]Top, Main, Index

Sets line width for current context.

lineWidth context width
Parameters
contextctx
widthDouble value
Return value

Nothing.

measureText [::pix::ctx]Top, Main, Index

Information about the measured text.

measureText context text
Parameters
contextctx
textstring
Return value

A Tcl dict that contains information about the measured text (such as its width, for example).

miterLimit [::pix::ctx]Top, Main, Index

Sets the miter limit.

miterLimit context miterlimit
Parameters
contextctx
miterlimitDouble value
Description

This is relevant when lineJoin is set to MiterJoin and controls the maximum length of the miter. If the miter limit is exceeded, a bevel join is used instead.

Return value

Nothing.

moveTo [::pix::ctx]Top, Main, Index

Begins a new sub-path at the specified coordinate.

moveTo context coordinates
Parameters
contextctx
coordinatesA Tcl list {x y}
Description

This operation sets the current pen position without drawing anything, establishing a new starting point for subsequent path instructions (such as lineTo, curveTo, or arc).

Return value

Nothing.

new [::pix::ctx]Top, Main, Index

Creates and sets a new drawing context.

new size ?value?
Parameters
sizeA list {width height}
valuestring color or img Optional, default "".
Return value

A new handle ctx object.

polygon [::pix::ctx]Top, Main, Index

Adds an n-sided regular polygon at (x, y) of size to the current path.

polygon context coordinates size sides
Parameters
contextctx
coordinatesA list {x y}
sizeDouble value
sidesInteger value
Return value

Nothing.

quadraticCurveTo [::pix::ctx]Top, Main, Index

Adds a quadratic Bézier curve to the current sub-path.

quadraticCurveTo context coordinates1 coordinates2
Parameters
contextctx
coordinates1A list {cpx cpy}
coordinates2A list {x y}
Description

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 pix::ctx::moveTo before creating the quadratic Bézier curve.

Return value

Nothing.

rect [::pix::ctx]Top, Main, Index

Adds a rectangle to the current path.

rect context coordinates size
Parameters
contextctx
coordinatesA list {x y}
sizeA list {width height}
Return value

Nothing.

resetTransform [::pix::ctx]Top, Main, Index

Resets the current transform to the identity matrix.

resetTransform context
Parameters
contextctx
Return value

Nothing.

restore [::pix::ctx]Top, Main, Index

Restores the most recently saved context state by popping the top entry in the drawing state stack. If there is no saved state, this method does nothing.

restore context
Parameters
contextctx
Return value

Nothing.

rotate [::pix::ctx]Top, Main, Index

Applies a rotation to the transformation matrix.

rotate context angle
Parameters
contextctx
angledouble (radians)
Description

The rotation is centered at the origin (0,0) and moves counter-clockwise.

Return value

Nothing.

roundedRect [::pix::ctx]Top, Main, Index

Draws a rectangle with rounded corners that is filled according to the current fillStyle.

roundedRect context coordinates size radius
Parameters
contextctx
coordinatesA list {x y}
sizeA list {width height}
radiusDouble value or list radius {nw ne se sw}
Return value

Nothing.

save [::pix::ctx]Top, Main, Index

Saves the entire state of the context by pushing the current state onto a stack.

save context
Parameters
contextctx
Description

The pix::ctx::save procedure adds the current context state to the stack, and the pix::ctx::restore procedure pops the top context state from the stack and restores the context state to the top state.

Return value

Nothing.

saveLayer [::pix::ctx]Top, Main, Index

Saves the entire state of the context by pushing the current state onto a stack and allocates a new image layer for subsequent drawing. Calling restore blends the current layer image onto the prior layer or root image.

saveLayer context
Parameters
contextctx
Return value

Nothing.

scale [::pix::ctx]Top, Main, Index

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

scale context coordinates
Parameters
contextctx
coordinatesA list {x y}
Return value

Nothing.

setLineDash [::pix::ctx]Top, Main, Index

Sets line dash for current context.

setLineDash context dashes
Parameters
contextctx
dashesA list of numbers
Return value

Nothing.

setTransform [::pix::ctx]Top, Main, Index

Overrides the current transformation matrix.

setTransform context matrix3x3
Parameters
contextctx
matrix3x3A list of 9 values
Description

You can retrieve the current matrix with pix::ctx::getTransform and restore it later using pix::ctx::setTransform.

To append a transformation instead of overriding it, use pix::ctx::transform.

The matrix is a list of 9 values representing a 3x3 matrix. The values are in row order:

set matrix {
  a b c
  d e f
  g h i
}
Return value

Nothing.

stroke [::pix::ctx]Top, Main, Index

Strokes (outlines) the current or given path with the current strokeStyle.

stroke context ?path?
Parameters
contextctx
pathpath Optional, default "".
Return value

Nothing.

strokeCircle [::pix::ctx]Top, Main, Index

Draws a circle that is stroked (outlined) according to the current strokeStyle and other context settings.

strokeCircle context coordinates radius
Parameters
contextctx
coordinatesA list {cx cy}
radiusDouble value
Return value

Nothing.

strokeEllipse [::pix::ctx]Top, Main, Index

Draws an ellipse that is stroked (outlined) according to the current strokeStyle and other context settings.

strokeEllipse context coordinates radiusx radiusy
Parameters
contextctx
coordinatesA list {x y}
radiusxDouble value
radiusyDouble value
Return value

Nothing.

strokePath [::pix::ctx]Top, Main, Index

See img::strokePath procedure.

strokePath

strokePolygon [::pix::ctx]Top, Main, Index

Draws an n-sided regular polygon at {x y} of size that is stroked (outlined) according to the current strokeStyle and other context settings.

strokePolygon context coordinates size sides
Parameters
contextctx
coordinatesA list {x y}
sizeDouble value
sidesInteger value
Return value

Nothing.

strokeRect [::pix::ctx]Top, Main, Index

Draws a rectangle that is stroked (outlined) according to the current strokeStyle and other context settings.

strokeRect context coordinates size
Parameters
contextctx
coordinatesA list {x y}
sizeA list {width height}
Return value

Nothing.

strokeRoundedRect [::pix::ctx]Top, Main, Index

Draws a rounded rectangle that is stroked (outlined) according to the current strokeStyle and other context settings.

strokeRoundedRect context coordinates size radius
Parameters
contextctx
coordinatesA list {x y}
sizeA list {width height}
radiusDouble value or list of {nw ne se sw}
Return value

Nothing.

strokeSegment [::pix::ctx]Top, Main, Index

Draws a line segment from (x, y) to (x1, y1) using the current stroke style.

strokeSegment context coordinates1 coordinates2
Parameters
contextctx
coordinates1A list {x y} (start point)
coordinates2A list {x1 y1} (end point)
Return value

Nothing.

strokeStyle [::pix::ctx]Top, Main, Index

Sets the stroke style for the current context.

strokeStyle context color
Parameters
contextctx
colorpaint object or color string
Description

If the color string format is incorrect, an error will be generated.

Return value

Nothing.

strokeText [::pix::ctx]Top, Main, Index

Draws the outlines of the characters of a text string at the specified coordinates.

strokeText context text coordinates
Parameters
contextctx
textstring
coordinatesA list {x y}
Return value

Nothing.

textAlign [::pix::ctx]Top, Main, Index

Sets text alignment.

textAlign context horizontalAlignment
Parameters
contextctx
horizontalAlignmentEnum value
Return value

Nothing.

textBaseline [::pix::ctx]Top, Main, Index

Sets the text baseline alignment for the current context.

textBaseline context baselineAlignment
Parameters
contextctx
baselineAlignmentEnum value (BaselineAlignment)
Description

This value determines how text is aligned relative to its baseline.

Return value

Nothing.

transform [::pix::ctx]Top, Main, Index

Multiplies the current transform with the matrix described by the arguments of this method.

transform context matrix3x3
Parameters
contextctx
matrix3x3A list
Description

This is useful if you want to add a new transform to the current transform matrix without replacing the current transform matrix.

For example, if you have set a transform matrix using pix::ctx::setTransform and later want to add a rotation to the current transform matrix, you can use pix::ctx::transform to add the rotation to the current transform matrix.

Another example is if you want to add a scale to the current transform matrix, you can use pix::ctx::transform to add the scale to the current transform matrix.

Return value

Nothing.

translate [::pix::ctx]Top, Main, Index

Adds a translation transformation to the current matrix.

translate context coordinates
Parameters
contextctx
coordinatesA list {x y}
Description

The translation is by the given (x, y) vector in the current coordinate system.

This is the same:

ctx.transform = ctx.transform.translate(vec2(x, y))
# or:
ctx.transform = ctx.transform * Mat3.translation(vec2(x, y))
Return value

Nothing.

writeFile [::pix::ctx]Top, Main, Index

Save context to image file.

writeFile context filePath
Parameters
contextctx
filePathstring (*.png|*.bmp|*.qoi|*.ppm)
Description

The context is rendered into an image which is then saved to the file specified by $filePath.
Therefore, it's generally safer to specify the format separately from the file name, like so:

pix::ctx::writeFile $ctx 'image.png'

This ensures that the image is saved in the correct format regardless of the current format of the context.

Return value

Nothing.