#include <gandalf/image/image_display.h>
Gandalf uses OpenGL to display images. It assumes that as well as the
standard OpenGL libraries, the GL user toolkit (GLUT) is also installed.
Because GLUT is event-driven, program control needs to be passed to the
GLUT event handler by calling glutMainLoop() after creating the
initial windows you want. Remember that creating a window using the
gan_display_new_window() function (see below) will not make it
appear immediately. The window creation event needs to be processed by GLUT.
This needs to be borne in mind when reading the description of the functions
below. The simplest example using the functions is in
gandalf/image/bitmap_test.c.
Once an OpenGL window has been set up and a Gandalf image pImage created, calls to
glRasterPos2i ( 0, 0 );
gan_image_display ( pImage );
will display the image using the OpenGL function glDrawPixels.
This involves a fair amount of OpenGL calls to set the display windows up.
To simply create an OpenGL window and display a Gandalf image in it,
Gandalf provides functions to make this easy for you. You can use the code
Gan_Image *pImage;
int iWindowID;
/* create OpenGL window to display image/graphics with coordinates
in the range (0-200) vertically and (0-300) horizontally, using a
zoom factor of 2 so that the size on the screen will be 400x600.
The window is placed at offset 100,100 from the corner of the screen.
*/
gan_display_new_window ( 200, 300, 2.0, "Graphics", 100, 100,
&iWindowID );
/* ... create and fill image pImage ... */
/* display image with top-left pixel at position (0,0) */
gan_image_display ( pImage );
The image is drawn so that if its dimensions match those passed as the first
two arguments to
/* set position in OpenGL window as top-left position in image drawn
* subsequently by gan_image_display() */
glRasterPos2i ( 30, 40 );
The window is available for the standard
OpenGL graphics functions. The name of the window ("Graphics" in the above
example) is shown in the bar at the top of the graphics window.
If the graphics window changes, the window
identifier iWindowID can be used to switch back to the created
window using
glutSetWindow ( iWindowID );
To create several identically sized graphics windows, use this routine:
int iWindowID, *aiWindowID;
/* create an OpenGL window containing 2 rows and 3 columns of
sub-windows, each containing a 300x200 graphics window, each of
which contains a (0-900) by (0-600) coordinate frame shrunk to
300x200 using a zoom factor of 1/3 */
gan_display_new_window_array ( 2, 3, 900, 600, 1.0/3.0, "Graphics",
100, 100, &iWindowID, &aiWindowID );
The sub-windows are created using the function glutCreateSubWindow().
In this case there is both a window identifier for the main display window
and an array of window identifiers for the sub-windows, stored in the
array in raster-scan order.
Gandalf also provides a routine that creates a window and displays the image all in one, determining the graphics window size from a zoom factor passed in:
/* create display window and display image zoomed to double its size */
gan_image_display_new_window ( pImage, 2.0, "Graphics", 100, 100, &iWindowID );
This is useful for debugging purposes as the easiest way to display an image.
The gan_display_new_window() function stores the windows created in a list, so that the images displayed in the windows can be automatically refreshed. When you have finished with the graphics windows created by gan_display_new_window(), remove them using the function
gan_image_display_free_windows();
Note that this free function only applies to windows created by
gan_display_new_window(). Graphics windows created using
the other functions in this section are refreshed using standard
OpenGL routines (glutDisplayFunc() etc.).
Error detection: All the routines except gan_image_display_free_windows() return a boolean result, which is GAN_FALSE if an error occurs, invoking the Gandalf error handler.