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 at least the BMP, GIF, JPEG, PCX, and PNG file formats; for a list of the supported formats, see /usr/photon/dll/pi_io_*.

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

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

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 PgDrawPhImage() or 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.

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

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

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

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

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No