Adding Code for Writing a New File Format

Note: Despite the wide variety of displays and file formats xv deals with, internally it only manipulates either 8-bit colormapped images or 24-bit RGB images. Your Write() routine must be prepared to take either sort of image, and convert it (if necessary) to the image format that your file format dictates.

If you haven't already done so (if/when you created the Load() function):

Make a copy of xvpbm.c , calling it something appropriate. For the rest of this appendix, mentally replace the string ' xvpbm.c ' with the name of your new file.

Edit the Makefile and/or the Imakefile so that your new module will be compiled. In the Makefile , add " xvpbm.o " to the " OBJS = ... " macro definition. In the Imakefile , add " xvpbm.o " to the end of the " OBJS1 = ... " macro definition, and " xvpbm.c" to the end of the "SRCS1 = ..." macro definition.

Edit the new module.

You'll need to #include "xv.h" , of course.

The module should have one externally callable function that does the work of writing the file. The function is called with a large number of arguments, described below. The function should return '0' if everything succeeded, and '-1' on failure.

/*******************************************/
int WritePBM(fp,pic,ptype,w,h,rmap,gmap,bmap,numcols,colorstyle,raw,comment)
     FILE *fp;
     byte *pic;
     int   ptype, w,h;
     byte *rmap, *gmap, *bmap;
     int   numcols, colorstyle, raw;
     char *comment;
/*******************************************/

file *fp;

This is a pointer to an already- fopen() 'd stream. Your function should neither open nor close this stream, as that all gets handled elsewhere in xvdir.c .

 

byte *pic;

This points to the image data that will be written. In the case of a PIC8 image, pic will point to a w*h long array of bytes, one byte per pixel, starting at the top-left, and proceeding in normal scan-line order. There is no padding of any sort at the end of the lines.

 

In the case of a PIC24 image, pic will point to a w*h*3 long array of bytes. There are three bytes per pixel, in red, green, blue order. The pixels start at the top-left, and proceed in normal scan line order. There is no padding of any sort at the end of the lines.

 

int ptype, w, h;

These variables describe the format of pic . ptype can be set to either PIC8 or PIC24 . w and h are the width and height of the image, in pixels.

 

byte *rmap, *gmap, *bmap;
int numcols;

These pointers point to the colormap associated with the image. They are only relevant when ptype is PIC8, meaning that pic is an 8-bit per pixel colormapped image. These arrays will each be numcols entries long, with a maximum length of 256. Do not attempt to access entries >= numcols , as the colormaps are not necessarily 256 entries long. You are guaranteed that pixel values found in pic will be within the range [0..numcols-1], so you don't have to check each pixel value. Also, do not attempt to access these arrays at all if ptype is PIC24, as these pointers will probably be NULL in that case.

 

int colorstyle;

The Colors choice selected in the xv save window. It can be either F_FULLCOLOR , F_GREYSCALE , or F_BWDITHER . It will not be F_REDUCED . If the user selects Reduced Color in the xv save window, the appropriate image will be computed, and you'll be given that image, and colorstyle will be set to F_FULLCOLOR .

 

Likewise, if the user has selected B/W Dithered in the xv save window, an appropriate black-and-white image will have been generated before your Write() routine is called, so you won't have to worry about that. Such an image will be a PIC8 image, with a 2-entry colormap. It is up to you to decide which of the two colors should be written as black, and which should be written as white. You should do this by comparing the values of MONO(rmap[0],gmap[0],bmap[0]) and MONO(rmap[1],gmap[1],bmap[1]). Whichever value is smaller is the darker of the two, and should be written as black.

 

int raw;

This is a value passed in specifically for the WritePBM() function, as PBM has two closely-related subformats (raw, and ascii) both of which are written by this one function. Your function won't need this, nor should it be passed in to your function.

 

char *comment;

This will point to a zero-terminated character string which contains the comments that should be written into the image file. Note that this string can be of any length, and it may contain any number of lines (separated by '\n' characters). If your image format supports comments in the file, you should write this information to the file. If it doesn't, you should just ignore this variable. Also, this variable may be NULL, (signifying 'no comments'), in which case it should not be used.

You may pass more parameters, since you're going to be adding the call to this function later on. For example, in my PBM code, I pass one more parameter, 'raw' (whether to save the file as 'raw' or 'ascii') to handle two very similar formats. (Rather than having to write WritePBMRaw() and WritePBMAscii() functions.)

Write the function as you deem appropriate. See xvpbm.c for an example of a Write() routine that writes different formats for 1-bit per pixel images, 8-bit per pixel images, and 24-bit per pixel images, based on ptype and colorstyle .

Note: If your file format can only handle 8-bit images, and ptype is set to PIC24 , you will have to call Conv24to8() to convert the 24-bit image into an 8-bit colormapped image that you can write to the file. See xvgifwr.c for an example of how this is done.

That done, edit ' xv.h ' and add a function declaration for your new function. Search for ' WritePBM() ' in the file for a sample declaration to copy.

Also find the block that begins with:

#define F_GIF       0
#define F_JPEG      ( 0 + F_JPGINC)

and add a definition for your format. Note that it'll be easiest to tack it on at the end.

These numbers must be contiguous, as they are used as indices into the fmtMB menu in xvdir.c .

Edit 'xvdir.c'. This is the module that controls the xv save window.

Add another format name, in the appropriate position, to the saveFormats[] string array.

In the function DoSave() , find the following block:

switch (fmt) {
  case F_GIF:
    rv = WriteGIF(fp, thepic, ptype, w, h, rp, gp, bp, nc, col,
picComments);
  break;
  case F_PM:
    rv = WritePM (fp, thepic, ptype, w, h, rp, gp, bp, nc, col,
picComments);
  break;

and add a case for your function.

Finally, if your format has a common 3 or 4 letter filename suffix (like, ".gif", ".jpg", etc.), you should modify the changeSuffix() routine in xvdir.c so that it recognizes your suffix, and puts your suffix on when someone selects your format.

And It's just that easy!

Writing Complex Formats

Okay, maybe it's not that easy...

If your format requires some additional information to specify how the file should be saved (such as the 'quality' setting in JPEG, or position/size parameters in PostScript), then your task is somewhat more difficult. You'll have to create some sort of pop-up dialog box to get the additional information that you want. You'll also have to change the way your Write() function gets called (as it will now get called from your pop-up dialog box). (Though, if you only feel like doing a quick hack, you can probably just use the GetStrPopUp() function to get a one-line character string from the user, and avoid the complication of writing your own dialog box.)

This is not recommended for anyone who doesn't understand Xlib programming. Frankly, it's not recommended for those who do, either, but they at least stand some chance of success.

The more adventurous types who wish to pursue this should take a look at the xvjpeg.c code, which implements an extremely simple pop-up dialog. A considerably more complicated dialog box is implemented in xvps.c. In addition to writing a module like these for your format, you'll also have to add the appropriate hooks to the DoSave() function (in xvdir.c) and the HandleEvent() function (in xvevent.c ). 'grep PS *.c' will be helpful in finding places where the xvps.c module is called.