Description
The GNOME canvas is an engine for creating structured graphics.
This means that graphical items like lines,
rectangles, and text, can be inserted into the canvas and referred
to later for manipulation. Item attributes include properties
like their position and color. The canvas takes care of all
drawing operations so that it will never flicker. The canvas is
designed to be extensible by letting the user define custom
graphical items, and thus it can work as a generic display engine
for applications.
Details
GNOME_CANVAS_EPSILON
#define GNOME_CANVAS_EPSILON 1e-10 |
This macro defines a ‘small’ floating-point value for
the internal computations that the canvas performs. It can be
used by item implementations as a test to see whether a number is
“almost zero”.
GNOME_CANVAS_COLOR()
#define GNOME_CANVAS_COLOR(r, g, b) |
This macro is used to build a 32-bit integer with an RGB color
specification. The specified values must be integers in the range
[0, 255].
GNOME_CANVAS_COLOR_A()
#define GNOME_CANVAS_COLOR_A(r, g, b, a) |
This macro is used to build a 32-bit integer with an RGBA color
specification. This is the same as an RGB color specification,
but with an added alpha or opacity value. The specified values
must be integers in the range [0, 255].
struct GnomeCanvasBuf
typedef struct {
/* 24-bit RGB buffer for rendering */
guchar *buf;
/* Rowstride for the buffer */
int buf_rowstride;
/* Rectangle describing the rendering area */
ArtIRect rect;
/* Background color, given as 0xrrggbb */
guint32 bg_color;
/* Invariant: at least one of the following flags is true. */
/* Set when the render rectangle area is the solid color bg_color */
unsigned int is_bg : 1;
/* Set when the render rectangle area is represented by the buf */
unsigned int is_buf : 1;
} GnomeCanvasBuf; |
This structure is passed to the render method
of canvas items when they need to paint themselves on an
antialiased canvas. The buf field
points to a 24-bit RGB buffer for rendering. The
buf_rowstride field specifies the
number of bytes in each row in the buffer, which should be used to
calculate byte offsets inside it. The buffer's pixel offsets in
canvas pixel coordinates are given by the
rect rectangle. The
is_bg and
is_buf fields are flags that items can
use to implement rendering optimizations, and they ar used in
conjunction with the bg_color field.
The is_buf flag specifies whether the
contents of the buffer are an accurate representation of the state
of the canvas. If this flag is true, then the RGB data in the
buf is valid, that is, it contains
meaningful data.
The is_bg flag specifies whether the
buffer has all its pixels set to the same color. This allows
canvas items to optimize for this case by doing alpha compositing
for a smaller set of values than if the buffer had pixels of
different colors.
At least one of these flags is on at any one time. The meaning of
their combinations is as follows:
Table 1. Values for is_bg and
is_buf
is_buf | is_bg | Meaning |
---|
FALSE | TRUE | The buffer does not contain meaningful data. However,
it should be considered as if it were filled with the
solid color specified in the
bg_color field. Item
implementations may want to call
gnome_canvas_buf_ensure_buf() to
fill the buffer automatically.
|
TRUE | FALSE | The buffer contains meaningful data and not all of its
pixels may be the same color. Item implementations can
use the buffer data as-is for alpha compositing.
|
TRUE | TRUE | The buffer contains meaningful data, and all the pixels
are of the same color. Item implementations can use the
buffer data as-is for alpha compositing, or be smarter
and do less operations since they can just composite
over a single color.
|
Whenever an item paints to an RGB buffer in which the
is_bg field was true, the item is then
responsible for turning off this flag if it knows that the result
will not be pixels all of the same color. If a large item, like a
solid rectangle, knows that it will be filling the buffer with a
solid color, then it take any one of the following actions:
Fill the actual pixels in the buffer with the solid color
and turn off the is_bg flag. It
should then turn on the is_buf
flag.
Fill the actual pixels in the buffer with the solid color,
set the bg_color field to that
same color, and turn on both the
is_bg and
is_buf flags. This is correct,
but is wasteful, since it could have done just the following
instead.
Just set the bg_color to the
solid color, turn on the is_bg
flag, and turn off the is_buf
flag. This means that the buffer does not contain the
actual meaningful data, and the next item to be repainted
should look at the solid color instead. This is the most
efficient version.
Most item implementations may only need to perform the actions for
the first case described above. The other two are simply
optimizations they can perform.
gnome_canvas_new ()
GtkWidget* gnome_canvas_new (void); |
Creates a new empty canvas. If the user wishes to use the image item inside this canvas, then
the gdk_imlib visual and colormap should be pushed into Gtk+'s stack before calling this
function, and they can be popped afterwards.
gnome_canvas_new_aa ()
GtkWidget* gnome_canvas_new_aa (void); |
Creates a new antialiased empty canvas. You want to push the GdkRgb colormap and visual for this.
gnome_canvas_root ()
Queries the root group of a canvas.
gnome_canvas_set_scroll_region ()
void gnome_canvas_set_scroll_region (GnomeCanvas *canvas,
double x1,
double y1,
double x2,
double y2); |
Sets the scrolling region of the canvas to the specified rectangle. The canvas
will then be able to scroll only within this region. The view of the canvas is
adjusted as appropriate to display as much of the new region as possible.
gnome_canvas_get_scroll_region ()
void gnome_canvas_get_scroll_region (GnomeCanvas *canvas,
double *x1,
double *y1,
double *x2,
double *y2); |
Queries the scroll region of the canvas.
gnome_canvas_set_pixels_per_unit ()
void gnome_canvas_set_pixels_per_unit
(GnomeCanvas *canvas,
double n); |
Sets the zooming factor of the canvas by specifying the number of pixels that correspond to
one canvas unit.
gnome_canvas_scroll_to ()
void gnome_canvas_scroll_to (GnomeCanvas *canvas,
int cx,
int cy); |
Makes the canvas scroll to the specified offsets, given in canvas pixel units. The canvas
will adjust the view so that it is not outside the scrolling region. This function is typically
not used, as it is better to hook scrollbars to the canvas layout's scrolling adjusments.
gnome_canvas_get_scroll_offsets ()
void gnome_canvas_get_scroll_offsets (GnomeCanvas *canvas,
int *cx,
int *cy); |
Queries the scrolling offsets of the canvas.
gnome_canvas_update_now ()
Forces an immediate redraw or update of the canvas. If the canvas does not
have any pending redraw requests, then no action is taken. This is typically
only used by applications that need explicit control of when the display is
updated, like games. It is not needed by normal applications.
gnome_canvas_get_item_at ()
Looks for the item that is under the specified position (given in world
coordinates).
gnome_canvas_request_redraw_uta ()
void gnome_canvas_request_redraw_uta (GnomeCanvas *canvas,
ArtUta *uta); |
Informs a canvas that the specified area, given as a microtile array, needs to be repainted.
gnome_canvas_request_redraw ()
void gnome_canvas_request_redraw (GnomeCanvas *canvas,
int x1,
int y1,
int x2,
int y2); |
Convenience function that informs a canvas that the specified area, specified as a
rectangle, needs to be repainted. This function converts the rectangle to a microtile
array and feeds it to gnome_canvas_request_redraw_uta(). The rectangle includes
x1 and y1, but not x2 and y2.
gnome_canvas_w2c_affine ()
void gnome_canvas_w2c_affine (GnomeCanvas *canvas,
double affine[6]); |
Gets the affine transform that converts world coordinates into canvas pixel coordinates.
gnome_canvas_w2c ()
void gnome_canvas_w2c (GnomeCanvas *canvas,
double wx,
double wy,
int *cx,
int *cy); |
Converts world coordinates into canvas pixel coordinates. Usually only needed
by item implementations.
gnome_canvas_w2c_d ()
void gnome_canvas_w2c_d (GnomeCanvas *canvas,
double wx,
double wy,
double *cx,
double *cy); |
Converts world coordinates into canvas pixel coordinates. Usually only needed
by item implementations. This version results in double coordinates, which
are useful in antialiased implementations.
gnome_canvas_c2w ()
void gnome_canvas_c2w (GnomeCanvas *canvas,
int cx,
int cy,
double *wx,
double *wy); |
Converts canvas pixel coordinates to world coordinates. Usually only needed
by item implementations.
gnome_canvas_window_to_world ()
void gnome_canvas_window_to_world (GnomeCanvas *canvas,
double winx,
double winy,
double *worldx,
double *worldy); |
Converts window-relative coordinates into world coordinates. Use this when you need to
convert from mouse coordinates into world coordinates, for example.
gnome_canvas_world_to_window ()
void gnome_canvas_world_to_window (GnomeCanvas *canvas,
double worldx,
double worldy,
double *winx,
double *winy); |
Converts world coordinates into window-relative coordinates.
gnome_canvas_get_color ()
int gnome_canvas_get_color (GnomeCanvas *canvas,
char *spec,
GdkColor *color); |
Allocates a color based on the specified X color specification. As a convenience to item
implementations, it returns TRUE if the color was allocated, or FALSE if the specification
was NULL. A NULL color specification is considered as "transparent" by the canvas.
gnome_canvas_set_stipple_origin ()
void gnome_canvas_set_stipple_origin (GnomeCanvas *canvas,
GdkGC *gc); |
Sets the stipple origin of the specified GC as is appropriate for the canvas. This is
typically only needed by item implementations.