Rasterizing pages. More...

Data Structures
struct	caps_rstr_page_desc

struct	caps_rstr_page_limits
	Limits the rasterizer has when rasterizing the current document. More...

struct	caps_rstr_page
	Physical print medium description. More...

struct	caps_rstr_raster

Macros
#define	FAV_ROTATION_NONE (0)

#define	FAV_ROTATION_COUNTERCLOCKWISE (-90)

#define	FAV_ROTATION_CLOCKWISE (+90)

Functions
int	caps_rstr_job_attach (struct caps_rasterizer rstr, int fd, struct caps_ppd_options_table ppd_options, const char *params)

void	caps_rstr_job_detach (struct caps_rasterizer *rstr)

struct caps_rstr_page_limits	caps_rstr_limits_get (struct caps_rasterizer *rstr)

void	caps_rstr_printer_feature_set (struct caps_rasterizer *rstr, enum caps_rstr_feature feature)

int	caps_rstr_page_get_next (struct caps_rasterizer rstr, const struct caps_rstr_page_desc *pg_desc)

int	caps_rstr_page_rasterize (struct caps_rasterizer rstr, const struct caps_rstr_page pg)

int	caps_rstr_raster_get (struct caps_rasterizer rstr, struct caps_rstr_raster desc)

const void *	caps_rstr_line_get (struct caps_rasterizer rstr, const struct caps_rstr_raster desc, unsigned line_no)

Detailed Description

Usage notes.

Process one document

Process one page

The page information was retrieved via the call to caps_rstr_page_get_next() and stored into the caps_rstr_page_desc. The printer driver should analyze this information and setup the caps_rstr_page to the printer's capabilities accordingly. caps_rstr_page will be used in the next step, e.g. caps_rstr_page_rasterize() (to rasterize the current page).

Attention: The information in caps_rstr_page_desc can change on a page by page base regarding orientation and page size for example.

Print one page

This is almost your job to convert the rastered input data into the data format the printer expects.

Macro Definition Documentation

◆ FAV_ROTATION_NONE

#define FAV_ROTATION_NONE (0)

There is no favoured rotation if the documents needs to be rotated to fit the print medium. The library is free in the rotation direction.

◆ FAV_ROTATION_COUNTERCLOCKWISE

#define FAV_ROTATION_COUNTERCLOCKWISE (-90)

If the documents needs to be rotated to fit the print medium, rotate it -90 ° (e.g counter clock wise) to meet printer requirements.

Left: view orientation, right: print orientation

Refer Predictable Print Rotation as well

◆ FAV_ROTATION_CLOCKWISE

#define FAV_ROTATION_CLOCKWISE (+90)

If the documents needs to be rotated to fit the print medium, rotate it +90 ° (e.g. clock wise) to meet printer requirements.

Left: view orientation, right: print orientation

Refer Predictable Print Rotation as well

Function Documentation

◆ caps_rstr_job_attach()

int caps_rstr_job_attach	(	struct caps_rasterizer *	rstr,
		int	fd,
		struct caps_ppd_options_table *	ppd_options,
		const char *	params
	)

Attach a printing job to a rasterizer engine

Parameters

[in,out]	rstr	The rasterizer engine
[in]	fd	The file descriptor of the document opened for reading (e.g. the print job)
[in]	ppd_options	Copy of the printer's PPD defaults
[in]	params	Printing parameter string (IPP style) (can be NULL)

Return values

0	On success
-ENOTSUP	Document format isn't supported
-EPERM	Printing of the document is prohibited (PDF has such a feature)
-ENODATA	Short on data to detect the MIME type
-EINVAL	Bad document format (broken content)
-ESPIPE	Used page-ranges print parameter lead to an empty print
negative	errno else (from a read() call for example)

This call attaches a job to the rasterizer.

This call selects the backend which is capable of rasterizing printing job's data format. E.g. it selects a PDF rasterizer if it is in Portable Document Format.

The required parameters can be retrieved from the coordinator via its caps_pp_document_desc and caps_pp_handle and:

the file descriptor via caps_pp_job_fh_get()
the printing parameter via caps_pp_job_parameter_get()
the PPD options via caps_pp_ppd_options_get()

Note: After a successful attach, you should call caps_rstr_limits_get() to see, if you can deal with the limitations the used rasterizer might has.; A returned -ESPIPE gives a hint, that the user has selected a page-ranges print parameter outside the amount of available pages in the document.; Does not return in case of memory failure.

Precondition: A rasterizer engine must be already created via caps_rstr_create()

Postcondition: When done, caps_rstr_job_detach() frees the resources

◆ caps_rstr_job_detach()

void caps_rstr_job_detach ( struct caps_rasterizer * rstr )

Detach the current job from the rasterizer engine and free resources

Parameters

[in] rstr The rasterizer engine

Frees all used resources:

the filehandle to the job's data is closed (parameter fd in call caps_rstr_job_attach())
the PPD option table is freed

Note: If the filehandle refers a self removing file (created via caps_helper_invisible_file_create()), it will remove the related file at this point of time.

Precondition: An already attached print job

◆ caps_rstr_limits_get()

struct caps_rstr_page_limits caps_rstr_limits_get ( struct caps_rasterizer * rstr )

Get the rasterizer dependend (static) limits for the attached document

Parameters

[in] rstr The rasterizer engine

Returns: The Limits

After attaching a job to a rastrizer it can report about limitiations it might have for this kind of document format.
For example a CUPS raster as an input document is limited to exactly one colour format: the one provided in the CUPS raster. Maybe your driver can deal with it - maybe not. This function can help you to see, if printing will be possible. if not, you should reject the job.

Note: If no job and no rasterizer is attached, all returned fields are zeroed out.

Postcondition: The returned limits are valid if a job is attached, e.g. a rasterizer according to the document type is available. Which is true if a previous caps_rstr_job_attach() has returned successfully.

◆ caps_rstr_printer_feature_set()

void caps_rstr_printer_feature_set	(	struct caps_rasterizer *	rstr,
		enum caps_rstr_feature	feature
	)

Enable a printer feature for the current print job

Parameters

[in]	rstr	The rasterizer engine
[in]	feature	Enabled feature for this job

Note: Can be called before a job is attached to the rasterizer

Precondition: Must be done prior the first call to caps_rstr_page_get_next()

◆ caps_rstr_page_get_next()

int caps_rstr_page_get_next	(	struct caps_rasterizer *	rstr,
		const struct caps_rstr_page_desc **	pg_desc
	)

Call for the next document's page information

Parameters

[in]	rstr	The rasterizer engine
[in,out]	pg_desc	Where to store the pointer to the page description

Return values

0	On success (page is valid)
-EOF	Premature end of document
-EINVAL	Rasterizer is in trouble with the requested page

This call will move forward in the document to the next page to print (or to its first page if called the first time).

In a simplex print job, this means always one side of a medium. In a duplex print job this could also mean to "move forward" to the opposite side of the current medium.

Be prepared and check the state machine related members in the returned pg_desc (like caps_rstr_page_desc::duplex_front, caps_rstr_page_desc::duplex_reverse or caps_rstr_page_desc::eject_medium) to get an idea what has to be done at this page.

The printer driver should use the information in pg_desc to setup its own part of the job and fill a caps_rstr_page to instruct the rasterizer in the next step (e.g. the call to caps_rstr_page_rasterize())

Note: The pg_desc member caps_rstr_page_desc::last_page signals if it is the last page, e.g. the printing job is finaly done after this page is printed.; The members caps_rstr_page_desc::medium_sz and caps_rstr_page_desc::medium_name might contain corrected and thus, unified values according to info read from libpaper.
This should help to simplify printer driver's descision what medium to select to print this page.

Precondition: A successfull call to caps_rstr_job_attach()

Postcondition: Don't call again, if the page from the previous call was marked as the last page to print.

◆ caps_rstr_page_rasterize()

int caps_rstr_page_rasterize	(	struct caps_rasterizer *	rstr,
		const struct caps_rstr_page *	pg
	)

Rasterize the page with all parameters into the memory

Parameters

[in]	rstr	The rasterizer engine
[in]	pg	The page setup how the rasterizer should convert the page into a raster

Return values

0	On success
-ENOTSUP	A setting or some settings in `pg` aren't possible.
-EINVAL	Failed to rasterize the pages content

This call lets the attached rasterizer convert the current page into a corresponding raster image according to settings in pg made by the printer driver. This will also consider related printing parameters shown in Supported Printing Parameter for the content of the page.

If this function fails, most of the time with -ENOTSUP due to impossible colour format selections. Thus, you should call caps_rstr_limits_get() to see, if there are limitations, you need to deal with or to reject the job.

Precondition: A successfull call to caps_rstr_page_get_next() (once per page)

◆ caps_rstr_raster_get()

int caps_rstr_raster_get	(	struct caps_rasterizer *	rstr,
		struct caps_rstr_raster *	desc
	)

Get the full description of the memory based raster image

Parameters

[in]	rstr	The rasterizer engine
[out]	desc	The description of the rasterized image

Return values

0	on success, e.g. `*desc` is valid
-EINVAL	Trouble with the rasterizer `*desc` is invalid

The dot data is always in the format described in desc->format. Refer header file libcapsshared.h for enum caps_colour_format dot details.

◆ caps_rstr_line_get()

const void * caps_rstr_line_get	(	struct caps_rasterizer *	rstr,
		const struct caps_rstr_raster *	desc,
		unsigned	line_no
	)

Get a pointer to a line of dots of the rastered image data

Parameters

[in]	rstr	The rasterizer engine
[out]	desc	The raster image data description
[in]	line_no	Raster line number to read out (0 … caps_rstr_raster::length) (must be valid!)

Returns: Pointer to the requested constant dot data

Note: Does not return in case of line_no is outside the length of the raster data

The returned pointer points into the raster data. The data should not be changed in any way nor the returned address freed after use.

Attention: The line length is desc->width dots and the size of each dot depends on the desc->cf mode. Refer caps_rstr_raster for details.

Data Structures

Macros

Functions

Detailed Description

Process one document

Process one page

Print one page

Macro Definition Documentation

◆ FAV_ROTATION_NONE

◆ FAV_ROTATION_COUNTERCLOCKWISE

◆ FAV_ROTATION_CLOCKWISE

Function Documentation

◆ caps_rstr_job_attach()

◆ caps_rstr_job_detach()

◆ caps_rstr_limits_get()

◆ caps_rstr_printer_feature_set()

◆ caps_rstr_page_get_next()

◆ caps_rstr_page_rasterize()

◆ caps_rstr_raster_get()

◆ caps_rstr_line_get()