Reference
Geometric primitives
Graphics.Vec2
— TypeVec2(x, y) -> v
Create a Cartesian representation v
of a vector (or point) in two dimensions.
Graphics.Point
— TypePoint(x, y) -> p
Create a Cartesian representation p
of a point in two dimensions. Point
is an alias of Vec2
.
Graphics.BoundingBox
— TypeBoundingBox(xmin, xmax, ymin, ymax) -> bb
Create a representation bb
of a rectangular region, specifying the coordinates of the horizontal (x) and vertical (y) edges.
Geometry API
Graphics.aspect_ratio
— Functionaspect_ratio(bb::BoundingBox) -> r
Compute the ratio r
of the height and width of bb
.
Example
julia> bb = BoundingBox(Point(0, 0), Point(1920, 1080)); # landscape
julia> aspect_ratio(bb)
0.5625
julia> rationalize(ans)
9//16
Graphics.center
— Functioncenter(obj) -> p::Point
Compute the center coordinate of obj
.
The fallback implementation of this function returns the center of bounding box, not the geometric center, or centroid.
Graphics.deform
— Functiondeform(bb::BoundingBox, Δl, Δr, Δt, Δb) -> bbnew
Add Δl
(left), Δr
(right), Δt
(top), and Δb
(bottom) to the edges of a BoundingBox
. The sign of each value follows the positive direction of the axis. The "top" and "bottom" are representations when the y-axis is directed downward.
Example
julia> bb = BoundingBox(Point(1, 1), Point(10, 10));
julia> bbnew = deform(bb, 0.5, -1.0, -0.25, 1.0);
julia> xrange(bbnew), yrange(bbnew)
((1.5, 9.0), (0.75, 11.0))
Graphics.diagonal
— Functiondiagonal(obj) -> diag
Get the diagonal length of obj
. The fallback implementation of this function returns the diagonal length of the bounding box of obj
.
Graphics.isinside
— Functionisinside(bb::BoundingBox, p::Point) -> tf::Bool
isinside(bb::BoundingBox, x, y) -> tf::Bool
Determine whether the point lies within bb
.
Graphics.shift
— Functionshift(bb::BoundingBox, Δx, Δy) -> bbnew
Shift center by (Δx, Δy)
, keeping width & height fixed.
Graphics.height
— Functionheight(obj) -> h
Get the vertical length of obj
.
Graphics.width
— Functionwidth(obj) -> w
Get the horizontal length of obj
.
Graphics.xmin
— Functionxmin(obj) -> xmin
Get the minimum x coordinate of the bounding box of obj
.
Graphics.xmax
— Functionxmax(obj) -> xmax
Get the maximum x coordinate of the bounding box of obj
.
Graphics.ymin
— Functionymin(obj) -> ymin
Get the minimum x coordinate of the bounding box of obj
.
Graphics.ymax
— Functionymax(obj) -> ymax
Get the maximum y coordinate of the bounding box of obj
.
Graphics.xrange
— Functionxrange(obj) -> (xmin, xmax)
Get the horizontal range of the bounding box that minimally contains obj
.
Graphics.yrange
— Functionyrange(obj) -> (ymin, ymax)
Get the vertical range of the bounding box that minimally contains obj
.
2d drawing contexts
Graphics.GraphicsDevice
— TypeGraphicDevice
An abstract graphics output device; can create GraphicsContext
s.
Graphics.GraphicsContext
— TypeGraphicsContext
An abstract object that can actually be drawn to.
Graphics.creategc
— Functioncreategc(gd::GraphicsDevice) -> gc::GraphicContext
Create a new GraphicContext
.
Graphics.getgc
— Functiongetgc(obj) -> gc::GraphicContext
Get a GraphicsContext
from something that might be drawable.
Coordinate systems
Graphics.set_coordinates
— Functionset_coordinates(gc::GraphicsContext, device::BoundingBox, user::BoundingBox)
set_coordinates(gc::GraphicsContext, user::BoundingBox)
Set the device->user coordinate transformation of c
so that device
, expressed in "device coordinates" (pixels), is equivalent to user
as expressed in "user coordinates". If device
is omitted, it defaults to the full span of gc
, BoundingBox(0, width(gc), 0, height(gc))
.
Graphics.reset_transform
— Functionreset_transform(gc::GraphicsContext)
Reset the current transformation.
Graphics.rotate
— Functionrotate(p::Vec2, angle::Real, o::Vec2 = Vec2(0, 0)) -> pnew::Vec2
Rotate p
around o
by angle
(in radians).
The direction of rotation for positive angles is from the positive x-axis toward the positive y-axis. For example, the direction of rotation is "clockwise" when the x-axis is directed right and the y-axis is directed downward.
Example
julia> rotate(Vec2(2, 1), 0.5π, Vec2(1, 1))
Vec2(1.0, 2.0)
rotate(bb::BoundingBox, angle::Real, o::Point) -> bbnew
Rotate bb
around o
by angle
(in radians), returning the BoundingBox
that encloses the vertices of the rotated box.
rotate(gc::GraphicsContext, angle)
Rotate the user-space axes by angle
(in radians). The rotation takes places after any existing transformation.
See also: rotate(p::Vec2, angle::Real, o::Vec2)
.
Graphics.scale
— Functionscale(gc::GraphicsContext, sx, sy)
Scale the user-space x-axis and y-axis by sx
and sy
respectively. The scaling takes places after any existing transformation.
Graphics.translate
— Functiontranslate(gc::GraphicsContext, Δx, Δy)
Translate the user-space origin by (Δx, Δy)
. The translation takes places after any existing transformation.
Graphics.user_to_device!
— Functionuser_to_device!(gc::GraphicsContext, c::Vector{Float64})
Transform a coordinate c
from the user space to the device space.
See also: user_to_device
, device_to_user!
Graphics.device_to_user!
— Functiondevice_to_user!(gc::GraphicsContext, c::Vector{Float64})
Transform a coordinate c
from the device space to the user space.
See also: device_to_user
, user_to_device!
Graphics.user_to_device_distance!
— Functionuser_to_device_distance!(gc::GraphicsContext, d::Vector{Float64})
Transform a distance vector d
from the user space to the device space. This function is similar to the device_to_user!
except that the translation components will be cancelled.
Graphics.device_to_user_distance!
— Functiondevice_to_user_distance!(gc::GraphicsContext, d::Vector{Float64})
Transform a distance vector d
from the device space to the user space. This function is similar to the user_to_device!
except that the translation components will be cancelled.
Graphics.user_to_device
— Functionuser_to_device(gc::GraphicsContext, x, y) -> (xd, yd)
Transform a user space coordinate (x, y)
to the device space coordinate (xd, yd)
.
See also: user_to_device!
, device_to_user
Graphics.device_to_user
— Functiondevice_to_user(gc::GraphicsContext, x, y) -> (xu, yu)
Transform a device space coordinate (x, y)
to the user space coordinate (xu, yu)
.
See also: device_to_user!
, user_to_device
Lines
Graphics.set_line_width
— Functionset_line_width(gc::GraphicsContext, w)
Set the current line width (in device-depended units). The actual width and aspect-ratio on the screen may be affected by the transformation.
Graphics.set_dash
— Functionset_dash(gc::GraphicsContext, dashes::Vector{Float64}, offset)
Set the dash pattern. The dashes
is a Vector
of positive lengths. The odd-numbered elements represent the length of the "on" state, and the even-numbered elements represent the length of the "off" (blank) state. The offset
specifies an offset at which the stroke begins. If dashes
is empty, dashing is disabled.
Colors and painting (drawing attributes)
Graphics.set_source
— Functionset_source(gc::GraphicsContext, src)
Set the source pattern to src
. If the src
is a Color
, it is used as the source color.
Graphics.set_source_rgb
— Functionset_source_rgb(gc::GraphicsContext, r, g, b)
Set the source pattern to an opaque color RGB(r, g, b)
. The color components are in the range [0, 1]
, not [0, 255]
.
See also: set_source_rgba
.
Graphics.set_source_rgba
— Functionset_source_rgba(gc::GraphicsContext, r, g, b, a)
Set the source pattern to a transparent color RGBA(r, g, b, a)
. The color and alpha components are in the range [0, 1]
, not [0, 255]
.
See also: set_source_rgb
.
Graphics.save
— Functionsave(gc::GraphicsContext)
Save the copy of current context gc
. The context is saved onto an internal stack, for example.
See also: restore
The function name save
conflicts with the save
in the FileIO package, which is likely to be used with the Graphics package.
Graphics.restore
— Functionrestore(gc::GraphicsContext)
Restore the context saved by a preceding save
. The state at the time of the call is overwritten with the restored context, and the restored context is removed from an internal stack, for example.
Clipping
Graphics.clip
— Functionclip(gc::GraphicsContext)
Set a new clipping region based on the current path and fill within the context.
See also: reset_clip
, clip_preserve
.
Graphics.clip_preserve
— Functionclip_preserve(gc::GraphicsContext)
Set a new clipping region based on the current path and fill within the context. Unlike the clip
function, this function preserves the path within the context.
Graphics.reset_clip
— Functionreset_clip(gc::GraphicsContext)
Remove the clipping region set by the clip
or clip_preserve
function.
Graphics.inner_canvas
— Functioninner_canvas(gc::GraphicsContext, device::BoundingBox, user::BoundingBox)
inner_canvas(gc::GraphicsContext, x, y, w, h, l, r, t, b)
Create a rectangular drawing area inside device
(represented in device-coordinates), giving it user-coordinates user
. Any drawing that occurs outside this box is clipped.
x
, y
, w
, and h
are an alternative parametrization of device
, and l
, r
, t
, b
parametrize user
.
See also: set_coordinates
.
Paths
Graphics.move_to
— Functionmove_to(gc::GraphicsContext, x, y)
Begin a new sub-path. The current point will be moved to (x, y)
.
See also: rel_move_to
.
Graphics.line_to
— Functionline_to(gc::GraphicsContext, x, y)
Add a line to the current path from the current point to the position (x, y)
. The current point will be moved to (x, y)
.
See also: rel_line_to
.
Graphics.rel_line_to
— Functionrel_line_to(gc::GraphicsContext, Δx, Δy)
Add a line to the current path from the current point of (x, y)
to the position (x + Δx, y + Δy)
. The current point will be moved to (x + Δx, y + Δy)
.
See also: line_to
.
Graphics.rel_move_to
— Functionrel_move_to(gc::GraphicsContext, Δx, Δy)
Begin a new sub-path. The current point will be moved to (x + Δx, y + Δy)
, where (x, y)
is the previous current point.
See also: move_to
.
Graphics.new_path
— Functionnew_path(gc::GraphicsContext)
Clear the current path.
Depending on the backend, the new path may actually begin when a path element is added.
Graphics.new_sub_path
— Functionnew_sub_path(gc::GraphicsContext)
Begin a new sub-path. The current point will be cleared.
See also: move_to
.
Graphics.close_path
— Functionclose_path(gc::GraphicsContext)
Add a line to the current path from the current point to the beginning of the current sub-path and closes the sub-path. The current point will be changed to the joined point.
There is a difference between closing a subpath and drawing a line to the equivalent coordinate. This difference might be visualized as a difference in drawing stroke endpoints.
Graphics.arc
— Functionarc(gc::GraphicsContext, xc, yc, radius, angle1, angle2)
Add a circular arc with the specified radius
to the current path. The arc is centered at (xc, yc)
, begins at angle1
and ends at angle2
. The angle1
and angle2
are in radians. The arc will be drawn in the direction of increasing angles.
High-level paths
Graphics.rectangle
— Functionrectangle(gc::GraphicsContext, x, y, width, height)
rectangle(gc::GraphicsContext, user::BoundingBox)
Add a sub-path rectangle to the current path. The x
and y
specify the (typically the upper left) corner coordinate of the rectangle, and the width
and height
specify the size.
You can also specify the position and size by a BoundingBox
in user-space coordinate.
Graphics.circle
— Functioncircle(gc::GraphicsContext, x, y, r)
Add a sub-path circle to the current path. The x
and y
specify the center coordinate of the circle, and the r
specifies the radius.
Graphics.polygon
— Functionpolygon(gc::GraphicsContext, verts::Matrix, idx::Vector)
Add a closed sub-path polygon with the given vertices. The verts
is a collection of vertex coordinates in the following matrix form:
[x1 x2 x3 ... xn;
y1 y2 y3 ... yn]
The idx
is a vector of vertex indices, i.e. the matrix column numbers.
You can reuse the vertex coordinates by specifying the same index in idx
. This is useful when drawing meshes.
polygon(gc::GraphicsContext, points::AbstractVector)
Add a closed sub-path polygon with the given vertices to .
Fill and stroke
Base.fill
— Functionfill(gc::GraphicsContext)
Fill the current path according to the current fill rule. The current path will be cleared from the context.
See also: fill_preserve
.
Graphics.fill_preserve
— Functionfill_preserve(gc::GraphicsContext)
Fill the current path according to the current fill rule. Unlike the fill
function, this function preserves the current path within the context.
Graphics.paint
— Functionpaint(gc::GraphicsContext)
Paint the current source everywhere within the current clipping region.
Graphics.stroke
— Functionstroke(gc::GraphicsContext)
Stroke the current path according to the current stroke style. The current path will be cleared from the context.
The stroke
function ignores the current transformation. If you want to apply the current transformation to the stroke, use stroke_transformed
.
See also: stroke_preserve
.
Graphics.stroke_preserve
— Functionstroke_preserve(gc::GraphicsContext)
Stroke the current path according to the current stroke style. Unlike the stroke
function, this function preserves the current path within the context.
The stroke_preserve
function ignores the current transformation. If you want to apply the current transformation to the stroke, use stroke_transformed_preserve
.
Graphics.stroke_transformed
— Functionstroke_transformed(gc::GraphicsContext)
Stroke the current path according to the current stroke style and the current transformation.
See also: stroke
.
Graphics.stroke_transformed_preserve
— Functionstroke_transformed_preserve(gc::GraphicsContext)
Stroke the current path according to the current stroke style and the current transformation. Unlike the stroke_transformed
function, this function preserves the current path within the context.
See also: stroke_preserve
.