Loading¶

Define a callback function like this:

   static Bool
   load( PImgCodec instance, PImgLoadFileInstance fi)
   {
   }

Just that function is not enough for the whole mechanism to work, but the bindings will come later. Let us imagine we work with an imaginary library libduff, and we want to load files of .duf format. [ To discern imaginary code from real, imaginary will be prepended with _ - for example, _libduff_loadfile ]. So, we call the _libduff_loadfile() function, which loads black-and-white, 1-bits/pixel images, where 1 is white and 0 is black.

   static Bool
   load( PImgCodec instance, PImgLoadFileInstance fi)
   {
      _LIBDUFF * _l = _libduff_load_file( fi-> fileName);
      if ( !_l) return false;
      // - create storage for our file
      CImage( fi-> object)-> create_empty( fi-> object,
        _l-> width, _l-> height, imBW);
      // Prima wants images aligned to a 4-byte boundary,
      // happily libduff has the same considerations
      memcpy( PImage( fi-> object)-> data, _l-> bits,
        PImage( fi-> object)-> dataSize);
      _libduff_close_file( _l);
      return true;
   }

Prima keeps an open handle of the file; if libduff can use file handles, then we can use it too, which is more robust than just file names because the caller can also load images from a byte stream.

   {
     _LIBDUFF * _l = _libduff_load_file_from_handle( fi-> f);
      ...
   // In both cases, you don't need to close the handle -
   // however you might, it is ok:
      _libduff_close_file( _l);
      fclose( fi-> f);
   // You just assign it to NULL to indicate that you've closed it
      fi-> f = NULL;
      ...
   }

Together with load() you will need to implement minimal open_load() and close_load() functions.

The simplest open_load() returns a non-null pointer as a success flag:

   static void *
   open_load( PImgCodec instance, PImgLoadFileInstance fi)
   {
      ... open file handle ...
      return (void*)1;
   }

Its result will be stored in "PImgLoadFileInstance-> instance" for future reference. If it was dynamically allocated, free it in close_load(). A dummy close_load() is doing nothing but must be present nevertheless:

   static void
   close_load( PImgCodec instance, PImgLoadFileInstance fi)
   {
   }

Writing to "PImage-> data"¶

Prima formats its image data as 32-bit aligned scanlines in a contiguous memory block. If libduff allows reading from files by scanlines, we can use the "lineSize" field to properly address the data:

   PImage i = ( PImage) fi-> object;
   // note - since this notation is more convenient than
   // PImage( fi-> object)-> , instead i-> will be used
   Byte * dest = i-> data + ( _l-> height - 1) * i-> lineSize;
   while ( _l-> height--) {
      _libduff_read_next_scanline( _l, dest);
      dest -= i-> lineSize;
   }

Note that the image is filled in reverse - Prima images are built like a classical XY-coordinate grid, where Y ascends upwards.

Here ends the simple part. You can skip down to the "Registering with the image subsystem" part if you want it fast.

Palette¶

Our libduff images can be black-and-white in two ways - where 0 is black and 1 is white and vice versa. While 0B/1W perfectly corresponds to the "imbpp1 | imGrayScale" Prima image type and no palette operations are needed ( Prima cares automatically about these), a 0W/1B is a black-and-white grayscale image that should be treated like the imbpp1 type with custome palette:

     if ( l-> _reversed_BW) {
        i-> palette[0].r = i-> palette[0].g = i-> palette[0].b = 0xff;
        i-> palette[1].r = i-> palette[1].g = i-> palette[1].b = 0;
     }

Note. The image always has a palette array with a size enough to store 256 colors, since it can't know beforehand the actual palette size. If the color palette for, say, a 4-bit image contains 15 out of the 16 colors possible, the code like

     i-> palSize = 15;

does the trick.

Data conversion¶

Prima defines image scanline size to be aligned to 32 bits, and the formula for the calculation of the scanline size is

    lineSize = (( width * bits_per_pixel + 31) / 32) * 4;

Prima defines many converting routines between different data formats. Some of them can be applied to scanlines, and some to the whole image ( because sampling algorithms generally may need access to more than a single scanline). These are defined in include/img_conv.h, and probably the ones that you'll need would be "bc_format1_format2", which works on scanlines, and also "ibc_repad" that does byte repadding.

For those who are especially lucky, some libraries do not check between machine byte format and file byte format. Prima unfortunately doesn't provide an easy method for determining this situation, but you'll have to convert your data in the appropriate way to have picture data displayed correctly. Note the "BYTEORDER" symbol that is ( usually ) defined in sys/types.h.

Loading with no data¶

If a high-level code just needs information about the image dimensions and bit depth rather than its pixels, a codec should be able to provide that in an effective way. The implementation above would still work but will use more memory and time. The "PImgLoadFileInstance-> noImageData" flag indicates if image data is needed. On that condition, the codec needs to report only the dimensions of the image - but the type must be set anyway. Here is the full code:

   static Bool
   load( PImgCodec instance, PImgLoadFileInstance fi)
   {
      _LIBDUFF * _l = _libduff_load_file( fi-> fileName);
      HV * profile = fi-> frameProperties;
      PImage i = ( PImage) fi-> frameProperties;
      if ( !_l) return false;
      CImage( fi-> object)-> create_empty( fi-> object, 1, 1,
         _l-> _reversed_BW ? imbpp1 : imBW);
      // copy palette, if any
      if ( _l-> _reversed_BW) {
         i-> palette[0].r = i-> palette[0].g = i-> palette[0].b = 0xff;
         i-> palette[1].r = i-> palette[1].g = i-> palette[1].b = 0;
      }
      if ( fi-> noImageData) {
         // report dimensions
         pset_i( width,  _l-> width);
         pset_i( height, _l-> height);
         return true;
      }
      // - create storage for our file
      CImage( fi-> object)-> create_empty( fi-> object,
           _l-> width, _l-> height,
           _l-> _reversed_BW ? imbpp1 : imBW);
      // Prima wants images aligned to a 4-byte boundary,
      // happily libduff has the same considerations
      memcpy( PImage( fi-> object)-> data, _l-> bits,
        PImage( fi-> object)-> dataSize);
      _libduff_close_file( _l);
      return true;
   }

The newly introduced macro "pset_i" is a convenience operator, assigning integer (i) as a value to a hash key, given as a first parameter - it becomes a string literal upon the expansion. The hash used for storage is a perl scalar of type "HV*". The following code

        HV * profile = fi-> frameProperties;
        pset_i( width, _l-> width);

is a syntax sugar for

        hv_store(
            fi-> frameProperties,
            "width", strlen( "width"),
            newSViv( _l-> width),
            0);

hv_store(), which together with HV's and SV's and the other symbols are described in perlguts.

Returning extra information¶

The most useful image attributes are dimensions, type, palette, and (pixel) data. However different formats can supply a fair amount of other image information, often irrelevant but sometimes useful. In the perl code, an image has access have a special hash reference 'extras' on object, where all this information is stored. Codec can report also such data, storing it in "PImgLoadFileInstance-> frameProperties". Data should be stored in the native perl format, so if you're not familiar with perl scalar implementation, you might want to read it first (see perlguts), especially if you want to return arrays and hashes. But for simple types, one can return the following perl scalars:

integers

        pset_i( integer, _l-E<gt> integer);
    

floats

        pset_f( float, _l-E<gt> float);
    

strings

        pset_c( string, _l-E<gt> charstar);
    

- note - no "malloc" call is required

prima objects

        pset_H( Handle, _l-E<gt> primaHandle);
    

SVs

        pset_sv_noinc( scalar, newSVsv(sv));
    

hashes

        pset_sv_noinc( scalar, ( SV *) newHV());
    

hashes created through "newHV" can be filled in the same manner as described here

arrays

        pset_sv_noinc( scalar, ( SV *) newAV());
    

arrays (AVs) are described in perlguts also, but the most useful function here is "av_push". To push 4 values, for example, this code:

    AV * av = newAV();
    for ( i = 0;i < 4;i++) av_push( av, newSViv( i));
    pset_sv_noinc( myarray, newRV_noinc(( SV *) av);
    

is a C equivalent to

      ->{extras}-> {myarray} = [0,1,2,3];
    

High-level code can specify if the extra information should be loaded. This behavior is determined by the flag "PImgLoadFileInstance-> loadExtras". A codec may choose to not respect this flag, and thus the image extra information will not be returned. All data that can be possibly extracted from an image, should be listen in the "<char ** PImgCodecInfo-" loadOutput>> array:

   static char * loadOutput[] = {
      "hotSpotX",
      "hotSpotY",
      NULL
   };
   static ImgCodecInfo codec_info = {
      ...
      loadOutput
   };
   static void *
   init( PImgCodecInfo * info, void * param)
   {
      *info = &codec_info;
      ...
   }

The code above is taken from codec_X11.c, where the X11 bitmap can provide the location of the hotspot, as two integers, X and Y. The type of the data is not specified.

Loading to icons¶

If high-level code wants an Icon object with 1-bit mask (and-mask) instead of an Image object, Prima can take care of producing the mask automatically. However, if codec can read the explicit transparency data, it might instead change the final mask in a more precise way. The mask pixels are stored on the Icon obejct in the "mask" field.

a) Let us imagine, that a 4-bit image always carries a transparent color index, in the 0-15 range. In this case, the following code will create the correct mask:

      if ( kind_of( fi-> object, CIcon) &&
           ( _l-> transparent >= 0) &&
           ( _l-> transparent < PIcon( fi-> object)-> palSize)) {
         PRGBColor p = PIcon( fi-> object)-> palette;
         p += _l-> transparent;
         PIcon( fi-> object)-> maskColor = ARGB( p->r, p-> g, p-> b);
         PIcon( fi-> object)-> autoMasking = amMaskColor;
      }

Of course,

      pset_i( transparentColorIndex, _l-> transparent);

would be also helpful to report.

b) if an explicit bit mask is contained in the image, the code will be using the "amNone" constant instead:

      if ( kind_of( fi-> object, CIcon) &&
           ( _l-> maskData >= 0)) {
         memcpy( PIcon( fi-> object)-> mask, _l-> maskData, _l-> maskSize);
         PIcon( fi-> object)-> autoMasking = amNone;
      }

Note that the mask is also subject to LSB/MSB and 32-bit alignment issues. Treat it as a regular imbpp1 data format.

c) A format supports transparency information, but the image does not contain any. In this case no, action is required on the codec's part; the high-level code specifies if the transparency mask is created ( iconUnmask field ).

d) The full alpha transparency, if present, can be loaded into a 8-bit alpha mask. The icon mask storage should be upgraded to accomodate for the 8-bit mask pixel depth by calling either "mask" or "create_empty_icon" methods.

open_load() and close_load()¶

open_load() and close_load() are used as brackets for load requests. If a codec assigns "false" to "PImgCodecInfo-> canLoadMultiple" that means that it can only load a single image object from an image file, even if the image format supports many images per file. It may report the total amount of frames, but still be incapable of loading them. There is also a load sequence, called null-load, when no load() calls are made, just open_load() and close_load(). These requests are made in case the codec can provide some file information without loading frames at all. It can be any information, of whatever kind. It has to be stored in the hash "PImgLoadFileInstance-> fileProperties", to be filled once on open_load(). The only exception is "PImgLoadFileInstance-> frameCount", which can be updated during one of load() calls. Actually, the "frameCount" field could be filled during any load stage, except close_load(), so that the Prima code that drives the multiframe logic would be able to correctly track individual images.

Even if the codec can only load single image per file, it is still advised to fill this field, at least to tell whether a file is empty ("frameCount == 0") or not ( "frameCount == 1"). More information about the "frameCount" field can be found below in the chapters dedicated to the multiframe requests.

Load input¶

So far a codec is expected to respond for the "noImageData" hint only, and it is possible to allow a high-level code to alter the codec load behavior, passing specific parameters. "PImgLoadFileInstance-> profile" is a hash, that contains these parameters. The data that should be applied to all frames and/or the whole image file are set there when open_load() is called. These data, plus frame-specific keys passed to every load() call. However, Prima passes only those hash keys, which are returned by the load_defaults() function. This function returns a newly created ( by calling newHV()) hash, with the accepted keys and their default ( and always valid ) value pairs. The example below defines the "speed_vs_memory" field, which should accept integer values 0, 1, or 2.

   static HV *
   load_defaults( PImgCodec c)
   {
      HV * profile = newHV();
      pset_i( speed_vs_memory, 1);
      return profile;
   }
   ...
   static Bool
   load( PImgCodec instance, PImgLoadFileInstance fi)
   {
        ...
        HV * profile = fi-> profile;
        if ( pexist( speed_vs_memory)) {
           int speed_vs_memory = pget_i( speed_vs_memory);
           if ( speed_vs_memory < 0 || speed_vs_memory > 2) {
                strcpy( fi-> errbuf, "speed_vs_memory should be 0, 1 or 2");
                return false;
           }
           _libduff_set_load_optimization( speed_vs_memory);
        }
   }

The latter code chunk can be applied to open_load() as well.

Returning an error¶

The image subsystem defines no severity gradation for codec errors. If an error occurs during loading, the codec returns a false value, which is "NULL" on open_load() and "false" on load(). It is advisable to explain the error, otherwise, the user gets just the generic "Load error" string. To do so, the error message is to be copied to "PImgLoadFileInstance-> errbuf :: char[256]" . On an extremely severe error codec may call croak(), which jumps to the closest G_EVAL block. If there are no G_EVAL blocks then the program aborts. This condition could also happen if the codec calls some Prima code that issues croak(). This condition is untrappable, - at least without calling perl functions. Understanding that that behavior is not acceptable, it is still under design.