## 5.2 The 3DCanvas Widget

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)`.

HTML Documentation Maintainance:`Arturo Espinosa <arturo@nuclecu.unam.mx>`