Displaying images

      #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
gan_display_new_window(), the displayed image will completely fill the window. If you want the image displayed at a position offset from the top-left corner of the window you will need an appropriate call to glRasterPos2i(), such as

      /* 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.