::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
| img | |
| paint | |
| paint | |
| double | |
| double | |
| double | |
| Enum LineCap | |
| Enum LineJoin | |
| string filePath to a .ttf or .otf file. | |
| double | |
| Enum HorizontalAlignment | |
| Enum BaselineAlignment |
Enum BaselineAlignment:Top, Main, Index
- TopBaseline
- HangingBaseline
- MiddleBaseline
- AlphabeticBaseline
- IdeographicBaseline
- BottomBaseline
CommandsTop, Main, Index
arc [::pix::ctx]Top, Main, Index
Adds a circular arc to the current sub-path.
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
coordinates1 | A list {x1 y1} |
coordinates2 | A 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.
Parameters
context | ctx |
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.
Parameters
context | ctx |
coordinates1 | A list {cp1x cp1y} (first control point) |
coordinates2 | A list {cp2x cp2y} (second control point) |
coordinates3 | A 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.
Parameters
context | ctx |
coordinates | A list {cx cy} |
radius | Double value |
Return value
Nothing.
clearRect [::pix::ctx]Top, Main, Index
Erases the pixels in a rectangular area.
Parameters
context | ctx |
coordinates | A list {x y} |
size | A list {width height} |
Return value
Nothing.
clip [::pix::ctx]Top, Main, Index
Sets the current path as the clipping region.
Parameters
context | ctx |
path | path object Optional, default "". |
windingRule | Enum 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.
Parameters
context | ctx |
Return value
Nothing.
destroy [::pix::ctx]Top, Main, Index
Destroy the ctx or all contexts if special word all is specified.
Parameters
value | ctx or string value. |
Return value
Nothing.
drawImage [::pix::ctx]Top, Main, Index
Draws a source image onto the destination image.
Parameters
context | ctx |
image | img |
options | See description below: |
Description
There are 3 ways to use this proc:
- simple destination:
destinationXY A list destination coordinates {dX dY}. - destination + size destination:
destinationXY A list destination coordinates {dX dY}. destinationWH A list destination size {dW dH}. - 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.
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
path | path 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
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
coordinates | A list {x y} |
radiusx | Double value |
radiusy | Double value |
Return value
Nothing.
fillPath [::pix::ctx]Top, Main, Index
See img::fillPath procedure.
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.
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
coordinates | A list {x y} |
size | A list {width height} |
Return value
Nothing.
fillRoundedRect [::pix::ctx]Top, Main, Index
Draws a rounded rectangle that is filled according to the current fillStyle.
Parameters
context | ctx |
coordinates | A list {x y} |
size | A list {width height} |
radius | Double value or list of {nw ne se sw} |
Return value
Nothing.
fillStyle [::pix::ctx]Top, Main, Index
Fills current style.
Parameters
context | ctx |
value | paint 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.
Parameters
context | ctx |
text | string |
coordinates | A list {x y} |
Return value
Nothing.
font [::pix::ctx]Top, Main, Index
Sets font for current context.
Parameters
context | ctx |
filePath | string |
Return value
Nothing.
fontSize [::pix::ctx]Top, Main, Index
Sets font size for current context.
Parameters
context | ctx |
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.
Parameters
context | ctx |
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, andSquareCap, 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, andBevelJoin, each affecting the appearance of corners where lines meet. - miterLimit : A double value that sets the miter limit. This is relevant when
lineJoinis set toMiterJoinand 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.
- fontSize : A double value representing the font size for text rendering in the context.
- transform : A list of 9 values representing the transformation matrix applied to the context.
- textAlign : An enum value that specifies the horizontal alignment of text within the context.
- textBaseline : An enum value that specifies the vertical alignment of text within the context.
- fillStyle : The paint object handle given to ctx::fillStyle, the color (rgba string) when a color was given, or an empty string.
- strokeStyle : The same for ctx::strokeStyle.
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.
Parameters
context | ctx |
Return value
Image key as string.
getInfoStruct [::pix::ctx]Top, Main, Index
See ctx::get procedure.
getLineDash [::pix::ctx]Top, Main, Index
Gets line dash for current context.
Parameters
context | ctx |
Return value
A list with current values.
getSize [::pix::ctx]Top, Main, Index
Gets the size of the image associated with the context.
Parameters
context | ctx |
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.
Parameters
context | ctx |
Return value
A matrix as Tcl list.
globalAlpha [::pix::ctx]Top, Main, Index
Sets color alpha.
Parameters
context | ctx |
alpha | Double 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.
Parameters
context | ctx |
coordinates | A list {x y} |
path | path 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.
Parameters
context | ctx |
coordinates | A list {x y} |
path | path Optional, default "". |
Return value
A Tcl boolean value.
lineCap [::pix::ctx]Top, Main, Index
Sets the style of the end caps for lines.
Parameters
context | ctx |
enum | Enum 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.
Parameters
context | ctx |
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 segment to the current sub-path from the current pen position to the specified coordinates.
Parameters
context | ctx |
coordinates | A 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:
- Drawing an open box shape from (10,10) to (10,20) via (20,10) and (20,20):
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.
Parameters
context | ctx |
width | Double value |
Return value
Nothing.
measureText [::pix::ctx]Top, Main, Index
Information about the measured text.
Parameters
context | ctx |
text | string |
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.
Parameters
context | ctx |
miterlimit | Double 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.
Parameters
context | ctx |
coordinates | A 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.
Parameters
size | A list {width height} |
value | string 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.
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
coordinates1 | A list {cpx cpy} |
coordinates2 | A 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.
Parameters
context | ctx |
coordinates | A list {x y} |
size | A list {width height} |
Return value
Nothing.
resetTransform [::pix::ctx]Top, Main, Index
Resets the current transform to the identity matrix.
Parameters
context | ctx |
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.
Parameters
context | ctx |
Return value
Nothing.
rotate [::pix::ctx]Top, Main, Index
Applies a rotation to the transformation matrix.
Parameters
context | ctx |
angle | double (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.
Parameters
context | ctx |
coordinates | A list {x y} |
size | A list {width height} |
radius | Double 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.
Parameters
context | ctx |
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.
Parameters
context | ctx |
Return value
Nothing.
scale [::pix::ctx]Top, Main, Index
Adds a scaling transformation to the context units horizontally and/or vertically.
Parameters
context | ctx |
coordinates | A list {x y} |
Return value
Nothing.
setLineDash [::pix::ctx]Top, Main, Index
Sets line dash for current context.
Parameters
context | ctx |
dashes | A list of numbers |
Return value
Nothing.
setTransform [::pix::ctx]Top, Main, Index
Overrides the current transformation matrix.
Parameters
context | ctx |
matrix3x3 | A 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.
Parameters
context | ctx |
path | path 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.
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
coordinates | A list {x y} |
radiusx | Double value |
radiusy | Double value |
Return value
Nothing.
strokePath [::pix::ctx]Top, Main, Index
See img::strokePath procedure.
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.
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
coordinates | A list {x y} |
size | A 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.
Parameters
context | ctx |
coordinates | A list {x y} |
size | A list {width height} |
radius | Double 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.
Parameters
context | ctx |
coordinates1 | A list {x y} (start point) |
coordinates2 | A list {x1 y1} (end point) |
Return value
Nothing.
strokeStyle [::pix::ctx]Top, Main, Index
Sets the stroke style for the current context.
Parameters
context | ctx |
color | paint 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.
Parameters
context | ctx |
text | string |
coordinates | A list {x y} |
Return value
Nothing.
textAlign [::pix::ctx]Top, Main, Index
Sets text alignment.
Parameters
context | ctx |
horizontalAlignment | Enum value |
Return value
Nothing.
textBaseline [::pix::ctx]Top, Main, Index
Sets the text baseline alignment for the current context.
Parameters
context | ctx |
baselineAlignment | Enum 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.
Parameters
context | ctx |
matrix3x3 | A 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.
Parameters
context | ctx |
coordinates | A 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.
Parameters
context | ctx |
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.