Next: Adding New Formats, Up: Supported Image Formats [Contents][Index]

#### 37.5.1 Built-in support

Each image file format in Forms Library is identified by any one of three pieces of information, the formal name, the short name, and the file extension. For example, for the GIF format, the formal name is `"CompuServe GIF"`16, the short name is `"GIF"`, and file extension is `"gif"`. This information is used to specify the output format for `flimage_dump()`.

The following table summarizes the supported file formats with comments

FormalName | ShortName | Extension | Comments
--- | --- | --- | ---
Portable Pixmap | ppm | ppm
Portable Graymap | pgm | pgm
Portable Bitmap | pbm | pbm
CompuServe GIF | gif | gif
Windows/OS2 BMP file | bmp | bmp
JPEG/JFIF format | jpeg | jpg
X Window Bitmap | xbm | xbm
X Window Dump | xwd | xwd
X PixMap | xpm | xpm | XPM3 only
NASA/NOST FITS | fits | fits | Standard FITS and IMAGE extension
Portable Network Graphics | png | png | needs netpbm
SGI RGB format | iris | rgb | need pbmplus/netpbm package
PostScript format | ps | ps | needs gs for reading
Tagged Image File Format | tiff | tif | no compression support

To avoid executable bloating with unnecessary code, only ppm, pgm, pbm and compression filters (gzip and compress) are enabled by default. To enable other formats, call `flimage_enable_xxx()` once anywhere after `fl_initialize()`, where `xxx` is the short name for the format. For example, to enable BMP format, `flimage_enable_bmp()` should be called.

Further, if you enable GIF support, you’re responsible for any copyright/patent and intellectual property dispute arising from it. Under no circumstance should the authors of the Forms Library be liable for the use or misuse of the GIF format.

Usually there are choices on how the image should be read and written. The following is a rundown of the built-in options that control some aspects of image support. Note that these options are persistent in nature and once set they remain in force until reset.

    typedef struct {
        int quality;
        int smoothing;
    } FLIMAGE_JPEG_OPTIONS;

    void flimage_jpeg_output_options(FLIMAGE_JPEG_OPTIONS *option);

The default quality factor for JPEG output is 75. In general, the higher the quality factor rhe better the image is, but the file size gets larger. The default smoothing factor is 0.

    void flimage_pnm_output_options(int raw_format);

For PNM (ppm, pgm, and pbm) output, two variants are supported, the binary (raw) and ASCII format. The raw format is the default. If the output image is of type `FL_IMAGE_GRAY16`, ASCII format is always output.

    void flimage_gif_output_options(int interlace);

If `interlace` is true, an interlaced output is generated. Transparency, comments, and text are controlled, respectively, by `image->tran_rgb`, `image->comments` and `image->text`.

PostScript options affect both reading and writing.

    FLIMAGE_PS_OPTION *flimage_ps_options(void);

where the control structure has the following members

`int orientation`

  The orientation of the generated image on paper. Valid options are `FLPS_AUTO`, `FLPS_PORTRAIT` and `FLPS_LANDSCAPE`. The default is `FLPS_AUTO`.

`int auto_fit`

  By default, the output image is scaled to fit the paper if necessary. Set it to false (0) to turn auto-scaling off.

`float xdpi, ydpi`

  These two are the screen resolution. Typical screens these days have resolutions about 80 dpi. The settings of these affect both reading and writing.

`float paper_w`

  The paper width, in inches. The default is 8.5 in.

`float paper_h`

  The paper height, in inches. The default is 11.0 in

`char* tmpdir`

  A directory name where temporary working files go. The default is `/tmp`.

`float hm, vm`

  Horizontal and vertical margins, in inches, to leave when writing images. The default is 0.4 in (about 1 cm).

`float xscale`

  Default is 1.0.

`float yscale`

  Default is 1.0.

`int first_page_only`

  If set, only the first page of the document will be loaded even if the document is multi-paged. The default setting is false.

To change an option, simply call `flimage_ps_options()` and change the field from the pointer returned by the function:

    void SetMyPageSize(float w, float h) {
        FLIMAGE_PS_OPTION *options = flimage_ps_options();

        options->paper_w = w;
        options->paper_h = h;
    }

All these option setting routines can be used either as a configuration routine or an image-by-image basis by always calling one of these routines before `flimage_dump()`. For example,

    flimage_jpeg_output_options(option_for_this_image);
    flimage_dump(im, "file","jpeg");

You can also utilize the `image->pre_write` function to set the options. This function, if set, is always called inside `flimage_dump()` before the actual output begins.

#### Footnotes

### (16)

The Graphics Interchange Format (c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated.

Next: Adding New Formats, Up: Supported Image Formats [Contents][Index]