JavaFX 24 · javafx.scene.canvas.GraphicsContext · APIdia, the JavaDoc alternative

This class is used to issue draw calls to a Canvas using a buffer.

Each call pushes the necessary parameters onto the buffer where they will be later rendered onto the image of the Canvas node by the rendering thread at the end of a pulse.

A Canvas only contains one GraphicsContext, and only one buffer. If it is not attached to any scene, then it can be modified by any thread, as long as it is only used from one thread at a time. Once a Canvas node is attached to a scene, it must be modified on the JavaFX Application Thread.

Calling any method on the GraphicsContext is considered modifying its corresponding Canvas and is subject to the same threading rules.

A GraphicsContext also manages a stack of state objects that can be saved or restored at anytime.

The GraphicsContext maintains the following rendering attributes which affect various subsets of the rendering methods:

List of Rendering Attributes
Attribute	Save/Restore?	Default value	Description
Common Rendering Attributes
`Clip`	Yes	No clipping	An anti-aliased intersection of various clip paths to which rendering is restricted.
`Global Alpha`	Yes	`1.0`	An opacity value that controls the visibility or fading of each rendering operation.
`Global Blend Mode`	Yes	`SRC_OVER`	A `BlendMode` enum value that controls how pixels from each rendering operation are composited into the existing image.
`Transform`	Yes	`Identity`	A 3x2 2D affine transformation matrix that controls how coordinates are mapped onto the logical pixels of the canvas image.
`Effect`	Yes	`null`	An `Effect` applied individually to each rendering operation.
Fill Attributes
`Fill Paint`	Yes	`BLACK`	The `Paint` to be applied to the interior of shapes in a fill operation.
Stroke Attributes
`Stroke Paint`	Yes	`BLACK`	The `Paint` to be applied to the boundary of shapes in a stroke operation.
`Line Width`	Yes	`1.0`	The width of the stroke applied to the boundary of shapes in a stroke operation.
`Line Cap`	Yes	`SQUARE`	The style of the end caps applied to the beginnings and ends of each dash and/or subpath in a stroke operation.
`Line Join`	Yes	`MITER`	The style of the joins applied between individual segments in the boundary paths of shapes in a stroke operation.
`Miter Limit`	Yes	`10.0`	The ratio limit of how far a `MITER` line join may extend in the direction of a sharp corner between segments in the boundary path of a shape, relative to the line width, before it is truncated to a `BEVEL` join in a stroke operation.
`Dashes`	Yes	`null`	The array of dash lengths to be applied to the segments in the boundary of shapes in a stroke operation.
`Dash Offset`	Yes	`0.0`	The distance offset into the array of dash lengths at which to start the dashing of the segments in the boundary of shapes in a stroke operation.
Text Attributes
`Font`	Yes	`Default Font`	The font used for all fill and stroke text operations.
`Text Align`	Yes	`LEFT`	The horizontal alignment of text with respect to the `X` coordinate specified in the text operation.
`Text Baseline`	Yes	`BASELINE`	The vertical position of the text relative to the `Y` coordinate specified in the text operation.
`Font Smoothing`	Yes	`GRAY`	The type of smoothing (antialiasing) applied to the glyphs in the font for all fill text operations.
Path Attributes
`Current Path`	No	Empty path	The path constructed using various path construction methods to be used in various path filling, stroking, or clipping operations.
`Fill Rule`	Yes	`NON_ZERO`	The method used to determine the interior of paths for a path fill or clip operation.
Image Attributes
`Image Smoothing`	Yes	`true`	A boolean state which enables or disables image smoothing for `drawImage(all forms)`.

The various rendering methods on the GraphicsContext use the following sets of rendering attributes:

Rendering Attributes Table
Method	Common Rendering Attributes	Fill Attributes	Stroke Attributes	Text Attributes	Path Attributes	Image Attributes
Basic Shape Rendering
`fillRect()`, `fillRoundRect()`, `fillOval()`, `fillArc()`	Yes	Yes	No	No	No	No
`strokeLine()`, `strokeRect()`, `strokeRoundRect()`, `strokeOval()`, `strokeArc()`	Yes	No	Yes	No	No	No
`clearRect()`	Yes [1]	No	No	No	No	No
`fillPolygon()`	Yes	Yes	No	No	Yes [2]	No
`strokePolygon()`, `strokePolyline()`	Yes	No	Yes	No	No	No
[1] Only the Transform, Clip, and Effect apply to clearRect() [2] Only the Fill Rule applies to fillPolygon(), the current path is left unchanged
Text Rendering
`fillText()`, `fillText(with maxWidth)`	Yes	Yes	No	Yes [3]	No	No
`strokeText()`, `strokeText(with maxWidth)`	Yes	No	Yes	Yes [3]	No	No
[3] The Font Smoothing attribute only applies to filled text
Path Rendering
`beginPath()`, `moveTo()`, `lineTo()`, `quadraticCurveTo()`, `bezierCurveTo()`, `arc()`, `arcTo()`, `appendSVGPath()`, `closePath()`, `rect()`	Yes [4]	No	No	No	No	No
`fill()`	Yes [4]	Yes	No	No	Yes	No
`stroke()`	Yes [4]	No	Yes	No	Yes [5]	No
`clip()`	No	No	No	No	Yes	No
[4] Transform applied only during path construction [5] Fill Rule only used for fill() and clip()
Image Rendering
`drawImage(all forms)`	Yes	No	No	No	No	Yes
Miscellaneous
`applyEffect()`, `PixelWriter methods`	No	No	No	No	No	No

Example:

import javafx.scene.*;
import javafx.scene.paint.*;
import javafx.scene.canvas.*;

Group root = new Group();
Scene s = new Scene(root, 300, 300, Color.BLACK);

final Canvas canvas = new Canvas(250,250);
GraphicsContext gc = canvas.getGraphicsContext2D();

gc.setFill(Color.BLUE);
gc.fillRect(75,75,100,100);

root.getChildren().add(canvas);

Modifier and Type	Class and Description
pack-priv static class	GraphicsContext.State

Modifier and Type	Field and Description
pack-priv LinkedList<Path2D>	clipStack
private float[]	coords
pack-priv GraphicsContext.State	curState
private static final int[]	numsegs
pack-priv Path2D	path
pack-priv boolean	pathDirty
private static final byte[]	pgtype
private float[]	polybuf
pack-priv LinkedList<GraphicsContext.State>	stateStack
pack-priv Canvas	theCanvas
private boolean	txdirty
private PixelWriter	writer

Access	Constructor and Description
pack-priv	GraphicsContext(Canvas theCanvas)

Method Summary

Modifier and Type	Method and Description
public void	appendSVGPath(String the SVG Path string. svgpath) Appends an SVG Path string to the current path.
public void	applyEffect(Effect the effect to apply onto the entire destination or null. e) Applies the given effect to the entire bounds of the canvas and stores the result back into the same canvas.
public void	arc(double the center x position of the arc. centerX, double the center y position of the arc. centerY, double the x radius of the arc. radiusX, double the y radius of the arc. radiusY, double the starting angle of the arc in the range `0-360.0` startAngle, double the length of the baseline of the arc. length) Adds path elements to the current path to make an arc that uses Euclidean degrees.
public void	arcTo(double the X coordinate of the first point of the arc. x1, double the Y coordinate of the first point of the arc. y1, double the X coordinate of the second point of the arc. x2, double the Y coordinate of the second point of the arc. y2, double the radius of the arc in the range {0.0-positive infinity}. radius) Adds segments to the current path to make an arc.
public void	beginPath() Resets the current path to empty.
public void	bezierCurveTo(double the X coordinate of first Bezier control point. xc1, double the Y coordinate of the first Bezier control point. yc1, double the X coordinate of the second Bezier control point. xc2, double the Y coordinate of the second Bezier control point. yc2, double the X coordinate of the end point. x1, double the Y coordinate of the end point. y1) Adds segments to the current path to make a cubic Bezier curve.
public void	clearRect(double X position of the upper left corner of the rectangle. x, double Y position of the upper left corner of the rectangle. y, double width of the rectangle. w, double height of the rectangle. h) Clears a portion of the canvas with a transparent color value.
public void	clip() Intersects the current clip with the current path and applies it to subsequent rendering operation as an anti-aliased mask.
public void	closePath() Closes the path.
public void	drawImage(Image the image to be drawn or null. img, double the X coordinate on the destination for the upper left of the image. x, double the Y coordinate on the destination for the upper left of the image. y) Draws an image at the given x, y position using the width and height of the given image.
public void	drawImage(Image the image to be drawn or null. img, double the X coordinate on the destination for the upper left of the image. x, double the Y coordinate on the destination for the upper left of the image. y, double the width of the destination rectangle. w, double the height of the destination rectangle. h) Draws an image into the given destination rectangle of the canvas.
public void	drawImage(Image the image to be drawn or null. img, double the source rectangle's X coordinate position. sx, double the source rectangle's Y coordinate position. sy, double the source rectangle's width. sw, double the source rectangle's height. sh, double the destination rectangle's X coordinate position. dx, double the destination rectangle's Y coordinate position. dy, double the destination rectangle's width. dw, double the destination rectangle's height. dh) Draws the specified source rectangle of the given image to the given destination rectangle of the Canvas.
public void	fill() Fills the path with the current fill paint.
public void	fillArc(double the X coordinate of the arc. x, double the Y coordinate of the arc. y, double the width of the arc. w, double the height of the arc. h, double the starting angle of the arc in degrees. startAngle, double the angular extent of the arc in degrees. arcExtent, ArcType closure type (Round, Chord, Open) or null. closure) Fills an arc using the current fill paint.
public void	fillOval(double the X coordinate of the upper left bound of the oval. x, double the Y coordinate of the upper left bound of the oval. y, double the width at the center of the oval. w, double the height at the center of the oval. h) Fills an oval using the current fill paint.
public void	fillPolygon(double[] array containing the x coordinates of the polygon's points or null. xPoints, double[] array containing the y coordinates of the polygon's points or null. yPoints, int the number of points that make the polygon. nPoints) Fills a polygon with the given points using the currently set fill paint.
public void	fillRect(double the X position of the upper left corner of the rectangle. x, double the Y position of the upper left corner of the rectangle. y, double the width of the rectangle. w, double the height of the rectangle. h) Fills a rectangle using the current fill paint.
public void	fillRoundRect(double the X coordinate of the upper left bound of the oval. x, double the Y coordinate of the upper left bound of the oval. y, double the width at the center of the oval. w, double the height at the center of the oval. h, double the arc width of the rectangle corners. arcWidth, double the arc height of the rectangle corners. arcHeight) Fills a rounded rectangle using the current fill paint.
public void	fillText(String the string of text or null. text, double position on the x axis. x, double position on the y axis. y) Fills the given string of text at position x, y with the current fill paint attribute.
public void	fillText(String the string of text or null. text, double position on the x axis. x, double position on the y axis. y, double maximum width the text string can have. maxWidth) Fills text and includes a maximum width of the string.
private void	flushPolyBuf(GrowableDataBuffer buf, float[] polybuf, int n, byte command)
private GrowableDataBuffer	getBuffer()
public Canvas	Returns: Canvas the canvas that this `GraphicsContext` is issuing draw commands to. getCanvas() Gets the `Canvas` that the `GraphicsContext` is issuing draw commands to.
public Effect	Returns: the current effect used for all rendering calls, or null if there is no current effect getEffect(Effect an `Effect` object that may be used to store the copy of the current effect, if it is of a compatible type e) Gets a copy of the effect to be applied after the next draw call.
public Paint	Returns: p The `Paint` to be used as the fill `Paint`. getFill() Gets the current fill paint attribute.
public FillRule	Returns: current fill rule. getFillRule() Get the filling rule attribute for determining the interior of paths in fill and clip operations.
public Font	Returns: the Font getFont() Gets the current Font.
public FontSmoothingType	Returns: the `FontSmoothingType` getFontSmoothingType() Gets the current Font Smoothing Type.
public double	Returns: the current global alpha. getGlobalAlpha() Gets the current global alpha.
public BlendMode	Returns: the global `BlendMode` of the current state. getGlobalBlendMode() Gets the global blend mode.
public StrokeLineCap	Returns: `StrokeLineCap` with a value of Butt, Round, or Square. getLineCap() Gets the current stroke line cap. The default value is `SQUARE`.
public double[]	Returns: a copy of the current line dash array. getLineDashes() Gets a copy of the current line dash array.
public double	Returns: the line dash offset in the range `(-inf, +inf)` getLineDashOffset() Gets the current line dash offset.
public StrokeLineJoin	Returns: `StrokeLineJoin` with a value of Miter, Bevel, or Round. getLineJoin() Gets the current stroke line join.
public double	Returns: value between 0 and infinity. getLineWidth() Gets the current line width.
public double	Returns: the miter limit value in the range `0.0-positive infinity` getMiterLimit() Gets the current miter limit.
public PixelWriter	Returns: the `PixelWriter` for modifying the pixels of this `Canvas` getPixelWriter() Returns a `PixelWriter` object that can be used to modify the pixels of the `Canvas` associated with this `GraphicsContext`.
public Paint	Returns: the `Paint` to be used as the stroke `Paint`. getStroke() Gets the current stroke.
public TextAlignment	Returns: `TextAlignment` with values of Left, Center, Right, or Justify. getTextAlign() Gets the current `TextAlignment`.
public VPos	Returns: `VPos` with values of Top, Center, Baseline, or Bottom getTextBaseline() Gets the current Text Baseline.
public Affine	Returns: A copy of the current transform. getTransform(Affine A transform object that will be used to hold the result. If xform is non null, then this method will copy the current transform into that object. If xform is null a new transform object will be constructed. In either case, the return value is a copy of the current transform. xform) Copies the current transform into the supplied object, creating a new `Affine` object if it is null, and returns the object containing the copy.
public Affine	Returns: a copy of the transform of the current state. getTransform() Returns a copy of the current transform.
public boolean	Returns: image smoothing state isImageSmoothing() Gets the current image smoothing state.
public boolean	Returns: true if the point given is inside the path, false otherwise. isPointInPath(double the X coordinate to use for the check. x, double the Y coordinate to use for the check. y) Returns true if the the given x,y point is inside the path.
private static double	lenSq(double x0, double y0, double x1, double y1)
public void	lineTo(double the X coordinate of the ending point of the line. x1, double the Y coordinate of the ending point of the line. y1) Adds segments to the current path to make a line to the given x,y coordinate.
private void	markPathDirty()
public void	moveTo(double the X position for the move to command. x0, double the Y position for the move to command. y0) Issues a move command for the current path to the given x,y coordinate.
public void	quadraticCurveTo(double the X coordinate of the control point xc, double the Y coordinate of the control point yc, double the X coordinate of the end point x1, double the Y coordinate of the end point y1) Adds segments to the current path to make a quadratic Bezier curve.
public void	rect(double x position of the upper left corner of the rectangle. x, double y position of the upper left corner of the rectangle. y, double width of the rectangle. w, double height of the rectangle. h) Adds path elements to the current path to make a rectangle.
private void	reset()
private void	resetIfCovers(Paint p, double x, double y, double w, double h)
public void	restore() Pops the state off of the stack, setting the following attributes to their value at the time when that state was pushed onto the stack.
public void	rotate(double value in degrees to rotate the current transform. degrees) Rotates the current transform in degrees.
public void	save() Saves the following attributes onto a stack.
public void	scale(double value to scale in the x axis. x, double value to scale in the y axis. y) Scales the current transform by x, y.
public void	setEffect(Effect the effect to use, or null to disable effects e) Sets the effect to be applied after the next draw call, or null to disable effects.
public void	setFill(Paint The `Paint` to be used as the fill `Paint` or null. p) Sets the current fill paint attribute.
public void	setFillRule(FillRule `FillRule` with a value of Even_odd or Non_zero or null. fillRule) Set the filling rule attribute for determining the interior of paths in fill or clip operations.
public void	setFont(Font the Font or null. f) Sets the current Font.
public void	setFontSmoothingType(FontSmoothingType the `FontSmoothingType` or null fontsmoothing) Sets the current Font Smoothing Type.
public void	setGlobalAlpha(double the new alpha value, clamped to `[0.0, 1.0]` during actual use. alpha) Sets the global alpha of the current state.
public void	setGlobalBlendMode(BlendMode the `BlendMode` that will be set or null. op) Sets the global blend mode.
public void	setImageSmoothing(boolean `true` to enable or `false` to disable smoothing imageSmoothing) Sets the image smoothing state.
public void	setLineCap(StrokeLineCap `StrokeLineCap` with a value of Butt, Round, or Square or null. cap) Sets the current stroke line cap. The default value is `SQUARE`.
public void	setLineDashes(double... the array of finite non-negative dash lengths dashes) Sets the current stroke line dash pattern to a normalized copy of the argument.
public void	setLineDashOffset(double the line dash offset in the range `(-inf, +inf)` dashOffset) Sets the line dash offset.
public void	setLineJoin(StrokeLineJoin `StrokeLineJoin` with a value of Miter, Bevel, or Round or null. join) Sets the current stroke line join.
public void	setLineWidth(double value in the range {0-positive infinity}, with any other value being ignored and leaving the value unchanged. lw) Sets the current line width.
public void	setMiterLimit(double miter limit value between 0 and positive infinity with any other value being ignored and leaving the value unchanged. ml) Sets the current miter limit.
public void	setStroke(Paint The Paint to be used as the stroke Paint or null. p) Sets the current stroke paint attribute.
public void	setTextAlign(TextAlignment `TextAlignment` with values of Left, Center, Right or null. align) Defines horizontal text alignment, relative to the text `x` origin.
public void	setTextBaseline(VPos `VPos` with values of Top, Center, Baseline, or Bottom or null. baseline) Sets the current Text Baseline.
public void	setTransform(double - the X coordinate scaling element of the 3x4 matrix mxx, double - the Y coordinate shearing element of the 3x4 matrix myx, double - the X coordinate shearing element of the 3x4 matrix mxy, double - the Y coordinate scaling element of the 3x4 matrix myy, double - the X coordinate translation element of the 3x4 matrix mxt, double - the Y coordinate translation element of the 3x4 matrix myt) Sets the current transform.
public void	setTransform(Affine The affine to be copied and used as the current transform. xform) Sets the current transform.
public void	stroke() Strokes the path with the current stroke paint.
public void	strokeArc(double the X coordinate of the arc. x, double the Y coordinate of the arc. y, double the width of the arc. w, double the height of the arc. h, double the starting angle of the arc in degrees. startAngle, double arcExtent the angular extent of the arc in degrees. arcExtent, ArcType closure type (Round, Chord, Open) or null closure) Strokes an Arc using the current stroke paint.
public void	strokeLine(double the X coordinate of the starting point of the line. x1, double the Y coordinate of the starting point of the line. y1, double the X coordinate of the ending point of the line. x2, double the Y coordinate of the ending point of the line. y2) Strokes a line using the current stroke paint.
public void	strokeOval(double the X coordinate of the upper left bound of the oval. x, double the Y coordinate of the upper left bound of the oval. y, double the width at the center of the oval. w, double the height at the center of the oval. h) Strokes an oval using the current stroke paint.
public void	strokePolygon(double[] array containing the x coordinates of the polygon's points or null. xPoints, double[] array containing the y coordinates of the polygon's points or null. yPoints, int the number of points that make the polygon. nPoints) Strokes a polygon with the given points using the currently set stroke paint.
public void	strokePolyline(double[] array containing the x coordinates of the polyline's points or null. xPoints, double[] array containing the y coordinates of the polyline's points or null. yPoints, int the number of points that make the polyline. nPoints) Strokes a polyline with the given points using the currently set stroke paint attribute.
public void	strokeRect(double the X position of the upper left corner of the rectangle. x, double the Y position of the upper left corner of the rectangle. y, double the width of the rectangle. w, double the height of the rectangle. h) Strokes a rectangle using the current stroke paint.
public void	strokeRoundRect(double the X coordinate of the upper left bound of the oval. x, double the Y coordinate of the upper left bound of the oval. y, double the width at the center of the oval. w, double the height at the center of the oval. h, double the arc width of the rectangle corners. arcWidth, double the arc height of the rectangle corners. arcHeight) Strokes a rounded rectangle using the current stroke paint.
public void	strokeText(String the string of text or null. text, double position on the x axis. x, double position on the y axis. y) Draws the given string of text at position x, y with the current stroke paint attribute.
public void	strokeText(String the string of text or null. text, double position on the x axis. x, double position on the y axis. y, double maximum width the text string can have. maxWidth) Draws text with stroke paint and includes a maximum width of the string.
public void	transform(double - the X coordinate scaling element of the 3x4 matrix mxx, double - the Y coordinate shearing element of the 3x4 matrix myx, double - the X coordinate shearing element of the 3x4 matrix mxy, double - the Y coordinate scaling element of the 3x4 matrix myy, double - the X coordinate translation element of the 3x4 matrix mxt, double - the Y coordinate translation element of the 3x4 matrix myt) Concatenates the input with the current transform.
public void	transform(Affine The affine to be concatenated with the current transform or null. xform) Concatenates the input with the current transform.
public void	translate(double value to translate along the x axis. x, double value to translate along the y axis. y) Translates the current transform by x, y.
private boolean	tryArcTo(float x1, float y1, float x2, float y2, float radius)
pack-priv void	updateDimensions()
private void	updateTransform()
private void	writeArcType(ArcType closure)
private void	writeImage(Image img, double dx, double dy, double dw, double dh)
private void	writeImage(Image img, double dx, double dy, double dw, double dh, double sx, double sy, double sw, double sh)
private void	writeOp4(double x, double y, double w, double h, byte command)
private void	writeOp6(double x, double y, double w, double h, double v1, double v2, byte command)
private void	writePaint(Paint p, byte command)
pack-priv void	writeParam(double v, byte command)
private void	writeParam(byte v, byte command)
private void	writePath(byte command)
private void	writePoly(double[] xPoints, double[] yPoints, int nPoints, boolean close, byte command)
private void	writeRectParams(GrowableDataBuffer buf, double x, double y, double w, double h, byte command)
private void	writeText(String text, double x, double y, double maxWidth, byte command)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public final Class GraphicsContext

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary