Setting up the rasterizer for the current page

Setup the information the rasterizer requires to rasterize the document page in a way your printer needs it. More...

Functions
int	caps_drv_print_medium_default_setup (struct caps_drv *cdrv)
int	caps_drv_print_medium_colour_format_set (struct caps_drv *cdrv, enum caps_colour_format cf)
int	caps_drv_print_medium_size_set (struct caps_drv *cdrv, struct caps_rect page_size)
int	caps_drv_print_medium_favoured_rotation_set (struct caps_drv *cdrv, int rot)
int	caps_drv_print_medium_width_set (struct caps_drv *cdrv, double min, double max)
int	caps_drv_print_medium_length_set (struct caps_drv *cdrv, double min, double max)
int	caps_drv_print_medium_margins_set (struct caps_drv *cdrv, struct caps_area margins)
int	caps_drv_print_medium_resolution_set (struct caps_drv *cdrv, double x_res, double y_res)

Detailed Description

All these functions hide the details of libcapsraster behind. You can call them in the caps_generic_driver::page_setup() callback.

Function Documentation

caps_drv_print_medium_default_setup()

int caps_drv_print_medium_default_setup

(

struct caps_drv *

cdrv

)

Setup the details in a generic manner how to rasterize the next page for printing

Parameters

[in]

cdrv

libcapsdriver handle

Return values

0	On success (but read below)
-EINVAL	Invalid print colour format (this means the PPD and/or libcapsppd is/are broken)
-ENOTSUP	The requested print colour format isn't supported

You can use this call to setup the rasterization of the current page. If your printer is an ordinary short-edge-first-printer for ordinary media formats, you can use this function.

You can still overwrite some or all of these settings with caps_drv_print_medium_size_set(), caps_drv_print_medium_favoured_rotation_set(), caps_drv_print_medium_margins_set(), caps_drv_print_medium_colour_format_set() and caps_drv_print_medium_resolution_set().

Read Dealing with colour formats about details.

Precondition

Can be called within the caps_generic_driver::page_setup() callback.

Todo:

Add info what info will be set and used.

caps_drv_print_medium_colour_format_set()

int caps_drv_print_medium_colour_format_set	(	struct caps_drv *	cdrv,
		enum caps_colour_format	cf
	)

Setup the rasterize colour format for the next page

Parameters

[in]	cdrv	libcapsdriver handle
[in]	cf	The colour format the rasterizer should create the raster in

Return values

0	On success

Precondition

You should check first against the rasterizer limits (caps_drv_job_limits_get()) if your requested colour format is supported. Else the rasterizer will reject it later on.

caps_drv_print_medium_size_set()

int caps_drv_print_medium_size_set	(	struct caps_drv *	cdrv,
		struct caps_rect	page_size
	)

Setup the target medium's size in [pts]

Parameters

[in]	cdrv	libcapsdriver handle
[in]	page_size	The medium size

Return values

0	On success

This defines the size of the final raster. And in conjunction with the margins, it defines the printable area.

The final raster will cover this size at the given resolution.

Note

Both size and area are important for printing parameters like fittopage for example.

Attention

Experimetal only. Do not use, yet.

Todo:

Add images for the results when fittopage is used

Add link to the printing parameter

caps_drv_print_medium_favoured_rotation_set()

int caps_drv_print_medium_favoured_rotation_set	(	struct caps_drv *	cdrv,
		int	rot
	)

Parameters

[in]	cdrv	libcapsdriver handle
[in]	rot	0, -90 or +90

Return values

0	On success

caps_drv_print_medium_width_set()

int caps_drv_print_medium_width_set	(	struct caps_drv *	cdrv,
		double	min,
		double	max
	)

Set the minimal and maximal width the raster can have in [pts].

Parameters

[in]	cdrv	The framework handle
[in]	min	The minimal width the raster must cover
[in]	max	The maximal width the raster can cover

Return values

0	On success

For example a DIN A4 medium has a fixed width and your printer wants always the full pixel data in a line, even if not all pixels are covered by the raster image.
In this case set min and max to the same value. It could be a micro optimization to save bandwidth to only send the data with to be printed pixels. In this case the width of the raster image may only has the size of the really required width.
In this case set the min and max width to their correspoding values.

A different use case is a label printer with variable axis. For example if the printer can cut its medium at every width. In this case the min and max values are describing/considering physical or firmware limitations.

caps_drv_print_medium_size_set() sets min/max the same for both axis at once.

Refer caps_ppd_base::media_coverage for possible usage?

Attention

Experimetal only. Do not use, yet.

caps_drv_print_medium_length_set()

int caps_drv_print_medium_length_set	(	struct caps_drv *	cdrv,
		double	min,
		double	max
	)

Set the minimal and maximal length the raster can have in [pts].

Parameters

[in]	cdrv	The framework handle
[in]	min	The minimal length the raster must cover
[in]	max	The maximal length the raster can cover

Return values

0	On success

For example a DIN A4 medium has a fixed length and your printer wants always all lines of data for the full length, even if not all lines are covered by the raster image.
In this case set min and max to the same value.

It could be a micro optimization to save bandwidth to only send the lines with to be printed pixels. In this case the length of the raster image may only has the size of the really required length.
In this case set the min and max length to their correspoding values.

A different use case is a label printer with variable axis. For example if the printer can cut its medium at every length. In this case the min and max values are describing/considering physical or firmware limitations.

caps_drv_print_medium_size_set() sets min/max the same for both axis at once.

Refer caps_ppd_base::media_coverage for possible usage?

Attention

Experimetal only. Do not use, yet.

caps_drv_print_medium_margins_set()

int caps_drv_print_medium_margins_set	(	struct caps_drv *	cdrv,
		struct caps_area	margins
	)

Setup the medium's margins in [pts]

Parameters

[in]	cdrv	libcapsdriver handle
[in]	margins	Margin settings

Return values

0	On success

This defines the margins to keep free from printed dots.

This defines the printable area in conjunction with the medium's size (refer caps_drv_print_medium_size_set()) it is important for printing parameters like fittopage for example.

Misuse of caps_area! It defines four margins, not an area inbetween them!

Todo:

Add images for the results when fittopage is used

Add link to the printing parameter

caps_drv_print_medium_resolution_set()

int caps_drv_print_medium_resolution_set	(	struct caps_drv *	cdrv,
		double	x_res,
		double	y_res
	)

Setup the resolution for the raster

Parameters

[in]	cdrv	libcapsdriver handle
[in]	x_res	Horizontal resolution
[in]	y_res	Vertical resolution

Return values

0	On success

Horizontal und vertical resolution can be set independently.