PxLoadImage()

Read or query a graphic file

Synopsis:

#include <photon/PxImage.h>

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

Description:

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:

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 - substitute the color specified in the transparency member for the transparent color in the image.

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

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

scale

Not currently used.

transparent

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.

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.

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

#define PX_IMAGE_MODULES
#define PX_GIF_SUPPORT
#define PX_JPG_SUPPORT
#define PX_PCX_SUPPORT
#define PX_BMP_SUPPORT
#define PX_TGA_SUPPORT
#define PX_PNG_SUPPORT
#define PX_TIFF_SUPPORT

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.

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>

#define PX_IMAGE_MODULES     // define the modules we want
#define PX_GIF_SUPPORT
#define PX_JPG_SUPPORT
#define PX_PCX_SUPPORT
#define PX_BMP_SUPPORT

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

    PtMainLoop();
}

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

Classification:

Photon

See also:

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