Helper functions

Wrappers to avoid some libraries to be used explicitly. More...

Functions
const char *	caps_rstr_format_name_get (const struct caps_rect *size)
struct caps_rect	caps_rstr_format_size_get (const char *format_name)
int	caps_rstr_format_validate (const char *format_name)
int	caps_rstr_page_default_setup (struct caps_rasterizer *rstr, struct caps_rstr_page *pg)
int	caps_rstr_predictive_size_get (struct caps_rasterizer *rstr, struct caps_rect size, struct caps_rect *psize)

Detailed Description

Some features are already supported by different libraries. To avoid to link against them just to make use of one of their API functions, these wrappers do it for you instead.

Function Documentation

caps_rstr_format_name_get()

const char * caps_rstr_format_name_get

(

const struct caps_rect *

size

)

Get the medium format name with a specific size

Parameters

[in]

size

The size information (in [pts])

Returns

The name of the format

Returns the best matching medium format name like A4 or Letter for the specific size. This is a convenience function and a wrapper around libpaper and the retured medium format name is more or less guessed.

If it returns "custom", nobody has a clue what kind of format it is. Be prepared!

Note

size can be in every orientation

The opposite is caps_rstr_format_size_get()

caps_rstr_format_size_get()

struct caps_rect caps_rstr_format_size_get

(

const char *

format_name

)

Get dimension information of a specific medium format (in portrait orientation)

Parameters

[in]

format_name

Format name of the medium (like A4 or Letter)

Returns

The size information for format_name

If the medium format in format_name isn't known, the returned size will be 0.0 in both axis (e.g. empty). Refer CAPS_REC_IS_EMPTY to catch this case.

Note

This is a wrapper around libpaper

The opposite is caps_rstr_format_name_get()

Precondition

Refer paperconf -a for valid paper format names

caps_rstr_format_validate()

int caps_rstr_format_validate

(

const char *

format_name

)

Check if the given medium format name is a valid one (e.g. "known")

Parameters

[in]

format_name

Format name of the medium to check (like A4 or Letter)

Return values

0	If the medium format name is valid/known
negative	errno value else

Note

This is a wrapper around libpaper and for convinience.

Precondition

Refer paperconf -a for valid paper format names

caps_rstr_page_default_setup()

int caps_rstr_page_default_setup	(	struct caps_rasterizer *	rstr,
		struct caps_rstr_page *	pg
	)

Setup the details in a generic manner how to raster the next page for you

Parameters

[in]	rstr	The rasterizer engine
[out]	pg	Where to store the default settings how to raster the next page

Return values

0	On success (*next_page is valid)
-EINVAL	Invalid colour format
-ENOTSUP	Colour format for the specific MIME type not supported

You can use this call to initialize your caps_rstr_page structure in a generic way. If your printer is an ordinary printer for ordinary media formats, you can use this function. Call it when caps_rstr_page_get_next() returned and you are going to call caps_rstr_page_rasterize() next.

After the call, all members in caps_rstr_page are set to default values and you can still modify them as you like or your printer requires.

Note

For the case this function returns -ENOTSUP everything is set including the user selected colour format. Only the rasterizer doesn't support this colour format. The selected but not supported colour format is reported in caps_rstr_page::cf. If you can switch over to a different one, change this member to a colour format the rasterizer supports. And emulate the user selection afterwards. Or reject the job, if you can't deal with a different colour format.

Since

1.1.0 without the base printer description parameter

caps_rstr_predictive_size_get()

int caps_rstr_predictive_size_get	(	struct caps_rasterizer *	rstr,
		struct caps_rect	size,
		struct caps_rect *	psize
	)

Make a prediction about the size of the rastered page

Parameters

[in]	rstr	The rasterizer engine
[in]	size	The possible or known size component. The unknown edge should be '0.0'
[out]	psize	Predicted size of the raster

Return values

0	psize contains a size which should be used as the target raster
-EINVAL	No way to predict the missing edge (*psize is invalid)
-ENODATA	Both edges in size are zero, cannot calculate (*psize is invalid)
-EAGAIN	FIXME (*psize is invalid)

On one hand:

Life is easy if:

• the size of the available print medium is known - and fixed.
• the document should be printed in a 1:1 scale.

And then … there are details 🤦

What should happen if one of the coordinates is free? Free means, there is only a minimal and a maximal restriction in one or both coordiates. This is the case with label printers with a continuous medium. They can cut at every wanted length (the length is an example here).

On the other hand there are user settings like "fit to page". And in this case with label printers with a continuous medium a "page" is a moving target.

Attention

Experimental API. Expect everything than stability! And expect it fails!

Todo:

Do the calculation of the missed edge on the printer parameters