JSurface

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

Collaboration diagram for JSurface:

Typedefs
typedef struct _jsurface	t_jsurface
	An instance of a jgraphics surface.

Functions
t_jsurface *	jgraphics_image_surface_create (t_jgraphics_format format, int width, int height)
	Create an image surface. More...
t_jsurface *	jgraphics_image_surface_create_referenced (const char *filename, short path)
	Create an image surface, filling it with the contents of a file, and get a reference to the surface. More...
t_jsurface *	jgraphics_image_surface_create_from_file (const char *filename, short path)
	Create an image surface, filling it with the contents of a file. More...
t_jsurface *	jgraphics_image_surface_create_for_data (unsigned char *data, t_jgraphics_format format, int width, int height, int stride, method freefun, void *freearg)
	Create an image surface from given pixel data. More...
t_jsurface *	jgraphics_image_surface_create_from_filedata (const void *data, unsigned long datalen)
	Create a new surface from file data. More...
t_jsurface *	jgraphics_image_surface_create_from_resource (const void *moduleRef, const char *resname)
	Create a new surface from a resource in your external. More...
t_max_err	jgraphics_get_resource_data (const void *moduleRef, const char *resname, long extcount, t_atom *exts, void **data, unsigned long *datasize)
	Low-level routine to access an object's resource data. More...
t_jsurface *	jgraphics_surface_reference (t_jsurface *s)
	Create a reference to an existing surface. More...
void	jgraphics_surface_destroy (t_jsurface *s)
	Release or free a surface. More...
t_max_err	jgraphics_image_surface_writepng (t_jsurface *surface, const char *filename, short path, long dpi)
	Export a PNG file of the contents of a surface. More...
t_max_err	jgraphics_image_surface_writejpeg (t_jsurface *surface, const char *filename, short path)
	Export a JPEG file of the contents of a surface. More...
int	jgraphics_image_surface_get_width (t_jsurface *s)
	Retrieve the width of a surface. More...
int	jgraphics_image_surface_get_height (t_jsurface *s)
	Retrieve the height of a surface. More...
void	jgraphics_image_surface_set_pixel (t_jsurface *s, int x, int y, t_jrgba color)
	Set the color of an individual pixel in a surface. More...
void	jgraphics_image_surface_get_pixel (t_jsurface *s, int x, int y, t_jrgba *color)
	Retrieve the color of an individual pixel in a surface. More...
void	jgraphics_image_surface_scroll (t_jsurface *s, int x, int y, int width, int height, int dx, int dy, t_jpath **path)
void	jgraphics_image_surface_draw (t_jgraphics *g, t_jsurface *s, t_rect srcRect, t_rect destRect)
	Draw an image surface. More...
void	jgraphics_image_surface_draw_fast (t_jgraphics *g, t_jsurface *s)
	Draw an image surface quickly. More...
void	jgraphics_write_image_surface_to_filedata (t_jsurface *surf, long fmt, void **data, long *size)
	Get surface data ready for manually writing to a file. More...
void	jgraphics_image_surface_clear (t_jsurface *s, int x, int y, int width, int height)
	Set all pixels in rect to 0. More...
t_jgraphics *	jgraphics_create (t_jsurface *target)
	Create a context to draw on a particular surface. More...

Detailed Description

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

An image surface is a concrete instance that renders to an image in memory, essentially an offscreen bitmap.

Function Documentation

t_jgraphics* jgraphics_create

(

t_jsurface *

target

)

Create a context to draw on a particular surface.

When you are done, call jgraphics_destroy().

Parameters

target

The surface to which to draw.

Returns

The new graphics context.

t_max_err jgraphics_get_resource_data	(	const void *	moduleRef,
		const char *	resname,
		long	extcount,
		t_atom *	exts,
		void **	data,
		unsigned long *	datasize
	)

Low-level routine to access an object's resource data.

Parameters

moduleRef	A pointer to your external's module, which is passed to your external's main() function when the class is loaded.
resname	Base name of the resource data (without an extension)
extcount	Count of possible extensions (ignored on Windows)
exts	Array of symbol atoms containing possible filename extensions (ignored on Windows)
data	Returned resource data assigned to a pointer you supply
datasize	Size of the data returned

Remarks

You are responsible for freeing any data returned in the data pointer

Returns

A Max error code.

void jgraphics_image_surface_clear	(	t_jsurface *	s,
		int	x,
		int	y,
		int	width,
		int	height
	)

Set all pixels in rect to 0.

Parameters

s	The surface to clear.
x	The horizontal origin of the rect to clear.
y	The vertical origin of the rect to clear.
width	The width of the rect to clear.
height	The height of the rect to clear.

t_jsurface* jgraphics_image_surface_create	(	t_jgraphics_format	format,
		int	width,
		int	height
	)

Create an image surface.

Use jgraphics_surface_destroy() to free it when you are done.

Parameters

format	Defines the color format for the new surface.
width	Defines the width of the new surface.
height	Defines the height of the new surface.

Returns

A pointer to the new surface.

t_jsurface* jgraphics_image_surface_create_for_data	(	unsigned char *	data,
		t_jgraphics_format	format,
		int	width,
		int	height,
		int	stride,
		method	freefun,
		void *	freearg
	)

Create an image surface from given pixel data.

Data should point to start of top line of bitmap, stride tells how to get to next line. For upside down windows bitmaps, data = (pBits-(height-1)*stride) and stride is a negative number.

Parameters

data	The data. For example, an RGBA image loaded in memory.
format	The format of the data.
width	The width of the new surface.
height	The height of the new surface.
stride	The number of bytes between the start of rows in the dat buffer.
freefun	If not NULL, freefun will be called when the surface is destroyed
freearg	This will be passed to freefun if/when freefun is called.

Returns

A pointer to the new surface.

t_jsurface* jgraphics_image_surface_create_from_file	(	const char *	filename,
		short	path
	)

Create an image surface, filling it with the contents of a file.

Use jgraphics_surface_destroy() to free it when you are done.

Parameters

filename	The name of the file.
path	The path id of the file.

Returns

A pointer to the new surface.

t_jsurface* jgraphics_image_surface_create_from_filedata	(	const void *	data,
		unsigned long	datalen
	)

Create a new surface from file data.

Parameters

data	A pointer to the raw PNG or JPG bits.
datalen	The number of bytes in data.

Returns

The new surface.

See also

jgraphics_write_image_surface_to_filedata()

t_jsurface* jgraphics_image_surface_create_from_resource	(	const void *	moduleRef,
		const char *	resname
	)

Create a new surface from a resource in your external.

Parameters

moduleRef	A pointer to your external's module, which is passed to your external's main() function when the class is loaded.
resname	The name of the resource in the external.

Remarks

The following example shows an example of how this might be used in an external.

static s_my_surface = NULL;

int main(void *moduleRef)
{
   // (Do typical class initialization here)
   
   // now create the surface from a resource that we added to the Xcode/VisualStudio project
   s_my_surface = jgraphics_image_surface_create_from_resource(moduleRef, "myCoolImage");

   return 0;
}

t_jsurface* jgraphics_image_surface_create_referenced	(	const char *	filename,
		short	path
	)

Create an image surface, filling it with the contents of a file, and get a reference to the surface.

Use jgraphics_surface_destroy() to release your reference to the surface when you are done.

Parameters

filename	The name of the file.
path	The path id of the file.

Returns

A pointer to the new surface.

void jgraphics_image_surface_draw	(	t_jgraphics *	g,
		t_jsurface *	s,
		t_rect	srcRect,
		t_rect	destRect
	)

Draw an image surface.

This not in cairo, but, it seems silly to have to make a brush to just draw an image. This doesn't support rotations, however.

Parameters

g	The graphics context in which to draw the surface.
s	The surface to draw.
srcRect	The rect within the surface that should be drawn.
destRect	The rect in the context to which to draw the srcRect.

See also

jgraphics_image_surface_draw_fast()

void jgraphics_image_surface_draw_fast	(	t_jgraphics *	g,
		t_jsurface *	s
	)

Draw an image surface quickly.

The draw_fast version won't scale based on zoom factor or user transforms so make sure that this is what you want! Draws entire image, origin *can* be shifted via zoom and user transforms (even though image is not scaled based on those same transforms)

Parameters

g	The graphics context in which to draw the surface.
s	The surface to draw.

See also

jgraphics_image_surface_draw

int jgraphics_image_surface_get_height

(

t_jsurface *

s

)

Retrieve the height of a surface.

Parameters

s	The surface to query.

Returns

The height of the surface.

void jgraphics_image_surface_get_pixel	(	t_jsurface *	s,
		int	x,
		int	y,
		t_jrgba *	color
	)

Retrieve the color of an individual pixel in a surface.

Parameters

s	The surface.
x	The horizontal coordinate of the pixel.
y	The vertical coordinate of the pixel.
color	The address of a valid t_jrgba struct whose values will be filled in with the color of the pixel upon return.

int jgraphics_image_surface_get_width

(

t_jsurface *

s

)

Retrieve the width of a surface.

Parameters

s	The surface to query.

Returns

The width of the surface.

void jgraphics_image_surface_scroll	(	t_jsurface *	s,
		int	x,
		int	y,
		int	width,
		int	height,
		int	dx,
		int	dy,
		t_jpath **	path
	)

Parameters

s	The surface to scroll.
x	The origin of the rect to scroll.
y	The origin of the rect to scroll.
width	The width of the rect to scroll.
height	The height of the rect to scroll.
dx	The amount to scroll the surface horizontally.
dy	The amount to scroll the surface vertically.
path	Can pass NULL if you are not interested in this info. Otherwise pass a pointer and it will be returned with a path containing the invalid region.

void jgraphics_image_surface_set_pixel	(	t_jsurface *	s,
		int	x,
		int	y,
		t_jrgba	color
	)

Set the color of an individual pixel in a surface.

Parameters

s	The surface.
x	The horizontal coordinate of the pixel.
y	The vertical coordinate of the pixel.
color	The color of the pixel.

t_max_err jgraphics_image_surface_writejpeg	(	t_jsurface *	surface,
		const char *	filename,
		short	path
	)

Export a JPEG file of the contents of a surface.

Parameters

surface	The surface to export.
filename	Specify the name of the file to create.
path	Specify the path id for where to create the file.

Returns

A Max error code.

t_max_err jgraphics_image_surface_writepng	(	t_jsurface *	surface,
		const char *	filename,
		short	path,
		long	dpi
	)

Export a PNG file of the contents of a surface.

Parameters

surface	The surface to export.
filename	Specify the name of the file to create.
path	Specify the path id for where to create the file.
dpi	Define the resolution of the image (e.g. 72).

Returns

A Max error code.

void jgraphics_surface_destroy

(

t_jsurface *

s

)

Release or free a surface.

Parameters

s	The surface to release.

t_jsurface* jgraphics_surface_reference

(

t_jsurface *

s

)

Create a reference to an existing surface.

Use jgraphics_surface_destroy() to release your reference to the surface when you are done.

Parameters

s	The surface to reference.

Returns

The new reference to the surface.

void jgraphics_write_image_surface_to_filedata	(	t_jsurface *	surf,
		long	fmt,
		void **	data,
		long *	size
	)

Get surface data ready for manually writing to a file.

Parameters

surf	The surface whose data will be retrieved.
fmt	The format for the data. This should be a selection from t_jgraphics_fileformat.
data	The address of a pointer that will be allocated and filled. When you are done with this data you should free it using sysmem_freeptr().
size	The address of a variable to hold the size of the data upon return.

Remarks

A good example of this is to embed the surface as a PNG in a patcher file.

long size = 0;
void *data = NULL;

jgraphics_write_image_surface_to_filedata(x->j_surface, JGRAPHICS_FILEFORMAT_PNG, &data, &size);
if (size) {
   x->j_format = gensym("png");
   binarydata_appendtodictionary(data, size, gensym("data"), x->j_format, d);
   x->j_imagedata = data;
   x->j_imagedatasize = size;
}

See also

jgraphics_image_surface_create_from_filedata()