caps_rstr_raster Struct Reference

Data Fields
unsigned	medium_width
unsigned	medium_length
unsigned	margin_bottom
unsigned	margin_right
unsigned	margin_top
unsigned	margin_left
unsigned	offset_top
unsigned	offset_left
unsigned	width
unsigned	length
unsigned	dot_size
enum caps_colour_format	cf
const void *	buffer
ptrdiff_t	line_length

Detailed Description

Information about the rasterized image and how to print it on the medium

The rasterized image can have every format. It is unpredictable, since the rasterized document controles it. Don't rely ony any specific format!

This raster information provides everything to print it to the target medium, even if the rasterized image is smaller than the target medium.

The main information in caps_rstr_raster is the target medium size everything is calculated from and all results made for.

medium_width and medium_length defines the format of the target medium in [dots] or [lines] at the (previously) requested resolution.

The full target media

margin_bottom, margin_right, margin_top and margin_left define the margins at all four medium edges where nothing should be printed to. Their values are meant in [dots], respectively [lines].

Target media with restricted margin areas

The rasterized image is stored into memory at the position where the member buffer points to. This is read only memory for you!

The rasterized image size is defined by the members width and length in [dots], respectively [lines].

Some kind of raster image

The member dot_size defines the size of one dot in [bytes] (depending on the colour mode).

Attention

For the monochrome mode it even states '1' here which isn't correct. In the monochrome mode you need to know the size of a dot is one eights of a byte.

To be able to jump from one line to its next one in this rasterized image, the member line_length defines this offset. Its unit is [bytes].

As an alternative to access each line in the raster image you can use caps_rstr_line_get() instead.

Note

The length of each line is aligned to multiple of eight bytes on 32 Bit machines and multiple of sixteen bytes on 64 machines. The alignment of the buffer pointer is the same.

The rasterized image has a colour format, the dots are encoded in. The member cf defines this colour format.

And now the details:

• the rasterized image can be smaller than the target medium.

Now the members offset_top and offset_left come into play.

Placement of the raster image inside the medium

For all lines of the medium:

• there is no line to print to the medium, until you reach medium's line number offset_top
  • you can use this feature, if your printer has special commands to print empty lines. This might improve the print speed, due to data reduction and might reduce processing time as well, since the line content is predictable
• rasterized image's top line must be printed beginning with medium's line number offset_top
• all lines from the rasterized image are now to be printed up to rasterized image's length
• after that again, there is no line to print to the medium until the end of the medium.
  • like at the top of the medium, you can use printer features to print empty lines

For each line:

• there is no dot to print until you reach medium's collumn offset_left
• then medium's collumn starts here with the left dot of the rasterized image
• medium's collumn stops when rasterized image's width is reached
• again, after that, there is no dot to print until the medium's right edge

Empty area around the raster image

Margins need to be considered:

The rasterized image might contain the margins. So, expect dots in these areas, where no dots should be on the print medium. You need to wipe-out these margins by yourself. You even cannot rely on the fact, the rasterized image is smaller than the imageable area of the print medium, and the offsets will ensure the margins as well.

Some notes about buffer:

It is of type void*, but points to different dot formats depending on the member cf.

Colour mode	dot structure
CAPS_CF_MONOCHROME0	caps_dot_monochrome
CAPS_CF_MONOCHROME1	caps_dot_monochrome
CAPS_CF_GREY	caps_dot_grey
CAPS_CF_RGB	caps_dot_rgb
CAPS_CF_CMYK	caps_dot_cmyk

Note

Due to rounding, the width and length values can vary from the user defined values in struct caps_rstr_page

Attention

Due to rasterizer restrictions the real dot format may differ from the one the user has requested.

Field Documentation

medium_width

unsigned medium_width

Medium format's width, e.g. full [dot] count

medium_length

unsigned medium_length

Medium format's length, e.g. full [line] count

margin_bottom

unsigned margin_bottom

Amount of empty [lines] at the bottom edge of the medium

margin_right

unsigned margin_right

Amount of empty [dots] at the right edge of the medium

margin_top

unsigned margin_top

Amount of empty [lines] at the top edge of the medium

margin_left

unsigned margin_left

Amount of empty [dots] at the left edge of the medium

offset_top

unsigned offset_top

Empty [lines] from medium's top edge until the raster image starts

offset_left

unsigned offset_left

Empty [dots] from medium's left edge until the raster image starts

width

unsigned width

Raw raster image [dot] count in each line, the first dot (the left one) is always valid

Note

BUG! Connot be wider! Can be wider than the medium_width, offset_left might be negative in this case

length

unsigned length

Raw raster image [line] count, buffer points to

Note

BUG! cannot be higher! Can be heigher than the medium_length, offset_top might be negative in this case

dot_size

unsigned dot_size

Size of one dot in [bytes], buffer points to.

Attention

monochrome is special and uses '1' here, but covers 8 dots in this case!

cf

enum caps_colour_format cf

Raw raster image colour format. This defines the dot format buffer points to

buffer

const void* buffer

Pointer to the raw raster image data, left, top coordinate

line_length

ptrdiff_t line_length

Length of one line of the raw raster image in [bytes], buffer points to

---

The documentation for this struct was generated from the following file:

• libcapsraster/src/libcapsraster-api.h