diff --git a/cupsfilters/bannertopdf.c b/cupsfilters/bannertopdf.c index 60769e7b2..bac711fc4 100644 --- a/cupsfilters/bannertopdf.c +++ b/cupsfilters/bannertopdf.c @@ -28,34 +28,34 @@ #include #include - +// Banner information flags. typedef enum banner_info_e { - INFO_IMAGEABLE_AREA = 1, - INFO_JOB_BILLING = 1 << 1, - INFO_JOB_ID = 1 << 2, - INFO_JOB_NAME = 1 << 3, - INFO_JOB_ORIGINATING_HOST_NAME = 1 << 4, - INFO_JOB_ORIGINATING_USER_NAME = 1 << 5, - INFO_JOB_UUID = 1 << 6, - INFO_OPTIONS = 1 << 7, - INFO_PAPER_NAME = 1 << 8, - INFO_PAPER_SIZE = 1 << 9, - INFO_PRINTER_DRIVER_NAME = 1 << 10, - INFO_PRINTER_DRIVER_VERSION = 1 << 11, - INFO_PRINTER_INFO = 1 << 12, - INFO_PRINTER_LOCATION = 1 << 13, - INFO_PRINTER_MAKE_AND_MODEL = 1 << 14, - INFO_PRINTER_NAME = 1 << 15, - INFO_TIME_AT_CREATION = 1 << 16, - INFO_TIME_AT_PROCESSING = 1 << 17 + INFO_IMAGEABLE_AREA = 1, // I - Imageable area + INFO_JOB_BILLING = 1 << 1, // I - Job billing + INFO_JOB_ID = 1 << 2, // I - Job ID + INFO_JOB_NAME = 1 << 3, // I - Job name + INFO_JOB_ORIGINATING_HOST_NAME = 1 << 4, // I - Job originating host name + INFO_JOB_ORIGINATING_USER_NAME = 1 << 5, // I - Job originating user name + INFO_JOB_UUID = 1 << 6, // I - Job UUID + INFO_OPTIONS = 1 << 7, // I - Options + INFO_PAPER_NAME = 1 << 8, // I - Paper name + INFO_PAPER_SIZE = 1 << 9, // I - Paper size + INFO_PRINTER_DRIVER_NAME = 1 << 10, // I - Printer driver name + INFO_PRINTER_DRIVER_VERSION = 1 << 11, // I - Printer driver version + INFO_PRINTER_INFO = 1 << 12, // I - Printer info + INFO_PRINTER_LOCATION = 1 << 13, // I - Printer location + INFO_PRINTER_MAKE_AND_MODEL = 1 << 14, // I - Printer make and model + INFO_PRINTER_NAME = 1 << 15, // I - Printer name + INFO_TIME_AT_CREATION = 1 << 16, // I - Time at creation + INFO_TIME_AT_PROCESSING = 1 << 17 // I - Time at processing } banner_info_t; -typedef struct banner_s +typedef struct banner_s //*** Banner data structure *** { - char *template_file; - char *header, *footer; - unsigned infos; + char *template_file; // I - Template file path + char *header, *footer; // I - Header and footer text + unsigned infos; // I - Banner information flags } banner_t; static void @@ -883,14 +883,16 @@ generate_banner_pdf(banner_t *banner, return (0); } -int +// +// 'cfFilterBannerToPDF()' - Convert banner instructions to PDF. +// + +int // O - 0 on success, 1 on error cfFilterBannerToPDF(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - - // Template/Banner data directory + void *parameters) // I - Filter-specific parameters (Template/Banner data directory) { banner_t *banner; int num_options = 0; diff --git a/cupsfilters/bitmap.c b/cupsfilters/bitmap.c index 03fe7678b..26d9f1cd4 100644 --- a/cupsfilters/bitmap.c +++ b/cupsfilters/bitmap.c @@ -76,8 +76,7 @@ cfConvertBits(unsigned char *src, // I - Input string unsigned char *dst, // I - Destination string unsigned int x, // I - Column unsigned int y, // I - Row - unsigned int cupsNumColors,// I - Number of color components of - // output data + unsigned int cupsNumColors,// I - Number of color components of output data unsigned int bitspercolor) // I - Bitspercolor of output data { // assumed that max number of colors is 4 @@ -156,13 +155,12 @@ cfConvertBits(unsigned char *src, // I - Input string // color order. // -void // O - Exit status +void cfWritePixel(unsigned char *dst, // I - Destination string unsigned int plane, // I - Plane/Band unsigned int pixeli, // I - Pixel unsigned char *pixelBuf, // I - Input string - unsigned int cupsNumColors,// I - Number of color components of - // output data + unsigned int cupsNumColors,// I - Number of color components of output data unsigned int bitspercolor, // I - Bitspercolor of output data cups_order_t colororder) // I - Color Order of output data { @@ -395,7 +393,7 @@ cfReverseOneBitLineSwap(unsigned char *src, // I - Input line // raster data using ordered dithering. // -void // O - Output line +void cfOneBitLine(unsigned char *src, // I - Input line unsigned char *dst, // O - Destination line unsigned int width, // I - Width of raster image in pixels @@ -434,11 +432,10 @@ cfOneBitLine(unsigned char *src, // I - Input line // 8-bit raster data. // -void // O - Output line +void cfOneBitToGrayLine(unsigned char *src, // I - Input line unsigned char *dst, // O - Destination line - unsigned int width) // I - Width of raster image in - // pixels + unsigned int width) // I - Width of raster image in pixels { unsigned char mask = 0x80; for (unsigned int w = 0; w < width; w += 1) @@ -460,11 +457,11 @@ cfOneBitToGrayLine(unsigned char *src, // I - Input line // raster data. // -unsigned char -*cfRGB8toKCMYcm(unsigned char *src, - unsigned char *dst, - unsigned int x, - unsigned int y) +unsigned char // O - Output pixel +*cfRGB8toKCMYcm(unsigned char *src, // I - Input pixel (RGB) + unsigned char *dst, // I - Destination pixel (KCMYcm) + unsigned int x, // I - Column + unsigned int y) // I - Row { unsigned char cmyk[4]; unsigned char c; diff --git a/cupsfilters/catalog.c b/cupsfilters/catalog.c index b45e5abeb..eafca50de 100644 --- a/cupsfilters/catalog.c +++ b/cupsfilters/catalog.c @@ -25,12 +25,14 @@ #include #include +// +// 'cfGetURI()' - Get a file from the given URI and save it to a temporary file. +// -int // O - 1 on success, 0 on failure -cfGetURI(const char *url, // I - URL to get - char *name, // I - Temporary filename - size_t namesize) // I - Size of temporary filename - // buffer +int // O - 1 on success, 0 on failure +cfGetURI(const char *url, // I - URL to get + char *name, // I - Temporary filename + size_t namesize) // I - Size of temporary filename buffer { http_t *http = NULL; char scheme[32], // URL scheme @@ -76,15 +78,14 @@ cfGetURI(const char *url, // I - URL to get return (1); } - // -// 'cfCatalogFind()' - Find a CUPS message catalog file containing -// human-readable standard option and choice names -// for IPP printers +// 'cfCatalogSearchDirLocale()' - Search a directory for a CUPS message catalog file +// matching the given locale. // -char * -cfCatalogSearchDirLocale(const char *dirname, const char *locale) +char * // O - Catalog file path, or NULL if not found +cfCatalogSearchDirLocale(const char *dirname, // I - Directory name + const char *locale) // I - Locale name { char *catalog = NULL; char catalogpath[2048]; @@ -101,8 +102,14 @@ cfCatalogSearchDirLocale(const char *dirname, const char *locale) return (catalog); } -char * -cfCatalogSearchDirLang(const char *dirname, const char *lang) +// +// 'cfCatalogSearchDirLang()' - Search a directory for a CUPS message catalog file +// matching the given language. +// + +char * // O - Catalog file path, or NULL if not found +cfCatalogSearchDirLang(const char *dirname, // I - Directory name + const char *lang) // I - Language name { size_t lang_len; const char *c1, *c2; @@ -161,8 +168,13 @@ cfCatalogSearchDirLang(const char *dirname, const char *lang) return (catalog); } -char * -cfCatalogSearchDir(const char *dirname, const char *preferredlocale) +// +// 'cfCatalogSearchDir()' - Search a directory for a CUPS message catalog file matching +// the preferred locale. + +char * // O - Catalog file path, or NULL if not found +cfCatalogSearchDir(const char *dirname, // I - Directory name + const char *preferredlocale) // I - Preferred locale name { const char *c1, *c2; char *catalog = NULL; @@ -268,9 +280,15 @@ cfCatalogSearchDir(const char *dirname, const char *preferredlocale) return (catalog); } +// +// 'cfCatalogFind()' - Find a CUPS message catalog file containing +// human-readable standard option and choice names +// for IPP printers. +// -char * -cfCatalogFind(const char *preferreddir, const char *preferredlocale) +char * // O - Catalog file path, or NULL if not found +cfCatalogFind(const char *preferreddir, // I - Preferred directory + const char *preferredlocale) // I - Preferred locale name { const char *c; char buf[1024]; @@ -332,10 +350,14 @@ compare_options(void *a, ((catalog_opt_strings_t *)b)->name)); } +// +// 'cfCatalogFreeChoiceStrings()' - Free a choice strings entry containing the +// localized human-readable choice name. +// void -cfCatalogFreeChoiceStrings(void* entry, - void* user_data) +cfCatalogFreeChoiceStrings(void* entry, // I - Choice strings entry + void* user_data) // I - User data (unused) { catalog_choice_strings_t *entry_rec = (catalog_choice_strings_t *)entry; @@ -347,10 +369,14 @@ cfCatalogFreeChoiceStrings(void* entry, } } +// +// 'cfCatalogFreeOptionStrings()' - Free memory allocated for an option strings +// entry in the catalog. +// void -cfCatalogFreeOptionStrings(void* entry, - void* user_data) +cfCatalogFreeOptionStrings(void* entry, // I - Option strings entry + void* user_data) // I - User data (unused) { catalog_opt_strings_t *entry_rec = (catalog_opt_strings_t *)entry; @@ -363,18 +389,24 @@ cfCatalogFreeOptionStrings(void* entry, } } +// +// 'cfCatalogOptionArrayNew()' - Create a new array to store catalog option string entries. +// -cups_array_t * +cups_array_t * // O - New array cfCatalogOptionArrayNew() { return (cupsArrayNew(compare_options, NULL, NULL, 0, NULL, cfCatalogFreeOptionStrings)); } +// +// 'cfCatalogFindOption()' - Find a catalog option strings entry by name. +// -catalog_opt_strings_t * -cfCatalogFindOption(cups_array_t *options, - char *name) +catalog_opt_strings_t * // O - Option strings entry, or NULL if not found +cfCatalogFindOption(cups_array_t *options, // I - Catalog choice array + char *name) // I - Option name { catalog_opt_strings_t opt; @@ -385,10 +417,13 @@ cfCatalogFindOption(cups_array_t *options, return (cupsArrayFind(options, &opt)); } +// +// 'cfCatalogFindChoice()' - Find a catalog choice strings entry by name. +// -catalog_choice_strings_t * -cfCatalogFindChoice(cups_array_t *choices, - char *name) +catalog_choice_strings_t * // O - Choice strings entry, or NULL if not found +cfCatalogFindChoice(cups_array_t *choices, // I - Catalog choice array + char *name) // I - Choice name { catalog_choice_strings_t choice; @@ -399,11 +434,14 @@ cfCatalogFindChoice(cups_array_t *choices, return (cupsArrayFind(choices, &choice)); } +// +// 'cfCatalogAddOption()' - Add a catalog option strings entry to the options array. +// -catalog_opt_strings_t * -cfCatalogAddOption(char *name, - char *human_readable, - cups_array_t *options) +catalog_opt_strings_t * // O - Option strings entry +cfCatalogAddOption(char *name, // I - Option name + char *human_readable, // I - Human-readable option text + cups_array_t *options) // I - Catalog option array { catalog_opt_strings_t *opt = NULL; @@ -437,12 +475,15 @@ cfCatalogAddOption(char *name, return (opt); } +// +// 'cfCatalogAddChoice()' - Add a catalog choice strings entry to the option's choices array. +// -catalog_choice_strings_t * -cfCatalogAddChoice(char *name, - char *human_readable, - char *opt_name, - cups_array_t *options) +catalog_choice_strings_t * // O - Catalog choice entry +cfCatalogAddChoice(char *name, // I - Choice name + char *human_readable, // I - Human-readable choice text + char *opt_name, // I - Parent option name + cups_array_t *options) // I - Catalog option array { catalog_choice_strings_t *choice = NULL; catalog_opt_strings_t *opt; @@ -474,12 +515,14 @@ cfCatalogAddChoice(char *name, return (choice); } +// +// 'cfCatalogLookUpOption()' - Look up the human-readable text for a catalog option. +// - -char * -cfCatalogLookUpOption(char *name, - cups_array_t *options, - cups_array_t *printer_options) +char * // O - Human-readable option text or NULL +cfCatalogLookUpOption(char *name, // I - Option name + cups_array_t *options, // I - Catalog option array + cups_array_t *printer_options) // I - Printer-specific option array { catalog_opt_strings_t *opt = NULL; @@ -495,12 +538,15 @@ cfCatalogLookUpOption(char *name, return (NULL); } +// +// 'cfCatalogLookUpChoice()' - Look up the human-readable text for a catalog choice. +// -char * -cfCatalogLookUpChoice(char *name, - char *opt_name, - cups_array_t *options, - cups_array_t *printer_options) +char * // O - Human-readable choice text or NULL +cfCatalogLookUpChoice(char *name, // I - Choice name + char *opt_name, // I - Parent option name + cups_array_t *options, // I - Catalog option array + cups_array_t *printer_options) // I - Printer-specific option array { catalog_opt_strings_t *opt = NULL; catalog_choice_strings_t *choice = NULL; @@ -519,11 +565,14 @@ cfCatalogLookUpChoice(char *name, return (NULL); } +// +// 'cfCatalogLoad()' - Load a catalog file. +// void -cfCatalogLoad(const char *location, - const char *preferredlocale, - cups_array_t *options) +cfCatalogLoad(const char *location, // I - Catalog file location (path or URL) + const char *preferredlocale, // I - Preferred locale name + cups_array_t *options) // I - Catalog option array { char tmpfile[1024]; const char *filename = NULL; diff --git a/cupsfilters/catalog.h b/cupsfilters/catalog.h index 90a886a2d..62ae6ed62 100644 --- a/cupsfilters/catalog.h +++ b/cupsfilters/catalog.h @@ -73,15 +73,15 @@ extern "C" { // Data structure for IPP choice name and human-readable string typedef struct catalog_choice_strings_s { - char *name, - *human_readable; + char *name, // I - IPP choice name + *human_readable; // I - Human-readable string } catalog_choice_strings_t; // Data structure for IPP option name, human-readable string, and choice list typedef struct catalog_opt_strings_s { - char *name, - *human_readable; - cups_array_t *choices; + char *name, // I - IPP option name + *human_readable; // I - Human-readable string + cups_array_t *choices; // I - Array of choices for this option } catalog_opt_strings_t; diff --git a/cupsfilters/cmyk.c b/cupsfilters/cmyk.c index f9da7ecd3..c16ef0278 100644 --- a/cupsfilters/cmyk.c +++ b/cupsfilters/cmyk.c @@ -61,14 +61,10 @@ cfCMYKDelete(cf_cmyk_t *cmyk) // I - Color separation // void -cfCMYKDoBlack(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoBlack(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int k; // Current black value const short **channels; // Copy of channel LUTs @@ -244,14 +240,10 @@ cfCMYKDoBlack(const cf_cmyk_t *cmyk, // void -cfCMYKDoCMYK(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoCMYK(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int c, // Current cyan value m, // Current magenta value @@ -516,14 +508,10 @@ cfCMYKDoCMYK(const cf_cmyk_t *cmyk, // void -cfCMYKDoGray(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoGray(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int k, // Current black value kc; // Current black color value @@ -743,14 +731,10 @@ cfCMYKDoGray(const cf_cmyk_t *cmyk, // void -cfCMYKDoRGB(const cf_cmyk_t *cmyk, - // I - Color separation - const unsigned char *input, - // I - Input grayscale pixels - short *output, - // O - Output Device-N pixels - int num_pixels) - // I - Number of pixels +cfCMYKDoRGB(const cf_cmyk_t *cmyk, // I - Color separation + const unsigned char *input, // I - Input grayscale pixels + short *output, // O - Output Device-N pixels + int num_pixels) // I - Number of pixels { int c, // Current cyan value m, // Current magenta value @@ -1188,8 +1172,7 @@ cfCMYKSetBlack(cf_cmyk_t *cmyk, // I - CMYK color separation void cfCMYKSetCurve(cf_cmyk_t *cmyk, // I - CMYK color separation int channel, // I - Color channel - int num_xypoints, - // I - Number of X,Y points + int num_xypoints, // I - Number of X,Y points const float *xypoints, // I - X,Y points cf_logfunc_t log, // I - Log function void *ld) // I - Log function data diff --git a/cupsfilters/colord.c b/cupsfilters/colord.c index cca1ac57d..14cc28f57 100644 --- a/cupsfilters/colord.c +++ b/cupsfilters/colord.c @@ -24,12 +24,17 @@ #define QUAL_RESOLUTION 2 #define QUAL_SIZE 3 -char ** -cfColordGetQualifier(cf_filter_data_t *data, - const char *color_space, - const char *media_type, - int x_res, - int y_res) +// +// 'cfColordGetQualifier()' - Get the qualifier strings for the specified color space, +// media type, and resolution. +// + +char ** // O - Qualifier strings +cfColordGetQualifier(cf_filter_data_t *data, // I - Filter data + const char *color_space, // I - Color space + const char *media_type, // I - Media type + int x_res, // I - Horizontal resolution + int y_res) // I - Vertical resolution { int i, len; const char *val; @@ -311,10 +316,15 @@ get_device_path_for_device_id(cf_filter_data_t *data, return (device_path); } -char * -cfColordGetProfileForDeviceID(cf_filter_data_t *data, - const char *device_id, - const char **qualifier_tuple) +// +// 'cfColordGetProfileForDeviceID()' - Get the color profile for the specified +// device ID and qualifier tuple. +// + +char * // O - Profile filename +cfColordGetProfileForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id, // I - Device ID + const char **qualifier_tuple) // I - Qualifier tuple { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -438,9 +448,14 @@ get_profile_inhibitors(cf_filter_data_t *data, return (inhibitors); } -int -cfColordGetInhibitForDeviceID(cf_filter_data_t *data, - const char *device_id) +// +// 'cfColordGetInhibitForDeviceID()' - Get the number of inhibitors for the specified +// device ID. +// + +int // O - Non-zero if inhibited, 0 otherwise +cfColordGetInhibitForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id) // I - Device ID { cf_logfunc_t log = data->logfunc; void* ld = data->logdata; @@ -478,10 +493,15 @@ cfColordGetInhibitForDeviceID(cf_filter_data_t *data, #else -char * -cfColordGetProfileForDeviceID(cf_filter_data_t *data, - const char *device_id, - const char **qualifier_tuple) +// +// 'cfColordGetQualifier()' - Get the qualifier strings for the specified color space, +// media type, and resolution. +// + +char * // O - Qualifier strings +cfColordGetProfileForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id, // I - Device ID + const char **qualifier_tuple) // I - Qualifier tuple { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -490,9 +510,14 @@ cfColordGetProfileForDeviceID(cf_filter_data_t *data, return (NULL); } -int -cfColordGetInhibitForDeviceID(cf_filter_data_t *data, - const char *device_id) +// +// 'cfColordGetInhibitForDeviceID()' - Get the number of inhibitors for the specified +// device ID. +// + +int // O - Non-zero if inhibited, 0 otherwise +cfColordGetInhibitForDeviceID(cf_filter_data_t *data, // I - Filter data + const char *device_id) // I - Device ID { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; diff --git a/cupsfilters/colormanager.c b/cupsfilters/colormanager.c index f25788c68..aa482af7d 100644 --- a/cupsfilters/colormanager.c +++ b/cupsfilters/colormanager.c @@ -33,15 +33,11 @@ double blackpoint_default[3] = {0.0, 0.0, 0.0}; // -// Public functions +// 'cfCmIsPrinterCmDisabled()' - Check if color management is disabled for the printer. // -// -// Get printer color management status from the system's color manager -// - -int -cfCmIsPrinterCmDisabled(cf_filter_data_t *data) +int // O - Non-zero if disabled, 0 otherwise +cfCmIsPrinterCmDisabled(cf_filter_data_t *data) // I - Filter data { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -72,16 +68,16 @@ cfCmIsPrinterCmDisabled(cf_filter_data_t *data) // -// Get printer ICC profile from the system's color manager +// 'cfCmGetPrinterIccProfile()' - Get the ICC profile for the printer from colord or fallback option. // -int -cfCmGetPrinterIccProfile(cf_filter_data_t *data, - const char *color_space, - const char *media_type, - int x_res, - int y_res, - char **profile) // ICC Profile Path +int // O - Non-zero if profile found, 0 otherwise +cfCmGetPrinterIccProfile(cf_filter_data_t *data, // I - Filter data + const char *color_space, // I - Color space string + const char *media_type, // I - Media type string + int x_res, // I - X resolution + int y_res, // I - Y resolution + char **profile) // I - ICC profile path string { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; @@ -152,11 +148,11 @@ cfCmGetPrinterIccProfile(cf_filter_data_t *data, // -// Find the "cm-calibration" CUPS option +// 'cfCmGetCupsColorCalibrateMode()' - Get the color calibration mode from CUPS options. // -cf_cm_calibration_t -cfCmGetCupsColorCalibrateMode(cf_filter_data_t *data) +cf_cm_calibration_t // O - Color calibration mode +cfCmGetCupsColorCalibrateMode(cf_filter_data_t *data) // I - Filter data { int num_options = 0; cups_option_t *options = NULL; @@ -184,46 +180,61 @@ cfCmGetCupsColorCalibrateMode(cf_filter_data_t *data) // -// Accessor functions to return specific calibration data +// 'cfCmGammaAdobeRGB()' - Get the gamma value for Adobe RGB. // -// Gamma values - -double *cfCmGammaAdobeRGB(void) +double // O - Gamma value + *cfCmGammaAdobeRGB(void) { return (adobergb_gamma); } -double *cfCmGammaSGray(void) +// +// 'cfCmGammaSGray()' - Get the gamma value for sGray. +// + +double // O - Gamma value +*cfCmGammaSGray(void) { return (sgray_gamma); } +// +// 'cfCmWhitePointAdobeRGB()' - Get the whitepoint value for Adobe RGB. +// -// Whitepoint values - -double *cfCmWhitePointAdobeRGB(void) +double // O - Whitepoint value + *cfCmWhitePointAdobeRGB(void) { return (adobergb_wp); } -double *cfCmWhitePointSGray(void) +// +// 'cfCmWhitePointSGray()' - Get the whitepoint value for sGray. +// + +double // O - Whitepoint value + *cfCmWhitePointSGray(void) { return (sgray_wp); } +// +// 'cfCmMatrixAdobeRGB()' - Get the adapted primaries matrix for Adobe RGB. +// -// Adapted primaries matrix - -double *cfCmMatrixAdobeRGB(void) +double // O - Adapted primaries matrix +*cfCmMatrixAdobeRGB(void) { return (adobergb_matrix); } +// +// 'cfCmBlackPointDefault()' - Get the default blackpoint value. +// -// Blackpoint value - -double *cfCmBlackPointDefault(void) +double // O - Blackpoint value +*cfCmBlackPointDefault(void) { return (blackpoint_default); } diff --git a/cupsfilters/colormanager.h b/cupsfilters/colormanager.h index 2d0e9b5e0..daed09618 100644 --- a/cupsfilters/colormanager.h +++ b/cupsfilters/colormanager.h @@ -21,15 +21,13 @@ extern "C" { #include -#define CF_CM_CALIBRATION_STRING "cm-calibration" // String for "Color - // Calibration Mode" +#define CF_CM_CALIBRATION_STRING "cm-calibration" // String for "Color Calibration Mode" // Enum for status of CUPS color calibration typedef enum cf_cm_calibration_e { - CF_CM_CALIBRATION_DISABLED = 0, // "cm-calibration" option - // not found + CF_CM_CALIBRATION_DISABLED = 0, // "cm-calibration" option not found CF_CM_CALIBRATION_ENABLED = 1 // "cm-calibration" found } cf_cm_calibration_t; diff --git a/cupsfilters/dither.c b/cupsfilters/dither.c index 018fe21bb..2ee4b51eb 100644 --- a/cupsfilters/dither.c +++ b/cupsfilters/dither.c @@ -25,8 +25,6 @@ // // 'cfDitherDelete()' - Free a dithering buffer. // -// Returns 0 on success, -1 on failure. -// void cfDitherDelete(cf_dither_t *d) // I - Dithering buffer @@ -41,12 +39,11 @@ cfDitherDelete(cf_dither_t *d) // I - Dithering buffer // void -cfDitherLine(cf_dither_t *d, // I - Dither data - const cf_lut_t *lut, // I - Lookup table - const short *data, // I - Separation data - int num_channels, - // I - Number of components - unsigned char *p) // O - Pixels +cfDitherLine(cf_dither_t *d, // I - Dither data + const cf_lut_t *lut, // I - Lookup table + const short *data, // I - Separation data + int num_channels, // I - Number of components + unsigned char *p) // O - Pixels { register int x, // Horizontal position in line... pixel, // Current adjusted pixel... diff --git a/cupsfilters/driver.h b/cupsfilters/driver.h index 40e5d2716..ca5744278 100644 --- a/cupsfilters/driver.h +++ b/cupsfilters/driver.h @@ -86,10 +86,8 @@ typedef struct cf_rgb_s // *** Color separation lookup table *** int cube_size; // Size of color cube (2-N) on a side int num_channels; // Number of colors per sample unsigned char ****colors; // 4-D array of sample values - int cube_index[256]; // Index into cube for a given sRGB - // value - int cube_mult[256]; // Multiplier value for a given sRGB - // value + int cube_index[256]; // Index into cube for a given sRGB value + int cube_mult[256]; // Multiplier value for a given sRGB value int cache_init; // Are cached values initialized? unsigned char black[CF_MAX_RGB]; // Cached black (sRGB = 0,0,0) unsigned char white[CF_MAX_RGB]; // Cached white (sRGB = 255,255,255) diff --git a/cupsfilters/filter.c b/cupsfilters/filter.c index c1d5545d1..6262928d6 100644 --- a/cupsfilters/filter.c +++ b/cupsfilters/filter.c @@ -69,14 +69,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, - ...) +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; @@ -117,8 +117,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); } @@ -143,17 +143,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; @@ -187,9 +184,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; @@ -203,9 +204,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; @@ -232,16 +237,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; @@ -258,17 +260,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, @@ -316,28 +314,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 @@ -396,12 +381,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 @@ -542,13 +526,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 @@ -610,12 +594,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? @@ -955,16 +939,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? @@ -1603,24 +1583,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; @@ -1699,14 +1669,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 c9a66923f..da17d8c6e 100644 --- a/cupsfilters/filter.h +++ b/cupsfilters/filter.h @@ -52,50 +52,40 @@ extern "C" { typedef int (*cf_filter_iscanceledfunc_t)(void *data); -typedef struct cf_filter_data_s +typedef struct cf_filter_data_s // *** Data structure for filter functions *** { char *printer; // Print queue name or NULL int job_id; // Job ID or 0 char *job_user; // Job user or NULL char *job_title; // Job title or NULL - int copies; // Number of copies - // (1 if filter(s) should not treat it) - char *content_type; // Input MIME type (CUPS env variable - // CONTENT_TYPE) or NULL - char *final_content_type; // Output MIME type (CUPS env variable - // FINAL_CONTENT_TYPE) or NULL + int copies; // Number of copies (1 if filter(s) should not treat it) + char *content_type; // Input MIME type (CUPS env variable CONTENT_TYPE) or NULL + char *final_content_type; // Output MIME type (CUPS env variable FINAL_CONTENT_TYPE) or NULL ipp_t *job_attrs; // IPP attributes passed along with the job - ipp_t *printer_attrs; // Printer capabilities in IPP format - // (what is answered to get-printer-attributes - cups_page_header_t *header; - // CUPS/PWG Raster header (optional) - int num_options; + ipp_t *printer_attrs; // Printer capabilities in IPP format (what is answered to get-printer-attributes) + cups_page_header_t *header; // CUPS/PWG Raster header (optional) + int num_options; // Number of job options cups_option_t *options; // Job options as key/value pairs int back_pipe[2]; // File descriptors of backchannel pipe int side_pipe[2]; // File descriptors of sidechannel pipe cups_array_t *extension; // Extension data cf_logfunc_t logfunc; // Logging function, NULL for no logging void *logdata; // User data for logging function, can be NULL - cf_filter_iscanceledfunc_t iscanceledfunc; - // Function returning 1 when job is - // canceled, NULL for not supporting stop - // on cancel - void *iscanceleddata; // User data for is-canceled function, can be - // NULL + cf_filter_iscanceledfunc_t iscanceledfunc; // Function returning 1 when job is canceled, NULL for not supporting stop on cancel + void *iscanceleddata; // User data for is-canceled function, can be NULL } cf_filter_data_t; -typedef struct cf_filter_data_ext_s +typedef struct cf_filter_data_ext_s // *** Extension data for cf_filter_data_t *** { - char *name; - void *ext; + char *name; // Name of the extension data + void *ext; // Pointer to the extension data } cf_filter_data_ext_t; typedef int (*cf_filter_function_t)(int inputfd, int outputfd, int inputseekable, cf_filter_data_t *data, void *parameters); -typedef enum cf_filter_out_format_e // Possible output formats for filter - // functions +typedef enum cf_filter_out_format_e // *** Possible output formats for filter functions *** { CF_FILTER_OUT_FORMAT_PDF, // PDF CF_FILTER_OUT_FORMAT_PDF_IMAGE, // Raster-only PDF @@ -106,53 +96,35 @@ typedef enum cf_filter_out_format_e // Possible output formats for filter CF_FILTER_OUT_FORMAT_PXL // PCL-XL } cf_filter_out_format_t; -typedef struct cf_filter_filter_in_chain_s // filter entry for CUPS array to - // be supplied to cfFilterChain() - // filter function +typedef struct cf_filter_filter_in_chain_s // *** Filter entry for CUPS array to be supplied to cfFilterChain() filter function *** { cf_filter_function_t function; // Filter function to be called void *parameters; // Parameters for this filter function call char *name; // Name/comment, only for logging } cf_filter_filter_in_chain_t; -typedef struct cf_filter_external_s // Parameters for the - // cfFilterExternal() filter - // function +typedef struct cf_filter_external_s // *** Parameters for the cfFilterExternal() filter function *** { - const char *filter; // Path/Name of the CUPS filter to be called by - // this filter function, required - int exec_mode; // 0 if we call a CUPS filter, -1 if we call - // a System V interface script, 1 if we call a CUPS - // backend, 2 if we call a CUPS backend in - // device discovery mode + const char *filter; // Path/Name of the CUPS filter to be called by this filter function, required + int exec_mode; // 0 if we call a CUPS filter, -1 if we call a System V interface script, 1 if we call a CUPS backend, 2 if we call a CUPS backend in device discovery mode int num_options; // Extra options for the 5th command line - cups_option_t *options; // argument, options of filter_data have - // priority, 0/NULL if none - char **envp; // Additional environment variables, the already - // defined ones stay valid but can be overwritten - // by these ones, NULL if none + cups_option_t *options; // argument, options of filter_data have priority, 0/NULL if none + char **envp; // Additional environment variables, the already defined ones stay valid but can be overwritten by these ones, NULL if none } cf_filter_external_t; -typedef struct cf_filter_texttopdf_parameter_s // parameters container of - // environemnt variables needed - // by texttopdf filter - // function +typedef struct cf_filter_texttopdf_parameter_s // *** parameters container of environemnt variables needed by texttopdf filter function *** { - char *data_dir; - char *char_set; - char *content_type; - char *classification; + char *data_dir; // Data directory to be used for fonts and charsets, or NULL for default + char *char_set; // Charset to be used for prettyprint, or NULL for default + char *content_type; // Content type to be used for prettyprint, or NULL for default + char *classification; // Classification to be used for overprint/watermark, or NULL for default } cf_filter_texttopdf_parameter_t; -typedef struct cf_filter_universal_parameter_s // Contains input and output - // type to be supplied to the - // universal function, and also - // parameters for - // cfFilterTextToPDF() +typedef struct cf_filter_universal_parameter_s // *** Contains input and output type to be supplied to the universal function, and also parameters for cfFilterTextToPDF() *** { - char *actual_output_type; - cf_filter_texttopdf_parameter_t texttopdf_params; - const char *bannertopdf_template_dir; + char *actual_output_type; // Output MIME type + cf_filter_texttopdf_parameter_t texttopdf_params; // Parameters for cfFilterTextToPDF() filter function + const char *bannertopdf_template_dir; // Template directory for cfFilterBannerToPDF() filter function } cf_filter_universal_parameter_t; @@ -455,4 +427,4 @@ extern int cfFilterUniversal(int inputfd, } # endif // __cplusplus -#endif // !_CUPS_FILTERS_FILTER_H_ +#endif // !_CUPS_FILTERS_FILTER_H_ \ No newline at end of file diff --git a/cupsfilters/ghostscript.c b/cupsfilters/ghostscript.c index 9e8fa8fa4..9cbe9fc3a 100644 --- a/cupsfilters/ghostscript.c +++ b/cupsfilters/ghostscript.c @@ -34,25 +34,27 @@ #define PDF_MAX_CHECK_COMMENT_LINES 20 +// Ghostscript document type. typedef enum gs_doc_e { - GS_DOC_TYPE_PDF, - GS_DOC_TYPE_PS, - GS_DOC_TYPE_EMPTY, - GS_DOC_TYPE_UNKNOWN + GS_DOC_TYPE_PDF, // PDF document + GS_DOC_TYPE_PS, // PostScript document + GS_DOC_TYPE_EMPTY, // Empty document + GS_DOC_TYPE_UNKNOWN // Unknown document type } gs_doc_t; typedef cups_page_header_t gs_page_header; +// Ghostscript halftone type. typedef enum cups_halftone_type_e { - HALFTONE_DEFAULT, - HALFTONE_STOCHASTIC, - HALFTONE_FOO2ZJS, - HALFTONE_BI_LEVEL, - HALFTONE_DITHERING, - HALFTONE_GENORDERED, - HALFTONE_SPOT + HALFTONE_DEFAULT, // Default halftone type + HALFTONE_STOCHASTIC, // Stochastic halftone type + HALFTONE_FOO2ZJS, // foo2zjs halftone type + HALFTONE_BI_LEVEL, // Bi-level halftone type + HALFTONE_DITHERING, // Dithering halftone type + HALFTONE_GENORDERED, // Generalized ordered halftone type + HALFTONE_SPOT, // Spot halftone type } cups_halftone_type_t; static const char *ht_spot_functions[] = @@ -831,10 +833,8 @@ gs_spawn (const char *filename, // int // O - Error status -cfFilterGhostscript(int inputfd, // I - File descriptor input - // stream - int outputfd, // I - File descriptor output - // stream +cfFilterGhostscript(int inputfd, // I - File descriptor input stream + int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? cf_filter_data_t *data, // I - Job and printer data void *parameters) // I - Filter-specific parameters diff --git a/cupsfilters/ieee1284.c b/cupsfilters/ieee1284.c index 95d580d4b..069fc94dc 100644 --- a/cupsfilters/ieee1284.c +++ b/cupsfilters/ieee1284.c @@ -634,44 +634,49 @@ move_right_part( // to produce a clean make-and-model string we can use. // -char * // O - Normalized make-and-model string - // or NULL on error +char * // O - Normalized make-and-model string or NULL on error cfIEEE1284NormalizeMakeModel( - const char *make_and_model, // I - Original make-and-model string - // or device ID - const char *make, // I - Manufacturer name as hint for - // correct separation of - // make_and_model or adding - // make, or pointer into input - // string where model name starts - // or NULL, - // ignored on device ID with "MFG" - // field or for NO_MAKE_MODEL - cf_ieee1284_normalize_modes_t mode, // I - Bit field to describe how to - // normalize - regex_t *extra_regex, // I - Compiled regex to determine - // where the extra info after - // the driver name starts, also - // mark with parentheses which - // sub string should be the - // driver name - char *buffer, // O - String buffer, to hold the - // normalized input string, plus, - // after the terminating zero, the - // driver name if an appropriate - // extra_regex is supplied - // (*drvname will point to it) + const char *make_and_model, // I - Original make-and-model string or device ID + const char *make, /* + * I - Manufacturer name as hint for correct separation of + * make_and_model or adding + * make, or pointer into input + * string where model name starts + * or NULL, + * ignored on device ID with "MFG" + * field or for NO_MAKE_MODEL + */ + cf_ieee1284_normalize_modes_t mode, // I - Bit field to describe how to normalize + regex_t *extra_regex, /* + * I - Compiled regex to determine + * where the extra info after + * the driver name starts, also + * mark with parentheses which + * sub string should be the + * driver name + */ + char *buffer, /* + * O - String buffer, to hold the + * normalized input string, plus, + * after the terminating zero, the + * driver name if an appropriate + * extra_regex is supplied + * (*drvname will point to it) + */ size_t bufsize, // O - Size of string buffer - char **model, // O - Pointer to where model name - // starts in buffer or NULL - char **extra, // O - Pointer to where extra info - // starts in buffer (after comma, - // semicolon, parenthese, or - // start of extra_regex - // match) or NULL - char **drvname) // O - Driver name, string of the first - // matching parenthese expression - // in the extra_regex + char **model, // O - Pointer to where model name starts in buffer or NULL + char **extra, /* + * O - Pointer to where extra info + * starts in buffer (after comma, + * semicolon, parenthese, or + * start of extra_regex + * match) or NULL + */ + char **drvname) /* + * O - Driver name, string of the first + * matching parenthese expression + * in the extra_regex + */ { int i; char *bufptr; // Pointer into buffer diff --git a/cupsfilters/ieee1284.h b/cupsfilters/ieee1284.h index a87521106..c321f50b6 100644 --- a/cupsfilters/ieee1284.h +++ b/cupsfilters/ieee1284.h @@ -60,41 +60,43 @@ extern "C" { // Bit field to describe how to normalize make/model/device ID strings enum cf_ieee1284_normalize_modes_e { - CF_IEEE1284_NORMALIZE_COMPARE = 0x01, // Optimized for comparing, - // replacing any sequence of - // non-alpha-numeric characters - // by a single separator char, - // at any letter-number boundary - // and any camel-case boundary - // add a single separator char, - // 2 separator chars between - // make/model/extra, - // make all letters lowercase (or - // uppercase) - CF_IEEE1284_NORMALIZE_IPP = 0x02, // Only chars allowed in - // IPP keywords - CF_IEEE1284_NORMALIZE_ENV = 0x04, // Environment variable format - // upparcase and underscore - CF_IEEE1284_NORMALIZE_HUMAN = 0x08, // Human-readable, conserves - // spaces and special characters - // but does some clean-up + CF_IEEE1284_NORMALIZE_COMPARE = 0x01, /* + * Optimized for comparing, + * replacing any sequence of + * non-alpha-numeric characters + * by a single separator char, + * at any letter-number boundary + * and any camel-case boundary + * add a single separator char, + * 2 separator chars between + * make/model/extra, + * make all letters lowercase (or uppercase) + */ + CF_IEEE1284_NORMALIZE_IPP = 0x02, // Only chars allowed in IPP keywords + CF_IEEE1284_NORMALIZE_ENV = 0x04, // Environment variable format upparcase and underscore + CF_IEEE1284_NORMALIZE_HUMAN = 0x08, /* + * Human-readable, conserves + * spaces and special characters + * but does some clean-up + */ CF_IEEE1284_NORMALIZE_LOWERCASE = 0x10, // All letters lowercase CF_IEEE1284_NORMALIZE_UPPERCASE = 0x20, // All letters uppercase CF_IEEE1284_NORMALIZE_SEPARATOR_SPACE = 0x40,// Separator char is ' ' CF_IEEE1284_NORMALIZE_SEPARATOR_DASH = 0x80, // Separator char is '-' CF_IEEE1284_NORMALIZE_SEPARATOR_UNDERSCORE = 0x100,// Separator char is '_' - CF_IEEE1284_NORMALIZE_PAD_NUMBERS = 0x200, // Zero-pad numbers in strings - // to get better list sorting - // results - CF_IEEE1284_NORMALIZE_SEPARATE_COMPONENTS = 0x400,// In the output buffer put - // '\0' bytes between make, - // model, and extra, to use - // as separate strings - CF_IEEE1284_NORMALIZE_NO_MAKE_MODEL = 0x800, // No make/model/extra separation, - // do not try to identify, add, - // or clean up manufacturer - // name -}; + CF_IEEE1284_NORMALIZE_PAD_NUMBERS = 0x200, // Zero-pad numbers in strings to get better list sorting results + CF_IEEE1284_NORMALIZE_SEPARATE_COMPONENTS = 0x400, /* + * In the output buffer put + * '\0' bytes between make, + * model, and extra, to use + * as separate strings + */ + CF_IEEE1284_NORMALIZE_NO_MAKE_MODEL = 0x800, /* + * No make/model/extra separation, + * do not try to identify, add, + * or clean up manufacturer + * name + */ typedef unsigned cf_ieee1284_normalize_modes_t; // diff --git a/cupsfilters/image.c b/cupsfilters/image.c index 34556aa81..34f3bc81a 100644 --- a/cupsfilters/image.c +++ b/cupsfilters/image.c @@ -642,13 +642,14 @@ cfImageSetMaxTiles( // 'cfImageCrop()' - Crop an image. // (posw, posh): Position of left corner // (width, height): Width and height of required image. +// -cf_image_t* -cfImageCrop(cf_image_t* img, - int posw, - int posh, - int width, - int height) +cf_image_t* // O - New image +cfImageCrop(cf_image_t* img, // I - Image to crop + int posw, // I - Position of left corner + int posh, // I - Position of left corner + int width, // I - Width of required image + int height) // I - Height of required image { int image_width = cfImageGetWidth(img); cf_image_t* temp = calloc(1, sizeof(cf_image_t)); diff --git a/cupsfilters/imagetopdf.c b/cupsfilters/imagetopdf.c index 8ce51dd36..0d9f75fd4 100644 --- a/cupsfilters/imagetopdf.c +++ b/cupsfilters/imagetopdf.c @@ -35,9 +35,9 @@ // Types... // -struct pdfObject +struct pdfObject // **** PDF object information **** { - int offset; + int offset; // Offset of object in output file }; typedef struct imagetopdf_doc_s // **** Document information **** @@ -58,14 +58,14 @@ typedef struct imagetopdf_doc_s // **** Document information **** PageTop, // Top margin PageWidth, // Total page width PageLength; // Total page length - struct pdfObject *objects; - int currentObjectNo; - int allocatedObjectNum; - int currentOffset; - int xrefOffset; - int *pageObjects; - int catalogObj; - int pagesObj; + struct pdfObject *objects; // PDF objects + int currentObjectNo; // Current object number + int allocatedObjectNum; // Allocated number of objects + int currentOffset; // Current offset in output file + int xrefOffset; // Offset of xref table + int *pageObjects; // Page objects + int catalogObj; // Catalog object + int pagesObj; // Pages object const char *title; int xpages, // # x pages ypages, // # y pages @@ -82,15 +82,15 @@ typedef struct imagetopdf_doc_s // **** Document information **** float xsize, // Total size in points ysize, xsize2, - ysize2; + ysize2; // Total size in points for 2-up printing float aspect; // Aspect ratio cf_image_t *img; // Image to print int colorspace; // Output colorspace cf_ib_t *row; // Current row float gammaval; // Gamma correction value float brightness; // Gamma correction value - char linebuf[LINEBUFSIZE]; - FILE *outputfp; + char linebuf[LINEBUFSIZE]; // Line buffer for output + FILE *outputfp; // Output file pointer } imagetopdf_doc_t; @@ -582,11 +582,9 @@ out_image(imagetopdf_doc_t *doc, int // O - Error status cfFilterImageToPDF(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { imagetopdf_doc_t doc; // Document information cups_page_header_t h; // CUPS Raster page header, to diff --git a/cupsfilters/imagetoraster.c b/cupsfilters/imagetoraster.c index eea5602da..b6b3c7f86 100644 --- a/cupsfilters/imagetoraster.c +++ b/cupsfilters/imagetoraster.c @@ -183,8 +183,7 @@ cfFilterImageToRaster(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream int inputseekable, // I - Is input stream seekable? cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { imagetoraster_doc_t doc; // Document information int i; // Looping var diff --git a/cupsfilters/ipp-options-private.h b/cupsfilters/ipp-options-private.h index 10fbb6313..ab254b8a5 100644 --- a/cupsfilters/ipp-options-private.h +++ b/cupsfilters/ipp-options-private.h @@ -226,7 +226,7 @@ typedef struct cf_filter_options_s // All filter options in one structure bool mirror; // "mirror" value char page_border[128]; // "page-border" value int page_top, page_left, // Margin values - page_right, page_bottom; + page_right, page_bottom; // "page-top", "page-left", "page-right", "page-bottom" values char page_label[256]; // "page-label" value bool pdf_auto_rotate; // "pdfAutoRotate" value cf_filter_imgpos_t x_image_position; // "x-image-position" value diff --git a/cupsfilters/ipp.c b/cupsfilters/ipp.c index 813ebbaec..d02f4473d 100644 --- a/cupsfilters/ipp.c +++ b/cupsfilters/ipp.c @@ -46,8 +46,7 @@ typedef struct cf_size_s // **** Media Size (cups_size_t of libcups2) **** // millimeters right, // Right margin in hundredths of // millimeters - top; // Top margin in hundredths of - // millimeters + top; // Top margin in hundredths of millimeters } cf_size_t; @@ -66,15 +65,22 @@ log_printf(char *log, va_end(arglist); } -char * -cfResolveURI(const char *raw_uri) +// +// 'cfResolveURI()' - Resolve a URI, for example a DNS-SD-service-name-based URI to a host-name-based URI. +// + +char * // O - Resolved URI +cfResolveURI(const char *raw_uri) // I - Raw URI { return (cfResolveURI2(raw_uri, 0)); } -// Check how the driverless support is provided -int -cfCheckDriverlessSupport(const char* uri) +// +// 'cfCheckDriverlessSupport()' - Check how the driverless support is provided by the printer +// + +int // O - Support status +cfCheckDriverlessSupport(const char* uri) // I - Printer URI { int support_status = CF_DRVLESS_CHECKERR; ipp_t *response = NULL; @@ -87,80 +93,95 @@ cfCheckDriverlessSupport(const char* uri) return (support_status); } -// Get attributes of a printer specified only by URI -ipp_t * -cfGetPrinterAttributes(const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug) +// +// 'cfGetPrinterAttributes()' - Get attributes of a printer specified only by URI. +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes(const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug) // I - Debug mode { return (cfGetPrinterAttributes2(NULL, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug)); } -// Get attributes of a printer specified by URI and under a given HTTP -// connection, for example via a domain socket -ipp_t * -cfGetPrinterAttributes2(http_t *http_printer, - const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug) +// +// 'cfGetPrinterAttributes2()' - Get attributes of a printer specified by URI and under a given HTTP +// connection, for example via a domain socket. +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes2(http_t *http_printer, // I - HTTP connection to printer + const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug) // I - Debug mode { return (cfGetPrinterAttributes3(http_printer, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug, NULL)); } -// Get attributes of a printer specified by URI and under a given HTTP -// connection, for example via a domain socket, and give info about used -// fallbacks -ipp_t * -cfGetPrinterAttributes3(http_t *http_printer, - const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug, - int* driverless_info) +// +// 'cfGetPrinterAttributes3()' - Get attributes of a printer specified by URI and under a given HTTP +// connection, for example via a domain socket, and give info about used +// fallbacks +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes3(http_t *http_printer, // I - HTTP connection to printer + const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug, // I - Debug mode + int* driverless_info) // I - Pointer to variable to return driverless support status, or NULL { return (cfGetPrinterAttributes5(http_printer, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug, driverless_info, 0)); } +// +// 'cfGetPrinterAttributes4()' - Get attributes of a printer specified only by URI and given info about +// fax-support. +// -// Get attributes of a printer specified only by URI and given info about -// fax-support -ipp_t *cfGetPrinterAttributes4(const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug, - int is_fax) +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes4(const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug, // I - Debug mode + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { return (cfGetPrinterAttributes5(NULL, raw_uri, pattrs, pattrs_size, req_attrs, req_attrs_size, debug, NULL, is_fax)); } -// Get attributes of a printer specified by URI and under a given HTTP -// connection, for example via a domain socket, and give info about used -// fallbacks -ipp_t * -cfGetPrinterAttributes5(http_t *http_printer, - const char* raw_uri, - const char* const pattrs[], - int pattrs_size, - const char* const req_attrs[], - int req_attrs_size, - int debug, - int* driverless_info, - int is_fax) +// +// 'cfGetPrinterAttributes5()' - Get attributes of a printer specified by URI and under a given HTTP +// connection, for example via a domain socket, and give info about used +// fallbacks +// + +ipp_t * // O - IPP printer attributes +cfGetPrinterAttributes5(http_t *http_printer, // I - HTTP connection to printer + const char* raw_uri, // I - Printer URI + const char* const pattrs[], // I - Requested printer attributes + int pattrs_size, // I - Number of requested attributes + const char* const req_attrs[], // I - Required response attributes + int req_attrs_size, // I - Number of required attributes + int debug, // I - Debug mode + int* driverless_info, // I - Pointer to variable to return driverless support status, or NULL + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { char *uri; int have_http, uri_status, host_port, i = 0, total_attrs = 0, fallback, @@ -454,8 +475,14 @@ cfGetPrinterAttributes5(http_t *http_printer, #ifndef HAVE_LIBCUPS2 -char* -cfResolveURI2(const char *raw_uri, int is_fax) + +// +// 'cfResolveURI2()' - Resolve a URI, for example a DNS-SD-service-name-based URI to a host-name-based URI. +// + +char* // O - Resolved URI +cfResolveURI2(const char *raw_uri, // I - Raw URI + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { int options = HTTP_RESOLVE_DEFAULT; const char* auth_info_required = getenv("AUTH_INFO_REQUIRED"); @@ -483,13 +510,15 @@ is_string_tag(ipp_attribute_t *attr) // I - Attribute to check tag == IPP_TAG_KEYWORD); } -const char* // O - Attribute value as string -cfIPPAttrEnumValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same - // as to respond - // get-printer-attributes, - // or NULL to not consider +// +// 'cfIPPAttrEnumValForPrinter()' - Get the value of an enumerated attribute for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// + +const char* // O - Attribute value as string +cfIPPAttrEnumValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same as to respond get-printer-attributes, or NULL to not consider ipp_t *job_attrs, // I - Job attributes - const char *attr_name)// I - Attribute name + const char *attr_name) // I - Attribute name { ipp_attribute_t *attr; char printer_attr_name[256]; @@ -549,16 +578,16 @@ cfIPPAttrEnumValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same return (res); } +// +// 'cfIPPAttrIntValForPrinter()' - Get the value of an integer attribute for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// -int // O - 1: Success; 0: Error -cfIPPAttrIntValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same - // as to respond - // get-printer-attributes, - // or NULL to not consider +int // O - 1: Success; 0: Error +cfIPPAttrIntValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same as to respond get-printer-attributes, or NULL to not consider ipp_t *job_attrs, // I - Job attributes const char *attr_name,// I - Attribute name - int *value) // O - Attribute value as - // integer + int *value) // O - Attribute value as integer { ipp_attribute_t *attr; char printer_attr_name[256]; @@ -617,11 +646,15 @@ cfIPPAttrIntValForPrinter(ipp_t *printer_attrs, // I - Printer attributes, same return (retval); } +// +// 'cfIPPAttrResolutionForPrinter()' - Get the value of a resolution attribute for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// int // O - 1: Success; 0: Error -cfIPPAttrResolutionForPrinter(ipp_t *printer_attrs,// I - Printer attributes +cfIPPAttrResolutionForPrinter(ipp_t *printer_attrs, // I - Printer attributes ipp_t *job_attrs, // I - Job attributes - const char *attr_name,// I - Attribute name + const char *attr_name, // I - Attribute name int *xres, // O - X resolution (dpi) int *yres) // O - Y resolution (dpi) { @@ -716,10 +749,14 @@ cfIPPAttrResolutionForPrinter(ipp_t *printer_attrs,// I - Printer attributes return (retval); } +// +// 'cfIPPReverseOutput()' - Get the output order for a job, using the printer's +// attributes to validate the value and to provide a default if needed. +// -int -cfIPPReverseOutput(ipp_t *printer_attrs, - ipp_t *job_attrs) +int // O - 0: Original order; 1: Reverse order +cfIPPReverseOutput(ipp_t *printer_attrs, // I - Printer attributes + ipp_t *job_attrs) // I - Job attributes { int i; ipp_attribute_t *attr1, *attr2; @@ -776,64 +813,35 @@ cfIPPReverseOutput(ipp_t *printer_attrs, return (0); } - // -// 'cfGetBackSideOrientation()' - This functions returns the back -// side orientation using printer -// attributes. Meaning and reason for -// backside orientation: It only makes -// sense if printer supports duplex, -// so, if printer reports that it -// supports duplex printing via -// sides-supported IPP attribute, then -// it also reports back-side -// orientation for each PDL in PDL -// specific IPP attributes. Backside -// orientation is specially needed for -// raster PDLs as raster PDLs are -// specially made for raster printers -// which do not have sufficient memory -// to hold a full page bitmap(raster -// page). So they cannot build the -// whole page in memory before -// starting to print it. For one-sided -// printing it is easy to manage. The -// printer's mechanism pulls the page -// in on its upper edge and starts to -// print, from top to bottom, after -// that it ejects the page. For -// double-sided printing it does the -// same for the front side, but for -// the back side the mechanics of the -// printer has to turn over the sheet, -// and now, depending on how the sheet -// is turned over it happens that the -// edge arriving in the printing -// mechanism is the lower edge of the -// back side. And if the printer -// simply prints then, the back side -// is the wrong way around. The -// printer reports its need via back -// side orientation in such a case, so -// that the client knows to send the -// back side upside down for example. -// In vector PDLs, PDF and PostScript, -// always the full page's raster image -// is completely generated in the -// printer before the page is started, -// and therefore the printer can start -// to take the pixels from the lower -// edge of the raster image if needed, -// so back side orientation is always -// "normal" for these PDLs. And if a -// printer does not support duplex, -// back side orientation is not -// needed. -// - -int // O - Backside orientation (bit 0-2) - // Requires flipped margin? - // Yes: bit 4 set; No: bit 3 set +// 'cfGetBackSideOrientation()' - This functions returns the back side orientation using printer +// attributes. Meaning and reason for backside orientation: It only makes +// sense if printer supports duplex, so, if printer reports that it +// supports duplex printing via sides-supported IPP attribute, then +// it also reports back-side orientation for each PDL in PDL +// specific IPP attributes. Backside orientation is specially needed for +// raster PDLs as raster PDLs are specially made for raster printers +// which do not have sufficient memory to hold a full page bitmap(raster +// page). So they cannot build the whole page in memory before +// starting to print it. For one-sided printing it is easy to manage. The +// printer's mechanism pulls the page in on its upper edge and starts to +// print, from top to bottom, after that it ejects the page. For +// double-sided printing it does the same for the front side, but for +// the back side the mechanics of the printer has to turn over the sheet, +// and now, depending on how the sheet is turned over it happens that the +// edge arriving in the printing mechanism is the lower edge of the +// back side. And if the printer simply prints then, the back side +// is the wrong way around. The printer reports its need via back +// side orientation in such a case, so that the client knows to send the +// back side upside down for example. In vector PDLs, PDF and PostScript, +// always the full page's raster image is completely generated in the +// printer before the page is started, and therefore the printer can start +// to take the pixels from the lower edge of the raster image if needed, +// so back side orientation is always "normal" for these PDLs. And if a +// printer does not support duplex, back side orientation is not needed. +// + +int // O - Backside orientation (bit 0-2) Requires flipped margin? Yes: bit 4 set; No: bit 3 set cfGetBackSideOrientation(cf_filter_data_t *data) // I - Filter data { ipp_t *printer_attrs = data->printer_attrs; @@ -930,11 +938,14 @@ cfGetBackSideOrientation(cf_filter_data_t *data) // I - Filter data return (backside); } +// +// 'cfGetPrintRenderIntent()' - Get the print rendering intent from job attributes and printer attributes. +// -const char * -cfGetPrintRenderIntent(cf_filter_data_t *data, - char *ri, - int ri_len) +const char * // O - Rendering intent string, or NULL +cfGetPrintRenderIntent(cf_filter_data_t *data, // I - Filter data + char *ri, // O - Rendering intent buffer + int ri_len) // I - Buffer size { const char *val; int num_options = 0; @@ -1023,12 +1034,9 @@ cfGetPrintRenderIntent(cf_filter_data_t *data, // option list, together with the options // -int // O - New number of options - // in new option list +int // O - New number of options in new option list cfJoinJobOptionsAndAttrs(cf_filter_data_t* data, // I - Filter data - int num_options, // I - Current mumber of - // options in new option - // list + int num_options, // I - Current mumber of options in new option list cups_option_t **options) // IO - New option lsit { ipp_t *job_attrs = data->job_attrs; // Job attributes @@ -1166,11 +1174,14 @@ cfStrFormatd(char *buf, // I - String return (bufptr); } +// +// 'cfStrFormatf()' - Format a floating-point number with a given number of decimal places. +// -int -cfCompareResolutions(void *resolution_a, - void *resolution_b, - void *user_data) +int // O - Number of characters written +cfCompareResolutions(void *resolution_a, // I - First resolution + void *resolution_b, // I - Second resolution + void *user_data) // I - User data (not used) { cf_res_t *res_a = (cf_res_t *)resolution_a; cf_res_t *res_b = (cf_res_t *)resolution_b; @@ -1191,9 +1202,13 @@ cfCompareResolutions(void *resolution_a, return ((a > b) - (a < b)); } -void * -cfCopyResolution(void *resolution, - void *user_data) +// +// 'cfCopyResolution()' - Copy a resolution structure. +// + +void * // O - Copy of resolution +cfCopyResolution(void *resolution, // I - Resolution to copy + void *user_data) // I - User data (not used) { cf_res_t *res = (cf_res_t *)resolution; cf_res_t *copy; @@ -1208,25 +1223,37 @@ cfCopyResolution(void *resolution, return copy; } +// +// 'cfFreeResolution()' - Free a resolution structure. +// + void -cfFreeResolution(void *resolution, - void *user_data) +cfFreeResolution(void *resolution, // I - Resolution to free + void *user_data) // I - User data (not used) { cf_res_t *res = (cf_res_t *)resolution; if (res) free(res); } -cups_array_t * +// +// 'cfNewResolutionArray()' - Create a new array of resolutions. +// + +cups_array_t * // O - New array of resolutions cfNewResolutionArray() { return (cupsArrayNew(cfCompareResolutions, NULL, NULL, 0, cfCopyResolution, cfFreeResolution)); } -cf_res_t * -cfNewResolution(int x, - int y) +// +// 'cfNewResolution()' - Create a new resolution structure. +// + +cf_res_t * // O - New resolution structure +cfNewResolution(int x, // I - X resolution (dpi) + int y) // I - Y resolution (dpi) { cf_res_t *res = (cf_res_t *)calloc(1, sizeof(cf_res_t)); if (res) @@ -1237,13 +1264,16 @@ cfNewResolution(int x, return (res); } -// Read a single resolution from an IPP attribute, take care of -// obviously wrong entries (printer firmware bugs), ignoring -// resolutions of less than 60 dpi in at least one dimension and -// fixing Brother's "600x2dpi" resolutions. -cf_res_t * -cfIPPResToResolution(ipp_attribute_t *attr, - int index) +// +// 'cfIPPResToResolution()' - Read a single resolution from an IPP attribute, take care of +// obviously wrong entries (printer firmware bugs), ignoring +// resolutions of less than 60 dpi in at least one dimension and +// fixing Brother's "600x2dpi" resolutions. +// + +cf_res_t * // O - Resolution structure or NULL on error +cfIPPResToResolution(ipp_attribute_t *attr, // I - IPP attribute + int index) // I - Index of resolution to read { cf_res_t *res = NULL; int x = 0, y = 0; @@ -1271,8 +1301,12 @@ cfIPPResToResolution(ipp_attribute_t *attr, return (res); } -cups_array_t * -cfIPPAttrToResolutionArray(ipp_attribute_t *attr) +// +// 'cfIPPAttrToResolutionArray()' - Convert an IPP attribute to an array of resolutions. +// + +cups_array_t * // O - Array of resolutions +cfIPPAttrToResolutionArray(ipp_attribute_t *attr) // I - IPP attribute { cups_array_t *res_array = NULL; cf_res_t *res; @@ -1307,27 +1341,27 @@ cfIPPAttrToResolutionArray(ipp_attribute_t *attr) return (res_array); } -// Build up an array of common resolutions and most desirable default -// resolution from multiple arrays of resolutions with an optional -// default resolution. -// Call this function with each resolution array you find as "new", and -// in "current" an array of the common resolutions will be built up. -// You do not need to create an empty array for "current" before -// starting. Initialize it with NULL. -// "current_default" holds the default resolution of the array "current". -// It will get replaced by "new_default" if "current_default" is either -// NULL or a resolution which is not in "current" any more. -// "new" and "new_default" will be deleted/freed and set to NULL after -// each, successful or unsuccssful operation. -// Note that when calling this function the addresses of the pointers -// to the resolution arrays and default resolutions have to be given -// (call by reference) as all will get modified by the function. - -int // 1 on success, 0 on failure -cfJoinResolutionArrays(cups_array_t **current, - cups_array_t **new_arr, - cf_res_t **current_default, - cf_res_t **new_default) +// +// 'cfJoinResolutionArrays()' - Build up an array of common resolutions and most desirable default +// resolution from multiple arrays of resolutions with an optional +// default resolution. Call this function with each resolution array +// you find as "new", and in "current" an array of the common resolutions +// will be built up. You do not need to create an empty array for "current" +// before starting. Initialize it with NULL. "current_default" holds the +// default resolution of the array "current". It will get replaced by +// "new_default" if "current_default" is either +// NULL or a resolution which is not in "current" any more. +// "new" and "new_default" will be deleted/freed and set to NULL after +// each, successful or unsuccssful operation. +// Note that when calling this function the addresses of the pointers +// to the resolution arrays and default resolutions have to be given +// (call by reference) as all will get modified by the function. + +int // O - 1 on success, 0 on failure +cfJoinResolutionArrays(cups_array_t **current, // IO - Current array of common resolutions + cups_array_t **new_arr, // I - New array of resolutions to join with current + cf_res_t **current_default, // IO - Current default resolution of current array + cf_res_t **new_default) // I - New default resolution of new array { cf_res_t *res; int retval; @@ -1438,12 +1472,12 @@ pwg_copy_size(cf_size_t *size) // I - Media size to copy return (newsize); } +// +// 'cfGetPageDimensions()' - Get page dimensions from job attributes and options. +// -int // O - 1: Requested page size supported - // 2: Requested page size supported - // when rotated by 90 degrees - // 0: No page size requested - // -1: Requested size unsupported +int // O - 1: Requested page size supported; 2: Requested page size supported when rotated by 90 degrees; 0: No page size requested; -1: Requested size unsupported + cfGetPageDimensions(ipp_t *printer_attrs, // I - Printer attributes ipp_t *job_attrs, // I - Job attributes int num_options, // I - Number of options @@ -1457,8 +1491,7 @@ cfGetPageDimensions(ipp_t *printer_attrs, // I - Printer attributes float *right, // O - Right margin float *top, // O - Top margin char *name, // O - Page size name - ipp_t **media_col_entry)// O - media-col-database record of - // match + ipp_t **media_col_entry)// O - media-col-database record of match { int i; const char *attr_name; @@ -1768,6 +1801,9 @@ cfGetPageDimensions(ipp_t *printer_attrs, // I - Printer attributes return (size_requested ? -1 : 0); } +// +// 'cfSetPageDimensionsToDefault()' - Set page dimensions to default values if they are invalid. +// void cfSetPageDimensionsToDefault(float *width, // IO - Width (in pt, 1/72 inches) @@ -1856,28 +1892,31 @@ dimensions_for_name(char *size_name, return (search); } +// +// 'cfGenerateSizes()' - Generate a list of sizes from the printer attributes. +// void -cfGenerateSizes(ipp_t *response, - cf_gen_sizes_mode_t mode, - cups_array_t **sizes, - ipp_attribute_t **defattr, - int *width, - int *length, - int *left, - int *bottom, - int *right, - int *top, - int *min_width, - int *min_length, - int *max_width, - int *max_length, - int *custom_left, - int *custom_bottom, - int *custom_right, - int *custom_top, - char *size_name, - ipp_t **media_col_entry) +cfGenerateSizes(ipp_t *response, // I - Printer attributes + cf_gen_sizes_mode_t mode, // I - Mode of operation + cups_array_t **sizes, // IO - Array of sizes + ipp_attribute_t **defattr, // IO - Default media attribute + int *width, // IO - Width (in 1/2540 inches) + int *length, // IO - Length + int *left, // IO - Left margin + int *bottom, // IO - Bottom margin + int *right, // IO - Right margin + int *top, // IO - Top margin + int *min_width, // IO - Minimum width (in 1/2540 inches) + int *min_length, // IO - Minimum length + int *max_width, // IO - Maximum width (in 1/2540 inches) + int *max_length, // IO - Maximum length + int *custom_left, // IO - Minimum left margin (in 1/2540 inches) + int *custom_bottom, // IO - Minimum bottom margin + int *custom_right, // IO - Minimum right margin + int *custom_top, // IO - Minimum top margin + char *size_name, // IO - Page size name + ipp_t **media_col_entry) // IO - media-col-database record of match { ipp_attribute_t *default_attr, *attr, // xxx-supported diff --git a/cupsfilters/ipp.h b/cupsfilters/ipp.h index 25e585690..4ba8d9832 100644 --- a/cupsfilters/ipp.h +++ b/cupsfilters/ipp.h @@ -47,7 +47,7 @@ extern "C" { #define CF_GET_PRINTER_ATTRIBUTES_MAX_OUTPUT_LEN 8192 #define CF_GET_PRINTER_ATTRIBUTES_MAX_URI_LEN 2048 -extern char cf_get_printer_attributes_log[CF_GET_PRINTER_ATTRIBUTES_LOGSIZE]; +extern char cf_get_printer_attributes_log[CF_GET_PRINTER_ATTRIBUTES_LOGSIZE]; // Log for cfGetPrinterAttributes() and related functions // @@ -66,27 +66,27 @@ enum cf_driverless_support_modes_e }; // Backside orientations for duplex printing -typedef enum cf_backside_orient_e +typedef enum cf_backside_orient_e // Backside orientation for duplex printing { - CF_BACKSIDE_MANUAL_TUMBLE, - CF_BACKSIDE_ROTATED, - CF_BACKSIDE_FLIPPED, - CF_BACKSIDE_NORMAL + CF_BACKSIDE_MANUAL_TUMBLE, // Backside orientation for manual duplex printing + CF_BACKSIDE_ROTATED, // Backside orientation for rotated duplex printing + CF_BACKSIDE_FLIPPED, // Backside orientation for flipped duplex printing + CF_BACKSIDE_NORMAL // Backside orientation for normal duplex printing } cf_backside_orient_t; // Data structure for resolution (X x Y dpi) -typedef struct cf_res_s +typedef struct cf_res_s // **** Resolution (X x Y dpi) **** { - int x, y; + int x, y; // X and Y resolution in dpi } cf_res_t; -typedef enum cf_gen_sizes_mode_e +typedef enum cf_gen_sizes_mode_e // Mode for generating sizes { - CF_GEN_SIZES_DEFAULT = 0, - CF_GEN_SIZES_SEARCH, - CF_GEN_SIZES_SEARCH_BORDERLESS_ONLY -} cf_gen_sizes_mode_t; + CF_GEN_SIZES_DEFAULT = 0, // Default mode, generate all sizes + CF_GEN_SIZES_SEARCH, // Search for a specific size, return only that size + CF_GEN_SIZES_SEARCH_BORDERLESS_ONLY // Search for a specific size, return only that size if it is borderless +} cf_gen_sizes_mode_t; // diff --git a/cupsfilters/libcups2.c b/cupsfilters/libcups2.c index c60d5aae4..2db0e00ed 100644 --- a/cupsfilters/libcups2.c +++ b/cupsfilters/libcups2.c @@ -34,10 +34,13 @@ convert_to_port(char *a) return (port); } +// +// 'cfResolveURI2()' - Resolve a URI, for example a DNS-SD-service-name-based URI to a host-name-based URI. +// -char * -cfResolveURI2(const char *uri, - int is_fax) +char * // O - Resolved URI +cfResolveURI2(const char *uri, // I - Raw URI + int is_fax) // I - 1: Fax printer; 0: Not a fax printer { int ippfind_pid = 0, // Process ID of ippfind for IPP post_proc_pipe[2], // Pipe to post-processing for IPP diff --git a/cupsfilters/mupdftopwg.c b/cupsfilters/mupdftopwg.c index 9c8484fe7..49a6cc0dd 100644 --- a/cupsfilters/mupdftopwg.c +++ b/cupsfilters/mupdftopwg.c @@ -34,7 +34,7 @@ #define CUPS_IPTEMPFILE "/tmp/ip-XXXXXX" #define CUPS_OPTEMPFILE "/tmp/op-XXXXXX" -typedef cups_page_header_t mupdf_page_header; +typedef cups_page_header_t mupdf_page_header; // Use the same page header structure as in libcupsfilters/raster.h static int @@ -419,15 +419,16 @@ mutool_spawn(const char *filename, return (status); } +// +// 'cfFilterMuPDFToPWG()' - Filter function for converting PDF to PWG Raster using mutool. +// -int +int // O - Exit status of filter function: 0 on success, 1 on error cfFilterMuPDFToPWG(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { cf_filter_out_format_t outformat; char *val; diff --git a/cupsfilters/pack.c b/cupsfilters/pack.c index 1278da13f..3d8389a22 100644 --- a/cupsfilters/pack.c +++ b/cupsfilters/pack.c @@ -170,8 +170,7 @@ void cfPackHorizontalBit(const unsigned char *ipixels, // I - Input pixels unsigned char *obytes, // O - Output bytes int width, // I - Number of pixels - const unsigned char clearto, // I - Initial value of - // bytes + const unsigned char clearto, // I - Initial value of bytes const unsigned char bit) // I - Bit to check { register unsigned char b; // Current byte @@ -251,8 +250,7 @@ cfPackVertical(const unsigned char *ipixels, // I - Input pixels unsigned char *obytes, // O - Output bytes int width, // I - Number of input pixels const unsigned char bit, // I - Output bit - const int step) // I - Number of bytes between - // columns + const int step) // I - Number of bytes between columns { // // Loop through the entire array... diff --git a/cupsfilters/pclmtoraster.c b/cupsfilters/pclmtoraster.c index d1ca90149..48f66a502 100644 --- a/cupsfilters/pclmtoraster.c +++ b/cupsfilters/pclmtoraster.c @@ -29,7 +29,7 @@ #define MAX_BYTES_PER_PIXEL 32 // Structure to hold filter data and state -typedef struct pclmtoraster_data_s +typedef struct pclmtoraster_data_s { int outformat; // Output Format int numcolors; // number of Colour components(e.g. 3 for RGB, 4 for CYMK..) @@ -37,18 +37,14 @@ typedef struct pclmtoraster_data_s cups_page_header_t header; // CUPS page header char pageSizeRequested[64]; // Requested page size name int bi_level; // flag for printing - // image swapping - int swap_image_x; - int swap_image_y; - // margin swapping - int swap_margin_x; - int swap_margin_y; + int swap_image_x; // flag for swapping image in x direction + int swap_image_y; // flag for swapping image in y direction + int swap_margin_x; // flag for swapping margin in x direction + int swap_margin_y; // flag for swapping margin in y direction unsigned int nplanes; // Number of colour planes unsigned int nbands; // Number of colour bands unsigned int bytesPerLine; // bytes per line in output char colorspace[32]; // Colourspace string(Use fixed-size string) - int pixel_count; // Accumulated pixel byte count for bitmap - unsigned char *bitmap; // Accumulated image bitmap data } pclmtoraster_data_t; // @@ -71,8 +67,6 @@ init_pclmtoraster_data_t(pclmtoraster_data_t *data) // I - pclm data to initiali // Note: When CUPS_ORDER_BANDED, // cupsBytesPerLine = bytesPerLine * cupsNumColors strncpy(data->colorspace, "\0", sizeof(data->colorspace)); - data->pixel_count = 0; - data->bitmap = NULL; } // function pointer for color space conversion @@ -846,10 +840,12 @@ select_convert_func(int pgno, // I - Page number // NOTE: no error code, be sure to upload image object only. // -static bool // O - 1 if success, 0 if fail +bool // O - 1 if success, 0 if fail process_image(pdfio_dict_t *dict, // I - dictionary where images are there const char *key, // I - key names of xobjects - void *cb_data) // I - conversion data + pclmtoraster_data_t *data, // I - conversion data + int pixel_count, // I - pixel count for bitmap + unsigned char *bitmap) // O - bitmap values { const char *subtype; pclmtoraster_data_t *data; @@ -931,9 +927,10 @@ out_page(cups_raster_t* raster, // I - Raster stream int i; long long rotate = 0; float paperdimensions[2], margins[4], l, swap; - int temp = 0; + int pixel_count = 0, temp = 0; float mediaBox[4]; - unsigned char *colordata = NULL, + unsigned char *bitmap = NULL, + *colordata = NULL, *lineBuf = NULL, *line = NULL, *dp = NULL; @@ -1069,9 +1066,7 @@ out_page(cups_raster_t* raster, // I - Raster stream pdfio_dict_t *xobjects = pdfioDictGetDict(resources, "XObject"); // Iterate over the XObject dictionary to find images - data->pixel_count = 0; - data->bitmap = NULL; - pdfioDictIterateKeys(xobjects, process_image, data); + pdfioDictIterateKeys(xobjects, (pdfio_dict_cb_t)process_image, data); // Swap width and height in landscape images if(rotate == 270 || rotate == 90) @@ -1118,16 +1113,15 @@ out_page(cups_raster_t* raster, // I - Raster stream // Rotate Bitmap if (rotate) { - unsigned char *bitmap2 = (unsigned char *) malloc(data->pixel_count); - bitmap2 = rotate_bitmap(data->bitmap, bitmap2, rotate, - data->header.cupsHeight, + unsigned char *bitmap2 = (unsigned char *) malloc(pixel_count); + bitmap2 = rotate_bitmap(bitmap, bitmap2, rotate, data->header.cupsHeight, data->header.cupsWidth, data->rowsize, data->colorspace, log, ld); - free(data->bitmap); - data->bitmap = bitmap2; + free(bitmap); + bitmap = bitmap2; } - colordata = data->bitmap; + colordata = bitmap; // Write page image lineBuf = (unsigned char *)malloc(data->bytesPerLine * sizeof(unsigned char)); @@ -1170,9 +1164,7 @@ out_page(cups_raster_t* raster, // I - Raster stream } free(lineBuf); free(line); - free(data->bitmap); - data->bitmap = NULL; - data->pixel_count = 0; + free(bitmap); return (0); } diff --git a/cupsfilters/pdf.c b/cupsfilters/pdf.c index 4399b65d4..252f85b80 100644 --- a/cupsfilters/pdf.c +++ b/cupsfilters/pdf.c @@ -73,22 +73,24 @@ cfPDFLoadTemplate(const char *filename) // I - Filename of the PDF file // 'cf_pdf_write()' - helper which writes the PDF file to a FILE* // -ssize_t -cf_pdf_write_cb(void *context, const void *buffer, size_t bytes) +ssize_t // O - Number of bytes written +cf_pdf_write_cb(void *context, // I - Output FILE context + const void *buffer, // I - Data buffer + size_t bytes) // I - Number of bytes to write { return (ssize_t)fwrite(buffer, 1, bytes, (FILE *)context); } // // 'cfCopyPDFdoc()' - Copy the PDF file to another using PDFio, as PDFio doesn't -// explicitly support file modification. -// Thus we will copy contents into new streams and modify there. +// explicitly support file modification. +// Thus we will copy contents into new streams and modify there. // -cf_pdf_t* -cfCopyPDFdoc(cf_pdf_t *input_doc, - FILE *output_file, - iterate_data_t *iterate_helper) +cf_pdf_t* // O - Pointer to cf_pdf_t struct +cfCopyPDFdoc(cf_pdf_t *input_doc, // I - Pointer to input PDF file + FILE *output_file, // I - Pointer to output PDF file + iterate_data_t *iterate_helper) // I - PDF iteration helper data { cf_pdf_t *pdf = (cf_pdf_t*)pdfioFileCreateOutput(cf_pdf_write_cb, output_file, pdfioFileGetVersion((pdfio_file_t *)input_doc), NULL, NULL, NULL, NULL); @@ -258,13 +260,13 @@ cfPDFPrependStream(cf_pdf_t *pdf, // I - Pointer to PDF file // // 'cfPDFPrependStream1()' - Replacement API for the original above. -// Prepend a stream to the contents of a specified +// Prepend a stream to the contents of a specified // page in PDF file. // int // O - 0 on success, 1 on error cfPDFPrependStream1(cf_pdf_t *pdf, // I - Pointer to PDF file - iterate_data_t *iterate_helper, + iterate_data_t *iterate_helper, // I - PDF iteration helper data unsigned page_num, // I - page number to prepend to const char *buf, // I - Buffer containing stream data size_t len) // I - Length of Buffer @@ -356,13 +358,13 @@ cfPDFAddType1Font(cf_pdf_t *pdf, // I - Pointer to PDF object // // 'cfPDFAddType1Font1()' - Replacement to the API just above -// Add the specified type1 font face to the specified -// page in a PDF document. +// Add the specified type1 font face to the specified +// page in a PDF document. // int // O - 0 on success , 1 on error cfPDFAddType1Font1(cf_pdf_t *pdf, // I - Pointer to PDF object - iterate_data_t *iterate_helper, + iterate_data_t *iterate_helper, // I/O - PDF iteration helper data unsigned page_num, // I - Page number to add font to const char *name) // I - Name of the font { @@ -596,8 +598,8 @@ cfPDFDuplicatePage(cf_pdf_t *pdf, // I - pointer to PDF file // void -cfPDFWrite(cf_pdf_t *pdf, - FILE *file) +cfPDFWrite(cf_pdf_t *pdf, // I - Pointer to PDF object + FILE *file) // I - Output FILE { // PDFio doesn't work this way. } @@ -606,8 +608,9 @@ cfPDFWrite(cf_pdf_t *pdf, // 'cfPDFFillForm()' - Fill recognized fields with information // -int -cfPDFFillForm(cf_pdf_t *doc, cf_opt_t *opt) +int // O - 0 on sucess, 1 on failure +cfPDFFillForm(cf_pdf_t *doc, // I - PDF document + cf_opt_t *opt) // I - PDF form options { // TODO: PDFio does not directly support form filling. return 1; diff --git a/cupsfilters/pdf.h b/cupsfilters/pdf.h index 5f7afe06e..f40410117 100644 --- a/cupsfilters/pdf.h +++ b/cupsfilters/pdf.h @@ -36,11 +36,11 @@ struct _cf_opt cf_opt_t *next; }; -typedef struct iterate_data_s +typedef struct iterate_data_s // *** Helper structure for PDF page iteration *** { - cf_pdf_t *pdf; - pdfio_dict_t *page_dict; - pdfio_dict_t *page_resdict; + cf_pdf_t *pdf; // PDF document + pdfio_dict_t *page_dict; // Current page dictionary + pdfio_dict_t *page_resdict; // Current page resources dictionary }iterate_data_t; cf_pdf_t* cfPDFLoadTemplate(const char *filename); diff --git a/cupsfilters/pdftopdf-private.h b/cupsfilters/pdftopdf-private.h index 2f42e4e79..70d58240e 100644 --- a/cupsfilters/pdftopdf-private.h +++ b/cupsfilters/pdftopdf-private.h @@ -44,47 +44,43 @@ typedef struct { pdfio_obj_t *obj; // Track object pointers for cycle detection } VisitedObj; -typedef struct xform_document_s // Document information -{ - const char *filename, // Document filename +typedef struct xform_document_s // *** Document information *** +{ + const char *filename, // Document filename *format; // Document format - char tempfile[1024]; // Temporary PDF file, if any + char tempfile[1024]; // Temporary PDF file, if any const char *pdf_filename; // PDF filename pdfio_file_t *pdf; // PDF file for document int first_page, // First page number in document last_page, // Last page number in document - num_pages; // Number of pages to print in document + num_pages; // Number of pages to print in document } xform_document_t; -typedef struct xform_page_s // Output page +typedef struct xform_page_s // *** Output page *** { pdfio_file_t *pdf; // Output PDF file size_t layout; // Current layout cell - pdfio_obj_t *input[XFORM_MAX_LAYOUT]; - // Input page objects + pdfio_obj_t *input[XFORM_MAX_LAYOUT]; // Input page objects pdfio_dict_t *pagedict; // Page dictionary pdfio_dict_t *resdict; // Resource dictionary - pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; - // Resource name map + pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; // Resource name map pdfio_dict_t *restype; // Current resource type dictionary pdfio_stream_t *output; // Output page stream } xform_page_t; -typedef struct xform_page_ext_s // Output page +typedef struct xform_page_ext_s // *** Output page *** { pdfio_file_t *pdf; // Output PDF file - pdfio_obj_t **input; - // Input page objects + pdfio_obj_t **input; // Input page objects pdfio_dict_t *pagedict; // Page dictionary pdfio_dict_t *resdict; // Resource dictionary - pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; - // Resource name map + pdfio_dict_t *resmap[XFORM_MAX_LAYOUT]; // Resource name map pdfio_dict_t *restype; // Current resource type dictionary pdfio_stream_t *output; // Output page stream } xform_page_ext_t; -typedef struct xform_prepare_s // Preparation data +typedef struct xform_prepare_s // *** Preparation data *** { cf_filter_options_t *options; // Print options cups_array_t *errors; // Error messages @@ -95,11 +91,9 @@ typedef struct xform_prepare_s // Preparation data pdfio_rect_t media; // Default media box pdfio_rect_t crop; // Default crop box size_t num_outpages; // Number of output pages - xform_page_t outpages[XFORM_MAX_PAGES]; - // Output pages + xform_page_t outpages[XFORM_MAX_PAGES]; // Output pages size_t num_layout; // Number of layout rectangles - pdfio_rect_t layout[XFORM_MAX_LAYOUT]; - // Layout rectangles + pdfio_rect_t layout[XFORM_MAX_LAYOUT]; // Layout rectangles bool use_duplex_xform; // Use the back side transform matrix? pdfio_matrix_t duplex_xform; // Back side transform matrix bool has_form; // does PDF have Acroform(is flattening required?) diff --git a/cupsfilters/pdftopdf.c b/cupsfilters/pdftopdf.c index 894500343..73f010682 100644 --- a/cupsfilters/pdftopdf.c +++ b/cupsfilters/pdftopdf.c @@ -860,9 +860,13 @@ prepare_pages( } } +// +// 'getArrayAsMatrix()' - Convert a PDF array into a transformation matrix. +// + void -getArrayAsMatrix(pdfio_array_t *array, - pdfio_matrix_t cm) +getArrayAsMatrix(pdfio_array_t *array, // I - PDF array containing 6 matrix values + pdfio_matrix_t cm) // O - Transformation matrix { size_t array_size = pdfioArrayGetSize(array); if(array_size != 6) @@ -882,8 +886,12 @@ getArrayAsMatrix(pdfio_array_t *array, return; } -double -get_flags(pdfio_dict_t *annots_dict) +// +// 'get_flags()' - Get the annotation flags from a PDF annotation dictionary. +// + +double // O - Annotation flags +get_flags(pdfio_dict_t *annots_dict) // I - PDF annotation dictionary { double val = pdfioDictGetNumber(annots_dict, "F"); return val; @@ -1027,9 +1035,13 @@ transform_point(const pdfio_matrix_t matrix, *yp = matrix[0][1] * x + matrix[1][1] * y + matrix[2][1]; } -pdfio_rect_t -transform_rectangle(const pdfio_matrix_t matrix, - pdfio_rect_t r) +// +// 'transform_rectangle()' - Transform a rectangle using a transformation matrix. +// + +pdfio_rect_t // O - Transformed rectangle +transform_rectangle(const pdfio_matrix_t matrix, // I - Transformation matrix + pdfio_rect_t r) // I - Rectangle to transform { double min_x = DBL_MAX, min_y = DBL_MAX; double max_x = -DBL_MAX, max_y = -DBL_MAX; @@ -1061,8 +1073,12 @@ transform_rectangle(const pdfio_matrix_t matrix, return transformed; } -char* -unparse_matrix(pdfio_matrix_t matrix) +// +// 'unparse_matrix()' - Convert a transformation matrix into a PDF matrix string. +// + +char* // O - Matrix string, or NULL on error +unparse_matrix(pdfio_matrix_t matrix) // I - Transformation matrix { double comps[6] = {matrix[0][0], matrix[0][1], matrix[1][0], matrix[1][1], matrix[2][0], matrix[2][1]}; @@ -1111,8 +1127,13 @@ unparse_matrix(pdfio_matrix_t matrix) return result; } -pdfio_obj_t* -getAppearance(pdfio_dict_t *Annot_dict, char* value) +// +// 'getAppearance()' - Get the appearance object for a PDF annotation. +// + +pdfio_obj_t* // O - Appearance object, or NULL if not found +getAppearance(pdfio_dict_t *Annot_dict, // I - Annotation dictinonary + char* value) // I - Appearance key { pdfio_dict_t *AP_dict = pdfioDictGetDict(Annot_dict, "AP"); pdfio_obj_t* appearance_obj = pdfioDictGetObj(AP_dict, value); @@ -1193,12 +1214,16 @@ get_pdf_matrix(pdfio_dict_t *d, return 1; } -char* -special_pdfio_annotation_get_content(pdfio_obj_t *annot, - const char *name, - int page_rotate, - int forbidden_flags, - int required_flags) +// +// 'pdfio_annotation_get_content()' - Get the content stream for a PDF annotation. +// + +char* // O - Content stream string, or NULL on error +special_pdfio_annotation_get_content(pdfio_obj_t *annot, // I - PDF annotation object + const char *name, // I - XObject name + int page_rotate, // I - Page rotation angle + int forbidden_flags, // I - Annoation flag that must not be set + int required_flags) // I - Annoation flag that must be set { if (!annot || !name) { @@ -1280,12 +1305,16 @@ special_pdfio_annotation_get_content(pdfio_obj_t *annot, return out; } -char* -pdfio_annotation_get_content(pdfio_obj_t *annot, - const char *name, - int page_rotate, - int forbidden_flags, - int required_flags) +// +// 'pdfio_annotation_get_content()' - Get the content stream for a PDF annotation. +// + +char* // O - Content stream string, or NULL on error +pdfio_annotation_get_content(pdfio_obj_t *annot, // I - PDF annotation object + const char *name, // I - XObject name + int page_rotate, // I - Page rotation angle + int forbidden_flags, // I - Annotation flags that must not be set + int required_flags) // I - Annotation flags that must be set { if (!annot || !name) { @@ -1423,17 +1452,26 @@ pdfio_annotation_get_content(pdfio_obj_t *annot, return out; } +// +// 'merge_resources()' - Merge resources from the PDF dictionary into another. +// + void -merge_resources(pdfio_dict_t *dest, - pdfio_dict_t *source) +merge_resources(pdfio_dict_t *dest, // I - Destination resource dictionary + pdfio_dict_t *source) // I - Source resource dictionary { pdfioDictIterateKeys(source, (pdfio_dict_cb_t)merge_resources_cb, dest); } -bool -extractFontDetails(const char *da, - char *font_key, size_t keylen, - double *font_size) +// +// 'extractFontDetails()' - Extract the font key and size from a font description string. +// + +bool // O - Returns true on success, false on failure. +extractFontDetails(const char *da, // I - input string + char *font_key, // O - parsed font name output + size_t keylen, // I - buffer size + double *font_size) // O - parsed size output { if (!da || !font_key || keylen == 0 || !font_size) return false; @@ -2725,10 +2763,14 @@ prepare_documents( return (ret); } -// coping inputfp data to temp_fp, so that we have a filename, as it is required in pdfioFileOpen API -int -copy_fd_to_tempfile(int inputfd, - FILE *temp_file) +// +// 'copy_fd_to_tempfile()' - Coping inputfp data to temp_fp, so that we have a filename, +// as it is required in pdfioFileOpen API. +// + +int // O - 0 on success, -1 on failure +copy_fd_to_tempfile(int inputfd, // I - Input file descriptor + FILE *temp_file) // I - Temporary output file { char buffer[BUFSIZ]; ssize_t bytes_read, bytes_written; @@ -2752,12 +2794,17 @@ copy_fd_to_tempfile(int inputfd, return 0; } -int -cfFilterPDFToPDF(int inputfd, - int outputfd, - int inputseekable, - cf_filter_data_t *data, - void *parameters) +// +// 'cfFilterPDFToPDF()' - Filter a PDF file and write the processed +// PDF to the output. +// + +int // O - Returns 0 on success, 1 on failure +cfFilterPDFToPDF(int inputfd, // I - Input file descriptor + int outputfd, // I - Output file descriptor + int inputseekable, // I - Whether input is seekable + cf_filter_data_t *data, // I - Filter data + void *parameters) // I - Filter parameters { cf_logfunc_t log = data->logfunc; void *ld = data->logdata; diff --git a/cupsfilters/pdftoraster.c b/cupsfilters/pdftoraster.c index dd2359f13..5d4c9432c 100644 --- a/cupsfilters/pdftoraster.c +++ b/cupsfilters/pdftoraster.c @@ -75,16 +75,16 @@ #define MAX_BYTES_PER_PIXEL 32 extern int errno; -typedef struct cms_profile_s +typedef struct cms_profile_s // *** Color Management System profile structure *** { // for color profiles - cmsHPROFILE colorProfile; - cmsHPROFILE popplerColorProfile; - cmsHTRANSFORM colorTransform; - cmsCIEXYZ D65WhitePoint; - int renderingIntent; - int cm_disabled; - cf_cm_calibration_t cm_calibrate; + cmsHPROFILE colorProfile; // color profile + cmsHPROFILE popplerColorProfile; // color profile used by poppler + cmsHTRANSFORM colorTransform; // color transform + cmsCIEXYZ D65WhitePoint; // D65 white point + int renderingIntent; // rendering intent + int cm_disabled; // whether color management is disabled + cf_cm_calibration_t cm_calibrate; // whether color calibration is enabled } cms_profile_t; // @@ -101,34 +101,32 @@ init_cms_profile_t(cms_profile_t *profile) // I - profile structure to init profile->cm_disabled = 0; } -typedef struct pdftoraster_doc_s +typedef struct pdftoraster_doc_s // *** PDF to Raster Document Structure *** { - char *input_filename; - int pwgraster; - int bi_level; - bool allocLineBuf; - unsigned int bitspercolor; - unsigned int popplerNumColors; - unsigned int bitmapoffset[2]; - pdfio_file_t *pdf_doc; - cups_page_header_t header; - cf_logfunc_t logfunc; // Logging function, NULL for no - // logging - void *logdata; // User data for logging function, can - // be NULL + char *input_filename; // Input PDF file name + int pwgraster; // Whether to output PWG Raster (1) or CUPS Raster (0) + int bi_level; // Whether to output bi-level (1) or not (0) + bool allocLineBuf; // Whether to allocate a line buffer for the conversion function + unsigned int bitspercolor; // Bits per color + unsigned int popplerNumColors; // Number of colors in the poppler output + unsigned int bitmapoffset[2]; // Bitmap offset for the poppler output + pdfio_file_t *pdf_doc; // PDF document structure + cups_page_header_t header; // CUPS page header structure + cf_logfunc_t logfunc; // Logging function, NULL for no logging + void *logdata; // User data for logging function, can be NULL cups_file_t *inputfp; // Temporary file, if any FILE *outputfp; // Temporary file, if any - bool swap_image_x; - bool swap_image_y; + bool swap_image_x; // Whether to swap the image in the x direction + bool swap_image_y; // Whether to swap the image in the y direction // margin swapping - bool swap_margin_x; - bool swap_margin_y; - unsigned int nplanes; - unsigned int nbands; + bool swap_margin_x; // Whether to swap the margin in the x direction + bool swap_margin_y; // Whether to swap the margin in the y direction + unsigned int nplanes; // number of planes + unsigned int nbands; // number of bands unsigned int bytesPerLine; // number of bytes per line // Note: When CUPS_ORDER_BANDED, // cupsBytesPerLine = bytesPerLine * cupsNumColors - cms_profile_t *colour_profile; + cms_profile_t *colour_profile; // Color Management System profile structure } pdftoraster_doc_t; typedef unsigned char *(*convert_cspace_func)(unsigned char *src, @@ -146,12 +144,11 @@ typedef unsigned char *(*convert_line_func)(unsigned char *src, pdftoraster_doc_t* doc, convert_cspace_func convertCSpace); -typedef struct pdf_conversion_function_s +typedef struct pdf_conversion_function_s // *** PDF Conversion Function Structure *** { convert_cspace_func convertCSpace; // Function for conversion of colorspaces - convert_line_func convertLineOdd; // Function tom modify raster data of a - // line - convert_line_func convertLineEven; + convert_line_func convertLineOdd; // Function to modify raster data of a line + convert_line_func convertLineEven; // Function to modify raster data of a line } pdf_conversion_function_t; // @@ -159,7 +156,7 @@ typedef struct pdf_conversion_function_s // void -init_pdftoraster_doc_t(pdftoraster_doc_t *doc) // 0 - document structure. +init_pdftoraster_doc_t(pdftoraster_doc_t *doc) // I - document structure. { doc->pwgraster = 0; doc->bi_level = 0; @@ -792,16 +789,16 @@ line_swap_bit(unsigned char *src, return (dst); } -typedef struct func_table_s +typedef struct func_table_s // *** Function Table for Special Edge Cases *** { - enum cups_cspace_e cspace; - unsigned int bitsPerPixel; - unsigned int bitsPerColor; - convert_line_func convertLine; - bool allocLineBuf; - convert_line_func convertLineSwap; - bool allocLineBufSwap; -} func_table_t; + enum cups_cspace_e cspace; // Colour Space + unsigned int bitsPerPixel; // Bits per Pixel + unsigned int bitsPerColor; // Bits per Color + convert_line_func convertLine; // Function to modify raster data of a line + bool allocLineBuf; // Whether to allocate a line buffer for the conversion function + convert_line_func convertLineSwap; // Function to modify raster data of a line with swapping + bool allocLineBufSwap; // Whether to allocate a line buffer for the conversion function with swapping +} func_table_t; // Function table for Special Edge Cases static func_table_t specialCaseFuncs[] = @@ -2429,14 +2426,12 @@ set_color_profile(pdftoraster_doc_t *doc, // 'cfFilterPDFToRaster()' - Main Function for PDFtoRaster Conversion // -int +int // O - Exit status cfFilterPDFToRaster(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { // Constants for Printing Attributes or data const char *val; diff --git a/cupsfilters/pwgtopdf.c b/cupsfilters/pwgtopdf.c index 0be268909..4a5edd087 100644 --- a/cupsfilters/pwgtopdf.c +++ b/cupsfilters/pwgtopdf.c @@ -78,86 +78,75 @@ // Compression method for providing data to PCLm Streams. typedef enum compression_method_e { - DCT_DECODE = 0, - FLATE_DECODE, - RLE_DECODE + DCT_DECODE = 0, // JPEG compression + FLATE_DECODE, // Flate compression + RLE_DECODE // Run Length compression } compression_method_t; // Color conversion function typedef unsigned char *(*convert_function)(unsigned char *src, unsigned char *dst, unsigned int pixels); - -// Bit conversion function typedef unsigned char *(*bit_convert_function)(unsigned char *src, unsigned char *dst, - unsigned int pixels); - -typedef struct pwgtopdf_doc_s // **** Document information **** + unsigned int pixels); // Bit conversion function +typedef struct pwgtopdf_doc_s // *** Document information *** { - cmsHPROFILE colorProfile; // ICC Profile to be applied to - // PDF - int cm_disabled; // Flag raised if color - // management is disabled - convert_function conversion_function; // Raster color conversion - // function + cmsHPROFILE colorProfile; // ICC Profile to be applied to PDF + int cm_disabled; // Flag raised if color management is disabled + convert_function conversion_function; // Raster color conversion function bit_convert_function bit_function; // Raster bit function FILE *outputfp; // Temporary file, if any - cf_logfunc_t logfunc; // Logging function, NULL for no - // logging - void *logdata; // User data for logging - // function, can be NULL - cf_filter_iscanceledfunc_t iscanceledfunc; // Function returning 1 when - // job is canceled, NULL for not - // supporting stop on cancel - void *iscanceleddata; // User data for is-canceled - // function, can be NULL + cf_logfunc_t logfunc; // Logging function, NULL for no logging + void *logdata; // User data for logging function, can be NULL + cf_filter_iscanceledfunc_t iscanceledfunc; // Function returning 1 when job is canceled, NULL for not supporting stop on cancel + void *iscanceleddata; // User data for is-canceled function, can be NULL } pwgtopdf_doc_t; // PDF info structure -struct pdf_info{ - pdfio_file_t *pdf; - pdfio_dict_t *page_dict; - pdfio_obj_t *page; - pdfio_stream_t *page_stream; - char *temp_filename; - - unsigned pagecount; - unsigned width; - unsigned height; - unsigned line_bytes; - unsigned bpp; - unsigned bpc; - - unsigned pclm_num_strips; - unsigned pclm_strip_height_preferred; +struct pdf_info{ // *** PDF info structure *** + pdfio_file_t *pdf; // PDF file structure + pdfio_dict_t *page_dict; // PDF page dictionary + pdfio_obj_t *page; // PDF page object + pdfio_stream_t *page_stream; // PDF page stream + char *temp_filename; // Temporary file name for PDF output + + unsigned pagecount; // Number of pages in the PDF + unsigned width; // Width of the PDF page + unsigned height; // Height of the PDF page + unsigned line_bytes; // Number of bytes per line in the PDF page + unsigned bpp; // Bits per pixel in the PDF page + unsigned bpc; // Bits per component in the PDF page + + unsigned pclm_num_strips; // Number of strips in the PCLm page + unsigned pclm_strip_height_preferred; // Preferred strip height for the PCLm page - unsigned *pclm_strip_height; - size_t pclm_strip_height_size; + unsigned *pclm_strip_height; // Array of strip heights for the PCLm page + size_t pclm_strip_height_size; // Size of the pclm_strip_height array - unsigned *pclm_strip_height_supported; - size_t pclm_strip_height_supported_size; + unsigned *pclm_strip_height_supported; // Array of supported strip heights for the PCLm page + size_t pclm_strip_height_supported_size; // Size of the pclm_strip_height_supported array - compression_method_t *pclm_compression_method_preferred; - size_t pclm_compression_method_preferred_size; + compression_method_t *pclm_compression_method_preferred; // Array of preferred compression methods for the PCLm page + size_t pclm_compression_method_preferred_size; // Size of the pclm_compression_method_preferred array - char **pclm_source_resolution_supported; - size_t pclm_source_resolution_supported_size; + char **pclm_source_resolution_supported; // Array of supported source resolutions for the PCLm page + size_t pclm_source_resolution_supported_size; // Size of the pclm_source_resolution_supported array - char *pclm_source_resolution_default; - char *pclm_raster_back_side; + char *pclm_source_resolution_default; // Default source resolution for the PCLm page + char *pclm_raster_back_side; // Raster back side for the PCLm page - char **pclm_strip_data; - size_t *pclm_strip_data_size; + char **pclm_strip_data; // Array of strip data for the PCLm page + size_t *pclm_strip_data_size; // Array of sizes for the pclm_strip_data array - char *render_intent; - cups_cspace_t color_space; + char *render_intent; // Render intent for the PDF page + cups_cspace_t color_space; // Color space for the PDF page - char *page_data; - size_t page_data_size; - double page_width; - double page_height; - cf_filter_out_format_t outformat; + char *page_data; // Data for the PDF page + size_t page_data_size; // Size of the page_data array + double page_width; // Width of the PDF page in points + double page_height; // Height of the PDF page in points + cf_filter_out_format_t outformat; // Output format for the PDF page (PDF or PCLm) }; // @@ -165,7 +154,7 @@ struct pdf_info{ // void -init_pdf_info(struct pdf_info *info) +init_pdf_info(struct pdf_info *info) // I - pdf_info structure { info->pdf = NULL; @@ -211,15 +200,16 @@ init_pdf_info(struct pdf_info *info) info->outformat = CF_FILTER_OUT_FORMAT_PDF; } -// PDF color conversion function + typedef void (*pdf_convert_function)(struct pdf_info *info, - pwgtopdf_doc_t *doc); + pwgtopdf_doc_t *doc); // PDF color conversion function // // 'free_pdf_info()' - Freeing the dynamically allocated memory // -void free_pdf_info(struct pdf_info *info) +void +free_pdf_info(struct pdf_info *info) // I - pdf_info structure { if (info->pclm_strip_height) { @@ -366,16 +356,13 @@ no_color_conversion(unsigned char *src, // // 'split_strings()' - Split a string to a vector of strings given some -// delimiters -// -// O - std::vector of std::string after splitting -// I - input string to be split -// I - string containing delimiters +// delimiters. // -char** split_strings(const char *str, - const char *delimiters, - size_t *count) +char // O - std::vector of std::string after splitting +** split_strings(const char *str, // I - input string to be split + const char *delimiters, // I - string containing delimiters + size_t *count) // O - number of strings after splitting { *count = 0; if (!str || *str == '\0') @@ -491,15 +478,12 @@ num_digits(int n) // // 'int_to_fwstring()' - Convert a number to fixed width string by padding -// with zeroes -// O - converted string -// I - the integee which needs to be converted to string -// I - width of string required +// with zeroes. // -char* -int_to_fwstring(int n, - int width) +char* // O - converted string +int_to_fwstring(int n, // I - the integer which needs to be converted to string + int width) // I - width of string required { int num_zeroes = width - num_digits(n); if (num_zeroes < 0) @@ -1668,6 +1652,10 @@ set_profile(const char *path, return (1); } +// +// 'cfFilterPWGToPDF()' - Convert a PWG raster stream to PDF or PCLm. +// + int // O - Error status cfFilterPWGToPDF(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream diff --git a/cupsfilters/pwgtoraster.c b/cupsfilters/pwgtoraster.c index ee81000de..ca68734c0 100644 --- a/cupsfilters/pwgtoraster.c +++ b/cupsfilters/pwgtoraster.c @@ -67,40 +67,40 @@ #define MAX_BYTES_PER_PIXEL 32 -typedef struct cms_profile_s +typedef struct cms_profile_s // *** for color management *** { // for color profiles - cmsHPROFILE colorProfile; - cmsHPROFILE outputColorProfile; - cmsHTRANSFORM colorTransform; - cmsCIEXYZ D65WhitePoint; - int renderingIntent; - int cm_disabled; - cf_cm_calibration_t cm_calibrate; + cmsHPROFILE colorProfile; // ICC profile + cmsHPROFILE outputColorProfile; // ICC profile for output device + cmsHTRANSFORM colorTransform; // Color transform for color management + cmsCIEXYZ D65WhitePoint; // D65 white point + int renderingIntent; // Rendering intent for color management + int cm_disabled; // Flag raised if color management is disabled + cf_cm_calibration_t cm_calibrate; // Status of CUPS color management } cms_profile_t; -typedef struct pwgtoraster_doc_s -{ // **** Document information **** - cf_filter_data_t *data; - bool page_size_requested; - int bi_level; - bool allocLineBuf; - unsigned int bitspercolor; - unsigned int outputNumColors; - unsigned int bitmapoffset[2]; - cups_page_header_t inheader; - cups_page_header_t outheader; +typedef struct pwgtoraster_doc_s // *** Document information *** +{ + cf_filter_data_t *data; // Filter data + bool page_size_requested; // Flag indicating if page size is requested + int bi_level; // Bilevel flag + bool allocLineBuf; // Flag to allocate line buffer for conversion + unsigned int bitspercolor; // Bits per color + unsigned int outputNumColors; // Number of output colors + unsigned int bitmapoffset[2]; // Offset for bitmap data + cups_page_header_t inheader; // Input page header + cups_page_header_t outheader; // Output page header cups_file_t *inputfp; // Temporary file, if any FILE *outputfp; // Temporary file, if any // margin swapping - bool swap_margin_x; - bool swap_margin_y; - unsigned int nplanes; - unsigned int nbands; + bool swap_margin_x; // Flag to swap margins in x direction + bool swap_margin_y; // Flag to swap margins in y direction + unsigned int nplanes; // Number of planes in the output raster + unsigned int nbands; // Number of bands in the output raster unsigned int bytesPerLine; // number of bytes per line // Note: When CUPS_ORDER_BANDED, // cupsBytesPerLine = bytesPerLine * cupsNumColors - cms_profile_t color_profile; + cms_profile_t color_profile; // Color profile information for color management } pwgtoraster_doc_t; typedef unsigned char *(*convert_cspace_func)(unsigned char *src, @@ -117,11 +117,11 @@ typedef unsigned char *(*convert_line_func)(unsigned char *src, pwgtoraster_doc_t* doc, convert_cspace_func convertCSpace); -typedef struct conversion_function_s +typedef struct conversion_function_s // *** Conversion function information *** { convert_cspace_func convertCSpace; // Function for conversion of colorspaces convert_line_func convertLineOdd; // Function to modify raster data of a line - convert_line_func convertLineEven; + convert_line_func convertLineEven; // Function to modify raster data of a line } conversion_function_t; @@ -609,15 +609,15 @@ line_swap_bit(unsigned char *src, } -typedef struct func_table_s +typedef struct func_table_s // *** Conversion function table for special cases *** { - enum cups_cspace_e cspace; - unsigned int bitsPerPixel; - unsigned int bitsPerColor; - convert_line_func convertLine; - bool allocLineBuf; - convert_line_func convertLineSwap; - bool allocLineBufSwap; + enum cups_cspace_e cspace; // CUPS colorspace + unsigned int bitsPerPixel; // Bits per pixel + unsigned int bitsPerColor; // Bits per color + convert_line_func convertLine; // Function to modify raster data of a line + bool allocLineBuf; // Flag to allocate line buffer for conversion + convert_line_func convertLineSwap; // Function to modify raster data of a line with swapping + bool allocLineBufSwap; // Flag to allocate line buffer for conversion with swapping } func_table_t; @@ -2345,15 +2345,16 @@ set_color_profile(pwgtoraster_doc_t *doc, return (0); } +// +// 'cfFilterPWGToRaster()' - Convert a PWG raster stream to a CUPS raster stream. +// -int +int // O - 0 on success, 1 on error cfFilterPWGToRaster(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data,// I - Job and printer data - void *parameters) // I - Filter-specific parameters - // (unused) + void *parameters) // I - Filter-specific parameters (unused) { cf_filter_out_format_t outformat; pwgtoraster_doc_t doc; diff --git a/cupsfilters/raster.c b/cupsfilters/raster.c index ca78cac49..d331a6d01 100644 --- a/cupsfilters/raster.c +++ b/cupsfilters/raster.c @@ -76,7 +76,7 @@ _strlcpy(char *dst, // O - Destination string // 'cfRasterColorSpaceString()' - Return the color space name for a // cupsColorSpace value. -const char * +const char * // O - Color space name cfRasterColorSpaceString(cups_cspace_t cspace) // I - cupsColorSpace value { static const char * const cups_color_spaces[] = @@ -172,26 +172,13 @@ cfRasterColorSpaceString(cups_cspace_t cspace) // I - cupsColorSpace value // attributes/options. // -int // O - 0 on success, - // -1 on error +int // O - 0 on success, -1 on error cfRasterPrepareHeader(cups_page_header_t *h, // I - Raster header cf_filter_data_t *data, // I - Job and printer data - cf_filter_out_format_t final_outformat, - // I - Job output format - // (determines color space, - // and resolution) - cf_filter_out_format_t header_outformat, - // I - This filter's output - // format (determines - // header format) - int no_high_depth, // I - Suppress use of - // > 8 bit per color - cups_cspace_t *cspace) // IO - Color space we want to - // use, -1 for auto, we - // return color space - // actually used, -1 if - // no suitable color space - // found. + cf_filter_out_format_t final_outformat, // I - Job output format (determines color space, and resolution) + cf_filter_out_format_t header_outformat, // I - This filter's output format (determines header format) + int no_high_depth, // I - Suppress use of > 8 bit per color + cups_cspace_t *cspace) // IO - Color space we want to use, -1 for auto, we return color space actually used, -1 if no suitable color space found. { int i; ipp_t *printer_attrs, *job_attrs; @@ -595,27 +582,12 @@ cfRasterPrepareHeader(cups_page_header_t *h, // I - Raster header // requested, the highest. // -int // O - 0 on success, - // -1 on error +int // O - 0 on success, -1 on error cfRasterSetColorSpace(cups_page_header_t *h, // I - Raster header - const char *available, // I - Available color spaces - // from IPP attribute - // urf-supported or - // pwg-raster-document-type-supported - const char *color_mode, // I - print-color-mode IPP - // attribute setting - cups_cspace_t *cspace, // IO - Color space we want to - // use, -1 for auto, we - // return color space - // actually used, -1 if - // no suitable color space - // found. - int *high_depth) // IO - Do we want to print in - // high color depth? We - // reset to 0 if high - // quality not supported - // in the color space - // used. + const char *available, // I - Available color spaces from IPP attribute urf-supported or pwg-raster-document-type-supported + const char *color_mode, // I - print-color-mode IPP attribute setting + cups_cspace_t *cspace, // IO - Color space we want to use, -1 for auto, we return color space actually used, -1 if no suitable color space found. + int *high_depth) // IO - Do we want to print in high color depth? We reset to 0 if high quality not supported in the color space used. { int min_depth = 999; int max_depth = 0; diff --git a/cupsfilters/raster.h b/cupsfilters/raster.h index b9a832a2b..91470b932 100644 --- a/cupsfilters/raster.h +++ b/cupsfilters/raster.h @@ -48,8 +48,20 @@ 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, non-zero on error. +// + extern int cfRasterPrepareHeader(cups_page_header_t *h, cf_filter_data_t *data, cf_filter_out_format_t @@ -58,6 +70,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, -1 on error. +// + extern int cfRasterSetColorSpace(cups_page_header_t *h, const char *available, const char *color_mode, diff --git a/cupsfilters/testfilters.c b/cupsfilters/testfilters.c index 9c0e2b27f..4edfaef8c 100644 --- a/cupsfilters/testfilters.c +++ b/cupsfilters/testfilters.c @@ -18,15 +18,15 @@ # define cupsParseOptions(arg, end, num_options, options) cupsParseOptions(arg, num_options, options) #endif -/* - * 'remove_white_space()' - Remove white spaces from beginning and end of a string - */ typedef int (*cf_filter_func_t)(int input_fd, int output_fd, int input_seekable, cf_filter_data_t *data, void *parameters); -char* -remove_white_space( - char* str) +// +// 'remove_white_space()' - Remove white spaces from beginning and end of a string +// + +char* // O - Pointer to the modified string +remove_white_space(char* str) // I - Input string { char *end; while(isspace((unsigned char)*str)) str++; @@ -49,8 +49,12 @@ typedef struct { void *(*param_generator)(const char *output_mime); } FilterMapping; -void -*ghostscript_param_gen(const char *output_mime) +// +// 'ghostscript_param_gen()' - Generate parameters for the ghostscript filter based on output MIME type. +// + +void // O - Pointer to parameters structure, or NULL on error +*ghostscript_param_gen(const char *output_mime) // I - Output MIME type { cf_filter_out_format_t *out = malloc(sizeof(cf_filter_out_format_t)); if (strcasecmp(output_mime, "application/pdf") == 0) { @@ -78,9 +82,13 @@ FilterMapping filter_mappings[] = { { "texttopdf", cfFilterTextToPDF, NULL }, }; -cups_array_t* -parse_filter_chain(const char *filter_chain_str, - const char *output_mime) +// +// 'cfFilterFilterInChain()' - Call a filter function in the chain. +// + +cups_array_t* // O - Array of filters in the chain +parse_filter_chain(const char *filter_chain_str, // I - Comma-separated list of filter names + const char *output_mime) // I - Output MIME type { cups_array_t *chain = cupsArrayNew(NULL, NULL, NULL, 0, NULL, NULL); char *saveptr; @@ -196,10 +204,10 @@ create_media_size(int width, /* I - x-dimension in 2540ths */ return (media_size); } -/* - * 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test - * - */ +// +// 'test_wrapper()' - Utilizes libcupsfilters API for running a particular test +// +// /* @@ -217,18 +225,18 @@ test_wrapper( { */ -int +int // O - Exit status test_wrapper( - int num_clargs, - char *clargs[], - void *parameters, - int *JobCanceled, - ipp_t* emulated_ipp, - char* inputMIME, - char* outputMIME, - char* inputFile, - char* outputFile, - cups_array_t *filter_chain) + int num_clargs, // I - Number of command-line args + char *clargs[], // I - Command-line arguments + void *parameters, // I - Filter function parameters + int *JobCanceled, // I - Var set to 1 when job canceled + ipp_t* emulated_ipp, // I - Emulated printer IPP attributes + char* inputMIME, // I - Input MIME type + char* outputMIME, // I - Output MIME type + char* inputFile, // I - Input file name + char* outputFile, // I - Output file name + cups_array_t *filter_chain) { int inputfd; // Print file descriptor int outputfd; // File Descriptor for Output File @@ -1110,15 +1118,14 @@ load_legacy_attributes( } -/* - * 'run_test()' - Runs a particular test case - * - */ +// +// 'run_test()' - Runs a particular test case +// -int +int // O - Exit status run_test( - char * test_case, - char * currentFile) + char * test_case, // I - Test case string + char * currentFile) // I - Current file name { cups_array_t *filter_chain = NULL; @@ -1267,8 +1274,13 @@ run_test( } -int main(int argc, // I - Number of command-line args - char *argv[]) // I - Command-line arguments{ +// +// 'main()' - Main entry point for the test filter program. +// + +int // O - Exit status + main(int argc, // I - Number of command-line args + char *argv[]) // I - Command-line arguments { char *file_name; // File Name of Input Test File FILE *fp; // File Pointer diff --git a/cupsfilters/testpdf2.c b/cupsfilters/testpdf2.c index 628e10e6b..be4e292c3 100644 --- a/cupsfilters/testpdf2.c +++ b/cupsfilters/testpdf2.c @@ -43,12 +43,14 @@ write_string(_cf_pdf_out_t *pdf, _cfPDFOutputString(pdf, str, -1); } } -// }}} +// +// 'main()' - Main entry point for the test program. +// -int -main(int argc, - char *argv[]) +int // O - Exit status +main(int argc, // I - Number of command-line args + char *argv[]) // I - Command-line arguments { _cf_pdf_out_t *pdf; diff --git a/cupsfilters/texttopdf.c b/cupsfilters/texttopdf.c index 81e5f7f0e..f7a665284 100644 --- a/cupsfilters/texttopdf.c +++ b/cupsfilters/texttopdf.c @@ -481,7 +481,7 @@ typedef struct // **** Character/attribute structure... **** attr; // Any attributes } lchar_t; -typedef struct texttopdf_doc_s +typedef struct texttopdf_doc_s // *** Document data for texttopdf filter *** { int NumFonts; // Number of fonts to use _cf_fontembed_emb_params_t *Fonts[256][4]; // Fonts to use @@ -489,23 +489,21 @@ typedef struct texttopdf_doc_s unsigned char Codes[65536]; // Unicode glyph mapping to font int Widths[256]; // Widths of each font int Directions[256];// Text directions for each font - _cf_pdf_out_t *pdf; + _cf_pdf_out_t *pdf; // PDF output stream int FontResource; // Object number of font resource dictionary float FontScaleX, FontScaleY; // The font matrix lchar_t *Title, *Date; // The title and date strings - cups_page_header_t h; // CUPS Raster page header, to - // accommodate results of command - // line/IPP attribute parsing - cf_filter_texttopdf_parameter_t env_vars; - int NumKeywords; + cups_page_header_t h; // CUPS Raster page header, to accommodate results of command line/IPP attribute parsing + cf_filter_texttopdf_parameter_t env_vars; // Environment variables for texttopdf filter + int NumKeywords; // Number of keywords in the list float PageLeft, // Left margin PageRight, // Right margin PageBottom, // Bottom margin PageTop, // Top margin PageWidth, // Total page width - PageLength; - int NumPages; + PageLength; // Total page length + int NumPages; // Number of pages in the document int WrapLines, // Wrap text in lines SizeLines, // Number of lines on a page SizeColumns, // Number of columns on a line @@ -516,14 +514,14 @@ typedef struct texttopdf_doc_s Copies; // Number of copies to produce float CharsPerInch, // Number of character columns per inch LinesPerInch; // Number of lines per inch - int UTF8; + int UTF8; // Use UTF-8 encoding? char **Keywords; // List of known keywords... int Orientation, // 0 = portrait, 1 = landscape, etc. Duplex, // Duplexed? LanguageLevel, // Language level of printer - ColorDevice; - lchar_t **Page; + ColorDevice; // Color device? + lchar_t **Page; // The pages of the document, each page is a string of lchar_t } texttopdf_doc_t; diff --git a/cupsfilters/texttotext.c b/cupsfilters/texttotext.c index 0c241174c..c9bce02e5 100644 --- a/cupsfilters/texttotext.c +++ b/cupsfilters/texttotext.c @@ -39,18 +39,18 @@ // Type definitions // -typedef enum overlong_line_e +typedef enum overlong_line_e // How to treat overlong lines { - TRUNCATE = 0, - WORDWRAP = 1, - WRAPATWIDTH = 2 + TRUNCATE = 0, // Truncate lines to the page width + WORDWRAP = 1, // Wrap lines at word boundaries + WRAPATWIDTH = 2 // Wrap lines at the page width } overlong_line_t; -typedef enum newline_char_e +typedef enum newline_char_e // Character to send at end of line { - LF = 0, - CR = 1, - CRLF = 2 + LF = 0, // Line Feed + CR = 1, // Carriage Return + CRLF = 2 // Carriage Return + Line Feed } newline_char_t; @@ -63,11 +63,15 @@ static int is_false(const char *value); static int check_range(char *page_ranges, int even_pages, int odd_pages, int page); -int + +// +// 'cfFilterTextToText()' - Filter a text file to a text-only printer. +// + +int // O - Exit status cfFilterTextToText(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream - int inputseekable, // I - Is input stream seekable? - // (unused) + int inputseekable, // I - Is input stream seekable? (unused) cf_filter_data_t *data, // I - Job and printer data void *parameters) // I - Filter-specific parameters { diff --git a/cupsfilters/universal.c b/cupsfilters/universal.c index 69488741b..c2b98b9af 100644 --- a/cupsfilters/universal.c +++ b/cupsfilters/universal.c @@ -28,6 +28,10 @@ #include #include +// +// 'cfFilterUniversal()' - Filter a file from any input format to any output format. +// + int // O - Error status cfFilterUniversal(int inputfd, // I - File descriptor input stream int outputfd, // I - File descriptor output stream