Box Layer

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

Collaboration diagram for Box Layer:

Functions
t_max_err	jbox_invalidate_layer (t_object *b, t_object *view, t_symbol *name)
	Invalidate a layer, indicating that it needs to be re-drawn.
t_jgraphics *	jbox_start_layer (t_object *b, t_object *view, t_symbol *name, double width, double height)
	Create a layer, and ready it for drawing commands.
t_max_err	jbox_end_layer (t_object *b, t_object *view, t_symbol *name)
	Conclude a layer, indicating that it is complete and ready for painting.
t_max_err	jbox_paint_layer (t_object *b, t_object *view, t_symbol *name, double x, double y)
	Paint a layer at a given position.

---

Detailed Description

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

The general idea is to do something like this:

    t_jgraphics *g;
    g = jbox_start_layer(box, view, layername, width, height);
    if (g) {
        // draw to your new offscreen context here
        // the second time you call jbox_start_layer() it will return NULL
        // since you already drew it -- you don't have to do drawing the second time
        jbox_end_layer(box, view, layername);
    }
    jbox_paint_layer(box, view, layername, xpos, ypos);

Then, if something changes where you would need to redraw the layer you invalidate it:

    jbox_invalidate_layer(box, view, layername);

or

    jbox_invalidate_layer(box, NULL, layername); // to invalidate for all views

Each view has its own layer stored since if a patcher has multiple views each could be at a different zoom level.

---

Function Documentation

t_max_err jbox_end_layer	(	t_object *	b,
		t_object *	view,
		t_symbol *	name
	)

Conclude a layer, indicating that it is complete and ready for painting.

Parameters:

b	The object/box for the layer opened by jbox_start_layer().
view	The patcherview for the object opened by jbox_start_layer().
name	The name of the layer.

Returns:

A Max error code.

t_max_err jbox_invalidate_layer	(	t_object *	b,
		t_object *	view,
		t_symbol *	name
	)

Invalidate a layer, indicating that it needs to be re-drawn.

Parameters:

b	The object/box to invalidate.
view	The patcherview for the object which should be invalidated, or NULL for all patcherviews.
name	The name of the layer to invalidate.

Returns:

A Max error code.

t_max_err jbox_paint_layer	(	t_object *	b,
		t_object *	view,
		t_symbol *	name,
		double	x,
		double	y
	)

Paint a layer at a given position.

Note that the current color alpha value is used when painting layers to allow you to blend layers. The same is also true for jgraphics_image_surface_draw() and jgraphics_image_surface_draw_fast().

Parameters:

b	The object/box to be painted.
view	The patcherview for the object which should be painted, or NULL for all patcherviews.
name	The name of the layer to paint.
x	The x-coordinate for the position at which to paint the layer.
y	The y-coordinate for the position at which to paint the layer.

Returns:

A Max error code.

t_jgraphics* jbox_start_layer	(	t_object *	b,
		t_object *	view,
		t_symbol *	name,
		double	width,
		double	height
	)

Create a layer, and ready it for drawing commands.

The layer drawing commands must be wrapped with a matching call to jbox_end_layer() prior to calling jbox_paint_layer().

Parameters:

b	The object/box to which the layer is attached.
view	The patcherview for the object to which the layer is attached.
name	A name for this layer.
width	The width of the layer.
height	The height of the layer.

Returns:

A t_jgraphics context for drawing into the layer.