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 . In this case, there is no need to call MGraphics.init().

Constructors

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 object by passing the MGraphics instance to the Image constructor.

Properties

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.

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.

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.

Methods

append_path

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

append_path(path: MGraphicsPathHandle);

arc_negative

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

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

arc

Add a circular, clockwise arc to the current path.

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

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

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

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

Add a closed ellipse to the current path.

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

fill_extent

Get the enclosing rectangle of the current path.

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

fill_preserve_with_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_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_with_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);

fill

Fill the current path.

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

fill();

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

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]);

in_fill

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

Add a line segment to the current path.

line_to(x: number, y: number);

move_to

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);

ovalarc

Add an ellipical arc to the current path.

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

path_roundcorners

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

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

Create a linear gradient.

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

pattern_create_radial

Create a radial gradient.

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

pattern_create_rgba

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;

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_rounded

Add a closed rounded-rectangle to the current path.

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

rectangle

Add a closed rectangle to the current path

rectangle(x: number, y: number, width: number, height: 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

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

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

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);

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

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_source_rgba

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

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);

select_font_face

Sets the current font face by name

select_font_face(fontname: string);

set_font_size

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

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

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

set_line_join

Set the appearance of the connection point between lines.

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

set_line_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

Set the current transform matrix directly.

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

set_source_rgb

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);

set_source_rgba

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);

set_source_surface

Sets an image to use as a drawing source

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

set_source

Set the source pattern.

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

set_source(pattern: Pattern);

show_text

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);

stroke_preserve_with_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_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_with_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);

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();

svg_render

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

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

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);

transform

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);

translate_source_rgba

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

Adds a translation to the current transform matrix.

translate(t_x: number, t_y: number);

user_to_device

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];