Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pod::Prima::codecs(3) User Contributed Perl Documentationpod::Prima::codecs(3)

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

       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.

       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

       Simplest	open_load() returns non-null pointer - it is enough to report

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

   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

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

       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[] = {

	  static ImgCodecInfo codec_info = {

	  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"

       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.

       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

	  // 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
	      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:

	  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.

       Dmitry Karasik, <>.

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

perl v5.24.1			  2014-09-03		 pod::Prima::codecs(3)

NAME | DESCRIPTION | Start simple | Single-frame loading | Multiple-frame load | Saving | Registering with image subsystem | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:

home | help