Provided by: libprima-perl_1.28-1.2_amd64 bug

NAME

       Prima::codecs - How to write a codec for Prima image subsystem

DESCRIPTION

       How to write a codec for Prima image subsystem

Start simple

       There are many graphical formats in the world, and yet more libraries, that depend on
       them. Writing a codec that supports particular library is a tedious task, especially if
       one wants many formats. Usually you never want to get into internal parts, the
       functionality comes first, and who needs all those funky options that format provides? We
       want to load a file and to show it. Everything else comes later - if ever. So, in a way to
       not scare you off, we start it simple.

   Load
       Define a callback function like:

          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"
       As mentioned above, Prima insists on keeping its image data in 32-bit aligned scanlines.
       If libduff allows reading from file by scanlines, we can use this possibility as well:

          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.

Single-frame loading

   Palette
       Our libduff can be black-and-white in two ways - where 0 is black and 1 is white and vice
       versa. While 0B/1W is perfectly corresponding to imbpp1 | imGrayScale and no palette
       operations are needed ( Image cares automatically about these), 0W/1B is although black-
       and-white grayscale but should be treated like general imbpp1 type.

            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
       As mentioned before, Prima defines image scanline size to be aligned to 32 bits, and the
       formula for lineSize calculation is

           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
       If a high-level code just needs image information rather than all its bits, codec can
       provide it in a smart way. Old code will work, but will eat memory and time. A flag
       "PImgLoadFileInstance-> noImageData" is indicating if image data is needed. On that
       condition, codec needs to report only dimensions of the image - but the type must be set
       anyway.  Here comes 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 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
       Image attributes are dimensions, type, palette and data.  However, it is only Prima point
       of view - different formats can supply number of extra information, often irrelevant but
       sometimes useful. From perl code, Image has a hash reference 'extras' on object, where
       comes all this stuff. Codec can report also such data, storing it in
       "PImgLoadFileInstance-> frameProperties".  Data should be stored in native perl format, so
       if you're not familiar with perlguts, you better read it, especially if you want return
       arrays and hashes. But just in simple, you can return:

       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
       If high-level code wants an Icon instead of an Image, Prima takes care for producing and-
       mask automatically.  However, if codec knows explicitly about transparency mask stored in
       a file, it might change object in the way it fits better. Mask is stored on Icon in a "->
       mask" field.

       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()
       open_load() and close_load() are used as brackets for load requests, and although they
       come to full power in multiframe load requests, it is very probable that correctly written
       codec should use them. Codec that assigns "false" to "PImgCodecInfo-> canLoadMultiple"
       claims that it cannot load those images that have index different from zero. It may report
       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 codec can provide some file information
       without loading frames at all. It can be any information, of whatever kind. It have to be
       stored into the hash "PImgLoadFileInstance-> fileProperties", to be filled once on
       open_load(). The only exception is "PImgLoadFileInstance-> frameCount", which can be
       filled on open_load(). Actually, frameCount could be filled on any load stage, except
       close_load(), to make sense in frame positioning. Even single frame codec is advised to
       fill this field, at least to tell whether file is empty ( frameCount == 0) or not (
       frameCount == 1). More about frameCount comes into chapters dedicated to multiframe
       requests.  For strictly single-frame codecs it is therefore advised to care for
       open_load() and close_load().

   Load input
       So far codec is expected to respond for noImageData hint only, and it is possible to allow
       a high-level code to alter 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 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 load_defaults() function. This
       functions returns newly created ( by calling newHV()) hash, with accepted keys and their
       default ( and always valid ) value pairs.  Example below defines speed_vs_memory integer
       value, that should be 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
       Image subsystem defines no severity gradation for codec errors.  If error occurs during
       load, codec returns false value, which is "null" on open_load() and "false" on load. It is
       advisable to explain the error, otherwise the user gets just "Loading error" string. To do
       so, error message is to be copied to "PImgLoadFileInstance-> errbuf", which is
       "char[256]".  On an extreme severe error codec may call croak(), which jumps to the
       closest G_EVAL block. If there is no G_EVAL blocks then program aborts. This condition
       could also happen if 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.

Multiple-frame load

       In order to indicate that a codec is ready to read multiframe images, it must set
       "PImgCodecInfo-> canLoadMultiple" flag to true. This only means, that codec should respond
       to the "PImgLoadFileInstance-> frame" field, which is integer that can be in range from 0
       to "PImgLoadFileInstance-> frameCount - 1".  It is advised that codec should change the
       frameCount from its original value "-1" to actual one, to help Prima filter range requests
       before they go down to the codec. The only real problem that may happen to the codec which
       it strongly unwilling to initialize frameCount, is as follows.  If a loadAll request was
       made ( corresponding boolean "PImgLoadFileInstance-> loadAll" flag is set for codec's
       information) and frameCount is not initialized, then Prima starts loading all frames,
       incrementing frame index until it receives an error. Assuming the first error it gets is
       an EOF, it reports no error, so there's no way for a high-level code to tell whether there
       was an loading error or an end-of-file condition.  Codec may initialize frameCount at any
       time during open_load() or load(), even together with false return value.

Saving

       Approach for handling saving requests is very similar to a load ones.  For the same reason
       and with same restrictions functions save_defaults() open_save(), save() and close_save()
       are defined. Below shown a typical saving code and highlighted differences from load.  As
       an example we'll take existing codec_X11.c, which defines extra hot spot coordinates, x
       and y.

          static HV *
          save_defaults( PImgCodec c)
          {
             HV * profile = newHV();
             pset_i( hotSpotX, 0);
             pset_i( hotSpotY, 0);
             return profile;
          }

          static void *
          open_save( PImgCodec instance, PImgSaveFileInstance fi)
          {
             return (void*)1;
          }

          static Bool
          save( PImgCodec instance, PImgSaveFileInstance fi)
          {
             PImage i = ( PImage) fi-> object;
             Byte * l;
             ...

             fprintf( fi-> f, "#define %s_width %d\n", name, i-> w);
             fprintf( fi-> f, "#define %s_height %d\n", name, i-> h);
             if ( pexist( hotSpotX))
                fprintf( fi-> f, "#define %s_x_hot %d\n", name, (int)pget_i( hotSpotX));
             if ( pexist( hotSpotY))
                fprintf( fi-> f, "#define %s_y_hot %d\n", name, (int)pget_i( hotSpotY));
             fprintf( fi-> f, "static char %s_bits[] = {\n  ", name);
             ...
             // printing of data bytes is omitted
          }

          static void
          close_save( PImgCodec instance, PImgSaveFileInstance fi)
          {
          }

       Save request takes into account defined supported types, that are defined in
       "PImgCodecInfo-> saveTypes". Prima converts image to be saved into one of these formats,
       before actual save() call takes place.  Another boolean flag, "PImgSaveFileInstance->
       append" is summoned to govern appending to or rewriting a file, but this functionality is
       under design. Its current value is a hint, if true, for a codec not to rewrite but rather
       append the frames to an existing file. Due to increased complexity of the code, that
       should respond to the append hint, this behavior is not required.

       Codec may set two of PImgCodecInfo flags, canSave and canSaveMultiple. Save requests will
       never be called if canSave is false, and append requests along with multiframe save
       requests would be never invoked for a codec with canSaveMultiple set to false.  Scenario
       for a multiframe save request is the same as for a load one. All the issues concerning
       palette, data converting and saving extra information are actual, however there's no
       corresponding flag like loadExtras - codec is expected to save all information what it can
       extract from "PImgSaveFileInstance-> objectExtras" hash.

Registering with image subsystem

       Finally, the code have to be registered. It is not as illustrative but this part better
       not to be oversimplified.  A codec's callback functions are set into ImgCodecVMT
       structure.  Those function slots that are unused should not be defined as dummies - those
       are already defined and gathered under struct CNullImgCodecVMT. That's why all functions
       in the illustration code were defined as static.  A codec have to provide some information
       that Prima uses to decide what codec should load this particular file.  If no explicit
       directions given, Prima asks those codecs whose file extensions match to file's.  init()
       should return pointer to the filled struct, that describes codec's capabilities:

          // extensions to file - might be several, of course, thanks to dos...
          static char * myext[] = { "duf", "duff", nil };

          // we can work only with 1-bit/pixel
          static int    mybpp[] = {
              imbpp1 | imGrayScale, // 1st item is a default type
              imbpp1,
              0 };   // Zero means end-of-list. No type has zero value.

          // main structure
          static ImgCodecInfo codec_info = {
             "DUFF", // codec name
             "Numb & Number, Inc.", // vendor
             _LIBDUFF_VERS_MAJ, _LIBDUFF_VERS_MIN,    // version
             myext,    // extension
             "DUmb Format",     // file type
             "DUFF",     // file short type
             nil,    // features
             "",     // module
             true,   // canLoad
             false,  // canLoadMultiple
             false,  // canSave
             false,  // canSaveMultiple
             mybpp,  // save types
             nil,    // load output
          };

          static void *
          init( PImgCodecInfo * info, void * param)
          {
             *info = &codec_info;
             return (void*)1; // just non-null, to indicate success
          }

       The result of init() is stored into "PImgCodec-> instance", and info into "PImgCodec->
       info". If dynamic memory was allocated for these structs, it can be freed on done()
       invocation.  Finally, the function that is invoked from Prima, is the only that required
       to be exported, is responsible for registering a codec:

          void
          apc_img_codec_duff( void )
          {
             struct ImgCodecVMT vmt;
             memcpy( &vmt, &CNullImgCodecVMT, sizeof( CNullImgCodecVMT));
             vmt. init          = init;
             vmt. open_load     = open_load;
             vmt. load          = load;
             vmt. close_load    = close_load;
             apc_img_register( &vmt, nil);
          }

       This procedure can register as many codecs as it wants to, but currently Prima is designed
       so that one codec_XX.c file should be connected to one library only.

       The name of the procedure is apc_img_codec_ plus library name, that is required for a
       compilation with Prima.  File with the codec should be called codec_duff.c ( is our case)
       and put into img directory in Prima source tree. Following these rules, Prima will be
       assembled with libduff.a ( or duff.lib, or whatever, the actual library name is system
       dependent) - if the library is present.

AUTHOR

       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

       Prima, Prima::Image, Prima::internals, Prima::image-load