Get the full medium rasterized dot data to print

Reading the full medium raster line by line for your own processing. More...

Functions
ssize_t	caps_drv_raster_line_length_get (struct caps_drv *cdrv)
void *	caps_drv_raster_line_copy_get (struct caps_drv *cdrv, void *line_buf, unsigned line_no)
unsigned	caps_drv_raster_width_get (struct caps_drv *cdrv)
unsigned	caps_drv_raster_length_get (struct caps_drv *cdrv)
enum caps_colour_format	caps_drv_raster_cf_get (struct caps_drv *cdrv)

Detailed Description

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

In the caps_generic_driver::page_print callback you get access to a raster which covers the whole medium size you have set in the caps_generic_driver::page_setup's callback via caps_drv_print_medium_size_set(). Since the raster size depends on the medium size and the print resolution you always need the following functions to retrieve this information from the library.

Left: full medium raster Right: raw raster

Function Documentation

caps_drv_raster_line_length_get()

ssize_t caps_drv_raster_line_length_get

(

struct caps_drv *

cdrv

)

Calculate the amount of bytes required for a copy of one full line of dot data

Parameters

[in]

cdrv

libcapsdriver handle

Return values

Positive	Count of bytes for a full line of dots
Negative	No raster available, yet (it seems you called it prior the rasterizer did its job)

The required size depends on the raster's width and the colour mode.

The amount of required bytes can be used if you want to allocate your own dot data line buffer. Else it is handled internally in caps_drv_raster_line_copy_get().

Precondition

Can be called in the caps_generic_driver::page_print callback

caps_drv_raster_line_copy_get()

void * caps_drv_raster_line_copy_get	(	struct caps_drv *	cdrv,
		void *	line_buf,
		unsigned	line_no
	)

Copy a line of dots from the final raster into a buffer for further processing

Parameters

[in]	cdrv	libcapsdriver handle
[in]	line_buf	Buffer to write the dot data to (can be NULL to allocate a buffer internally, read below)
[in]	line_no	Line number to read out (0 … (caps_drv_raster_length_get() - 1)) (must be valid!)

Returns

Pointer to the dot data (line_buf or malloc'ed buffer)

This line contains the dot count for the full width of the target medium you have defined in caps_drv_print_medium_size_set(). It includes the margins where all dots are already wiped-out, e.g. a colour value is set in this area which means 'do not print anything here'. Refer CAPS_CF_MONOCHROME0/CAPS_CF_MONOCHROME1, caps_dot_grey, caps_dot_rgb and caps_dot_cmyk for the corresponding 'do not print anything here' values.

Note

If line_buf is NULL, the required memory for the dot data is malloc'ed inside this function and returned. You can re-use this buffer again for the next calls for the same page.

If you want to provide your own buffer, it must have a minimal size, because caps_drv_raster_line_copy_get() isn't able to detect if it might copy data behind the end of the buffer. The expected size is the product of the horizontal target medium dot count and the size of each dot. You can retrieve the horizontal dot count via caps_drv_raster_width_get().

Minimal size of line_buf for a specific colour format:

• CAPS_CF_MONOCHROME0: (caps_drv_raster_width_get() + 7) / 8 (e.g. round up to full bytes)
• CAPS_CF_MONOCHROME1: (caps_drv_raster_width_get() + 7) / 8 (e.g. round up to full bytes)
• CAPS_CF_GREY: caps_drv_raster_width_get() * sizeof(caps_dot_grey)
• CAPS_CF_RGB: caps_drv_raster_width_get() * sizeof(caps_dot_rgb)
• CAPS_CF_CMYK: caps_drv_raster_width_get() * sizeof(caps_dot_cmyk)

If you don't want to calculate it by your own, you can call the convenience function caps_drv_raster_line_length_get() instead.

Precondition

Can be called in the caps_generic_driver::page_print callback

Postcondition

If the buffer is allocated inside this function, it is correctly aligned and padded for the architecture (eight or sixteen bytes).

If the buffer was allocated inside this function, it needs to be freed afterwards by a simple free().

Internal information

Since libcapsraster creates rasters which can be smaller or larger than the available medium, we need to reconstruct a medium related line here from the available information about the raster.

Line restoring to cover the full medium width:

|<----------------------- caps_rstr_raster::medium_width ------------------------------>|
|<->| caps_rstr_raster::margin_left                  caps_rstr_raster::margin_right |<->|
|****--------------|#################################################|--------------****|
|    wiped out     |<-------- caps_rstr_raster::width -------------->|    wiped out
|<---------------->| caps_rstr_raster::offset_left

Note

Horizontal margins can be both zero. And caps_rstr_raster::width can be larger than caps_rstr_raster::medium_width at the same time.
Hopefully this routine now deals with it.

caps_drv_raster_width_get()

unsigned caps_drv_raster_width_get

(

struct caps_drv *

cdrv

)

Get the width in [dots] of the final raster

Parameters

[in]

cdrv

libcapsdriver handle

This width corresponds to the medium width and the print resolution set via caps_drv_print_medium_size_set() and caps_drv_print_medium_resolution_set() in the caps_generic_driver::page_setup callback.

Precondition

Can be called in the caps_generic_driver::page_print callback

caps_drv_raster_length_get()

unsigned caps_drv_raster_length_get

(

struct caps_drv *

cdrv

)

Get the length in [lines] of the final raster

Parameters

[in]

cdrv

libcapsdriver handle

This length corresponds to the medium length and the print resolution set via caps_drv_print_medium_size_set() and caps_drv_print_medium_resolution_set() the caps_generic_driver::page_setup callback.

Precondition

Can be called in the caps_generic_driver::page_print callback

caps_drv_raster_cf_get()

enum caps_colour_format caps_drv_raster_cf_get

(

struct caps_drv *

cdrv

)

Get the colour format of the final raster

Parameters

[in]

cdrv

libcapsdriver handle

Precondition

Can be called in the caps_generic_driver::page_print callback