From ef501d2f2ca0322fce26ddef75257841f570dd14 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sat, 21 Feb 2026 04:07:21 +0530 Subject: [PATCH 1/2] Improve API documentation in raster.h and filter.h --- cupsfilters/filter.h | 118 ++++++++++++++++++++++++++----------------- cupsfilters/raster.h | 20 +++++++- 2 files changed, 91 insertions(+), 47 deletions(-) diff --git a/cupsfilters/filter.h b/cupsfilters/filter.h index c9a66923f..2caa29e7f 100644 --- a/cupsfilters/filter.h +++ b/cupsfilters/filter.h @@ -209,17 +209,49 @@ extern int cfFilterPClose(int fd, cf_filter_data_t *data); +// +// 'cfFilterChain()' - Execute a chain of filter functions. +// +// Executes multiple filters in sequence. The output of one +// filter becomes the input of the next filter. All filters +// receive the same cf_filter_data_t structure. +// +// Parameters: +// inputfd - Input file descriptor. +// outputfd - Output file descriptor. +// inputseekable - Non-zero if input supports seeking. +// data - Job and printer data. +// parameters - Unsorted CUPS array of +// cf_filter_filter_in_chain_t* entries. +// +// Returns 0 on success and non-zero on error. +// + extern int cfFilterChain(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// Parameters: Unsorted (!) CUPS array of cf_filter_filter_in_chain_t* -// List of filters to execute in a chain, next filter takes output of -// previous filter as input, all get the same filter data, parameters -// are supplied individually in the array +// +// 'cfFilterExternal()' - Execute an external CUPS filter, +// backend, or System V interface script. +// +// This function runs an external program as part of the filter +// chain. It can call a CUPS filter, a CUPS backend (including +// device discovery mode), or a System V interface script. +// +// Parameters: +// inputfd - Input file descriptor. +// outputfd - Output file descriptor. +// inputseekable - Non-zero if input supports seeking. +// data - Job and printer data. +// parameters - Pointer to a cf_filter_external_t structure +// describing the external program to execute. +// +// Returns 0 on success and non-zero on error. +// extern int cfFilterExternal(int inputfd, int outputfd, @@ -227,23 +259,6 @@ extern int cfFilterExternal(int inputfd, cf_filter_data_t *data, void *parameters); -// Parameters: cf_filter_external_t* -// -// Path/Name of the external CUPS/System V filter or backend to be -// called by this filter function, specification whether we call a -// filter or a backend, and in case of backend, whether in job -// processing or discovery mode, extra options for the 5th command -// line argument, and extra environment variables -// -// CUPS filter: -// See "man filter" -// -// CUPS Backend: -// See "man backend" -// -// System V interface script: -// https://www.ibm.com/docs/en/aix/7.2?topic=configuration-printer-interface-scripts - extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); @@ -251,27 +266,28 @@ extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); + +// +// 'cfFilterGhostscript()' - Convert input data using Ghostscript. +// +// Uses Ghostscript to convert the input data to the desired +// output format. The output format must be specified via +// data->final_content_type or by passing a +// cf_filter_out_format_t parameter. +// +// Supported output formats include PDF, raster-only PDF, +// PCLm, CUPS Raster, PWG Raster, Apple Raster, and PCL-XL. +// +// Returns 0 on success and non-zero on error. +// + + extern int cfFilterGhostscript(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type -// or alternatively as parameter of type cf_filter_out_format_t. -// -// Output formats: PDF, raster-only PDF, PCLm, PostScript, CUPS Raster, -// PWG Raster, Apple Raster, PCL-XL -// -// Note: With the Apple Raster selection and a Ghostscript version -// without "appleraster" output device (9.55.x and older) the output -// is actually CUPS Raster but information about available color -// spaces and depths is taken from the urf-supported printer IPP -// attribute. This mode is for further processing with -// rastertopwg. With Ghostscript supporting Apple Raster output -// (9.56.0 and newer), we actually produce Apple Raster and no further -// filter is required. - extern int cfFilterBannerToPDF(int inputfd, int outputfd, @@ -432,6 +448,26 @@ extern int cfFilterTextToText(int inputfd, cf_filter_data_t *data, void *parameters); + +// +// 'cfFilterUniversal()' - Automatically select and execute +// the appropriate filter conversion pipeline. +// +// Determines the required data conversion based on the job's +// input content type (data->content_type) and the desired +// final output type (data->final_content_type). +// +// Parameters: +// inputfd - Input file descriptor. +// outputfd - Output file descriptor. +// inputseekable - Non-zero if input supports seeking. +// data - Job and printer data. +// parameters - Pointer to a +// cf_filter_universal_parameter_t structure +// providing additional conversion settings. +// +// Returns 0 on success and non-zero on error. +// extern int cfFilterUniversal(int inputfd, int outputfd, @@ -439,16 +475,6 @@ extern int cfFilterUniversal(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of input format via data->content_type and -// job's final output format via data->final_content_type -// -// Parameters: cf_filter_universal_parameter_t -// -// Contains: actual_output_type: Format which the filter should -// actually produce if different from job's final output -// format, otherwise NULL to produce the job's final output -// format -// texttopdf_params: parameters for texttopdf # ifdef __cplusplus diff --git a/cupsfilters/raster.h b/cupsfilters/raster.h index b9a832a2b..314c670db 100644 --- a/cupsfilters/raster.h +++ b/cupsfilters/raster.h @@ -46,10 +46,19 @@ extern "C" { // -// Prototypes... +// 'cfRasterColorSpaceString()' - Return a human-readable +// name for the given raster color space. // extern const char *cfRasterColorSpaceString(cups_cspace_t cspace); + +// +// 'cfRasterPrepareHeader()' - Prepare a CUPS/PWG raster page +// header based on job and printer data. +// +// Returns 0 on success and non-zero on error. +// + extern int cfRasterPrepareHeader(cups_page_header_t *h, cf_filter_data_t *data, cf_filter_out_format_t @@ -58,6 +67,15 @@ extern int cfRasterPrepareHeader(cups_page_header_t *h, header_outformat, int no_high_depth, cups_cspace_t *cspace); + +// +// 'cfRasterSetColorSpace()' - Update a raster header with the +// appropriate color space and color depth based on printer +// capabilities and job settings. +// +// Returns 0 on success and -1 on error. +// + extern int cfRasterSetColorSpace(cups_page_header_t *h, const char *available, const char *color_mode, From 694df083faab1b4b214a17d1fbdd62669cd52c99 Mon Sep 17 00:00:00 2001 From: Nayanjyoti Das Date: Sun, 1 Mar 2026 02:41:53 +0530 Subject: [PATCH 2/2] Improve documentation of filter and raster files --- cupsfilters/filter.c | 169 ++++++++++------------- cupsfilters/filter.h | 320 ++++++++++++++++++++++++++++--------------- cupsfilters/raster.h | 7 +- 3 files changed, 281 insertions(+), 215 deletions(-) diff --git a/cupsfilters/filter.c b/cupsfilters/filter.c index 84bf4f0b7..5dc93d9c0 100644 --- a/cupsfilters/filter.c +++ b/cupsfilters/filter.c @@ -68,14 +68,14 @@ fcntl_add_nonblock(int fd) // File descriptor to add O_NONBLOCK to // 'cfCUPSLogFunc()' - Output log messages on stderr, compatible to // CUPS, meaning that the debug level is // represented by a prefix like "DEBUG: ", "INFO: -// ", ... +// ", .... // -void -cfCUPSLogFunc(void *data, - cf_loglevel_t level, - const char *message, - ...) +void // O - None +cfCUPSLogFunc(void *data, // I - User data (not used) + cf_loglevel_t level, // I - Log level + const char *message, // I - Message format string + ...) // I - Additional arguments { va_list arglist; @@ -116,8 +116,8 @@ cfCUPSLogFunc(void *data, // by data is not zero. // -int -cfCUPSIsCanceledFunc(void *data) +int // O - 1 if canceled, 0 otherwise +cfCUPSIsCanceledFunc(void *data) // I - Pointer to canceled flag (int *) { return (*((int *)data) != 0 ? 1 : 0); } @@ -142,17 +142,14 @@ get_filter_data_ext_entry(cups_array_t *ext_array, } -void * // O - Extension record which got - // replaced, NULL if there was - // no record under this name, - // the added record is the one - // there, or no record was - // added. If not NULL the - // returned record should usually - // be deleted or freed. +// +// 'cfFilterDataAddExt()' - Add or replace an extension record in the filter data. +// + +void * // O - Replaced extension record, or NULL if none was replaced cfFilterDataAddExt(cf_filter_data_t *data, // I - Filter data record - const char *name, // I - Name of extension - void *ext) // I - Extension record to be added + const char *name, // I - Name of extension + void *ext) // I - Extension record to be added { cf_filter_data_ext_t *entry; void *old_ext = NULL; @@ -186,9 +183,13 @@ cfFilterDataAddExt(cf_filter_data_t *data, // I - Filter data record } -void * -cfFilterDataGetExt(cf_filter_data_t *data, - const char *name) +// +// 'cfFilterDataGetExt()' - Get an extension record from the filter data. +// + +void * // O - Extension record, or NULL +cfFilterDataGetExt(cf_filter_data_t *data, // I - Filter data record + const char *name) // I - Name of extension { cf_filter_data_ext_t *entry; @@ -202,9 +203,13 @@ cfFilterDataGetExt(cf_filter_data_t *data, } -void * -cfFilterDataRemoveExt(cf_filter_data_t *data, - const char *name) +// +// 'cfFilterDataRemoveExt()' - Remove an extension record from the filter data and return it. +// + +void * // O - Extension record, or NULL +cfFilterDataRemoveExt(cf_filter_data_t *data, // I - Filter data record + const char *name) // I - Name of extension { cf_filter_data_ext_t *entry; void *ext = NULL; @@ -231,16 +236,13 @@ cfFilterDataRemoveExt(cf_filter_data_t *data, // -// 'cfFilterGetEnvVar()' - Auxiliary function for cfFilterExternal(), -// gets value of an environment variable in a -// list of environment variables as used by -// the execve() function +// 'cfFilterGetEnvVar()' - Get the value of an environment variable from the +// supplied environment list. // -char * // O - The value, NULL if variable is not in - // list +char * // O - Value of variable, or NULL cfFilterGetEnvVar(char *name, // I - Name of environment variable to read - char **env) // I - List of environment variable serttings + char **env) // I - List of environment variable { int i = 0; @@ -257,17 +259,13 @@ cfFilterGetEnvVar(char *name, // I - Name of environment variable to read // -// 'cfFilterAddEnvVar()' - Auxiliary function for cfFilterExternal(), -// adds/sets an environment variable in a list of -// environment variables as used by the execve() -// function +// 'cfFilterAddEnvVar()' - Add or replace an environment variable in an environment list. // -int // O - Index of where the new value got - // inserted in the list -cfFilterAddEnvVar(char *name, // I - Name of environment variable to set - char *value, // I - Value of environment variable to set - char ***env) // I - List of environment variable serttings +int // O - Index of inserted entry, or -1 on error +cfFilterAddEnvVar(char *name, // I - Name of environment variable to set + char *value, // I - Value of environment variable to set + char ***env) // I - List of environment variable { char *p; int i = 0, @@ -315,28 +313,15 @@ cfFilterAddEnvVar(char *name, // I - Name of environment variable to set // -// 'cfFilterTee()' - This filter function is mainly for debugging. it -// resembles the "tee" utility, passing through the -// data unfiltered and copying it to a file. The -// file name is simply given as parameter. This -// makes using the function easy (add it as item of -// a filter chain called via cfFilterChain()) and -// can even be used more than once in the same -// filter chain (using different file names). In -// case of write error to the copy file, copying is -// stopped but the rest of the job is passed on to -// the next filter. If NULL is supplied as file -// name, the data is simply passed through without -// getting copied. -// +// 'cfFilterTee()' - Copy input data to a file (for debugging) while +// passing it unchanged to the output. -int // O - Error status +int // O - 0 on success, -1 on error cfFilterTee(int inputfd, // I - File descriptor input stream - int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? (unused) - cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters (File - // name) + int outputfd, // I - File descriptor output stream + int inputseekable, // I - Is input stream seekable? (unused) + cf_filter_data_t *data, // I - Job and printer data + void *parameters) // I - File name (const char *) { const char *filename = (const char *)parameters; ssize_t bytes, total = 0; // Bytes read/written @@ -395,12 +380,11 @@ cfFilterTee(int inputfd, // I - File descriptor input stream // -// 'cfFilterPOpen()' - Pipe a stream to or from a filter function Can -// be the input to or the output from the filter -// function. +// 'cfFilterPOpen()' - Create a pipe to a filter function and +// return a file descriptor for communicating with it. // -int // O - File decriptor +int // O - File descriptor cfFilterPOpen(cf_filter_function_t filter_func, // I - Filter function int inputfd, // I - File descriptor input stream or -1 @@ -541,13 +525,13 @@ cfFilterPOpen(cf_filter_function_t filter_func, // // 'cfFilterPClose()' - Close a piped stream created with -// cfFilterPOpen(). +// cfFilterPOpen() and wait for the filter process to finish. // -int // O - Error status +int // O - 0 on success, -1 on error cfFilterPClose(int fd, // I - Pipe file descriptor - int filter_pid, // I - PID of forked filter process - cf_filter_data_t *data) + int filter_pid, // I - PID of forked filter process + cf_filter_data_t *data) // O - Job and printer data { int status, // Exit status retval; // Return value @@ -609,12 +593,12 @@ compare_filter_pids(filter_function_pid_t *a, // I - First filter // -// 'cfFilterChain()' - Call filter functions in a chain to do a data -// format conversion which non of the individual -// filter functions does +// 'cfFilterChain()' - Call filter functions in a chain to perform a data +// format conversion which none of the individual +// filter functions can do alone. // -int // O - Error status +int // O - 0 on success, -1 on error cfFilterChain(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? @@ -954,16 +938,12 @@ sanitize_device_uri(const char *uri, // I - Device URI // -// 'cfFilterExternal()' - Filter function which calls an external -// classic CUPS filter or System V interface -// script, for example a (proprietary) printer -// driver which cannot be converted to a filter -// function or if it is too awkward or risky to -// convert for example when the printer -// hardware is not available for testing +// 'cfFilterExternal()' - Filter function that executes an ezternal CUPS filter +// or System V interface script, typically used when conversion +// to a native filter function is not possible. // -int // O - Error status +int // O - 0 on success, -1 on error cfFilterExternal(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? @@ -1585,24 +1565,14 @@ cfFilterExternal(int inputfd, // I - File descriptor input stream // -// 'cfFilterOpenBackAndSidePipes()' - Open the pipes for the back -// channel and the side channel, so -// that the filter functions can -// communicate with a backend. Only -// needed if a CUPS backend (either -// implemented as filter function -// or called via -// cfFilterExternal()) is called -// with the same filter_data record -// as the filters. Usually to be -// called when populating the -// filter_data record. +// 'cfFilterOpenBackAndSidePipes()' - Open the pipes for the back and side channels +// to allow communication between filter functions and a +// backend. Used when a CUPS backend runs with the same filter_data. +// // -int // O - 0 on success, - // -1 on error -cfFilterOpenBackAndSidePipes(cf_filter_data_t *data) // O - FDs in filter_data - // record +int // O - 0 on success, -1 on error +cfFilterOpenBackAndSidePipes(cf_filter_data_t *data) // O - FDs in filter_data record { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -1681,14 +1651,13 @@ cfFilterOpenBackAndSidePipes(cf_filter_data_t *data) // O - FDs in filter_data // // 'cfFilterCloseBackAndSidePipes()' - Close the pipes for the back -// hannel and the side channel. -// sually to be called when done +// channel and the side channel. +// Usually to be called when done // with the filter chain . // void -cfFilterCloseBackAndSidePipes(cf_filter_data_t *data) // I - FDs in filter_data - // record +cfFilterCloseBackAndSidePipes(cf_filter_data_t *data) // I - FDs in filter_data record { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; diff --git a/cupsfilters/filter.h b/cupsfilters/filter.h index 2caa29e7f..24b87b4a8 100644 --- a/cupsfilters/filter.h +++ b/cupsfilters/filter.h @@ -159,43 +159,101 @@ typedef struct cf_filter_universal_parameter_s // Contains input and output // // Prototypes... // +//'cfCUPSLogFunc()' - Logging callback functions used by filters. +// +// data: User-defined logging context. +// level: Log level of the message. +// message: printf-style format string. +// ...: Optional arguments for the format string. +// +// This function is used by filters to report status, debug +// information, warnings, and errors. +// extern void cfCUPSLogFunc(void *data, cf_loglevel_t level, const char *message, ...); +// +// 'cfCUPSIsCanceledFunc()' - Check whether the current job has been canceled. +// +// data: User-defined job context. +// Returns 1 if canceled, 0 otherwise. +// extern int cfCUPSIsCanceledFunc(void *data); +// 'cfFilterDataAddExt()' - Add an extension to the filter data. +// +// data: Filter data structure. +// name: Name of the extension. +// ext: Pointer to the extension data. +// + extern void *cfFilterDataAddExt(cf_filter_data_t *data, const char *name, void *ext); +// +// '*cfFilterDataGetExt()' - Retrieve an extension from the filter data. +// extern void *cfFilterDataGetExt(cf_filter_data_t *data, const char *name); +// +// '*cfFilterDataRemoveExt()'- Remove an extension from the filter data. +// extern void *cfFilterDataRemoveExt(cf_filter_data_t *data, const char *name); +// +// '*cfFilterGetEnvVar()' - Get the value of an environment variable from a given +// environment array. +// name: Name of the variable. +// env: Environment array. +// +// Returns a pointer to value string, or NULL if not found. +// + extern char *cfFilterGetEnvVar(char *name, char **env); +// +// 'cfFilterAddEnvVar()' - Add or update an environment variable. +// +// name: Name of the variable. +// value: Value of the variable. +// env: Environment array. +// +// Returns 0 on success, -1 on failure. +// extern int cfFilterAddEnvVar(char *name, char *value, char ***env); +// +// 'cfFilterTee()' - Filter function that copies input to output and optionally to a file. +// +// Parameters: parameters points to a const char* specifying the +// filename/path to copy the data to. +// + extern int cfFilterTee(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -// Parameters: Filename/path (const char *) to copy the data to - +// +// 'cfFilterPOpen()' - Start a filter function in a separate process. +// +// filter_func: Filter function to execute. +// parameters: Filter-specific parameters passed to the filter. +// filter_pid: Receives the process ID of the started filter. +// -extern int cfFilterPOpen(cf_filter_function_t filter_func, // I - Filter - // function +extern int cfFilterPOpen(cf_filter_function_t filter_func, int inputfd, int outputfd, int inputseekable, @@ -204,6 +262,15 @@ extern int cfFilterPOpen(cf_filter_function_t filter_func, // I - Filter int *filter_pid); +// +// 'cfFilterPClose()' - Wait for a filter process started by cfFilterPOpen(). +// +// fd: Input pipe file descriptor. +// filter_pid: Process ID of the filter. +// data: Job and printer. +// Return: 0 on success, -1 on failure. +// + extern int cfFilterPClose(int fd, int filter_pid, cf_filter_data_t *data); @@ -212,20 +279,10 @@ extern int cfFilterPClose(int fd, // // 'cfFilterChain()' - Execute a chain of filter functions. // -// Executes multiple filters in sequence. The output of one -// filter becomes the input of the next filter. All filters -// receive the same cf_filter_data_t structure. -// -// Parameters: -// inputfd - Input file descriptor. -// outputfd - Output file descriptor. -// inputseekable - Non-zero if input supports seeking. -// data - Job and printer data. -// parameters - Unsorted CUPS array of -// cf_filter_filter_in_chain_t* entries. -// -// Returns 0 on success and non-zero on error. -// +// Parameters: Pointer to an array of cf_filter_filter_in_chain_t defining the +// list of filters to execute. Each filter receives the previous filter's +// output as input. +// extern int cfFilterChain(int inputfd, int outputfd, @@ -233,26 +290,19 @@ extern int cfFilterChain(int inputfd, cf_filter_data_t *data, void *parameters); - // -// 'cfFilterExternal()' - Execute an external CUPS filter, -// backend, or System V interface script. +// 'cfFilterExternal()' - Executes an external filter or backend. // -// This function runs an external program as part of the filter -// chain. It can call a CUPS filter, a CUPS backend (including -// device discovery mode), or a System V interface script. +// This function runs a CUPS/System V filter or backend based on the input and output types +// specified in the parameters. // -// Parameters: -// inputfd - Input file descriptor. -// outputfd - Output file descriptor. -// inputseekable - Non-zero if input supports seeking. -// data - Job and printer data. -// parameters - Pointer to a cf_filter_external_t structure -// describing the external program to execute. +// See "man filter" and "man backend" for more information on CUPS filters and backends. // -// Returns 0 on success and non-zero on error. +// System V interface script: +// https://www.ibm.com/docs/en/aix/7.2?topic=configuration-printer-interface-scripts // + extern int cfFilterExternal(int inputfd, int outputfd, int inputseekable, @@ -260,25 +310,38 @@ extern int cfFilterExternal(int inputfd, void *parameters); -extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); +// +// 'cfFilterOpenBackAndSidePipes()' - Open the back and side pipes for communication with filters. +// -extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); +extern int cfFilterOpenBackAndSidePipes(cf_filter_data_t *data); +// +// 'cfFilterCloseBackAndSidePipes()' - Close the back and side pipes for communication with filters. +// +extern void cfFilterCloseBackAndSidePipes(cf_filter_data_t *data); + // -// 'cfFilterGhostscript()' - Convert input data using Ghostscript. -// -// Uses Ghostscript to convert the input data to the desired -// output format. The output format must be specified via -// data->final_content_type or by passing a -// cf_filter_out_format_t parameter. +// 'cfFilterGhostscript()' - Run Ghostscript to generate printer output. +// +// Converts input data using Ghostscript to the specified output format. +// The output format must be set via data->final_content_type or alternatively as parameter of type +// cf_filter_out_format_t. // -// Supported output formats include PDF, raster-only PDF, -// PCLm, CUPS Raster, PWG Raster, Apple Raster, and PCL-XL. +// Output formats: PDF, raster-only PDF, PCLm, PostScript, CUPS Raster, +// PWG Raster, Apple Raster, PCL-XL // -// Returns 0 on success and non-zero on error. +// Note: With the Apple Raster selection and a Ghostscript version +// without "appleraster" output device (9.55.x and older) the output +// is actually CUPS Raster but information about available color +// spaces and depths is taken from the urf-supported printer IPP +// attribute. This mode is for further processing with +// rastertopwg. With Ghostscript supporting Apple Raster output +// (9.56.0 and newer), we actually produce Apple Raster and no further +// filter is required. // @@ -288,6 +351,16 @@ extern int cfFilterGhostscript(int inputfd, cf_filter_data_t *data, void *parameters); +// +// 'cfFilterBannerToPDF()' - Generate a PDF banner page. +// +// Creates a banner or test page in PDF format. +// The parameter is a const char* specifying the template directory. +// CUPS uses /usr/share/cups/data/ by default. +// If a PDF file with added banner instructions is provided as input, +// the template directory is not required. +// + extern int cfFilterBannerToPDF(int inputfd, int outputfd, @@ -295,12 +368,9 @@ extern int cfFilterBannerToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// Parameters: const char* -// Template directory: In this directory there are the PDF template files -// for the banners and test pages. CUPS uses /usr/share/cups/data/ for that. -// If you submit a PDF file with added banner instructions as input file -// the template directory is not needed as the PDF input file itself is used -// as template. +// +// 'cfFilterImageToPDF()' - Convert an image to PDF format. +// extern int cfFilterImageToPDF(int inputfd, @@ -309,13 +379,9 @@ extern int cfFilterImageToPDF(int inputfd, cf_filter_data_t *data, void *parameters); - -extern int cfFilterImageToRaster(int inputfd, - int outputfd, - int inputseekable, - cf_filter_data_t *data, - void *parameters); - +// +// 'cfFilterImageToRaster()' - Convert an image to raster format. +// // Requires specification of output format via data->final_content_type // // Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLM @@ -328,6 +394,30 @@ extern int cfFilterImageToRaster(int inputfd, // processing with rastertopwg and/or pwgtopclm. This can change in the // future when we add Apple Raster and PWG Raster output support to // this filter function. +// + + +extern int cfFilterImageToRaster(int inputfd, + int outputfd, + int inputseekable, + cf_filter_data_t *data, + void *parameters); + +// +// 'cfFilterMuPDFToPWG()' - Convert PDF or XPS input to PWG Raster format using MuPDF. +// +// Requires specification of output format via data->final_content_type. +// +// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// +// Note: With CUPS Raster, Apple Raster, or PCLm selections the output +// is actually PWG Raster but information about available color spaces +// and depths is taken from the urf-supported printer IPP attribute, the +// pclm- attributes, or from a supplied CUPS Raster sample header +// (PCLM is always sGray/sRGB 8-bit). These modes are for further processing +// with pwgtoraster or pwgtopclm. This can change in the future when +// MuPDF adds further output formats. +// extern int cfFilterMuPDFToPWG(int inputfd, @@ -336,18 +426,13 @@ extern int cfFilterMuPDFToPWG(int inputfd, cf_filter_data_t *data, void *parameters); +// +// 'cfFilterPCLmToRaster()' - Convert PCLm input to raster format. +// // Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// Output formats: CUPS Raster, Apple Raster, PWG Raster // -// Note: With CUPS Raster, Apple Raster, or PCLm selections the output -// is actually PWG Raster but information about available color spaces -// and depths is taken from the urf-supported printer IPP attribute, -// the pclm- attributes, or from a supplied CUPS Raster sample header -// (PCLM is always sGray/sRGB 8-bit). These modes are for further -// processing with pwgtoraster or pwgtopclm. This can change in the -// future when MuPDF adds further output formats. - extern int cfFilterPCLmToRaster(int inputfd, int outputfd, @@ -355,9 +440,18 @@ extern int cfFilterPCLmToRaster(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, Apple Raster, or PWG Raster +// 'cfFilterPDFToPDF()' - Process PDF input and produce PDF output. +// +// (Optional) Specification of output format via +// data->final_content_type is used for determining whether this +// filter function does page logging for CUPS (output of "PAGE: XX YY" +// log messages) or not and also to determine whether the printer or +// driver generates copies or whether we have to send the pages +// repeatedly. +// Alternatively, the options "pdf-filter-page-logging", +// "hardware-copies", and "hardware-collate" can be used to manually do these selections. +// extern int cfFilterPDFToPDF(int inputfd, @@ -366,16 +460,17 @@ extern int cfFilterPDFToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// (Optional) Specification of output format via -// data->final_content_type is used for determining whether this -// filter function does page logging for CUPS (output of "PAGE: XX YY" -// log messages) or not and also to determine whether the printer or -// driver generates copies or whether we have to send the pages -// repeatedly. // -// Alternatively, the options "pdf-filter-page-logging", -// "hardware-copies", and "hardware-collate" can be used to manually -// do these selections. +// 'cfFilterPDFToRaster()' - Convert PDF input to raster format. +// +// Requires specification of output format via data->final_content_type +// +// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// +// Note: With PCLm selection the output is actually PWG Raster but color space and +// depth will be 8-bit sRGB or SGray, the only color spaces supported by PCLm. +// This mode is for further processing with pwgtopclm. +// extern int cfFilterPDFToRaster(int inputfd, @@ -384,15 +479,14 @@ extern int cfFilterPDFToRaster(int inputfd, cf_filter_data_t *data, void* parameters); +// +// 'cfFilterPWGToRaster()' - Convert PWG Raster input to raster format. +// // Requires specification of output format via data->final_content_type // -// Output formats: CUPS Raster, PWG Raster, Apple Raster, PCLm +// Output formats: CUPS Raster, Apple Raster, PWG Raster +// // -// Note: With PCLm selection the output is actually PWG Raster but -// color space and depth will be 8-bit sRGB or SGray, the only color -// spaces supported by PCLm. This mode is for further processing with -// pwgtopclm. - extern int cfFilterPWGToRaster(int inputfd, int outputfd, @@ -400,9 +494,14 @@ extern int cfFilterPWGToRaster(int inputfd, cf_filter_data_t *data, void *parameters); +// +// 'cfFilterPWGToPDF()' - Convert PWG Raster input to PDF format. +// // Requires specification of output format via data->final_content_type +// or alternatively as parameter of type cf_filter_out_format_t. // -// Output formats: CUPS Raster, PWG Raster, Apple Raster +// Output formats: PDF, PCLm +// extern int cfFilterPWGToPDF(int inputfd, @@ -411,11 +510,13 @@ extern int cfFilterPWGToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type -// or alternatively as parameter of type cf_filter_out_format_t. +// 'cfFilterRasterToPWG()' - Convert raster input to PWG Raster format. +// +// Requires specification of output format via data->final_content_type. +// +// Output formats: Apple Raster or PWG Raster, if PCLM is specified PWG +// Raster is produced to feed into the cfFilterPWGToPDF() filter function // -// Output formats: PDF, PCLm - extern int cfFilterRasterToPWG(int inputfd, int outputfd, @@ -423,12 +524,14 @@ extern int cfFilterRasterToPWG(int inputfd, cf_filter_data_t *data, void *parameters); -// Requires specification of output format via data->final_content_type // -// Output formats: Apple Raster or PWG Raster, if PCLM is specified -// PWG Raster is produced to feed into the cfFilterPWGToPDF() filter -// function. - +// 'cfFilterTextToPDF()' - Convert text input to PDF format. +// +// Parameters: cf_filter_texttopdf_parameter_t* +// +// Data directory (fonts, charsets), charset, content type (for prettyprint), +// classification (for overprint/watermark) +// extern int cfFilterTextToPDF(int inputfd, int outputfd, @@ -436,11 +539,9 @@ extern int cfFilterTextToPDF(int inputfd, cf_filter_data_t *data, void *parameters); -// Parameters: cf_filter_texttopdf_parameter_t* // -// Data directory (fonts, charsets), charset, content type (for prettyprint), -// classification (for overprint/watermark) - +// 'cfFilterTextToText()' - Process plain text input and produce plain text output. +// extern int cfFilterTextToText(int inputfd, int outputfd, @@ -448,27 +549,21 @@ extern int cfFilterTextToText(int inputfd, cf_filter_data_t *data, void *parameters); - // -// 'cfFilterUniversal()' - Automatically select and execute -// the appropriate filter conversion pipeline. +// 'cfFilterUniversal()' - Universal filter function for various conversions. // -// Determines the required data conversion based on the job's -// input content type (data->content_type) and the desired -// final output type (data->final_content_type). +// Requires specification of input format via data->content_type and +// job's final output format via data->final_content_type. // -// Parameters: -// inputfd - Input file descriptor. -// outputfd - Output file descriptor. -// inputseekable - Non-zero if input supports seeking. -// data - Job and printer data. -// parameters - Pointer to a -// cf_filter_universal_parameter_t structure -// providing additional conversion settings. +// Parameters: cf_filter_universal_parameter_t* // -// Returns 0 on success and non-zero on error. +// Contains: actual_output_type: Format which the filter should +// actually produce if different from job's final output +// format, otherwise NULL to produce the job's final output +// format +// texttopdf_params: parameters for texttopdf // - + extern int cfFilterUniversal(int inputfd, int outputfd, int inputseekable, @@ -476,7 +571,6 @@ extern int cfFilterUniversal(int inputfd, void *parameters); - # ifdef __cplusplus } # endif // __cplusplus diff --git a/cupsfilters/raster.h b/cupsfilters/raster.h index 314c670db..91470b932 100644 --- a/cupsfilters/raster.h +++ b/cupsfilters/raster.h @@ -45,6 +45,9 @@ extern "C" { #endif +// +// Prototypes... +// // // 'cfRasterColorSpaceString()' - Return a human-readable // name for the given raster color space. @@ -56,7 +59,7 @@ extern const char *cfRasterColorSpaceString(cups_cspace_t cspace); // 'cfRasterPrepareHeader()' - Prepare a CUPS/PWG raster page // header based on job and printer data. // -// Returns 0 on success and non-zero on error. +// Returns 0 on success, non-zero on error. // extern int cfRasterPrepareHeader(cups_page_header_t *h, @@ -73,7 +76,7 @@ extern int cfRasterPrepareHeader(cups_page_header_t *h, // appropriate color space and color depth based on printer // capabilities and job settings. // -// Returns 0 on success and -1 on error. +// Returns 0 on success, -1 on error. // extern int cfRasterSetColorSpace(cups_page_header_t *h,