Max 5 API Reference

JGraphics
[User Interface]

The JGraphics API provided in Max 5 is an interface for drawing based on the API for the Cairo vector graphics library ( http://en.wikipedia.org/wiki/Cairo_%28graphics%29 , http://cairographics.org/manual/ ). More...

Collaboration diagram for JGraphics:

Data Structures

struct  t_jgraphics_font_extents
 A structure for holding information related to how much space the rendering of a given font will use. More...

Modules

 JSurface
 

A surface is an abstract base class for something you render to.


 Scalable Vector Graphics
 JFont
 JGraphics Matrix Transformations
 

The t_jmatrix is one way to represent a transformation.


 JPattern
 

A pattern is like a brush that is used to fill a path with.


 Colors
 TextField
 

The textfield is a high-level text display object that may be used by a UI object to represent text in a patcher.


 TextLayout
 

A textlayout is lower-level text rendering object used by higher-level entities such as TextField.


 Popup Menus
 

Popup menu API so externals can create popup menus that can also be drawn into.


 Box Layer
 

The boxlayer functions provide way to make it easier to use cached offscreen images (layers) in your drawing.


Defines

#define JGRAPHICS_RECT_BOTTOM(rect)   (((rect)->y)+((rect)->height))
 Determine the coordinate of the bottom of a rect.
#define JGRAPHICS_RECT_RIGHT(rect)   (((rect)->x)+((rect)->width))
 Determine the coordinate of the right side of a rect.
#define JGRAPHICS_PI   (3.1415926535897932384626433832795028842)
 Utility macro to return the value of Pi.
#define JGRAPHICS_2PI   (2. * 3.1415926535897932384626433832795028842)
 Utility macro to return the value of twice Pi.
#define JGRAPHICS_PIOVER2   (0.5 * 3.1415926535897932384626433832795028842)
 Utility macro to return the value of half of Pi.
#define JGRAPHICS_3PIOVER2   ((3.0 * JGRAPHICS_PI) / 2.0)
 Utility macro to return the 270º Case.

Typedefs

typedef
typedefBEGIN_USING_C_LINKAGE
struct _jgraphics 
t_jgraphics
 An instance of a jgraphics drawing context.
typedef struct _jpath t_jpath
 An instance of a jgraphics path.
typedef struct _jtextlayout t_jtextlayout
 An instance of a jgraphics text layout object.
typedef struct _jtransform t_jtransform
 An instance of a jgraphics transform.
typedef struct _jsvg t_jsvg
 An instance of an SVG object.
typedef struct _jpopupmenu t_jpopupmenu
 An instance of a pop-up menu.

Enumerations

enum  t_jgraphics_format {
  JGRAPHICS_FORMAT_ARGB32,
  JGRAPHICS_FORMAT_RGB24,
  JGRAPHICS_FORMAT_A8
}
 

Enumeration of color formats used by jgraphics surfaces.

More...
enum  t_jgraphics_fileformat {
  JGRAPHICS_FILEFORMAT_PNG,
  JGRAPHICS_FILEFORMAT_JPEG
}
 

Enumeration of file formats usable for jgraphics surfaces.

More...
enum  t_jgraphics_text_justification {
  JGRAPHICS_TEXT_JUSTIFICATION_LEFT = 1,
  JGRAPHICS_TEXT_JUSTIFICATION_RIGHT = 2,
  JGRAPHICS_TEXT_JUSTIFICATION_HCENTERED = 4,
  JGRAPHICS_TEXT_JUSTIFICATION_TOP = 8,
  JGRAPHICS_TEXT_JUSTIFICATION_BOTTOM = 16,
  JGRAPHICS_TEXT_JUSTIFICATION_VCENTERED = 32,
  JGRAPHICS_TEXT_JUSTIFICATION_HJUSTIFIED = 64,
  JGRAPHICS_TEXT_JUSTIFICATION_CENTERED = JGRAPHICS_TEXT_JUSTIFICATION_HCENTERED + JGRAPHICS_TEXT_JUSTIFICATION_VCENTERED
}
 

Enumeration of text justification options, which are specified as a bitmask.

More...

Functions

int jgraphics_round (double d)
 Utility for rounding a double to an int.
t_jgraphicsjgraphics_reference (t_jgraphics *g)
 Get a reference to a graphics context.
void jgraphics_destroy (t_jgraphics *g)
 Release or free a graphics context.
void jgraphics_new_path (t_jgraphics *g)
 Begin a new path.
t_jpathjgraphics_copy_path (t_jgraphics *g)
 Get a copy of the current path from a context.
void jgraphics_path_destroy (t_jpath *path)
 Release/free a path.
void jgraphics_append_path (t_jgraphics *g, t_jpath *path)
 Add a path to a graphics context.
void jgraphics_close_path (t_jgraphics *g)
 Close the current path in a context.
void jgraphics_path_roundcorners (t_jgraphics *g, double cornerRadius)
 Round out any corners in a path.
void jgraphics_get_current_point (t_jgraphics *g, double *x, double *y)
 Get the current location of the cursor in a graphics context.
void jgraphics_arc (t_jgraphics *g, double xc, double yc, double radius, double angle1, double angle2)
 Add a circular, clockwise, arc to the current path.
void jgraphics_ovalarc (t_jgraphics *g, double xc, double yc, double radiusx, double radiusy, double angle1, double angle2)
 Add a non-circular arc to the current path.
void jgraphics_arc_negative (t_jgraphics *g, double xc, double yc, double radius, double angle1, double angle2)
 Add a circular, counter-clockwise, arc to the current path.
void jgraphics_curve_to (t_jgraphics *g, double x1, double y1, double x2, double y2, double x3, double y3)
 Add a cubic Bezier spline to the current path.
void jgraphics_rel_curve_to (t_jgraphics *g, double x1, double y1, double x2, double y2, double x3, double y3)
 Add a cubic Bezier spline to the current path, using coordinates relative to the current point.
void jgraphics_line_to (t_jgraphics *g, double x, double y)
 Add a line segment to the current path.
void jgraphics_rel_line_to (t_jgraphics *g, double x, double y)
 Add a line segment to the current path, using coordinates relative to the current point.
void jgraphics_move_to (t_jgraphics *g, double x, double y)
 Move the cursor to a new point and begin a new subpath.
void jgraphics_rel_move_to (t_jgraphics *g, double x, double y)
 Move the cursor to a new point and begin a new subpath, using coordinates relative to the current point.
void jgraphics_rectangle (t_jgraphics *g, double x, double y, double width, double height)
 Add a closed rectangle path in the context.
void jgraphics_oval (t_jgraphics *g, double x, double y, double width, double height)
 Deprecated -- do not use.
void jgraphics_rectangle_rounded (t_jgraphics *g, double x, double y, double width, double height, double ovalwidth, double ovalheight)
 Add a closed rounded-rectangle path in the context.
void jgraphics_ellipse (t_jgraphics *g, double x, double y, double width, double height)
 Add a closed elliptical path in the context.
void jgraphics_select_font_face (t_jgraphics *g, const char *family, t_jgraphics_font_slant slant, t_jgraphics_font_weight weight)
 Specify a font for a graphics context.
void jgraphics_select_jfont (t_jgraphics *g, t_jfont *jfont)
 Specify a font for a graphics context by passing a t_jfont object.
void jgraphics_set_font_size (t_jgraphics *g, double size)
 Specify the font size for a context.
void jgraphics_set_underline (t_jgraphics *g, char underline)
 Turn underlining on/off for text in a context.
void jgraphics_show_text (t_jgraphics *g, const char *utf8)
 Display text at the current position in a context.
void jgraphics_font_extents (t_jgraphics *g, t_jgraphics_font_extents *extents)
 Return the extents of the currently selected font for a given graphics context.
void jgraphics_text_measure (t_jgraphics *g, const char *utf8, double *width, double *height)
 Return the height and width of a string given current graphics settings in a context.
void jgraphics_text_measure_wrapped (t_jgraphics *g, const char *utf8, double wrapwidth, long includewhitespace, double *width, double *height, long *numlines)
 Return the height, width, and number of lines that will be used to render a given string.
long jgraphics_system_canantialiastexttotransparentbg ()
 Determine if you can anti-alias text to a transparent background.
void jgraphics_user_to_device (t_jgraphics *g, double *x, double *y)
 User coordinates are those passed to drawing functions in a given t_jgraphics context.
void jgraphics_device_to_user (t_jgraphics *g, double *x, double *y)
 User coordinates are those passed to drawing functions in a given t_jgraphics context.
void jgraphics_getfiletypes (void *dummy, long *count, long **filetypes, char *alloc)
 Get a list of of filetypes appropriate for use with jgraphics surfaces.
long jgraphics_rectintersectsrect (t_rect *r1, t_rect *r2)
 Simple utility to test for rectangle intersection.
long jgraphics_rectcontainsrect (t_rect *outer, t_rect *inner)
 Simple utility to test for rectangle containment.
void jgraphics_position_one_rect_near_another_rect_but_keep_inside_a_third_rect (t_rect *positioned_rect, const t_rect *positioned_near_this_rect, const t_rect *keep_inside_this_rect)
 Generate a t_rect according to positioning rules.

Detailed Description

The JGraphics API provided in Max 5 is an interface for drawing based on the API for the Cairo vector graphics library ( http://en.wikipedia.org/wiki/Cairo_%28graphics%29 , http://cairographics.org/manual/ ).

Internally, the drawing is rendered using JUCE ( http://rawmaterialsoftware.com/juce/ ), however JUCE functions cannot be called directly.


Define Documentation

#define JGRAPHICS_2PI   (2. * 3.1415926535897932384626433832795028842)

Utility macro to return the value of twice Pi.

#define JGRAPHICS_3PIOVER2   ((3.0 * JGRAPHICS_PI) / 2.0)

Utility macro to return the 270º Case.

#define JGRAPHICS_PI   (3.1415926535897932384626433832795028842)

Utility macro to return the value of Pi.

#define JGRAPHICS_PIOVER2   (0.5 * 3.1415926535897932384626433832795028842)

Utility macro to return the value of half of Pi.


Enumeration Type Documentation

Enumeration of file formats usable for jgraphics surfaces.

Enumerator:
JGRAPHICS_FILEFORMAT_PNG 

Portable Network Graphics (PNG) format.

JGRAPHICS_FILEFORMAT_JPEG 

JPEG format.

Enumeration of color formats used by jgraphics surfaces.

Enumerator:
JGRAPHICS_FORMAT_ARGB32 

Color is represented using 32 bits, 8 bits each for the components, and including an alpha component.

JGRAPHICS_FORMAT_RGB24 

Color is represented using 32 bits, 8 bits each for the components. There is no alpha component.

JGRAPHICS_FORMAT_A8 

The color is represented only as an 8-bit alpha mask.

Enumeration of text justification options, which are specified as a bitmask.

Enumerator:
JGRAPHICS_TEXT_JUSTIFICATION_LEFT 

Justify left.

JGRAPHICS_TEXT_JUSTIFICATION_RIGHT 

Justify right.

JGRAPHICS_TEXT_JUSTIFICATION_HCENTERED 

Centered horizontally.

JGRAPHICS_TEXT_JUSTIFICATION_TOP 

Justified to the top.

JGRAPHICS_TEXT_JUSTIFICATION_BOTTOM 

Justified to the bottom.

JGRAPHICS_TEXT_JUSTIFICATION_VCENTERED 

Centered vertically.

JGRAPHICS_TEXT_JUSTIFICATION_HJUSTIFIED 

Horizontally justified.

JGRAPHICS_TEXT_JUSTIFICATION_CENTERED 

Shortcut for Centering both vertically and horizontally.


Function Documentation

void jgraphics_append_path ( t_jgraphics g,
t_jpath path 
)

Add a path to a graphics context.

Parameters:
g The graphics context.
path The path to add.
void jgraphics_arc ( t_jgraphics g,
double  xc,
double  yc,
double  radius,
double  angle1,
double  angle2 
)

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

Parameters:
g The graphics context.
xc The horizontal coordinate of the arc's center.
yc The vertical coordinate of the arc's center.
radius The radius of the arc.
angle1 The starting angle of the arc in radians. Zero radians is center right (positive x axis).
angle2 The terminal angle of the arc in radians. Zero radians is center right (positive x axis).
void jgraphics_arc_negative ( t_jgraphics g,
double  xc,
double  yc,
double  radius,
double  angle1,
double  angle2 
)

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

Parameters:
g The graphics context.
xc The horizontal coordinate of the arc's center.
yc The vertical coordinate of the arc's center.
radius The radius of the arc.
angle1 The starting angle of the arc in radians. Zero radians is center right (positive x axis).
angle2 The terminal angle of the arc in radians. Zero radians is center right (positive x axis).
void jgraphics_close_path ( t_jgraphics g  ) 

Close the current path in a context.

This will add a line segment to close current subpath.

Parameters:
g The graphics context.
t_jpath* jgraphics_copy_path ( t_jgraphics g  ) 

Get a copy of the current path from a context.

Parameters:
g A copy of the current path.
void jgraphics_curve_to ( t_jgraphics g,
double  x1,
double  y1,
double  x2,
double  y2,
double  x3,
double  y3 
)

Add a cubic Bezier spline to the current path.

Parameters:
g The graphics context.
x1 The first control point.
y1 The first control point.
x2 The second control point.
y2 The second control point.
x3 The destination point.
y3 The destination point.
void jgraphics_destroy ( t_jgraphics g  ) 

Release or free a graphics context.

Parameters:
g The context to release.
void jgraphics_device_to_user ( t_jgraphics g,
double *  x,
double *  y 
)

User coordinates are those passed to drawing functions in a given t_jgraphics context.

Device coordinates refer to patcher canvas coordinates, before any zooming.

void jgraphics_ellipse ( t_jgraphics g,
double  x,
double  y,
double  width,
double  height 
)

Add a closed elliptical path in the context.

Parameters:
g The graphics context.
x The horizontal origin.
y The vertical origin.
width The width of the rect.
height The height of the rect.
void jgraphics_font_extents ( t_jgraphics g,
t_jgraphics_font_extents extents 
)

Return the extents of the currently selected font for a given graphics context.

Parameters:
g Pointer to a jgraphics context.
extents The address of a t_jgraphics_font_extents structure to be filled with the results.
void jgraphics_get_current_point ( t_jgraphics g,
double *  x,
double *  y 
)

Get the current location of the cursor in a graphics context.

Parameters:
g The graphics context.
x The address of a variable that will be set to the horizontal cursor location upon return.
y The address of a variable that will be set to the vertical cursor location upon return.
void jgraphics_getfiletypes ( void *  dummy,
long *  count,
long **  filetypes,
char *  alloc 
)

Get a list of of filetypes appropriate for use with jgraphics surfaces.

Parameters:
dummy Unused.
count The address of a variable to be set with the number of types in filetypes upon return.
filetypes The address of a variable that will represent the array of file types upon return.
alloc The address of a char that will be flagged with a 1 or a 0 depending on whether or not memory was allocated for the filetypes member.
Remarks:
This example shows a common usage of jgraphics_getfiletypes().
    char       filename[MAX_PATH_CHARS];
    long       *type = NULL;
    long       ntype;
    long       outtype;
    t_max_err  err;
    char       alloc;
    short      path;
    t_jsurface *surface;
    
    if (want_to_show_dialog) {
        jgraphics_getfiletypes(x, &ntype, &type, &alloc);
        err = open_dialog(filename, &path,(void *)&outtype, (void *)type, ntype);
        if (err)
            goto out;
    } 
    else {      
        strncpy_zero(filename, s->s_name, MAX_PATH_CHARS);
        err = locatefile_extended(filename, &path, &outtype, type, ntype);
        if (err)
            goto out;
    }
    surface = jgraphics_image_surface_create_referenced(filename, path); 
out:
    if (alloc)
        sysmem_freeptr((char *)type);
void jgraphics_line_to ( t_jgraphics g,
double  x,
double  y 
)

Add a line segment to the current path.

Parameters:
g The graphics context.
x The destination point.
y The destination point.
void jgraphics_move_to ( t_jgraphics g,
double  x,
double  y 
)

Move the cursor to a new point and begin a new subpath.

Parameters:
g The graphics context.
x The new location.
y The new location.
void jgraphics_new_path ( t_jgraphics g  ) 

Begin a new path.

This action clears any current path in the context.

Parameters:
g The graphics context.
void jgraphics_oval ( t_jgraphics g,
double  x,
double  y,
double  width,
double  height 
)

Deprecated -- do not use.

Adds a closed oval path in the context, however, it does not scale appropriately.

Parameters:
g The graphics context.
x The horizontal origin.
y The vertical origin.
width The width of the oval.
height The height of the oval.
void jgraphics_ovalarc ( t_jgraphics g,
double  xc,
double  yc,
double  radiusx,
double  radiusy,
double  angle1,
double  angle2 
)

Add a non-circular arc to the current path.

Parameters:
g The graphics context.
xc The horizontal coordinate of the arc's center.
yc The vertical coordinate of the arc's center.
radiusx The horizontal radius of the arc.
radiusy The vertical radius of the arc.
angle1 The starting angle of the arc in radians. Zero radians is center right (positive x axis).
angle2 The terminal angle of the arc in radians. Zero radians is center right (positive x axis).
void jgraphics_path_destroy ( t_jpath path  ) 

Release/free a path.

Parameters:
path The path to release.
void jgraphics_path_roundcorners ( t_jgraphics g,
double  cornerRadius 
)

Round out any corners in a path.

This action clears any current path in the context.

Parameters:
g The graphics context.
cornerRadius The amount by which to round corners.
void jgraphics_position_one_rect_near_another_rect_but_keep_inside_a_third_rect ( t_rect positioned_rect,
const t_rect positioned_near_this_rect,
const t_rect keep_inside_this_rect 
)

Generate a t_rect according to positioning rules.

Parameters:
positioned_rect The address of a valid t_rect whose members will be filled in upon return.
positioned_near_this_rect A pointer to a rect near which this rect should be positioned.
keep_inside_this_rect A pointer to a rect defining the limits within which the new rect must reside.
void jgraphics_rectangle ( t_jgraphics g,
double  x,
double  y,
double  width,
double  height 
)

Add a closed rectangle path in the context.

Parameters:
g The graphics context.
x The horizontal origin.
y The vertical origin.
width The width of the rect.
height The height of the rect.
void jgraphics_rectangle_rounded ( t_jgraphics g,
double  x,
double  y,
double  width,
double  height,
double  ovalwidth,
double  ovalheight 
)

Add a closed rounded-rectangle path in the context.

Parameters:
g The graphics context.
x The horizontal origin.
y The vertical origin.
width The width of the rect.
height The height of the rect.
ovalwidth The width of the oval used for the round corners.
ovalheight The height of the oval used for the round corners.
long jgraphics_rectcontainsrect ( t_rect outer,
t_rect inner 
)

Simple utility to test for rectangle containment.

Parameters:
outer The address of the first rect for the test.
inner The address of the second rect for the test.
Returns:
Returns true if the inner rect is completely inside the outer rect, otherwise false.
long jgraphics_rectintersectsrect ( t_rect r1,
t_rect r2 
)

Simple utility to test for rectangle intersection.

Parameters:
r1 The address of the first rect for the test.
r2 The address of the second rect for the test.
Returns:
Returns true if the rects intersect, otherwise false.
t_jgraphics* jgraphics_reference ( t_jgraphics g  ) 

Get a reference to a graphics context.

When you are done you should release your reference with jgraphics_destroy().

Parameters:
g The context you wish to reference.
Returns:
A new reference to the context.
void jgraphics_rel_curve_to ( t_jgraphics g,
double  x1,
double  y1,
double  x2,
double  y2,
double  x3,
double  y3 
)

Add a cubic Bezier spline to the current path, using coordinates relative to the current point.

Parameters:
g The graphics context.
x1 The first control point.
y1 The first control point.
x2 The second control point.
y2 The second control point.
x3 The destination point.
y3 The destination point.
void jgraphics_rel_line_to ( t_jgraphics g,
double  x,
double  y 
)

Add a line segment to the current path, using coordinates relative to the current point.

Parameters:
g The graphics context.
x The destination point.
y The destination point.
void jgraphics_rel_move_to ( t_jgraphics g,
double  x,
double  y 
)

Move the cursor to a new point and begin a new subpath, using coordinates relative to the current point.

Parameters:
g The graphics context.
x The new location.
y The new location.
int jgraphics_round ( double  d  ) 

Utility for rounding a double to an int.

Parameters:
d floating-point input.
Returns:
rounded int output.
void jgraphics_select_font_face ( t_jgraphics g,
const char *  family,
t_jgraphics_font_slant  slant,
t_jgraphics_font_weight  weight 
)

Specify a font for a graphics context.

Parameters:
g The graphics context.
family The name of the font family (e.g. "Arial").
slant Define the slant to use for the font.
weight Define the weight to use for the font.
void jgraphics_select_jfont ( t_jgraphics g,
t_jfont jfont 
)

Specify a font for a graphics context by passing a t_jfont object.

Parameters:
g The graphics context.
jfont A jfont object whose attributes will be copied to the context.
void jgraphics_set_font_size ( t_jgraphics g,
double  size 
)

Specify the font size for a context.

Parameters:
g The graphics context.
size The font size.
void jgraphics_set_underline ( t_jgraphics g,
char  underline 
)

Turn underlining on/off for text in a context.

Parameters:
g The graphics context.
underline Pass true or false to set the appropriate behavior.
void jgraphics_show_text ( t_jgraphics g,
const char *  utf8 
)

Display text at the current position in a context.

Parameters:
g The graphics context.
utf8 The text to display.
long jgraphics_system_canantialiastexttotransparentbg (  ) 

Determine if you can anti-alias text to a transparent background.

You might want to call this and then disable "useimagebuffer" if false *and* you are rendering text on a transparent background.

Returns:
Non-zero if you can anti-alias text to a transparent background.
void jgraphics_text_measure ( t_jgraphics g,
const char *  utf8,
double *  width,
double *  height 
)

Return the height and width of a string given current graphics settings in a context.

Parameters:
g Pointer to a jgraphics context.
utf8 A string containing the text whose dimensions we wish to find.
width The address of a variable to be filled with the width of the rendered text.
height The address of a variable to be filled with the height of the rendered text.
void jgraphics_text_measure_wrapped ( t_jgraphics g,
const char *  utf8,
double  wrapwidth,
long  includewhitespace,
double *  width,
double *  height,
long *  numlines 
)

Return the height, width, and number of lines that will be used to render a given string.

Parameters:
g Pointer to a jgraphics context.
utf8 A string containing the text whose dimensions we wish to find.
wrapwidth The number of pixels in width at which the text should be wrapped if it is too long.
includewhitespace Set zero to not include white space in the calculation, otherwise set this parameter to 1.
width The address of a variable to be filled with the width of the rendered text.
height The address of a variable to be filled with the height of the rendered text.
numlines The address of a variable to be filled with the number of lines required to render the text.
void jgraphics_user_to_device ( t_jgraphics g,
double *  x,
double *  y 
)

User coordinates are those passed to drawing functions in a given t_jgraphics context.

Device coordinates refer to patcher canvas coordinates, before any zooming.

Copyright © 2008, Cycling '74