OTK - Image Functions

Image Functions


Generally to place images within GUI panels, you do not need to know much about them.
The following high-level functions enable you to attach images to objects on your
screen:   (The images can be read from image-files.)

OtkWidget OtkMakeImagePanel( OtkWidget container, char *file_name, float left, float top, float horiz_size, float vert_size )
- Displays image from file in specified panel location.
void Otk_Set_Button_Icon_File( OtkWidget button, char *file_name )
- See Button Functions.

By default, Otk operates with PPM image files.  However, JPEG, JPG, GIF, and PNG images can
also be accepted, assuming the expected NetPBM utilities are available on
your system to convert the images automatically.  You can use various utilities to
convert from other formats.

The above functions provide simple operation for common image related tasks.
However, if you wish to do more advanced things with images, such as to create your
own images, or to filter or manipulate images, then the information below may
be helpful.

Images in Otk are held in the Otk_image data structure.
Important fields within this structure, that are relevant to users, are:

  struct Otk_image		/* (Not actual structure, but valid fields.) */
      {
       char *filename;		/* Filename image came form, or image's name. */
       int cols, rows;		/* Image dimensions. */
       struct Otk_image_rec *image;  /* RGB pixel array. */
      }

    struct Otk_image_rec
     { 
      unsigned char r, g, b; 	/* RGB pixel value. */
     };


Brightness of Red, Green, Blue, are recorded as unsigned 8-bit values ranging
from 0 (dark) to 255 (bright).

Important functions associated with images are:

struct Otk_image *Otk_Read_Image_File( char *fname )
- Reads named file into Otk_image data structure for manipulation and usage in functions.
struct Otk_image *Otk_Make_Image_From_Matrix( char *name, int nrows, int ncols, struct Otk_image_rec *newimage )
- Accepts an RGB matrix array, and creates a displayable Otk_Image structure.
OtkWidget OtkMakeImagePanel_ImgPtr( OtkWidget container, struct Otk_image *image_ptr, float left, float top, float horiz_size, float vert_size )
- Displays image from image-structure in specified panel location. Companion function for OtkMakeImagePanel() above.
void Otk_Dispose_Image( char *filename )
- Releases all resources associated with named image.
void Otk_Set_Button_Icon( OtkWidget button, struct Otk_image *image_ptr )
- See Button Functions.


For example, you could create your own image and attach it to any panel, 
including the OuterWindow panel, as show below:


	struct Otk_image *your_image;
	int ncols, nrows, col, row;
	Otk_image_rec *imgmtrx;

	ncols = 100;
	nrows = 100;
	imgmtrx = (Otk_image_rec *)malloc( nrows * ncols * sizeof(Otk_image_rec) );
	for (row=0;  row < nrows;  row++)
	 for (col=0;  col < ncols;  col++)
	  {
	   imgmtrx[row*ncols+col]->r = 200;
	   imgmtrx[row*ncols+col]->g = 100 - row;
	   imgmtrx[row*ncols+col]->b = 20 + col;
	  }
	your_image = Otk_Make_Image_From_Matrix( "YourImage", nrows, ncols, imgmtrx );
	OtkMakeImagePanel_ImgPtr( OtkOuterWindow, your_image, 10, 10, 80, 80 );


Another example, you could read-in an image, brighten it, and display it:


	struct Otk_image *your_pic;
        int col, row;

	your_pic = Otk_Read_Image_File( "image.ppm" ):
	for (row=0;  row < your_pic->rows;  row++)
         for (col=0;  col < your_pic->cols;  col++)
          {
           your_pic->image[row*ncols+col].r = MAX( 255, 20 + your_pic->image[row*ncols+col].r );
           your_pic->image[row*ncols+col].g = MAX( 255, 20 + your_pic->image[row*ncols+col].g );
           your_pic->image[row*ncols+col].b = MAX( 255, 20 + your_pic->image[row*ncols+col].b );
          }
        OtkMakeImagePanel_ImgPtr( OtkOuterWindow, your_pic, 10, 10, 80, 80 );

Embedding Images Within Your Application

Much of the above discussion assumes that images are read from external image-files when your application runs. This is fine for images that change. But your application may depend on fixed images, such as for panel background textures, or button icons. Referencing external files at run-time may be inconvenient for several reasons:

You may not know where the user will install your application files or where she will run it from. So relative path references to the image files may break, and absolute paths may be wrong.
When moving your application, or sending it to a user, you would need to also send all the image files, and be sure the user places them in the correct location(s).

A conceptually simpler approach is to compile any fixed image-data directly into your executable. Your application can then be distributed as a single stand-alone executable file, without dependencies on other files.

A set of convenience functions, for efficiently embedding image-data into your programs and displaying it at run-time, can be found at Image2Code.

<-- Back

Back to main page