PxLoadImage()

Read or query a graphic file

Synopsis:

#include <photon/PxImage.h>

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

Arguments:

filename

The name of the graphic file that you want to load or query.

methods

A pointer to a PxMethods_t structure that lets you modify the behavior of the function; see below.

If this argument is NULL, the function loads the graphic file specified by filename.

Library:

phexlib

Description:

This function reads a graphic file into memory. Photon supports at least the BMP, GIF, JPEG, PCX, PNG, and SGI file formats.

To draw an image, call PgDrawPhImage() or PgDrawPhImagemx().

When you're finished with the image, you can free the allocated members of the image structure 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.

PxMethods_t

The PxMethods_t structure alters how PxLoadImage() behaves. This structure 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;
    void     *colors;
    int      ncolors;
} PxMethods_t;

The members are as follows:

flags

You can OR the following into flags:

• PX_QUERY — just query the graphic file. A PhImage_t structure is returned on success.
• PX_LOAD — read the graphic file into memory and convert it to a format that Photon can display.
• PX_SUPPRESS_TAG — don't calculate tag IDs for the palette and image.
• PX_DODITHER — this option currently applies to JPEG images only. Perform FS dithering if the image loading library for the source type supports it.
• PX_DIRECT_COLOR — this option currently applies to JPEG images only. Load the graphic file as a 24-bit image if the loader library for the source type supports it.
• PX_USECOLORS — if loading a JPEG image, use the palette provided by the application instead of calculating one. The image will look much better on palette-based drivers.
• PX_TRANSPARENT — make the image transparent, using the detected transparent color and the image's chroma scheme.

void *(*px_alloc)( long nbytes, int type );
void *(*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_NORMAL — the memory allocation is unspecific.
• PX_IMAGE — the memory allocation is for the image data.
• PX_PALETTE — the memory allocation is for the palette.

Your px_alloc function must return a pointer to the allocated memory.

void *(*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 string.

---

The loader frees all of the memory that it allocated before calling this function.

---

void *(*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 string.

void *(*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.

---

You can call PxTerminate() in this function to abort the call to PxLoadImage() if something has gone wrong.

---

scale

Not currently used.

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.

---

PxLoadImage() doesn't use the value that px_free, px_error, px_warning, and px_progress return. These functions can return NULL to avoid compiler warnings.

---

Threads and PxLoadImage()

As described in “Threads” in the Parallel Operations chapter of the Photon Programmer's Guide, you need to be careful when using the Photon library in a multi-threaded program; you need to call PtEnter() and PtLeave() around any calls to the Photon library.

However, PxLoadImage() is completely separate from the rest of the Photon library. It's not thread-safe, so you do need to make sure that only one thread at a time is trying to use it; but you could use your own mutex instead of the PtEnter() lock, and if you know that you have only one thread that ever loads images, you don't even need that.

Of course, if the methods that you pass to PxLoadImage() use any Photon calls such as PgShmemCreate(), you need to call PtEnter() and PtLeave() around them.

This can create problems if you're using your own mutex and you have a Photon callback that wants to call PxLoadImage(): if one thread locks your mutex and then blocks in PtEnter() while the Photon thread invokes the callback, and the callback tries to lock your mutex without calling PtLeave(), you have a deadlock. You have to design carefully to avoid such situations — but that's normal in multi-threading.

Returns:

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

Examples:

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>

#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;

int 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;

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

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

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

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

            case 'S':
                UseShmem^=1;
                break;
        }
    }

    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;
    else
        methods.flags |= PX_LOAD;

    if( ( img = PxLoadImage( fname,
                             &methods ) ) == NULL ) {
        fprintf( stderr, "Error loading/query %s\n",
                 fname );
        PtExit( 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 );
    PtExit( EXIT_SUCCESS );
    }

    /* 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, Pt_NO_PARENT, 2, arg );

    /* Create a label widget with the image. Remember that
       the widget creates a copy of the PhImage_t structure.
       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_IMAGE, img, 0 );
    PtCreateWidget( PtLabel, window, 2, arg );

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

    free( img );

    PtRealizeWidget( window );

    PtMainLoop();
    return EXIT_SUCCESS;
}

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 );
    }
    return NULL;
}

void *warning( char *msg )
{
    printf( "%s\n", msg );
    return NULL;
}

void *error( char *msg )
{
    printf( "%s\n", msg );
    PtExit( EXIT_FAILURE );
    return NULL;
}

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

Classification:

Photon

See also:

PgDrawPhImage*(), PgDrawPhImageRect*(), PgDrawRepPhImage*(), PgSetPalette(), PgSetFillColor(), PgSetTextColor(), PgShmemCleanup(), PhCreateImage(), PhImage_t, PhMakeGhostBitmap(), PhMakeTransBitmap(), PhMakeTransparent(), PhReleaseImage(), PtCRC(), PtCRCValue(), PxTerminate()

“Images” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide