Whole document tree

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