Library internal API. More...

Data Structures
struct	rstr_provider
	Callbacks of one rasterizer. More...

struct	raster_adapt_preparation
	Required adaptions from the document's content to the raster content. More...

struct	rstr_print_state

struct	doc_page_range_entry

struct	doc_range_list

struct	doc_page_range

struct	document_desc
	Parameter description for the to be processed print job. More...

struct	caps_rasterizer
	Declare the externally transparent structure for internal use. More...

Macros
#define	caps_print_debug(fmt, ...)

#define	DSO_VISIBLE

#define	ARRAY_SIZE(x) (sizeof(x)/sizeof(x[0]))

#define	_(string) (string)

#define	NLS_(string) (string)

#define	JOB_ORIENTATION_UNSET 360

#define	RSTR_ALL_CFORMATS (/CAPS_CF_MONOCHROME0 \| CAPS_CF_MONOCHROME1 \|/ CAPS_CF_GREY \| CAPS_CF_RGB \| CAPS_CF_CMYK)

#define	ptsperinch 72.0

#define	RECT_IS_PORTRAIT 1

#define	RECT_IS_LANDSCAPE 0

Enumerations
enum	rstr_tweaks { RSTRS_INHERIT_FILEDESC = 1 }
	Rasterizer tweaks. More...

enum	caps_rstr_alignment { CAPS_RSTR_ALIGN_CENTER = 0 , CAPS_RSTR_ALIGN_TOP = 1 , CAPS_RSTR_ALIGN_BOTTOM = 2 , CAPS_RSTR_ALIGN_LEFT = 4 , CAPS_RSTR_ALIGN_RIGHT = 8 }

enum	caps_rstr_orientation { CAPS_RSTR_ORIENT_HEAD_UP = 0 , CAPS_RSTR_ORIENT_LANDSCAPE = 1 , CAPS_RSTR_ORIENT_HEAD_DOWN = 2 , CAPS_RSTR_ORIENT_SEASCAPE = 3 }

Functions
void	handle_initial_page (struct document_desc *job, unsigned pcnt)

int	handle_next_page (struct document_desc *job)

void	page_setup (struct document_desc job, struct raster_adapt_preparation setup, const struct caps_rstr_page *page)

void	simplex_next_page (struct document_desc *job)

void	simplex_collating_next_page (struct document_desc *job)

void	duplex_collating_next_page (struct document_desc *job)

void	duplex_next_page (struct document_desc *job)

unsigned	job_page_get_next (struct document_desc *job, unsigned cpage)

unsigned	job_page_count_calculate (struct document_desc *job, unsigned pgs)

struct document_desc *	job_create (int fd, struct caps_ppd_options_table ppd_options, const char params)

void	job_destroy (struct document_desc *job)

int	job_file_seek (struct document_desc *job, off_t offset)

ssize_t	job_file_read (struct document_desc job, void buf, size_t count)

bool	job_is_duplex (struct document_desc *job)

bool	job_is_collating (struct document_desc *job)

unsigned	job_copies_get (struct document_desc *job)

static int	rect_orient (const struct caps_rect *rect)

static struct caps_rect	rect_tip_over (const struct caps_rect r)

static unsigned	pts_to_pixel (double pts, double resolution)

Detailed Description

Copyright: GNU General Public License 2 or later

Author: Jürgen Borleis

Version: 1.0.0

Warning: Use as experimental

Macro Definition Documentation

◆ caps_print_debug

#define caps_print_debug	(	fmt,
		...
	)

output a debug trace message. Used to track program states in even more detail

◆ DSO_VISIBLE

#define DSO_VISIBLE

◆ ARRAY_SIZE

#define ARRAY_SIZE ( x ) (sizeof(x)/sizeof(x[0]))

◆ _

#define _ ( string ) (string)

◆ NLS_

#define NLS_ ( string ) (string)

◆ JOB_ORIENTATION_UNSET

#define JOB_ORIENTATION_UNSET 360

◆ RSTR_ALL_CFORMATS

#define RSTR_ALL_CFORMATS (/*CAPS_CF_MONOCHROME0 | CAPS_CF_MONOCHROME1 |*/ CAPS_CF_GREY | CAPS_CF_RGB | CAPS_CF_CMYK)

The colour raster formats supported by default

Bug:: Both monochrome formats aren't supported anymore (at least not by default)

◆ ptsperinch

#define ptsperinch 72.0

Define points per inch

◆ RECT_IS_PORTRAIT

#define RECT_IS_PORTRAIT 1

◆ RECT_IS_LANDSCAPE

#define RECT_IS_LANDSCAPE 0

Enumeration Type Documentation

◆ rstr_tweaks

enum rstr_tweaks

Some special tweaks how a rasterizer deals with its file data and the callbacks. Used to mark special requirements to inform the framework about these requirements.

Enumerator
RSTRS_INHERIT_FILEDESC	Rasterizer inherits the document file descriptor and will close it by itself

◆ caps_rstr_alignment

enum caps_rstr_alignment

CAPS_RSTR_ALIGN_TOP and CAPS_RSTR_ALIGN_LEFT must be possible at the same time

Enumerator
CAPS_RSTR_ALIGN_CENTER
CAPS_RSTR_ALIGN_TOP
CAPS_RSTR_ALIGN_BOTTOM
CAPS_RSTR_ALIGN_LEFT
CAPS_RSTR_ALIGN_RIGHT

◆ caps_rstr_orientation

enum caps_rstr_orientation

Enumerator
CAPS_RSTR_ORIENT_HEAD_UP	imaged across the short edge of the medium
CAPS_RSTR_ORIENT_LANDSCAPE	imaged across the long edge of the medium
CAPS_RSTR_ORIENT_HEAD_DOWN	imaged across the short edge of the medium, head down
CAPS_RSTR_ORIENT_SEASCAPE	imaged across the long edge of the medium, head down

Function Documentation

◆ handle_initial_page()

void handle_initial_page	(	struct document_desc *	job,
		unsigned	pcnt
	)

Setup information prior processing a printing job

Parameters

[in,out]	job	Infos about the print job
[in]	pcnt	Full page count of this document (from the selected rasterizer)

Handles simplex and duplex prints, with collation or non-collating and one copy (per medium or per document) or more than one copies (per medium or per document).

Here, the full amount of to be printed pages gets calculated as well. Refer caps_pp_job_progression_report() for what it's good for…

Note: Keep caps_rstr_page_desc::copies = '0' here, to enter the printing loop correctly

Precondition: job_page_count_calculate() must be already called

◆ handle_next_page()

int handle_next_page ( struct document_desc * job )

Handle all these ugly details to calculate the next page to print

Parameters

[in,out] job Infos about the print job

Return values

0	A new page was selected and must be rasterized
1	The same page was kept, no rasterizing required.

◆ page_setup()

void page_setup	(	struct document_desc *	job,
		struct raster_adapt_preparation *	setup,
		const struct caps_rstr_page *	page
	)

Setup all required parameters for the current page in order to rasterize it in the next step

Parameters

[in,out]	job	Collected job info
[out]	setup	Setup how to raster the page
[in]	page	The crude print configuration from the printer driver

The calculations here are made when the printer driver calls caps_rstr_page_rasterize().

What we have:

the size and orientation of the source page (from the current document's page)
the settings from the user's printing parameters
the size and orientation of the target medium (from the printer driver)

What we calculate here:

how to convert the source page into the destination page
- depending on various flags this includes:
  - rotation
  - scaling
  - cropping
- the flags are
  - some defaults if no related user's printing parameters are given
  - the user's printing parameters itself
  - restrictions the printer has

Note: Called by caps_rstr_page_rasterize()

Todo:: Deal with fidelity

◆ simplex_next_page()

void simplex_next_page ( struct document_desc * job )

Move forward in the document for simplex printing

Parameters

[in,out] job Infos about the print job

Non-collating use case.

◆ simplex_collating_next_page()

void simplex_collating_next_page ( struct document_desc * job )

Move forward in the document for simplex printing and repeat the whole document on demand

Parameters

[in,out] job Infos about the print job

This routine covers the "Simplex printing happens with 1…n copies and collating" use case.

Collating usecase. If copies are required, it was already set in handle_initial_page()

If rstr_print_state::copies_to_be_done is '1' it behaves the same like simplex_simple()

Attention: Progression reporting in handle_next_page() relies on this function's behaviour!

◆ duplex_collating_next_page()

void duplex_collating_next_page ( struct document_desc * job )

Print rstr_print_state::copies_to_be_done of a document

Parameters

[in,out] job Infos about the print job

This function is mustbe called in a loop until the last page of the last copy was printed. The last page of the last copy is marked via caps_rstr_page_desc::last_page == 1

rstr_print_state::copies_to_be_done can be '1' as well

Precondition: state must be initialized to 0 on the first call

Note: Can be called for the first page as well (rstr_print_state::current_page == 0)

◆ duplex_next_page()

void duplex_next_page ( struct document_desc * job )

Print non-collating duplex with or without copies

Parameters

[in,out] job Infos about the print job

◆ job_page_get_next()

unsigned job_page_get_next	(	struct document_desc *	job,
		unsigned	cpage
	)

Move to the next to be printed page in the document according to the existing page ranges

Parameters

[in,out]	job	The information collection about the job
[in]	cpage	Current page (or: last already printed page, e.g. page from the last call), 0 … UINT_MAX

Return values

Number	The number of the next to be printed page
0	If there are no more pages in the document to print

The page value of 0 has a special meaning: this returns the first to be printed page in the document.

In order to step through the document, start with page = 0, and continue to call this function with the returned value of the last call.

Precondition: At least one page range must exist: "1-UINT_MAX" if user has none defined. ensure_one_page_range() does the job.; job_page_count_calculate() must be already called

◆ job_page_count_calculate()

unsigned job_page_count_calculate	(	struct document_desc *	job,
		unsigned	pgs
	)

Calculate the amount of to be printed pages from the document in one turn

Parameters

[in,out]	job	The information collection about the job
[in]	pgs	The document's last page number

Return values

Positive	Amount of to be printed pages
'0'	Nothing to print

If a full page range is given and the document has 10 pages, the calculation is simple. But if pages ranges are given and they restrict the pages to be printed, a real calculation is required.

Note: If the retun value is '0', it means the user has selected an invalid page range. E.g. the selected page range(s) are not part of the document

Attention: This calculation doesn't honor copies. Takes the result like copies=1

Precondition: The print range entries must be valid (e.g. already checked).

Todo:: Honor duplex print which is differently ("pages" versus "media")

◆ job_create()

struct document_desc * job_create	(	int	fd,
		struct caps_ppd_options_table *	ppd_options,
		const char *	params
	)

Create a new job data collection

Parameters

[in]	fd	The documents file descriptor for reading
[in]	ppd_options	The job's corresponding default PPD settings
[in]	params	The print parameter (can be NULL)

Return values

Pointer A pointer to a dynamic job data collection structure

Creates a job and pre-process the ppd_options and params.

Note: Does not return in case of a memory failure; The ppd_options table will be freed by job_destroy()

Postcondition: Needs to be freed with job_destroy() when done

◆ job_destroy()

void job_destroy ( struct document_desc * job )

Free job related data

Parameters

[in] job The job data collection to destroy

Frees the related resources and closes the document related file descriptor on demand

◆ job_file_seek()

int job_file_seek	(	struct document_desc *	job,
		off_t	offset
	)

Wrapper to read some data from the document

Parameters

[in]	job	The job data collection
[in]	offset	The read offset in the document's file

Return values

0	Successful
Negative	An errno code from the lseek syscall

◆ job_file_read()

ssize_t job_file_read	(	struct document_desc *	job,
		void *	buf,
		size_t	count
	)

Wrapper to read some data from the document

Parameters

[in]	job	The job data collection
[in,out]	buf	Where to store the read data
[in]	count	Size in bytes of `buf`

Return values

Positive	The count of bytes read from the file into `buf`
Negative	An errno code from the read syscall

◆ job_is_duplex()

bool job_is_duplex ( struct document_desc * job )

Check if this job should be printed in duplex mode

Parameters

[in] job The job data collection

Return values

true	Print in duplex mode
false	Print in simplex mode

◆ job_is_collating()

bool job_is_collating ( struct document_desc * job )

Check if this job should be printed in collating mode

Parameters

[in] job The job data collection

Return values

true	Print collated
false	Print non-collated

◆ job_copies_get()

unsigned job_copies_get ( struct document_desc * job )

Read the amount of media copies to print

Parameters

[in] job The job data collection

Returns: Amount of copies to print (never '0')

TODO can this ever happen?

◆ rect_orient()

static int rect_orient ( const struct caps_rect * rect )

inlinestatic

Return the crude orientation of the given recangle defintion

Parameters

[in] rect The size defintion

Return values

RECT_IS_PORTRAIT	The `rect` defines a portrait orientation
RECT_IS_LANDSCAPE	The `rect` defines a landscape orientation

The rect's caps_rect::width is always expected as its leading edge. E.g. it will be printed first. And thus, its size is the reference for the portrait/landscape detection.

A square page is always detected as portrait.

◆ rect_tip_over()

static struct caps_rect rect_tip_over ( const struct caps_rect r )

inlinestatic

Tip over the rectangle information

Parameters

[in] r The rectangle information to tip over

Returns: The tip over rectangle information

◆ pts_to_pixel()

static unsigned pts_to_pixel	(	double	pts,
		double	resolution
	)

inlinestatic

Convert Postscript [Points] (1/72 inch) to [dots] at the given resolution

Parameters

[in]	pts	Postscript Points to convert
[in]	resolution	Dots Per Inch (DPI)

Returns: Dot count

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ caps_print_debug

◆ DSO_VISIBLE

◆ ARRAY_SIZE

◆ _

◆ NLS_

◆ JOB_ORIENTATION_UNSET

◆ RSTR_ALL_CFORMATS

◆ ptsperinch

◆ RECT_IS_PORTRAIT

◆ RECT_IS_LANDSCAPE

Enumeration Type Documentation

◆ rstr_tweaks

◆ caps_rstr_alignment

◆ caps_rstr_orientation

Function Documentation

◆ handle_initial_page()

◆ handle_next_page()

◆ page_setup()

◆ simplex_next_page()

◆ simplex_collating_next_page()

◆ duplex_collating_next_page()

◆ duplex_next_page()

◆ job_page_get_next()

◆ job_page_count_calculate()

◆ job_create()

◆ job_destroy()

◆ job_file_seek()

◆ job_file_read()

◆ job_is_duplex()

◆ job_is_collating()

◆ job_copies_get()

◆ rect_orient()

◆ rect_tip_over()

◆ pts_to_pixel()