[Previous] [Contents] [Index] [Next]


Read or query a graphic file


#include <photon/PxImage.h>

PhImage_t * PxLoadImage( char *filename,
                         PxMethods_t *methods );


This function reads a graphic file into memory. Photon supports the BMP, GIF, JPG, PCX, and JPEG file formats, among others. For a complete list of the currently supported formats, see <photon/PxImage.h>.

The filename argument specifies the name of the graphic file to load or query.

The methods argument points to a structure that lets you modify the behavior of the function. If this argument is NULL, the function loads the graphic file specified by filename. PxMethods_t is defined as:

typedef struct pxmethods
    int         flags;
    void        *(*px_alloc)( long nbytes, int type );
    void        *(*px_free)( void *memory, int type );
    void        *(*px_error)( char *msg );
    void        *(*px_warning)( char *msg );
    void        *(*px_progress)( int percent );
    PhDim_t     scale;
    PgColor_t   transparent;
    void        *colors;
    int         ncolors;
} PxMethods_t;

The members are as follows:

You can OR the following into flags:
*(*px_alloc)( long nbytes, int type );
*(*px_free)( void *memory, int type );
Memory allocation/deallocation routines that you supply. The deallocation routine is called only if the image can't be loaded. The type can be one of the following:
*(*px_error)( char *msg );
An error routine that you supply. The loader calls this function if it encounters a fatal error while loading the graphic file. The msg argument is a pointer to an error-message string.

Note that all memory allocated by the loader is freed before this function is called.

*(*px_warning)( char *msg );
A warning routine that you supply. The loader calls this function if it encounters a nonfatal error while loading the graphic file. The msg argument is a pointer to a warning-message string.
*(*px_progress)( int percent );
A progress routine that you supply. The loader calls this function after it loads/decodes a scan line. The percent argument is a fixed point number in the following format:


The upper 16 bits are the whole portion; the lower 16 bits are the decimal portion.

Not currently used.
This member is used with the PX_TRANSPARENT flag. If this flag is set, the transparent color in the image is replaced by the color specified by transparent. You should set transparent to be a color that isn't used in the image.

Once the image is loaded, use PhMakeTransBitmap() to create a transparency mask for this color.

colors, ncolors
Used in conjunction with the PX_USECOLORS flag. The colors argument points to a palette, and ncolors indicates the number of valid entries in the palette.

To draw an image, call PgDrawPhImagemx().

The allocated members of the image structure can be freed by calling PhReleaseImage() after setting the image's flag member to indicate which parts of the image should be freed. You can then free the PhImage_t structure. For more information, see PhImage_t.

Choosing which file formats to support

When you compile your application, you get to choose which graphic-file formats the image library supports.

Note: Including support for certain graphic-file formats increases the size of your application code. To keep your code small, we recommend that you include only the formats you need.

To choose specific formats, simply define the PX_IMAGE_MODULES manifest followed by any number of PX_XXX_SUPPORT files as shown below.

Note: The module inclusion flags must be defined before the <photon/PxImage.h> header file is included.


In the example above, the PX_IMAGE_MODULES manifest tells the preprocessor that you're defining an array of supported file formats. The manifests on the next seven lines initialize the array.


A pointer to a PhImage_t structure, or NULL if an error occurs.


This example can use either shared or normal memory. The advantage of using shared memory is that it takes less time to draw the image. If you're not using shared memory, increasing the draw buffer size causes more drawing to be buffered before being sent to the graphics driver; this isn't as important if you're using shared memory.

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <malloc.h>
#include <assert.h>
#include <ctype.h>
#include <signal.h>

#include <Ph.h>
#include <Pt.h>

#define PX_IMAGE_MODULES     // define the modules we want

#include <photon/PxImage.h>

void *memory_allocate( long nbytes, int type );
void memory_free( void *memory, int type );
void warning( char *msg );
void error( char *msg );
void progress( int percent );

int         UseShmem = 1;

void main( int argc, char *argv[] )
    int         c;
    PtArg_t     arg[5];
    PtWidget_t  *window;
    char        fname[255] = { 0 };
    int         Query = 0;
    PhImage_t   *img;
    PxMethods_t methods;

    while( ( c = getopt( argc, argv,
                         "f:QS" ) ) != -1 ) {
        switch( c ) {

            case 'f':         // filename
                strncpy(fname, optarg, 200 );

            case 'Q':         // query file
                Query = 1;

            case 'S':

    memset( &methods, 0, sizeof( PxMethods_t ) );
    methods.px_alloc    = memory_allocate;
    methods.px_free     = memory_free;
    methods.px_warning  = warning;
    methods.px_error    = error;
    methods.px_progress = progress;

    if( Query )
        methods.flags |= PX_QUERY;
        methods.flags |= PX_LOAD;

    if( ( img = PxLoadImage( fname,
                             &methods ) ) == NULL ) {
        fprintf( stderr, "Error loading/query %s\n",
                 fname );
        exit( EXIT_FAILURE );

    /* Make sure PhReleaseImage() releases any allocated
       members of the PhImage_t structure. */

    img->flags |= Ph_RELEASE_IMAGE_ALL;

    if( Query ) {
      printf( "Image width:   %d\n", img->size.w );
      printf( "Image height:  %d\n", img->size.h );
      printf( "Image BPL:     %d\n", img->bpl );
      printf( "Image colors:  %d\n", img->colors );
      printf( "Image type:    %d\n", img->type );
    exit( EXIT_SUCCESS );

    /* initialize widget library and attach to Photon */
    if( PtInit( NULL ) )
        exit( EXIT_FAILURE );

    /* increase the draw buffer */
    PgSetDrawBufferSize( 0x8000 );   

    /* create a window */
    PtSetArg( &arg[0], Pt_ARG_DIM, &img->size, 0 );
    PtSetArg( &arg[1], Pt_ARG_WINDOW_TITLE, 
              "Photon Image Viewer", 0 );
    window = PtCreateWidget( PtWindow, NULL, 2, arg );

    /* Create a label widget with the image. Remember that the
       widget creates a copy of the PhImage_t structure (because
       Pt_ARG_LABEL_DATA is an Alloc resource). The widget 
       doesn't copy data pointed to by the PhImage_t members. */

    PtSetArg( &arg[0], Pt_ARG_LABEL_TYPE, Pt_IMAGE, 0 );
    PtSetArg( &arg[1], Pt_ARG_LABEL_DATA, 
              img, sizeof( PhImage_t ) );
    PtCreateWidget( PtLabel, window, 2, arg );

    /* Free the PhImage_t structure (but not its contents). */

    free( img );

    PtRealizeWidget( window );


void * memory_allocate( long nbytes, int type )
    if( type == PX_IMAGE && UseShmem ) {
        return( PgShmemCreate( nbytes, NULL ) );
    else {
        return( calloc( 1, nbytes ) );

void memory_free( void *memory, int type )
    if( type == PX_IMAGE && UseShmem ) {
        PgShmemDestroy( memory );
    else {
        free( memory );

void warning( char *msg )
    printf( "%s\n", msg );

void error( char *msg )
    printf( "%s\n", msg );
    exit( EXIT_FAILURE );

void progress( int percent )
    printf( "Load Status:  %d.%d percent\n", 
             percent >> 16, percent & 0xffff );



Interrupt handler No
Signal handler No
Thread No

See also:

PgDrawPhImagemx(), PgSetPalette(), PgSetFillColor(), PgSetTextColor(), PgShmemCleanup(), PhImage_t, PhMakeGhostBitmap(), PhMakeTransBitmap(), PhReleaseImage()

[Previous] [Contents] [Index] [Next]