::pix::ctxTop, Main, Index

NoteTop, Main, Index

This namespace provides a 2D API commonly used on the web. For more info, see: https://developer.mozilla.org/en-US/docs/Web/API/ContextRenderingContext2D

Struct Context:Top, Main, Index

image	img
fillStyle	paint
strokeStyle	paint
globalAlpha	double
lineWidth	double
miterLimit	double
lineCap	Enum LineCap
lineJoin	Enum LineJoin
font	string ## File path to a .ttf or .otf file.
fontSize	double
textAlign	Enum HorizontalAlignment
textBaseline	Enum BaselineAlignment

Enum BaselineAlignment:Top, Main, Index

BaselineAlignment	enum
TopBaseline
HangingBaseline
MiddleBaseline
AlphabeticBaseline
IdeographicBaseline
BottomBaseline

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

`context`	ctx::new
`coordinates`	list x,y
`radius`	double value
`angleStart`	double value (radian)
`angleEnd`	double value (radian)
`ccw`	boolean 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

`context`	ctx::new
`coordinates1`	list x1,y1
`coordinates2`	list x2,y2
`radius`	double value

Return value

Nothing.

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

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

beginPath context

Parameters

context ctx::new

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. 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 moveTo() before creating the Bézier curve.

bezierCurveTo context coordinates1 coordinates2 coordinates3

Parameters

`context`	ctx::new
`coordinates1`	list cp1x,cp1y
`coordinates2`	list cp2x,cp2y
`coordinates3`	list x,y

Return value

Nothing.

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

Adds a circle to the current path.

circle context coordinates radius

Parameters

`context`	ctx::new
`coordinates`	list cx,cy
`radius`	double value

Return value

Nothing.

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

Erases the pixels in a rectangular area.

clearRect context coordinates size

Parameters

`context`	ctx::new
`coordinates`	list x,y
`size`	list width,height

Return value

Nothing.

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

Turns the path into the current clipping region. The previous clipping region, if any, is intersected with the current or given path to create the new clipping region.

clip context ?path? ?windingRule?

Parameters

`context`	ctx::new
`path`	path::new Optional, default `""`.
`windingRule`	Enum value Optional, default `NonZero`.

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

context ctx::new

Return value

Nothing.

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

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

destroy value

Parameters

value ctx 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

`context`	ctx::new
`image`	img::new
`options`	See description below:

Description

There are 3 ways to use this proc:

1. With simple destination:

destinationXY

A list destination coordinates dx,dy.

2. With destination + size destination:

destinationXY	A list destination coordinates dx,dy.
destinationWH	A list destination size dw,dh.

3. With source + size source + destination + size destination:

source	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

`context`	ctx::new
`coordinates`	list x,y
`radiusx`	double value
`radiusy`	double value

Return value

Nothing.

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

Fills the path with the current fillStyle.

fill context ?path? ?windingRule?

Parameters

`context`	ctx::new
`path`	path::new Optional, default `""`.
`windingRule`	Enum 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

`context`	ctx::new
`coordinates`	list cx,cy
`radius`	double 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

`context`	ctx::new
`coordinates`	list x,y
`radiusx`	double value
`radiusy`	double 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

`context`	ctx::new
`coordinates`	list x,y
`size`	double value
`sides`	integer 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

`context`	ctx::new
`coordinates`	list x,y
`size`	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

`context`	ctx::new
`coordinates`	list x,y
`size`	list width,height
`radius`	double value or list radius {nw ne se sw}

Return value

Nothing.

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

Fills current style.

fillStyle context value

Parameters

`context`	ctx::new
`value`	paint::new 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

`context`	ctx::new
`text`	string
`coordinates`	list x,y

Return value

Nothing.

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

Sets font for current context.

font context filepath

Parameters

`context`	ctx::new
`filepath`	string

Return value

Nothing.

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

Sets font size for current context.

fontSize context size

Parameters

`context`	ctx::new
`size`	double 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

context ctx::new

Description

The dictionary includes:

image : A nested Tcl dictionary with the following keys:

addr	A pointer to the raw image data.
width	An integer representing the width of the image in pixels.
height	An integer representing the height of the image in pixels.

globalAlpha : A double value indicating the global alpha (transparency) level of the context. This affects the transparency of all drawing operations performed on the context.
lineWidth : A double value specifying the current line width used for stroking operations. This determines the thickness of lines drawn in the context.
lineCap : An enum value describing the style of the end caps for lines. Possible values include 'ButtCap', 'RoundCap', and 'SquareCap', which define how the end points of lines are rendered.
lineJoin : An enum value that indicates the style of the join between two lines. Options include 'MiterJoin', 'RoundJoin', and 'BevelJoin', each affecting the appearance of corners where lines meet.
miterLimit : A double value that sets the miter limit. 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.
font : A string representing the font settings for text rendering in the context. This includes font family, size, weight, and style, and dictates how text appears when drawn onto the context.

Return value

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

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

Gets line dash for current context.

getLineDash context

Parameters

context ctx::new

Return value

A list with current values.

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

Gets matrix for current context.

getTransform context

Parameters

context ctx::new

Description

The matrix is represented as a sequence of 3 sequences of floats, where each inner sequence represents a row of the matrix.

The first element of the first row represents the x component of the transformation, the second element represents the y component of the transformation, and the third element represents the z component of the transformation.

Return value

A matrix as Tcl list.

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

Sets color alpha.

globalAlpha context alpha

Parameters

`context`	ctx::new
`alpha`	double value

Description

This determines the transparency level of the drawing operations. The alpha value must be a floating-point number between 0.0 (completely transparent) and 1.0 (completely opaque).

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

`context`	ctx::new
`coordinates`	list x,y
`path`	path::new Optional, default `""`.
`windingRule`	Enum 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

`context`	ctx::new
`coordinates`	list x,y
`path`	path::new Optional, default `""`.

Return value

A Tcl boolean value.

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

`context`	ctx::new
`lineJoin`	Enum 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 to the current sub-path by connecting the sub-path's last point to the specified (x, y) coordinates.

lineTo context coordinates

Parameters

`context`	ctx::new
`coordinates`	list x,y

Description

The lineTo method can be called multiple times to draw multiple lines. Each call to lineTo adds a line to the current path, and the stroke method will draw all of the lines in the path.

For example, to draw a square with the top-left corner at (10, 10) and the bottom-right corner at (20, 20), you can use the following code:

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

This code will draw a square with the top-left corner at (10, 10) and the bottom-right corner at (20, 20).

Return value

Nothing.

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

Sets line width for current context.

lineWidth context width

Parameters

`context`	ctx::new
`width`	double value

Return value

Nothing.

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

Information about the measured text.

measureText context text

Parameters

`context`	ctx::new
`text`	string

Return value

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

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

Begins a new sub-path at the point (x, y).

moveTo context coordinates

Parameters

`context`	ctx::new
`coordinates`	list x,y

Description

This is a fundamental operation, it clears the current path and starts a new path at the point given.
The subsequent path operations are all relative to this point.

The point is the starting point of the new path that is being built.
The point is used as the first point of the path that is being built.
The point is used as the reference point for all of the relative path operations, such as lineTo, curveTo, and arc.
The point is used as the starting point for the built path.
The point should be the first point that is used in the path.

Return value

Nothing.

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

Sets a new context.

new size ?value?

Parameters

`size`	list width,height
`value`	string color or img::new Optional, default `none`.

Return value

A new 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

`context`	ctx::new
`coordinates`	list x,y
`size`	double value
`sides`	integer value

Return value

Nothing.

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

Adds a quadratic Bézier curve 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 moveTo() before creating the quadratic Bézier curve.

quadraticCurveTo context coordinates1 coordinates2

Parameters

`context`	ctx::new
`coordinates1`	list cpx,cpy
`coordinates2`	list x,y

Return value

Nothing.

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

Adds a rectangle to the current path.

rect context coordinates size

Parameters

`context`	ctx::new
`coordinates`	list x,y
`size`	list width,height

Return value

Nothing.

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

Resets the current transform to the identity matrix.

resetTransform context

Parameters

context ctx::new

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

context ctx::new

Return value

Nothing.

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

Adds a rotation to the transformation matrix.

rotate context angle

Parameters

`context`	ctx::new
`angle`	double value (radian)

Description

The rotation is around the origin (0,0). The rotation is counterclockwise. The angle is in radians.

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

`context`	ctx::new
`coordinates`	list x,y
`size`	list width,height
`radius`	list {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

context ctx::new

Description

The pix::ctx::save procedure adds the current context state to the stack, and the 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

context ctx::new

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

`context`	ctx::new
`coordinates`	list x,y

Return value

Nothing.

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

Sets line dash for current context.

setLineDash context dashes

Parameters

`context`	ctx::new
`dashes`	list

Return value

Nothing.

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

Overrides the transform matrix being applied to the context.

setTransform context matrix3x3

Parameters

`context`	ctx::new
`matrix3x3`	list

Description

If you want to save the current transform matrix, you can get it by calling pix::ctx::getTransform and later restore it using pix::ct::setTransform. If you want to add a new transform to the current transform matrix, use pix::ctx::transform instead.

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

`context`	ctx::new
`path`	path::new 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

`context`	ctx::new
`coordinates`	list cx,cy
`radius`	double 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

`context`	ctx::new
`coordinates`	list x,y
`radiusx`	double value
`radiusy`	double 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

`context`	ctx::new
`coordinates`	list x,y
`size`	double value
`sides`	integer 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

`context`	ctx::new
`coordinates`	list x,y
`size`	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

`context`	ctx::new
`coordinates`	list x,y
`size`	list width,height
`radius`	double value or list radius {nw ne se sw}

Return value

Nothing.

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

Strokes a segment (draws a line from ax, ay to bx, by) according to the current strokeStyle and other context settings.

strokeSegment context coordinates1 coordinates2

Parameters

`context`	ctx::new
`coordinates1`	list x,y
`coordinates2`	list x1,y1

Description

Create a segment using the start and stop vectors 'start' is the beginning point of the segment (x, y) 'stop' is the end point of the segment (x1, y1) The segment represents a line that will be drawn from start to stop

Return value

Nothing.

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

Sets color style current context.

strokeStyle context color

Parameters

`context`	ctx::new
`color`	paint::new or string color

Description

If the string is not in the correct format, 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

`context`	ctx::new
`text`	string
`coordinates`	list x,y

Return value

Nothing.

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

Sets text alignment.

textAlign context horizontalAlignment

Parameters

`context`	ctx::new
`horizontalAlignment`	Enum value

Return value

Nothing.

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

Set the base line alignment for the current context.

textBaseline context baselineAlignment

Parameters

`context`	ctx::new
`baselineAlignment`	Enum value

Description

Parse the second argument as an enum value of type BaselineAlignment. This value tells us how to align the text 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

`context`	ctx::new
`matrix3x3`	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

`context`	ctx::new
`coordinates`	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

`context`	ctx::new
`filePath`	string (.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.