class MGraphics

Drawing context for rendering shapes and images.

The MGraphics object combines a virtual drawing canvas with functions to manage drawing to that canvas. In enables you to draw simple shapes, complex paths, text, and images.

Most of the time, you'll work with the global MGraphics object, always stored in a global variable called mgraphics, in order to perform custom drawing of a jsui object, or in a jspainter file. In that case, make sure to call the MGraphics.init() method somewhere in global scope:

// Initialize mgraphics
mgraphics.init();

// Now you can use mgraphics in your custom drawing code
function paint() {
  mgraphics.rectangle(50, 0, 200, 100);
  mgraphics.fill();
}

It's also possible to create your own MGraphics object in order to draw to an offsceen Image. In this case, there is no need to call MGraphics.init().

Index

Constructors

• new MGraphics(width, height)

Properties

• autofill
• autopaint
• autosketch
• relative_coords
• size
• textfieldvisible

Methods

• append_path(path)
• arc(xc, yc, radius, angle1, angle2)
• arc_negative(xc, yc, radius, angle1, angle2)
• clear_surface()
• close_path()
• copy_path()
• curve_to(x1, y1, x2, y2, x3, y3)
• device_to_user(position)
• ellipse(x, y, width, height)
• fill()
• fill_extents()
• fill_preserve()
• fill_preserve_with_alpha(alpha)
• fill_with_alpha(alpha)
• font_extents()
• get_current_point()
• get_line_cap()
• get_line_join()
• get_line_width()
• get_matrix()
• getfontlist()
• identity_matrix()
• image_surface_draw(image, source_rect)
• image_surface_draw_fast(image)
• in_fill(position)
• init()
• line_to(x, y)
• move_to(x, y)
• new_path()
• ovalarc(xc, yc, radiusx, radiusy, angle1, angle2)
• paint()
• paint_with_alpha(alpha)
• path_roundcorners(radius)
• pattern_create_for_surface(image)
• pattern_create_linear(x1, y1, x2, y2)
• pattern_create_radial(x1, y1, rad1, x2, y2, rad2)
• pattern_create_rgba(red, green, blue, alpha)
• pop_group()
• pop_group_to_source()
• push_group()
• rectangle(x, y, width, height)
• rectangle_rounded(x, y, width, height, ovalwidth, ovalheight)
• redraw()
• rel_curve_to(x1, y1, x2, y2, x3, y3)
• rel_line_to(x, y)
• rel_move_to(x, y)
• restore()
• rotate(angle)
• save()
• scale(scale_x, scale_y)
• scale_source_rgba(sc_red, sc_green, sc_blue, sc_alpha)
• scale_source_rgba(colors)
• select_font_face(fontname, bold, italic)
• set_dash(dashes)
• set_font_size(fontsize)
• set_line_cap(cap)
• set_line_join(join)
• set_line_width(width)
• set_matrix(xx, xy, yx, yy, x0, y0)
• set_matrix(matrix)
• set_source(pattern)
• set_source_rgb(red, green, blue)
• set_source_rgb(colors)
• set_source_rgba(red, green, blue, alpha)
• set_source_rgba(colors)
• set_source_surface(image, dx, dy)
• show_text(text_to_display)
• stroke()
• stroke_preserve()
• stroke_preserve_with_alpha(alpha)
• stroke_with_alpha(alpha)
• svg_render(source, x, y, width, height, opacity)
• text_measure(text)
• text_path(text_to_display)
• transform(xx, xy, yx, yy, x0, y0)
• transform(matrix)
• translate(t_x, t_y)
• translate_source_rgba(t_red, t_green, t_blue, t_alpha)
• translate_source_rgba(colors)
• user_to_device(position)

new MGraphics(width, height)

new MGraphics(width: number, height: number);

Creates a new MGraphics instance

Create a MGraphics context, including a buffer of offscreen memory to to render to, which can be used as a drawing context for creating saved or persistent images. An MGraphics instance can also be copied into an Image object by passing the MGraphics instance to the Image constructor.

append_path(path)

Appends a stored path to the current path at the current end point.

append_path(path: MGraphicsPathHandle);

arc(xc, yc, radius, angle1, angle2)

Add a circular, clockwise arc to the current path.

arc(xc: number, yc: number, radius: number, angle1: number, angle2: number);

arc_negative(xc, yc, radius, angle1, angle2)

Add a circular, counter-clockwise arc to the current path.

arc_negative(
  xc: number,
  yc: number,
  radius: number,
  angle1: number,
  angle2: number,
);

autofill 1 | 0

Enable or disable automatic fill after stroke.

With autofill enabled, any call to MGraphics.stroke() will also fill the current path automatically.

autopaint 1 | 0

Turns on/off painting of the global MGraphics object.

See MGraphics.autosketch for technical details about managing autosketch and autopaint. In most cases, use the MGraphics.init() method to enable custom drawing with mgraphics.

autosketch 1 | 0

Turns on/off painting with the global sketch object.

In the context of a jsui or jspainter object, the object draws itself using two layers: sketch and mgraphics. By default, only the sketch layer renders, and the mgraphics layer is unused. If the mgraphics layer is enabled, then the object will call into the user-defined paint() function to draw the mgraphics layer on top of the sketch layer. Calling MGraphics.init() will set autosketch to 0 and autopaint to 1, disabling the sketch layer and displaying only custom drawing in the mgraphics layer. In most cases, this is the easiest way to implement custom drawing.

clear_surface()

Clear the current surface.

Erases all drawing on the current surface, returning it to a transparent state.

clear_surface(): void;

close_path()

Close the current path.

Adds a line from the current point to the starting point of the path, which closes it.

close_path();

copy_path()

Returns a copy of the current path.

Returns a copy of the current path to be stored and reused later.

copy_path(): MGraphicsPathHandle;

curve_to(x1, y1, x2, y2, x3, y3)

Add a cubic Bezier spline to the current path.

curve_to(
  x1: number,
  y1: number,
  x2: number,
  y2: number,
  x3: number,
  y3: number,
);

device_to_user(position)

Convert a point in device space to user space.

The inverse of MGraphics.user_to_device().

device_to_user(position: [number, number]): [number, number];

ellipse(x, y, width, height)

Add a closed ellipse to the current path.

ellipse(x: number, y: number, width: number, height: number);

fill()

Fill the current path.

Fill the current path, using the current MGraphics context settings including color. The path is discarded afterwards.

fill();

fill_extents()

Get the enclosing rectangle of the current path.

fill_extents(): [number, number, number, number];

fill_preserve()

Draw and preserve the current path.

Fill the current path, using the current MGraphics context settings including color. Do not discard the path afterwards, which can be useful, for example, when you want to draw the stroke and fill with different colors.

fill_preserve();

fill_preserve_with_alpha(alpha)

Fill and preserve the current path with alpha override.

Fill the current path, but override the alpha value of the current color with a new alpha channel value. This lets you change transparency without resetting the color values. Do not discard the path afterwards.

fill_preserve_with_alpha(alpha: number);

fill_with_alpha(alpha)

Fill the current path with alpha override.

Fill the current path, but override the alpha value of the current color with a new alpha channel value. This lets you change transparency without resetting the color values. The path is discarded afterwards.

fill_with_alpha(alpha: number);

font_extents()

Get ascent, descent, and height for font.

Returns the ascent, descent, and height for the current font. Ascent measures the distance from the text baseline to the tallest glyph. Descent measures the distance from the text baseline to the lowest point on any glyph under the baseline. Height is simply ascent plut descent.

font_extents(): [number, number, number];

get_current_point()

The current drawing position.

This is the point at which any new additions to the current path would begin. It is also the end point of the current path, and if you close the current path, this point will be connected back to the start of the the path. Most functions that add to the path will move this point.

get_current_point(): [number, number];

get_line_cap()

Get the current line cap.

get_line_cap(): "butt" | "round" | "square";

get_line_join()

Get the current line join.

get_line_join(): "miter" | "round" | "bevel";

get_line_width()

Get the current line width.

get_line_width(): number;

get_matrix()

Retrieve the current transformation matrix.

get_matrix(): MGraphicsMatrixHandle;

getfontlist()

Get a list of installed fonts.

Get a list of all fonts installed on your system.

getfontlist(): string[];

identity_matrix()

Reset the transform matrix to identity (no transformation).

identity_matrix();

image_surface_draw(image, source_rect)

Draw an image into the current surface.

Place an image (typically stored as an Image object) into the current surface. The drawing is placed at the top-left of the drawing context, changeable using a transform matrix or translate function. You can also choose the section of the image to draw using four optional arguments that describe a rectangle taken from the image.

image_surface_draw(
  image: Image,
  source_rect?: [number, number, number, number],
);

image_surface_draw_fast(image)

Draw an image quickly into the current surface.

A faster version of MGraphics.image_surface_draw() that draws the image directly without applying transforms.

image_surface_draw_fast(image: Image): void;

in_fill(position)

Determine if a point is within the current path.

Assuming the current path is fillable, tests if the given position is contained in the current path.

in_fill(position: [number, number]): 1 | 0;

init()

Initialize the mgraphics system.

Initialize the mgraphics system. Call this somewhere in global scope (usually near the top of your JavaScript file) in order to use mgraphics in your custom drawing code.

init(): void;

line_to(x, y)

Add a line segment to the current path.

line_to(x: number, y: number);

move_to(x, y)

Move the current point to a new location.

Move the current point to a new location, and begin a new subpath.

move_to(x: number, y: number);

new_path()

Create a new, empty path.

new_path();

ovalarc(xc, yc, radiusx, radiusy, angle1, angle2)

Add an ellipical arc to the current path.

ovalarc(
  xc: number,
  yc: number,
  radiusx: number,
  radiusy: number,
  angle1: number,
  angle2: number,
);

paint()

Paint the current source everywhere within the current clip region.

paint(): void;

paint_with_alpha(alpha)

Paint with alpha.

Paint the current source everywhere within the current clip region, using the given alpha value.

paint_with_alpha(alpha: number): void;

path_roundcorners(radius)

Round the corners of the current path.

Modify the current path by rounding the corners to the radius provided, or as close as possible depending on the path's angle.

path_roundcorners(radius: number);

pattern_create_for_surface(image)

Create a pattern using an image.

Create a pattern using an image for the background. Repeating patterns depends on the extend value set using the Pattern.set_extend() function

pattern_create_for_surface(image: Image): Pattern;

pattern_create_linear(x1, y1, x2, y2)

Create a linear gradient.

pattern_create_linear(
  x1: number,
  y1: number,
  x2: number,
  y2: number,
): Pattern;

pattern_create_radial(x1, y1, rad1, x2, y2, rad2)

Create a radial gradient.

pattern_create_radial(
  x1: number,
  y1: number,
  rad1: number,
  x2: number,
  y2: number,
  rad2: number,
): Pattern;

pattern_create_rgba(red, green, blue, alpha)

Create a solid color pattern.

pattern_create_rgba(
  red: number,
  green: number,
  blue: number,
  alpha: number,
): Pattern;

pop_group()

Completes a path execution group and returns the result.

Complete a path execution group, returning the results as a Pattern.

pop_group(): Pattern;

pop_group_to_source()

Pop a group and set it as the current source.

Complete a path execution group and set the result as the current source. This is equivalent to calling MGraphics.pop_group() and then passing the result to MGraphics.set_source().

pop_group_to_source(): void;

push_group()

Define a starting point for a path execution group.

Define a starting point for a path execution group. This group can be used for creating an image from a set of path functions without actually drawing the results to the screen.

push_group();

rectangle(x, y, width, height)

Add a closed rectangle to the current path

rectangle(x: number, y: number, width: number, height: number);

rectangle_rounded(x, y, width, height, ovalwidth, ovalheight)

Add a closed rounded-rectangle to the current path.

rectangle_rounded(
  x: number,
  y: number,
  width: number,
  height: number,
  ovalwidth: number,
  ovalheight: number,
);

redraw()

Request that the current display area be redrawn.

Request that the current display area be redrawn. Max will then call your custom paint() function as part of the next available drawing loop. You should never call your custom paint() function directly.

redraw(): void;

rel_curve_to(x1, y1, x2, y2, x3, y3)

Add a cubic Bezier spline relative to the current point.

Add a cubic Bezier spline to the current path. The arguments to this function are coordinates relative to the current point.

rel_curve_to(
  x1: number,
  y1: number,
  x2: number,
  y2: number,
  x3: number,
  y3: number,
);

rel_line_to(x, y)

Add a line segment relative to the current point.

Add a line segment to the current path. The arguments to this function are coordinates relative to the current point.

rel_line_to(x: number, y: number);

rel_move_to(x, y)

Move the current point relative to the current point.

Move the current point to a new location, and begin a new subpath. The arguments to this function are relative to the current point.

rel_move_to(x: number, y: number);

relative_coords 1 | 0

Enable or disable the use of relative coordinates.

When disabled, the origin [0, 0] will be the top-left, and [width, height] will be the bottom-right, where width and height are the dimensions of MGraphics.size. When relative_coords is enabled, the origin [0, 0] will be in the center of the drawing area. The y-coordinate -1 will always be the top, and 1 will always be the bottom. The x-coordinate of the left edge will depend on the aspect ratio of the drawing area. If the width of the drawing area is x times the height, then the left edge will be -x and the right edge will be x.

restore()

Pop the current MGraphics state.

Pop the most recent saved MGraphics state off the stack and apply it. See MGraphics.save().

restore(): void;

rotate(angle)

Adds a rotation to the current transform matrix.

rotate(angle: number);

save()

Push the current MGraphics state.

Push the current MGraphics state, including stroke and fill color, the current matrix transform, line style, and font style, onto the state stack. After making changes, call MGraphics.restore() to return to the saved state.

save(): void;

scale(scale_x, scale_y)

Add a scale to the current transform matrix.

Add a scale to the current transform matrix. This will stretch or squish the drawing horizontally or vertially. Affects line widths.

scale(scale_x: number, scale_y: number);

scale_source_rgba(sc_red, sc_green, sc_blue, sc_alpha)

Modifies the color transform by adding a scale.

Modifies the color transform by adding a scale. When drawing, MGraphics will multiple the current source color by this scale before drawing. This can be useful if you want to modify the source color in some way without losing the source color. Calling this function again will scale the color further. There is no way to reset the color transform without using MGraphics.save() and MGraphics.restore().

scale_source_rgba(
  sc_red: number,
  sc_green: number,
  sc_blue: number,
  sc_alpha: number,
);

scale_source_rgba(colors)

Modifies the color transform by adding a scale, using an array

scale_source_rgba(colors: [number, number, number, number]);

select_font_face(fontname, bold, italic)

Sets the current font face by name

select_font_face(fontname: string, bold?: "bold", italic?: "italic");

set_dash(dashes)

Set the dash pattern for stroked lines.

Sets the dash pattern to be used when stroking a path. The pattern is defined by an array of alternating dash and gap lengths. Call with no arguments to clear the dash pattern and return to a solid line.

set_dash(...dashes: number[]): void;

set_font_size(fontsize)

Set the current font size

Set the current font size. Floating point and integers are both accepted.

set_font_size(fontsize: number);

set_line_cap(cap)

Set the drawing style for the end point of a line.

set_line_cap(cap: "butt" | "round" | "square");

set_line_join(join)

Set the appearance of the connection point between lines.

set_line_join(join: "miter" | "round" | "bevel");

set_line_width(width)

Set the current line width.

Set the width of path lines drawn using the MGraphics.stroke() function. The interpretation of this value is dependent on the coordinate system in use, set with MGraphics.relative_coords

set_line_width(width: number);

set_matrix(xx, xy, yx, yy, x0, y0)

Set the current transform matrix directly.

set_matrix(
  xx: number,
  xy: number,
  yx: number,
  yy: number,
  x0: number,
  y0: number,
);

set_matrix(matrix)

Set the current transform matrix directly, using an array

set_matrix(matrix: [number, number, number, number, number, number]);

set_source(pattern)

Set the source pattern.

Sets the pattern to be used for the next MGraphics.fill() call.

set_source(pattern: Pattern);

set_source_rgb(red, green, blue)

Set the color used for drawing.

Set the color used for drawing, and set the opacity to 1 (fully opaque).

set_source_rgb(red: number, green: number, blue: number): void;

set_source_rgb(colors)

Set drawing color using an array

Set the color used for drawing, and set the opacity to 1 (fully opaque).

set_source_rgb(colors: [number, number, number]): void;

set_source_rgba(red, green, blue, alpha)

Set the color and alpha used for drawing.

Set the color and alpha used for drawing. Values are between 0 and 1.

set_source_rgba(
  red: number,
  green: number,
  blue: number,
  alpha: number,
): void;

set_source_rgba(colors)

Set drawing color and alpha using an array

Set the color and alpha used for drawing. Values are between 0 and 1.

set_source_rgba(colors: [number, number, number, number]): void;

set_source_surface(image, dx, dy)

Sets an image to use as a drawing source

set_source_surface(image: Image, dx?: number, dy?: number);

show_text(text_to_display)

Draw text without a path.

Draws the text at the current location, using the current font face and font size. This does not create a path or modify the current path. Matrix transforms will not affect this drawing.

show_text(text_to_display: string);

size [number, number] read-only

Get the current size of the MGraphics canvas

If you're using the global mgraphics instance as part of custom drawing code for jsui or with jspainter, then this will be the size of the object being redrawn.

stroke()

Draw the outline of the current path.

Draw the outline of the current path, using the current settings for color, line width, etc. The path is discarded afterwards.

stroke();

stroke_preserve()

Draw and preserve the outline of the current path.

Draw the outline of the current path, using the current settings for color, line width, etc. Do not discard the path afterwards, which can be useful, for example, when you want to draw the stroke and fill with different colors.

stroke_preserve();

stroke_preserve_with_alpha(alpha)

Draw and preserve the outline of the current path with alpha override.

Draw the outline of the current path, but override the alpha value of the current color with a new alpha channel value. This lets you change transparency without resetting the color values. Do not discard the path afterwards.

stroke_preserve_with_alpha(alpha: number);

stroke_with_alpha(alpha)

Draw the outline of the current path with alpha override.

Draw the outline of the current path, but override the alpha value of the current color with a new alpha channel value. This lets you change transparency without resetting the color values. The path is discarded afterwards.

stroke_with_alpha(alpha: number);

svg_render(source, x, y, width, height, opacity)

Render an SVG image.

Draw an SVG image in the current graphics context. The SVG source can be either a filename, or a raw SVG string, or an MGraphicsSVG object. Optional x, y, width, and height arguments determine the destination rect into which the SVG will be rendered.

svg_render(
  source: MGraphicsSVG | string,
  x?: number,
  y?: number,
  width?: number,
  height?: number,
  opacity?: number,
);

text_measure(text)

Measure the bounds of text

Returns an array contaning the width and height of the given text, as it would appear if rendered in the current font face and font size.

text_measure(text: string): [number, number];

text_path(text_to_display)

Create a path from text

Creates a path from the given text, using the current font face and font size. Once the text is in the path, it can be transformed just like an ordinary path.

text_path(text_to_display: string);

textfieldvisible 1 | 0

Enable or disable the display of a text field when the user clicks on the jsui/jspainter.

transform(xx, xy, yx, yy, x0, y0)

Modify the current transform matrix by multiplying.

Modify the current transform matrix by multiplying. Useful if you already have a transform matrix that you want to include in the current matrix transform.

transform(
  xx: number,
  xy: number,
  yx: number,
  yy: number,
  x0: number,
  y0: number,
);

transform(matrix)

Modify the current transform matrix by multiplying, using an array

transform(matrix: [number, number, number, number, number, number]);

translate(t_x, t_y)

Adds a translation to the current transform matrix.

translate(t_x: number, t_y: number);

translate_source_rgba(t_red, t_green, t_blue, t_alpha)

Modifies the color transform by adding an offset.

Modifies the color transform by adding an offset. When drawing, MGraphics will add this offset to the current source color before drawing. This can be useful if you want to modify the source color in some way without losing the source color. Calling this function again will increase or decrease the color offset. There is no way to reset the color transform without using MGraphics.save() and MGraphics.restore().

translate_source_rgba(
  t_red: number,
  t_green: number,
  t_blue: number,
  t_alpha: number,
);

translate_source_rgba(colors)

Modifies the color transform by adding an offset, using an array

translate_source_rgba(colors: [number, number, number, number]);

user_to_device(position)

Convert a user space point to device space.

Convert a point in user space, in which drawing occurs, to device space, the coordinate system after matrix transforms have been applied. If MGraphics were an oil painting, user space would be the position of a point on the canvas, and device space would be where that same point appears in a photograph taken of the painting.

user_to_device(position: [number, number]): [number, number];