=head1 NAME

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

=head1 DESCRIPTION

How to write a codec for the Prima image subsystem

=head1 Start simple

There are many graphical formats in the world, and yet more libraries, that
depend on them. Writing a codec that supports a particular library is a tedious
task, especially if one wants to support more than one format. 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 display its content. Everything else comes later - if ever. So, in a way to
not scare you off, we start it simple.

=head2 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.  I<[ To discern imaginary code from real,
imaginary will be prepended with _  - for example, _libduff_loadfile ]>. So, we call
the C<_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 C<load()> you will need to implement minimal C<open_load()>
and C<close_load()> functions.

The simplest C<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 C<< PImgLoadFileInstance-> instance >>
for future reference. If it was dynamically allocated, free it in C<close_load()>.
A dummy C<close_load()> is doing nothing but must be present nevertheless:

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


=head2 Writing to C<< PImage-> data >>

Prima formats its image data as 32-bit aligned scanlines in a contiguous memory
block. If I<libduff> allows reading from files by scanlines, we can use the
C<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
L<"Registering with the image subsystem"> part if you want it fast.

=head1 Single-frame loading

=head2 Palette

Our I<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 C<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.

=head2 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 F<include/img_conv.h>, and probably the ones
that you'll need would be C<bc_format1_format2>, which works on scanlines, and
also C<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
C<BYTEORDER> symbol that is ( usually ) defined in F<sys/types.h>.

=head2 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 C<< 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 C<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 C<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 L<perlguts>.

=head2  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 C<'extras'> on object, where all this
information is stored. Codec can report also such data, storing it in
C<< 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 L<perlguts>), especially if you want to return
arrays and hashes. But for simple types, one can return the following perl scalars:

=over

=item integers

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

=item floats

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

=item strings

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

- note - no C<malloc> call is required

=item prima objects

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

=item SVs

	pset_sv_noinc( scalar, newSVsv(sv));

=item hashes

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

hashes created through C<newHV> can be filled in the same manner as described here

=item arrays

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

arrays (AVs) are described in perlguts also, but the most useful function here
is C<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];

=back

High-level code can specify if the extra information should be loaded. This
behavior is determined by the flag C<< 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 C<<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.

=head2 Loading to icons

If high-level code wants an Icon object with 1-bit mask (I<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 C<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 C<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 C<mask> or C<create_empty_icon>
methods.

=head2 open_load() and close_load()

C<open_load()> and C<close_load()> are used as brackets for load requests.  If a
codec assigns C<false> to C<< 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 C<open_load()> and
C<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 C<< PImgLoadFileInstance-> fileProperties >>, 
to be filled once on C<open_load()>. The only exception is
C<< PImgLoadFileInstance-> frameCount >>, which can be updated during one of 
C<load()> calls.  Actually, the C<frameCount> field could be filled during any
load stage, except C<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 (C<frameCount == 0>)
or not ( C<frameCount == 1>). More information about the C<frameCount> field
can be found below in the chapters dedicated to the multiframe requests.

=head2 Load input

So far a codec is expected to respond for the C<noImageData> hint only, and it
is possible to allow a high-level code to alter the codec load behavior,
passing specific parameters.  C<< 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 C<load_defaults()> function. This function
returns a newly created ( by calling C<newHV()>) hash, with the accepted keys and their
default ( and always valid ) value pairs. The example below defines
the C<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.

=head2 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 C<NULL> on
C<open_load()> and C<false> on C<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 C<< 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.

=head1 Multiple-frame load

To indicate that the codec is ready to read multiframe images, it must set the
C<< PImgCodecInfo-> canLoadMultiple >> flag to true. This only means, that
codec should respond to the C<< PImgLoadFileInstance-> frame >> field, which
value is an integer that should be in the range from C<0> to
C<< PImgLoadFileInstance-> frameCount - 1 >>.  It is advised that the codec
should change the frameCount from its original value C<-1> to the 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 is unwilling to
initialize C<frameCount>, is as follows. If a loadAll request was made (
corresponding boolean C<< 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 a loading error or an
end-of-file condition.  Codec may initialize the C<frameCount> field at any
time during C<open_load()> or C<load()>, even while returning a false return
value to the caller.

=head1 Saving

The approach for handling saving requests is very similar to the handling of
the loading requests.  For the same reason and with the same restrictions
functions C<save_defaults()>, C<open_save()>, C<save()>, and C<close_save()>
are defined. Below is an example of typical saving code with highlighted
differences from the loading code. As an example, we'll take existing
F<img/codec_X11.c>, which defines extra hotspot 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)
   {
   }

A saving request takes into account the image types that the codec previously
declared to support, and that are defined in the C<< PImgCodecInfo-> saveTypes >> array. 
Prima converts an image to be saved into one of these formats,
before the actual C<save()> call takes place. 

A codec may also set two of C<PImgCodecInfo> flags, C<canSave> and
C<canSaveMultiple>. Save requests will never be called if C<canSave> is false,
and correspondingly, the multiframe save requests
would be never invoked for a codec with C<canSaveMultiple> set to false.  The
scenario for a multiframe save request is the same as for a multiframe loading
request. All the issues concerning palette, data converting, and saving extra
information are actual, however, there's no corresponding flag like
C<loadExtras> - the codec is expected to save all information that it can
extract from the C<< PImgSaveFileInstance-> objectExtras >> hash.


=head1 Registering with the image subsystem

Finally, the codec has to be registered. All of its callback functions are to
be set into a C<ImgCodecVMT> structure.  The function slots that are unused
should not be defined as dummies - those are already defined and gathered under
the C<CNullImgCodecVMT> struct. That's why all functions in the illustration
code were defined as static. A codec has to provide some information that Prima
uses to decide which codec should load a particular file type. If no explicit
directions are given, Prima would only ask the codecs that match with the
loaded file's extensions.  The C<init()> function should return a pointer to
the filled struct, that describes the codec's capabilities:

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

   // 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
      NULL,    // features
      "",     // module
      true,   // canLoad
      false,  // canLoadMultiple
      false,  // canSave
      false,  // canSaveMultiple
      mybpp,  // save types
      NULL,    // 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 in the C<< PImgCodec-> instance >>, and
the information in the C<< PImgCodec-> info >> field. If dynamic memory was
allocated for these structs, it can be freed on C<done()> invocation which
happens at the end of the program run.  Finally, the function that is invoked
from Prima, is the only one that is required to be exported, and 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, NULL);
   }

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 I<apc_img_codec_> plus the library name, which is
required for a compilation with Prima.  The file with the codec should be
called C<codec_duff.c> (in our case) and put into the C<img> directory in the
Prima source tree. Following these rules, Prima will be assembled with
C<libduff.a> ( or C<duff.lib>, or some other file, as the actual library name
is system dependent) if the library is present.

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::Image>, L<Prima::internals>, L<Prima::image-load>
