Functions
*********

This section of the manual is a complete reference to all of the functions comprising libgimpprint, with examples.

All of the libgimpprint functions can be declared by including the master libgimpprint header, <gimp-print/gimp-print.h>.  This should be done in every source file that uses gimpprint functions by putting

     #include <gimp-print/gimp-print.h>

at the top of each file.

Main functions
==============

These functions are essential to the correct functioning of libgimpprint.  All or most other functions in the library depend absolutely upon them.  In the case of stp_init, this function must be called before any of the other functions in the library.

 -- Function: int stp_init (void)

     This function initialises the libgimpprint library. It must be called before any of the other libgimpprint functions are called. It is responsible for setting up message catalogues (for internationalisation). This function may be called more than once, at any stage during the execution of a program.

     It returns zero on success, nonzero on failure.

stp_init might be used as follows:

     int
     main (int argc, char **argv)
     {
       stp_init();

       ...

     }

 -- Function: void * stp_malloc (size_t SIZE)

     Where SIZE is the amount of memory to allocate (in bytes).

     This function allocates memory. It will always return a pointer to the allocated memory. It will not return on failure.

     It returns a pointer to the allocated memory.

stp_vars_t functions
====================

 -- Data type: void * stp_vars_t
     This is an opaque data type, whose structure is not visible to the user.  This object contains all of the information about settings for a given printer, such as color (contrast, brightness), the type of printer, the dithering algorithm in use, and so forth.  Please see the stp_set_* and stp_get_* functions below for the accessors and mutators for this data type.

 -- Function: stp_vars_t stp_allocate_vars (void)
     Allocate a new stp_vars_t with default settings for all members.

 -- Function: void stp_copy_vars (stp_vars_t VD, const stp_vars_t VS)
     Copy the settings from VS to VD.

 -- Function: stp_vars_t stp_allocate_copy (const stp_vars_t VS)
     Allocate a new stp_vars_t, copying settings from VS.

 -- Function: void stp_free_vars (stp_vars_t VV)
     Free all resources associated with VV.  VV must not be used in any way following this call.

 -- Function: const char * stp_get_output_to (const stp_vars_t VV)
 -- Function: void stp_set_output_to (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_output_to_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the name of the command that this job will be printed to. This is used by front ends; the driver library always prints to a stream provided by the front end and never uses this directly.

 -- Function: const char * stp_get_driver (const stp_vars_t VV)
 -- Function: void stp_set_driver (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_driver_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the name of the driver (the type of printer).

 -- Function: const char * stp_get_ppd_file (const stp_vars_t VV)
 -- Function: void stp_set_ppd_file (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_ppd_file_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the name of the PPD file used by this print job.  Normally, only PostScript printers use PPD files.

 -- Function: const char * stp_get_resolution (const stp_vars_t VV)
 -- Function: void stp_set_resolution (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_resolution_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the resolution to be used in this print job.  Different drivers support different resolutions, and many drivers support multiple quality settings for a given DPI resolution.

 -- Function: const char * stp_get_media_size (const stp_vars_t VV)
 -- Function: void stp_set_media_size (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_media_size_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the name of the media size (e. g. A3, letter, legal) to be used in this print job.

 -- Function: const char * stp_get_media_type (const stp_vars_t VV)
 -- Function: void stp_set_media_type (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_media_type_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the name of the media type (e. g. plain paper, photo quality inkjet paper) to be used in this print job.

 -- Function: const char * stp_get_media_source (const stp_vars_t VV)
 -- Function: void stp_set_media_source (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_media_source_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the name of the media source (e. g. manual feed, tray A) to be used in this print job.

 -- Function: const char * stp_get_ink_type (const stp_vars_t VV)
 -- Function: void stp_set_ink_type (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_ink_type_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the name of the ink type (e. g. four color standard, six color photo) to be used in this print job.

 -- Function: const char * stp_get_dither_algorithm (const stp_vars_t VV)
 -- Function: void stp_set_dither_algorithm (stp_vars_t VV, const char *VAL)
 -- Function: void stp_set_dither_algorithm_n (stp_vars_t VV, const char *VAL, int BYTES)
     Get or set the dither algorithm to be used in this print job.

 -- Function: int stp_get_output_type (const stp_vars_t VV)
 -- Function: void stp_set_output_type (stp_vars_t VV, int VAL)
     Get or set the output type (color, grayscale, black and white) for this print job.

 -- Function: int stp_get_orientation (const stp_vars_t VV)
 -- Function: void stp_set_orientation (stp_vars_t VV, int VAL)
     Get or set the paper orientation for this print job.

 -- Function: int stp_get_left (const stp_vars_t VV)
 -- Function: void stp_set_left (stp_vars_t VV, int VAL)
     Get or set the left margin (in 1/72 inch units, or "points") for this print job.

 -- Function: int stp_get_top (const stp_vars_t VV)
 -- Function: void stp_set_top (stp_vars_t VV, int VAL)
     Get or set the top margin (in 1/72 inch units, or "points") for this print job.

 -- Function: int stp_get_image_type (const stp_vars_t VV)
 -- Function: void stp_set_image_type (stp_vars_t VV, int VAL)
     Get or set the image type (line art, continuous tone, solid colors) for this print job.

 -- Function: int stp_get_unit (const stp_vars_t VV)
 -- Function: void stp_set_unit (stp_vars_t VV, int VAL)
     Get or set the base unit (inches or centimeters) for this print job. This is provided for front ends; the package itself uses points as its unit of measurement.

 -- Function: int stp_get_page_width (const stp_vars_t VV)
 -- Function: void stp_set_page_width (stp_vars_t VV, int VAL)
     Get or set the width of the printed region of the page.

 -- Function: int stp_get_page_height (const stp_vars_t VV)
 -- Function: void stp_set_page_height (stp_vars_t VV, int VAL)
     Get or set the height of the printed region of the page.

 -- Function: int stp_get_input_color_model (const stp_vars_t VV)
 -- Function: void stp_set_input_color_model (stp_vars_t VV, int VAL)
     Get or set the color model (currently RGB or CMY) of the input to the driver.  Most front ends will use RGB input.

 -- Function: int stp_get_output_color_model (const stp_vars_t VV)
 -- Function: void stp_set_output_color_model (stp_vars_t VV, int VAL)
     Get or set the color model (currently RGB or CMY) of the output of the driver.  Most printers will use CMY.

 -- Function: float stp_get_scaling (const stp_vars_t VV)
 -- Function: void stp_set_scaling (stp_vars_t VV, float VAL)
     Get or set the scaling factor of the image.  If the scaling factor is greater than 0, it is interpreted as a percent (5.0-100.0 is the valid range) of the printable page region, using the more restrictive axis. For example, if the image to be printed should be 3" (wide) x 2" (high), and the printable page region is 8"x10.5", the scale factor should be 37.5 (3"/8").

     If the scaling is less than zero, it is interpreted as pixels per inch.

     It is likely that in the future this will be migrated into the front end.  There is no particular reason why the driver needs to know about this.

 -- Function: float stp_get_gamma (const stp_vars_t VV)
 -- Function: void stp_set_gamma (stp_vars_t VV, float VAL)
     Get or set the gamma of the print job (valid range: 0.1-4.0; default 1.0).  Note that this is not the absolute gamma used by the print job; it is scaled by the gamma appropriate for the printer.  This is true for all of the numerical parameters.

 -- Function: float stp_get_brightness (const stp_vars_t VV)
 -- Function: void stp_set_brightness (stp_vars_t VV, float VAL)
     Get or set the brightness of the print job (valid range: 0.0-2.0; default: 1.0).  Any value other than 1.0 will result in some possible values not being used; if brightness is less than 1.0, no output point will be pure white, and if brightness is greater than 1.0, no output point will be pure black (or cyan, or magenta, or yellow).

 -- Function: float stp_get_contrast (const stp_vars_t VV)
 -- Function: void stp_set_contrast (stp_vars_t VV, float VAL)
     Get or set the contrast of the print job (valid range: 0.0-4.0; default: 1.0).  Values less than 1.0 will result in pure white or black not being used (0.0 will make the entire image 50% gray). Values greater than 1.0 do not hard clip; while the contrast in the midtones increases, it only asymptotically approaches the limits.

 -- Function: float stp_get_cyan (const stp_vars_t VV)
 -- Function: void stp_set_cyan (stp_vars_t VV, float VAL)
     Get or set the cyan adjustment of the print job (range: 0.0-4.0; default: 1.0).  This currently adjusts the gamma of the cyan curve.  It is scaled by the cyan adjustment for the printer model in question.

 -- Function: float stp_get_magenta (const stp_vars_t VV)
 -- Function: void stp_set_magenta (stp_vars_t VV, float VAL)
     Get or set the magenta adjustment of the print job (range: 0.0-4.0; default: 1.0).  This currently adjusts the gamma of the magenta curve.  It is scaled by the magenta adjustment for the printer model in question.

 -- Function: float stp_get_yellow (const stp_vars_t VV)
 -- Function: void stp_set_yellow (stp_vars_t VV, float VAL)
     Get or set the yellow adjustment of the print job (range: 0.0-4.0; default: 1.0).  This currently adjusts the gamma of the yellow curve.  It is scaled by the yellow adjustment for the printer model in question.

 -- Function: float stp_get_saturation (const stp_vars_t VV)
 -- Function: void stp_set_saturation (stp_vars_t VV, float VAL)
     Get or set the saturation of the print job (range: 0.0-9.0; default: 1.0). Saturation of 0.0 produces grayscale output using composite (CMY or CMYK, as appropriate for the printer) color.

 -- Function: float stp_get_density (const stp_vars_t VV)
 -- Function: void stp_set_density (stp_vars_t VV, float VAL)
     Get or set the density of the print job (range: 0.0-2.0; default: 1.0).  This adjusts the amount of ink deposited in a linear fashion for all channels.  It is scaled by the density appropriate for the choice of printer, resolution, paper type, and other factors that the driver may deem appropriate.

 -- Function: float stp_get_app_gamma (const stp_vars_t VV)
 -- Function: void stp_set_app_gamma (stp_vars_t VV, float VAL)
     Get or set the gamma of the input (i. e. what the driving application uses).

 -- Function: void * stp_get_lut (const stp_vars_t VV)
 -- Function: void stp_set_lut (stp_vars_t VV, void *VAL)
     Get or set the color lookup table for the print job.  This is useful outside of the library for computing a preview of the printed result. The lookup table itself should be treated as an opaque handle.

 -- Function: unsigned char * stp_get_cmap (const stp_vars_t VV)
 -- Function: void stp_set_cmap (stp_vars_t VV, unsigned char *VAL)
     Get or set the color map for the print job.  This is a table of R,G,B values for 8-bit indexed input.  This may be moved outside of the library in the future; in this case, the front end would be required to do its own mapping and supply true-color RGB to the driver.

The following methods are used to perform output and error reporting by the driver.  The driver supplies a stream of output bytes; the front end is responsible for providing methods that accept this output and handle it appropriately.

 -- Function: stp_outfunc_t stp_get_outfunc (const stp_vars_t VV)
 -- Function: void stp_set_outfunc (const stp_vars_t VV, stp_outfunc_t VAL)
 -- Function: void * stp_get_outdata (const stp_vars_t VV)
 -- Function: void stp_set_outdata (stp_vars_t VV, void *VAL)

      -- Data type: stp_outfunc_t

               typedef void (*stp_outfunc_t) (void *data,
                             const char *buffer, size_t bytes);

     Get or set the output function the driver will use.  The front end must supply a suitable function for accepting the output data.  The stp_set_outdata method provides a way of passing an appropriate object to the output function.

 -- Function: stp_outfunc_t stp_get_errfunc (const stp_vars_t VV)
 -- Function: void stp_set_errfunc (const stp_vars_t VV, stp_outfunc_t VAL)
 -- Function: void * stp_get_errdata (const stp_vars_t VV)
 -- Function: void stp_set_errdata (stp_vars_t VV, void *VAL)
     Get or set the error reporting function that the driver will use. This is used to report errors or debugging information, and must be supplied.  A typical errfunc will simply print whatever it's passed to stderr.

/* * hue_map is an array of 49 doubles representing the mapping of hue * from (0..6) to (0..6) in increments of .125.  The hue_map is in CMY space, * so hue=0 is cyan. */ typedef void (*stp_convert_t)(const stp_vars_t vars, const unsigned char *in, unsigned short *out, int *zero_mask, int width, int bpp, const unsigned char *cmap, const double *hue_map, const double *lum_map, const double *sat_map);

 -- Function: void stp_merge_printvars (stp_vars_t USER, const stp_vars_t PRINT)

 -- Function: void stp_allocate_lut (stp_vars_t V, size_t STEPS)

 -- Function: void stp_free_lut (stp_vars_t V)

 -- Function: void stp_compute_lut (stp_vars_t V, size_t STEPS)

Dither functions
================

 -- Function: size_t stp_dither_algorithm_count (void)

 -- Function: const char * stp_dither_algorithm_name (int ID)

 -- Function: const char * stp_default_dither_algorithm (void)

Options functions
=================

 -- Data type: void * stp_option_t
     This is an opaque data type, whose structure is not visible to the user.

 -- Function: void stp_set_option(stp_vars_t V, const char *NAME, const char *DATA, int BYTES)

 -- Function: void stp_clear_option (stp_vars_t V, const char *NAME)

 -- Function: void stp_clear_all_options (stp_vars_t V)

 -- Function: size_t stp_option_count (const stp_vars_t V)

 -- Function: const stp_option_t stp_get_option_by_index (const stp_vars_t V, size_t IDX)

 -- Function: const stp_option_t stp_get_option_by_name (const stp_vars_t V, const char *NAME)

 -- Function: const char * stp_option_data (const stp_option_t OPTION)
     Note: not null delimited!

 -- Function: const char * stp_option_name (const stp_option_t OPTION)

 -- Function: size_t stp_option_length (const stp_option_t OPTION)

Paper functions
===============

 -- Data type: void * stp_papersize_t
     This is an opaque data type, whose structure is not visible to the user.

 -- Data type: stp_papersize_unit_t

          typedef enum papersize_unit
          {
            PAPERSIZE_ENGLISH,
            PAPERSIZE_METRIC
          } stp_papersize_unit_t;

 -- Function: int stp_known_papersizes (void)

 -- Function: const stp_papersize_t stp_get_papersize_by_name (const char *NAME)

 -- Function: const stp_papersize_t stp_get_papersize_by_size (int L, int W)

 -- Function: const stp_papersize_t stp_get_papersize_by_index (int INDEX)

 -- Function: const char * stp_papersize_get_name (const stp_papersize_t PT)

 -- Function: unsigned stp_papersize_get_width (const stp_papersize_t PT)

 -- Function: unsigned stp_papersize_get_height (const stp_papersize_t PT)

 -- Function: unsigned stp_papersize_get_top (const stp_papersize_t PT)

 -- Function: unsigned stp_papersize_get_left (const stp_papersize_t PT)

 -- Function: unsigned stp_papersize_get_bottom (const stp_papersize_t PT)

 -- Function: unsigned stp_papersize_get_right (const stp_papersize_t PT)

 -- Function: stp_papersize_unit_t stp_papersize_get_unit (const stp_papersize_t PT)

Printer functions
=================

 -- Data type: void * stp_printer_t
     This is an opaque data type, whose structure is not visible to the user.

 -- Function: int stp_known_printers (void)

 -- Function: const stp_printer_t stp_get_printer_by_index (int IDX)

 -- Function: const char * stp_printer_get_long_name (const stp_printer_t P)

 -- Function: const stp_printer_t stp_get_printer_by_long_name (const char *LONG_NAME)

 -- Function: const stp_printer_t stp_get_printer_by_driver (const char *DRIVER)

 -- Function: int stp_get_printer_index_by_driver (const char *DRIVER)

 -- Function: const char * stp_printer_get_driver (const stp_printer_t P)

 -- Function: int stp_printer_get_model (const stp_printer_t P)

 -- Function: const stp_printfuncs_t * stp_printer_get_printfuncs (const stp_printer_t P)

 -- Data type: stp_printfuncs_t

          typedef struct
          {
            char  **(*parameters)(const stp_printer_t printer,
                                  const char *ppd_file,
                                  const char *name, int *count);
            void  (*media_size)(const stp_printer_t printer,
                                const stp_vars_t v, int *width,
                                int *height);
            void  (*imageable_area)(const stp_printer_t printer,
                                    const stp_vars_t v,
                                    int *left, int *right,
                                    int *bottom, int *top);
            void  (*limit)(const stp_printer_t printer,
                           const stp_vars_t v,
                           int *width, int *height);
            void  (*print)(const stp_printer_t printer,
                           stp_image_t *image, const stp_vars_t v);
            const char *(*default_parameters)(const stp_printer_t printer,
                                              const char *ppd_file,
                                              const char *name);
            void  (*describe_resolution)(const stp_printer_t printer,
                                         const char *resolution,
                                         int *x, int *y);
            int   (*verify)(const stp_printer_t p, const stp_vars_t v);
          } stp_printfuncs_t;

 -- Data type: stp_image_t

          typedef struct stp_image
          {
            void (*init)(struct stp_image *image);
            void (*reset)(struct stp_image *image);
            void (*transpose)(struct stp_image *image);
            void (*hflip)(struct stp_image *image);
            void (*vflip)(struct stp_image *image);
            void (*crop)(struct stp_image *image,
                         int left, int top, int right,
                         int bottom);
            void (*rotate_ccw)(struct stp_image *image);
            void (*rotate_cw)(struct stp_image *image);
            void (*rotate_180)(struct stp_image *image);
            int  (*bpp)(struct stp_image *image);
            int  (*width)(struct stp_image *image);
            int  (*height)(struct stp_image *image);
            void (*get_row)(struct stp_image *image,
                  unsigned char *data, int row);
            const char *(*get_appname)(struct stp_image *image);
            void (*progress_init)(struct stp_image *image);
            void (*note_progress)(struct stp_image *image,
                  double current, double total);
            void (*progress_conclude)(struct stp_image *image);
            void *rep;
          } stp_image_t;

     This is an abstract data type for interfacing with the program which created the image.

 -- Function: const stp_vars_t stp_printer_get_printvars (const stp_printer_t P)

Settings functions
==================

 -- Function: stp_convert_t stp_choose_colorfunc (int OUTPUT_TYPE, int IMAGE_BPP, const unsigned char *CMAP, int *OUT_BPP, const stp_vars_t V)

 -- Function: void stp_compute_page_parameters (int PAGE_RIGHT, int PAGE_LEFT, int PAGE_TOP, int PAGE_BOTTOM, double SCALING, int IMAGE_WIDTH, int IMAGE_HEIGHT, stp_image_t *IMAGE, int *ORIENTATION, int *page_width, int *PAGE_HEIGHT, int *OUT_WIDTH, int *OUT_HEIGHT, int *LEFT, int *TOP)

 -- Function: const stp_vars_t stp_default_settings (void)

 -- Function: const stp_vars_t stp_maximum_settings (void)

 -- Function: const stp_vars_t stp_minimum_settings (void)

Version functions
=================

 -- Function: const char * stp_check_version (unsigned int REQUIRED_MAJOR,
     unsigned int REQUIRED_MINOR, unsigned int REQUIRED_MICRO)

     This function checks whether the version of libgimpprint that the program is linked with is equal to the version number passed to it. If the version is the same, the function returns NULL. If any of the version numbers do not match (i.e. the library version is too old or too new), a string containing a desription of the difference is returned. The first error found is returned. The function checks in the order major, minor, micro.

Version macros
--------------

 -- Macro: GIMPPRINT_CHECK_VERSION (major,minor,micro)

     This macro returns zero if the version of the libgimpprint headers are greater or equal to the version given as an argument. It returns nonzero if the version of the libgimpprint headers are less than the argument.

 -- Macro: GIMPPRINT_MAJOR_VERSION

 -- Macro: GIMPPRINT_MINOR_VERSION

 -- Macro: GIMPPRINT_MICRO_VERSION

 -- Macro: GIMPPRINT_CURRENT_INTERFACE

 -- Macro: GIMPPRINT_BINARY_AGE

 -- Macro: GIMPPRINT_INTERFACE_AGE

These macros are integers holding the version numbers. They should be used for compile-time checking only. To check version numbers at run-time, use the equivalent variables. Note that at present (4.1.x development branch) the library interface version numbers are not used.

Version variables
-----------------

 -- Variable: const unsigned int gimpprint_major_version

 -- Variable: const unsigned int gimpprint_minor_version

 -- Variable: const unsigned int gimpprint_micro_version

 -- Variable: const unsigned int gimpprint_current_interface

 -- Variable: const unsigned int gimpprint_binary_age

 -- Variable: const unsigned int gimpprint_interface_age

These variables hold the library version numbers. Because the version of the library may change on a system using shared libraries, these should be used instead of the equivalent macros when checking the library version at run-time. Note that library interface version numbers are not used in the development branch, but are in the stable branch.