The EZ graphics library is realized through the 3DCanvas widget. To each 3DCanvas widget, there is an associated data structure called the graphics context which contains the entire state attributes of the graphics library. An application can have as many 3DCanvases as it needs. However, there is only one active 3DCanvas at any given instant. Implicitly, the active 3DCanvas is set to the last created 3DCanvas.
To use the graphics library, one must
first create some 3DCanvases and display them. The graphics library comes to
existence only after an active 3DCanvas has been displayed.
To create a 3DCanvas widget, use
EZ_Widget *EZ_Create3DCanvas(EZ_Widget *parent)
If more than one 3DCanvases are needed. Use EZ_Set3DCanvas
to
set the active 3DCanvas. This function performs a graphics context
switch.
void EZ_Set3DCanvas(EZ_Widget *canvas)
Events for 3DCanvas are handled exactly the same as for the other widget in EZwgl. The difference is that 3DCanvas does not have a default event handler while other widgets have.
One should register at least one private event handler
for each 3DCanvas an application creates.
The private event handler should provide means to handle
at least the
EZ_REDRAW
and the EZ_RESIZE
events.
Event handlers are registered via EZ_AddEventHander
or
by
void EZ_Set3DCanvasEventHandle(EZ_Widget *canvas,
EZ_EventHandler handler)
This function hooks an event handler to a 3DCanvas widget.
Here is an example of event handlers.
void SampleEventHandler(EZ_Widget *canvas, void *vd, int et, XEvent *xev)
switch(et) case EZ_REDRAW: case EZ_RESIZE: /* redraw objects in canvas */ break; case EZ_KEY_PRESS: /* do something */ break; default: break;
EZwgl provides three additional commands for an application manipulate events for 3DCanvas widgets.
void EZ_GLResetEvents(EZ_Widget *canvas)
This function clears the event queue for the canvas
. If
canvas
is NULL
, it clears the event queue for
the current active 3DCanvas widget.
void EZ_GLEnterEvent(EZ_Widget *canvas,
int eType, int *values)
This function enters the specified event to canvas
or
the current active 3DCanvas if canvas
is NULL
.
For events of type EZ_BUTTON?_PRESS
,
EZ_BUTTON?_RELEASE
or EZ_POINTER_MOTION
,
values
, if not NULL
is an array of two integers
which specifies the pointer location in the current viewport.
(Origin is at the lower-left corner, offseted by the borderwidth.)
For EZ_KEY_PRESS
event, values
, if not NULL
is a pointer to an integer which specifies the keycode for the
key that is being pressed.
The screen coordinate system for a 3DCanvas is
different from that of other widgets. For a 3DCanvas, the
origin is the lower-left corner of the widget window while
for other widgets, the origin is the upper-lefte corner of
the widget window.
void EZ_GLNextEvent(EZ_Widget *canvas, XEvent *xevent)
This function checks Xlib's event queue for any outstanding
events. If the event queue is empty, it waits for the next
event to arrive. It then
removes the first event on the queue and copy it
to event
if event
is not NULL
.
If the removed event belongs to canvas
,
it returns the corresponding type. If the event does
belong to canvas
, it dispatches the event to
the relevent widget and returns 0
.
Like other widgets in the EZ widget library, a 3DCanvas may also
have a border. However, this introduces a problem for graphics
applications. Often, a graphics application needs to know
the exact size of its graphics windows. Unfortunately,
the function EZ_GetWidgetSize
returns the dimension of a
widget including its border. To remedy this problem, the EZ graphics
library provides an additional function to retrieve the dimension
of a 3DCanvas.
void EZ_Get3DCanvasSize(EZ_Widget *canvas, int *width_return,
int *height_return)
The EZ graphics library also provides an user convenience routine to save the contents of a 3DCanvas window.
void EZ_Save3DCanvas2PPMImage(EZ_Widget *canvas, chae *file_name)
This function reads the 3DCanvas window into an XImage, converts the image into a PPM image and save the result to the given file.
To Save the contents of a 3DCanvas to a postscript file, use the next two functions.
void EZ_Save3DCanvas2PSA(EZ_Widget *canvas, int mode, int dpi,
float scale, char *fileName)
void EZ_Save3DCanvas2PS(EZ_Widget *canvas, char *fileName)
This routine is equivalent to
EZ_Save3DCanvas2PSA(canvas,EZ_PORTRAIT, 200, 1.0,fileName)
.