Load

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

Just that function is not enough for whole mechanism to work, but bindings will come later. Let us imagine we work with an imaginary library libduff, that we want to load files of .duf format. [ To discern imaginary code from real, imaginary will be prepended with _ - like, _libduff_loadfile ]. So, we call _libduff_loadfile(), that 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 4-bytes boundary,
      // happily libduff has 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; so we can use it if libduff trusts handles vs names:

   {
     _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 have to implement minimal open_load() and close_load().

Simplest open_load() returns non-null pointer - it is enough to report 'o.k'

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

Its result will be available in "PImgLoadFileInstance-> instance", just in case. If it was dynamically allocated, free it in close_load(). Dummy close_load() is doing simply nothing:

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

Writing to "PImage-> 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 image is filled in reverse - Prima images are built like classical XY-coordinate grid, where Y ascends upwards.

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

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

NB. Image creates palette with size calculated by exponent of 2, since it can't know beforehand of the actual palette size. If color palette for, say, 4-bit image contains 15 of 16 possible for 4-bit image colors, code like

     i-> palSize = 15;

does the trick.

Data conversion

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

Prima defines number of converting routines between different data formats. Some of them can be applied to scanlines, and some to whole image ( due sampling algorithms ). These are defined in img_conv.h, and probably ones that you'll need would be "bc_format1_format2", which work on scanlines and probably ibc_repad, which combines some "bc_XX_XX" with 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 easy method for determining this situation, but you have to convert your data in appropriate way to keep picture worthy of its name. Note the BYTEORDER symbol that is defined ( usually ) in sys/types.h

Load with no data

   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 4-bytes boundary,
      // happily libduff has 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 string literal upon the expansion. Hash used for storage is a lexical of type "HV*". Code

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

is a prettier way for

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

hv_store(), HV's and SV's along with other funny symbols are described in perlguts.pod in Perl installation.

Return extra information

1.

integers: pset_i( integer, _l-> integer);

2.

floats: pset_f( float, _l-> float);

3.

strings: pset_c( string, _l-> charstar); - note - no malloc codec from you required

4.

prima objects: pset_H( Handle, _l-> primaHandle);

5.

SV's: pset_sv_noinc( scalar, newSVsv(sv));

6.

hashes: pset_sv_noinc( scalar, ( SV *) newHV()); - hashes created through newHV() can be filled just in the same manner as described here

7.

arrays: pset_sv_noinc( scalar, ( SV *) newAV()); - arrays (AV) are described in perlguts also, but most useful function here is av_push. To push 4 values, for example, follow 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 flag "PImgLoadFileInstance-> loadExtras". Codec may skip this flag, the extra information will not be returned, even if "PImgLoadFileInstance-> frameProperties" was changed. However, it is advisable to check for the flag, just for an efficiency. All keys, possibly assigned to frameProperties should be enumerated for high-level code. These strings should be represented into "char ** PImgCodecInfo-> loadOutput" array.

   static char * loadOutput[] = {
      "hotSpotX",
      "hotSpotY",
      nil
   };

   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 X11 bitmap can provide location of hot spot, two integers, X and Y. The type of the data is not specified.

Loading to icons

a) Let us imagine, that 4-bit image always carries a transparent color index, in 0-15 range. In this case, following code will create desirable 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.

b) if explicit bit mask is given, code will be like:

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

open_load() and close_load()

Load input

   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