The raster delivery interface from the Harlequin RIP core uses the pagebuffer device. More...

Files
file	swraster.h
	Header file definition Core raster delivery control and interface.

Data Structures
struct	RASTER_COLORANT
	Structure describing raster layout for a single colorant mapped to a channel (data stream). More...

struct	RASTER_CHANNEL
	Structure describing raster layout for a single channel (data stream) in a plane. More...

struct	RASTER_PLANE
	Structure describing raster layout for a single plane (contiguous block of memory) in a frame. More...

struct	RASTER_FRAME
	Structure describing raster layout for a single frame in a separation. More...

struct	RASTER_SHEET
	Structure describing raster layout for a single separation in a page. More...

struct	RASTER_LAYOUT
	Top-level structure describing raster layout for all separations, frames, planes, channels, and colorants in a page. More...

struct	raster_layout_iterator
	Raster layout iterator. More...

struct	RASTER_BANDSIZE
	Read/write structure used during the DeviceIOCtl_RasterBandSize IOCTL calls. More...

struct	RASTER_REQUIREMENTS
	Read/write structure used during the DeviceIOCtl_RasterRequirements, DeviceIOCtl_RenderingReady, DeviceIOCtl_RenderingPass and DeviceIOCtl_RenderingSheet IOCTL calls. More...

struct	RASTER_DESTINATION
	Structure whose values can be set by the raster consumer during a DeviceIOCtl_GetBufferForRaster IOCTL call to provide memory into which the RIP will render directly. More...

struct	RASTER_BLANK
	Structure modified by raster consumer during a DeviceIOCtl_BlankPage call to determine how to handle blank pages. Blank pages may be detected because all separations were omitted (in which case the PGB NumSeparations param will be 0), or if there is nothing on the display list. The DeviceIOCtl_BlankPage call will only be made for the final output pass, not for compositing or partial paints. The page number, separations, and all other relevant parameters will have been sent to the PGB device before the IOCtl call. More...

struct	SWMSG_BANDS_HANDLED

Macros
#define	DeviceIOCtl_RasterRequirements 103

#define	DeviceIOCtl_RenderingSheet 104

#define	DeviceIOCtl_GetBufferForRaster 105

#define	DeviceIOCtl_BlankPage 107

#define	DeviceIOCtl_RenderingReady 108

#define	DeviceIOCtl_RenderingPass 109

#define	DeviceIOCtl_RasterBandSize 110

Typedefs
typedef int32	sw_pgb_colorant_type
	A type used to hold channel colorant type values.

typedef int32	sw_pgb_special_handling
	Special handling options for colorants. More...

typedef int	raster_format_t
	One of the raster_format_t enumeration values.

typedef struct RASTER_COLORANT	RASTER_COLORANT
	Structure describing raster layout for a single colorant mapped to a channel (data stream).

typedef struct RASTER_CHANNEL	RASTER_CHANNEL
	Structure describing raster layout for a single channel (data stream) in a plane.

typedef struct RASTER_PLANE	RASTER_PLANE
	Structure describing raster layout for a single plane (contiguous block of memory) in a frame.

typedef struct RASTER_FRAME	RASTER_FRAME
	Structure describing raster layout for a single frame in a separation.

typedef struct RASTER_SHEET	RASTER_SHEET
	Structure describing raster layout for a single separation in a page.

typedef struct RASTER_LAYOUT	RASTER_LAYOUT
	Top-level structure describing raster layout for all separations, frames, planes, channels, and colorants in a page.

typedef int32	raster_layout_match
	Type definition for holding the raster layout similarity flags (defined in the raster_layout_match_values enumeration).

typedef struct raster_layout_iterator	raster_layout_iterator
	Raster layout iterator. More...

typedef int	raster_layout_iterator_flags
	Type definition for holding the raster layout iteration flags.

typedef struct RASTER_BANDSIZE	RASTER_BANDSIZE
	Read/write structure used during the DeviceIOCtl_RasterBandSize IOCTL calls.

typedef struct RASTER_REQUIREMENTS	RASTER_REQUIREMENTS
	Read/write structure used during the DeviceIOCtl_RasterRequirements, DeviceIOCtl_RenderingReady, DeviceIOCtl_RenderingPass and DeviceIOCtl_RenderingSheet IOCTL calls.

typedef struct RASTER_DESTINATION	RASTER_DESTINATION
	Structure whose values can be set by the raster consumer during a DeviceIOCtl_GetBufferForRaster IOCTL call to provide memory into which the RIP will render directly.

typedef struct RASTER_BLANK	RASTER_BLANK
	Structure modified by raster consumer during a DeviceIOCtl_BlankPage call to determine how to handle blank pages. Blank pages may be detected because all separations were omitted (in which case the PGB NumSeparations param will be 0), or if there is nothing on the display list. The DeviceIOCtl_BlankPage call will only be made for the final output pass, not for compositing or partial paints. The page number, separations, and all other relevant parameters will have been sent to the PGB device before the IOCtl call.

Enumerations
enum	{ SW_PGB_COLORANTTYPE_UNKNOWN = 0 , SW_PGB_COLORANTTYPE_PROCESS = 1 , SW_PGB_COLORANTTYPE_SPOT = 3 , SW_PGB_COLORANTTYPE_EXTRASPOT = 4 , SW_PGB_COLORANTTYPE_TYPE = 6 }
	Colorant types. More...

enum	SW_PGB_object_flags { SW_PGB_USER_OBJECT = (1u << 0u) , SW_PGB_UNUSED = (1u << 1u) , SW_PGB_MARKED = (1u << 2u) , SW_PGB_LW_OBJECT = (1u << 3u) , SW_PGB_TEXT_OBJECT = (1u << 4u) , SW_PGB_SHFILL_OBJECT = (1u << 5u) , SW_PGB_VIGNETTE_OBJECT = SW_PGB_SHFILL_OBJECT , SW_PGB_IMAGE_OBJECT = (1u << 6u) , SW_PGB_COMPOSITED_OBJECT = (1u << 7u) }
	Type bits in object map rasters. More...

enum	SW_PGB_special_handling { SW_PGB_SPECIALHANDLING_NONE = 0 , SW_PGB_SPECIALHANDLING_OPAQUE , SW_PGB_SPECIALHANDLING_OPAQUEIGNORE , SW_PGB_SPECIALHANDLING_TRANSPARENT , SW_PGB_SPECIALHANDLING_OBJECTMAP = 6 }
	Special handling values for colorants. More...

enum	raster_format_values { RASTER_FORMAT_CONTONE = 0 , RASTER_FORMAT_SCREENED = 1 , RASTER_FORMAT_RLE = 2 }
	Values for raster_format_t. More...

enum	raster_layout_copy_flags_values { RASTER_LAYOUT_SRC_SERIALIZED = 1 , RASTER_LAYOUT_DST_SERIALIZED = 2 }
	Flag bits for raster_layout_copy(). More...

enum	raster_layout_match_values { RASTER_LAYOUT_MATCH_A = 0x1 , RASTER_LAYOUT_MATCH_B = 0x2 , RASTER_LAYOUT_MATCH_M = 0x3 , RASTER_LAYOUT_MIDS = 0x10 , RASTER_LAYOUT_MOMITS = 0x20 , RASTER_LAYOUT_MBYTES = 0x40 , RASTER_LAYOUT_MNAMES = 0x80 , RASTER_LAYOUT_EQUAL = 0xffffff }
	A bitmask of flags indicating how similar raster layout comparisons are. More...

enum	raster_layout_iterator_flags_values { RASTER_LAYOUT_ITERATE_SHEETS = 1<<0 , RASTER_LAYOUT_ITERATE_IN_SHEET = 1<<1 , RASTER_LAYOUT_ITERATE_FRAMES = 1<<2 , RASTER_LAYOUT_ITERATE_IN_FRAME = 1<<3 , RASTER_LAYOUT_ITERATE_PLANES = 1<<4 , RASTER_LAYOUT_ITERATE_IN_PLANE = 1<<5 , RASTER_LAYOUT_ITERATE_CHANNELS = 1<<6 , RASTER_LAYOUT_ITERATE_IN_CHANNEL = 1<<7 , RASTER_LAYOUT_ITERATE_COLORANTS = 1<<8 , RASTER_LAYOUT_ITERATE_OMITTED = 1<<9 }
	A bitmask of flags used to control raster layout iteration. More...

enum	REQUIREMENTS_band_alloc { BAND_ALLOC_RIP = 0 , BAND_ALLOC_FRAMEBUFFER = 1 , BAND_ALLOC_SKIN = 2 }
	Values for the RASTER_REQUIREMENTS::have_framebuffer flag. More...

enum	REQUIREMENTS_band_order { BAND_ORDER_INCREASING = 0 , BAND_ORDER_ANY = 1 }
	Values for the RASTER_REQUIREMENTS::band_order flag. More...

enum	REQUIREMENTS_store_partial { PARTIAL_WSKIP_RSKIP = 0 , PARTIAL_WSTORE_RSTORE = 1 , PARTIAL_WRAST_RSKIP = 2 , PARTIAL_WRAST_RERASE = 3 }
	Values for the RASTER_REQUIREMENTS::store_partial flag. More...

enum	REQUIREMENTS_render_type { REQUIREMENTS_NO_RENDER = -1 , REQUIREMENTS_RENDER_PARTIAL = 0 , REQUIREMENTS_RENDER_COMPOSITE = 1 , REQUIREMENTS_RENDER_FINAL = 2 }
	Values for the RASTER_REQUIREMENTS::render_type field. More...

enum	REQUIREMENTS_empty_bands { WRITE_NONEMPTY_OUTPUT = 0 , WRITE_TRIMMED_OUTPUT = 1 , WRITE_ALL_OUTPUT = 2 }
	Values for the RASTER_REQUIREMENTS::write_empty_bands field. More...

enum	blank_page_action_t { BLANK_PAGE_REMOVE , BLANK_PAGE_COUNT , BLANK_PAGE_OUTPUT }
	Actions to take for blank pages. More...

enum	blank_page_reason_t { BLANK_BECAUSE_NO_CONTENT , BLANK_BECAUSE_SEPARATIONS_OMITTED }
	Reasons for a blank page. More...

Functions
RASTER_LAYOUT *	raster_layout_acquire (RASTER_LAYOUT *layout)

void	raster_layout_release (RASTER_LAYOUT *playout, void(free_fn)(RASTER_LAYOUT layout, void data), void *data)

size_t	raster_layout_copy (const RASTER_LAYOUT layout, void addr, int flags)

HqnResult	raster_layout_combine (RASTER_LAYOUT *pdst, const RASTER_LAYOUT src, int interleaving_style, int separation_style, unsigned int width, unsigned int height, unsigned int bandheight)

void	raster_layout_bandheight (RASTER_LAYOUT *layout, unsigned int bandheight)

raster_layout_match	raster_channel_compare (const RASTER_CHANNEL a, const RASTER_CHANNEL b, HqnResult *perr)

raster_layout_match	raster_plane_compare (const RASTER_PLANE a, const RASTER_PLANE b, HqnResult *perr)

raster_layout_match	raster_sheet_compare (const RASTER_SHEET a, const RASTER_SHEET b, HqnResult *perr)

HqBool	raster_layout_iterate (raster_layout_iterator *iterator, raster_layout_iterator_flags flags)

Detailed Description

The raster delivery interface from the Harlequin RIP core uses the pagebuffer device.

Raster output from the RIP is written to files on the pagebuffer device to deliver it to the RIP skin. The RIP skin may present a different raster interface to the application. Raster data may be read from the pagebuffer device when partial painting or transparency compositing. IO control operations (IOCtls) are used to pass information and requirements about rasters to the skin, and to request actions, including requesting raster destinations for outputting to framebuffers, and actions for blank page rendering.

Raster IOCtl structures

The raster layout structures define the layout of the raster data. These structures are referenced from all of the IOCtl message structures, allowing the layout of the raster that will be delivered to be determined during any IOCtl call.

The IOCtl message structures and the calls they are used for are:

RASTER_BANDSIZE: This message is used by the DeviceIOCtl_RasterBandSize call. This call is made when a new pagedevice is instantiated. It gives the skin an opportunity to influence the size and alignment of rasters that will be delivered to it.

RASTER_REQUIREMENTS: This message is used by the DeviceIOCtl_RasterRequirements, DeviceIOCtl_RenderingReady, DeviceIOCtl_RenderingPass and DeviceIOCtl_RenderingSheet IOCtl calls. It provides layout information about the raster, but also in the earlier calls allows the skin to determine how bands will be allocated, the order they may be delivered in, whether asynchronous output is allowed, how partial paints are handled, whether the skin requires a scratch working memory space and how large it should be, how empty bands are handled, and several other options.

RASTER_DESTINATION: This message is used by the DeviceIOCtl_GetBufferForRaster IOCtl call to request a band address if the skin has taken responsibility for allocating bands.

RASTER_BLANK: This message is used by the DeviceIOCtl_BlankPage call to determine how blank pages are handled.

Asynchronous output may be requested by the skin (by setting RASTER_REQUIREMENTS::bands_handled_by_caller to FALSE). The SWMSG_BANDS_HANDLED event provides the definition of the message structure used by the SWEVT_BANDS_HANDLED event handler to acknowledge completion of asynchronously output bands to the RIP.

Note: This interface is likely to change in future RIP versions. The pagebuffer device may be internalized or disappear. The raster layout and IOCtl structures will be maintained in future versions of this API.

Raster layout structures

The RASTER_LAYOUT structure and its sub-structures (RASTER_SHEET, RASTER_FRAME, RASTER_PLANE, RASTER_CHANNEL, and RASTER_COLORANT) are use to provide a template of what will be rendered, and how the rendered data is layed out.

Sub-structures of the raster layout are used to communicate the layout and format of raster output calls. Raster layouts can be retained and used as a template in conjunction with band or framebuffer addresses or other specific instance data to iterate over portions of a specific page's raster data, or to guide conversion or output of the raster data produced by the RIP.

A RASTER_LAYOUT represents the structure of the rasters for all of the separations within a page.

A RASTER_SHEET represents the structure of a separation. Each separation may contain multiple channels of data. A separation is sub-divided into a set of frames, each frame consisting of the data for the full height of the page, arranged in a set of bands.

A RASTER_FRAME represents a template for each band in a frame of a separation. Each separation may contain one or more frames, with the data for all of the channels in the frame presented as a contiguous range of bands/lines. Within each band in the frame, there may be multiple planes, representing chunks of channel data that the RIP will write to contiguous blocks of memory.

A RASTER_PLANE represents a contiguous block of memory that the RIP writes channel data into. There may be multiple interleaved channels within a plane (for pixel interleaved/chunky formats), or a single channel. There may be multiple planes within each band, each with a different channel or set of channels in it. The RASTER_PLANE format can represent contone data, screened data, or RLE format data in each plane. Channels can be interleaved within the plane in a flexible manner.

A RASTER_CHANNEL represents a single identifiable stream of data, with a specified number of values, stored in a specified number of bits. Channels may be interleaved within planes, or the sole channel within a plane. Each channel interleaving for a single pixel will be repeated across each line in a plane. The lines within a plane may have extra padding at the end of the pixel repeats to align them with byte, word, or stride boundaries specified by the customer.

A RASTER_COLORANT represents a color name mapped to a data channel. It is possible for more than one colorant to be mapped to a single channel (e.g., imposed separations on a single-channel output device), and also for channels to have no colorants mapped (e.g., a pre-separated file sent to a device that requires all channels present, such as a dye-sublimation printer that uses a four-color ribbon; or omitted separations when the channel has been marked as required in the pagedevice's ColorantFamily). In the case that the last colorant is removed from a required channel, it will be marked as omitted, and anonymised by having its name changed to "None".

A raster layout pointer is supplied to many of the raster output calls. The raster layout pointer is valid for the scope of the output call only. However, the raster layout pointer may be retained by calling raster_layout_acquire(), and released when desired by calling raster_layout_release(). Raster layouts may be copied into client memory using raster_layout_copy(). Raster layouts can be serialize and deserialized for communication or storage using raster_layout_copy() as well. Raster layouts may be iterated, stopping at sub-structures of interest, using raster_layout_iterate().

There is some limited ability for the client to modify rendering by changing fields in the raster layout. In particular, alignment and stride of data may be changed in the initial pagedevice setup, and separation omission flags may be changed just before rendering. Unless explicitly specified in the description for a raster output call, fields in a raster layout supplied by the RIP must not be changed by the client.

The raster_layout_combine() function is intended for use when processing eHVD elements. It can combine broadly similar raster layouts into a combined layout. The layouts supplied to it should have been generated by the same configuration, but may differ because of separation omission. There are comparison functions provided to help determine whether raster layouts sub-structures match for eHVD processing. The RASTER_SHEET, RASTER_PLANE, and RASTER_CHANNEL structures can be compared using raster_sheet_compare(), raster_plane_compare(), or raster_channel_compare() respectively.

raster_layout_bandheight() is also intended for use in eHVD processing. It allows the band height of a raster layout (usually the combined raster layout for eHVD output) to be modified.

Macro Definition Documentation

◆ DeviceIOCtl_BlankPage

#define DeviceIOCtl_BlankPage 107

Opcode for DEVICELIST_IOCTL(). Arg is a pointer to RASTER_BLANK.

◆ DeviceIOCtl_GetBufferForRaster

#define DeviceIOCtl_GetBufferForRaster 105

Opcode for DEVICELIST_IOCTL(). Arg is a pointer to RASTER_DESTINATION.

◆ DeviceIOCtl_RasterBandSize

#define DeviceIOCtl_RasterBandSize 110

Opcode for DEVICELIST_IOCTL(). Arg is a pointer to RASTER_BANDSIZE. N.B. This call is made at when a new pagedevice is initialized, to pass back information used to compute the band size.

◆ DeviceIOCtl_RasterRequirements

#define DeviceIOCtl_RasterRequirements 103

Opcode for DEVICELIST_IOCTL(). Arg is a pointer to RASTER_REQUIREMENTS. N.B. This ioctl is called from the interpreter, not serialized wrt. to the rest of the PGB calls.

◆ DeviceIOCtl_RenderingPass

#define DeviceIOCtl_RenderingPass 109

Opcode for DEVICELIST_IOCTL(). Arg is a pointer to RASTER_REQUIREMENTS. N.B. This call is made at the start of rendering each pass.

◆ DeviceIOCtl_RenderingReady

#define DeviceIOCtl_RenderingReady 108

Opcode for DEVICELIST_IOCTL(). Arg is a pointer to RASTER_REQUIREMENTS. N.B. This ioctl is called from the interpreter, not serialized wrt. to the rest of the PGB calls. This is the final call from the interpreter before rendering, it is the last chance to change the band order, band allocation, or raster store handling.

◆ DeviceIOCtl_RenderingSheet

#define DeviceIOCtl_RenderingSheet 104

Opcode for DEVICELIST_IOCTL(). Arg is a pointer to RASTER_REQUIREMENTS. This call is made at the start of rendering each sheet, after the pagebuffer parameters for the sheet have been set.

Typedef Documentation

◆ raster_layout_iterator

typedef struct raster_layout_iterator raster_layout_iterator

Raster layout iterator.

The general pattern for raster layout iteration is to initialize an iterator structure to {layout}, and then call raster_layout_iterate() in the condition test of a loop, with flags indicating what items of interest in the raster layout hierarchy to stop at. At each stop in the iterator, all of the levels in the iteration that were requested are set to the next item in the layout. All levels below the requested level are set to the first contained item in the requested level (so advancing to the next sheet will set up the iterator for the first frame, plane, channel, and colorant of that sheet, irregardless of the separation omission status of those items). Successive calls to raster_layout_iterate() can change the levels in the structure to stop at next. It is also permissible to start iteration at a particular location by initializing higher levels of the iterator to a particular sheet, frame, plane, or channel, leaving lower levels NULL, and then calling raster_layout_iterate() with flags set appropriately. It is also valid to copy an iterator, and use the copy to continue iterating from a location in the raster layout hierarchy with a different set of flags.

◆ sw_pgb_special_handling

typedef int32 sw_pgb_special_handling

Special handling options for colorants.

Note that any consumer which doesn't understand these will just not apply any special handling, which is correct. Furthermore any consumer which is aware of the specialHandling field but sees a value it doesn't recognise, should just not treat the colorant specially.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Colorant types.

The possible types of channel colorant.

Enumerator
SW_PGB_COLORANTTYPE_UNKNOWN	Colorant type is not known
SW_PGB_COLORANTTYPE_PROCESS	Process colorant
SW_PGB_COLORANTTYPE_SPOT	Spot colorant
SW_PGB_COLORANTTYPE_EXTRASPOT	Dynamic spot colorant
SW_PGB_COLORANTTYPE_TYPE	Object type

◆ blank_page_action_t

enum blank_page_action_t

Actions to take for blank pages.

Enumerator

BLANK_PAGE_REMOVE

The page is removed from the numbering sequence. The raster handler is not expected to generate any output or placeholder for this page.

BLANK_PAGE_COUNT

The page is counted in the numbering sequence. The raster handler may generate a blank page of its own, or a placeholder to indicate that there was a blank page.

BLANK_PAGE_OUTPUT

The page should go through the normal rendering and output mechanism, including opening the pagebuffer device, writing bands (if there are any to write) and closing the pagebuffer device.

If the PGB parameter WriteAllOutput is TRUE, the raster handler will be called for all bands of all frames.

For pages which have all separations omitted, or pages which have all content trimmed, there will be no bands written to the pagebuffer device. In this case, the open and close pagebuffer calls in the SDK's PGB device will generate a single raster callback with an invalid buffer address for each frame. This raster callback should use the trim_page, trim_start and trim_end fields from the raster description to detect trimmed out pages and perform the appropriate blank page action. It is preferable to handle these pages using BLANK_PAGE_COUNT instead.

◆ blank_page_reason_t

enum blank_page_reason_t

Reasons for a blank page.

Enumerator
BLANK_BECAUSE_NO_CONTENT	No content in the page (this is only used after all other reasons are tested).
BLANK_BECAUSE_SEPARATIONS_OMITTED	Separations all omitted.

◆ raster_format_values

enum raster_format_values

Values for raster_format_t.

Enumerator
RASTER_FORMAT_CONTONE	Plane contains continuous tone values.
RASTER_FORMAT_SCREENED	Plane contains screened data.
RASTER_FORMAT_RLE	Plane contains RLE data.

◆ raster_layout_copy_flags_values

enum raster_layout_copy_flags_values

Flag bits for raster_layout_copy().

Enumerator
RASTER_LAYOUT_SRC_SERIALIZED	The source raster layout is serialized.
RASTER_LAYOUT_DST_SERIALIZED	The destination raster layout will be serialized.

◆ raster_layout_iterator_flags_values

enum raster_layout_iterator_flags_values

A bitmask of flags used to control raster layout iteration.

Enumerator
RASTER_LAYOUT_ITERATE_SHEETS	Stop at each sheet.
RASTER_LAYOUT_ITERATE_IN_SHEET	Don't cross sheet boundaries.
RASTER_LAYOUT_ITERATE_FRAMES	Stop at each frame.
RASTER_LAYOUT_ITERATE_IN_FRAME	Don't cross frame boundaries.
RASTER_LAYOUT_ITERATE_PLANES	Stop at each plane.
RASTER_LAYOUT_ITERATE_IN_PLANE	Don't cross plane boundaries.
RASTER_LAYOUT_ITERATE_CHANNELS	Stop at each channel.
RASTER_LAYOUT_ITERATE_IN_CHANNEL	Don't cross channel boundaries.
RASTER_LAYOUT_ITERATE_COLORANTS	Stop at each colorant.
RASTER_LAYOUT_ITERATE_OMITTED	Stop at omitted items.

◆ raster_layout_match_values

enum raster_layout_match_values

A bitmask of flags indicating how similar raster layout comparisons are.

The match_a/match_b comparisons indicate if the layouts have supersets of each other's sheet/frame/plane/channel/colorant structure with the same bit depths and compatible offsets, etc. The other flags indicate whether certain other other aspects of the layouts are the same, including the sheet sizes, band heights, omission flags for all shared structures.

New flags may be added in future, so it's best to limit checks to just the aspects of the layout structure that must or must not match for each use case.

The flags used to test similarity will all be less than or equal to RASTER_LAYOUT_EQUAL.

Enumerator
RASTER_LAYOUT_MATCH_A	Layout A can represent layout B.
RASTER_LAYOUT_MATCH_B	Layout B can represent layout A.
RASTER_LAYOUT_MATCH_M	Mask for layout structure matches.
RASTER_LAYOUT_MIDS	Structure origin IDs same if set.
RASTER_LAYOUT_MOMITS	Omission flags same if set.
RASTER_LAYOUT_MBYTES	Line sizes same if set.
RASTER_LAYOUT_MNAMES	Colorant names same if set.
RASTER_LAYOUT_EQUAL	All items compared matched.

◆ REQUIREMENTS_band_alloc

enum REQUIREMENTS_band_alloc

Values for the RASTER_REQUIREMENTS::have_framebuffer flag.

Enumerator

BAND_ALLOC_RIP

RIP manages all output band memory.

BAND_ALLOC_FRAMEBUFFER

Skin provides full framebuffer, guaranteeing to store and return same contents across partial paints, including two-pass transparency.

BAND_ALLOC_SKIN

Skin allocates (subset of) bands for use by RIP. Bands are allocated by a raster destination call, and must remain valid until either a skin raster output call or the RIP issues a SWEVT_BANDS_HANDLED event with SWMSG_BANDS_HANDLED::final TRUE and a line range that includes the last line of the band.

The minimum number of bands the skin must allocate is the number of renderer threads allowed. The maximum number of bands may be limited by using the DynamicBandLimit systemparam.

The RIP SDK normally takes responsibility for storing and restoring the band contents across partial paints, including two-pass transparency, though this may be changed by setting the value of the RASTER_REQUIREMENTS::store_partial flag. Band memory may be released and re-acquired in between rendering passes.

◆ REQUIREMENTS_band_order

enum REQUIREMENTS_band_order

Values for the RASTER_REQUIREMENTS::band_order flag.

Enumerator
BAND_ORDER_INCREASING	Bands are strictly increasing.
BAND_ORDER_ANY	Bands can be supplied in any order.

◆ REQUIREMENTS_empty_bands

enum REQUIREMENTS_empty_bands

Values for the RASTER_REQUIREMENTS::write_empty_bands field.

Enumerator
WRITE_NONEMPTY_OUTPUT	Write only bands with non-empty contents.
WRITE_TRIMMED_OUTPUT	Write all bands from the first non-empty band to the last non-empty band.
WRITE_ALL_OUTPUT	Write all bands, even if empty.

◆ REQUIREMENTS_render_type

enum REQUIREMENTS_render_type

Values for the RASTER_REQUIREMENTS::render_type field.

Enumerator
REQUIREMENTS_NO_RENDER	Not rendering.
REQUIREMENTS_RENDER_PARTIAL	Partial paint render pass.
REQUIREMENTS_RENDER_COMPOSITE	Composite render pass.
REQUIREMENTS_RENDER_FINAL	Final render pass.

◆ REQUIREMENTS_store_partial

enum REQUIREMENTS_store_partial

Values for the RASTER_REQUIREMENTS::store_partial flag.

Enumerator
PARTIAL_WSKIP_RSKIP	Do nothing with the band when partial painting, do nothing to the band when previously partial painted. This is only appropriate for use with BAND_ALLOC_FRAMEBUFFER, where the expectation is that the bands are stored uncompressed between partial paints, and the same band address is used across partial paints.
PARTIAL_WSTORE_RSTORE	Write to the store if partial painting, read from the store if previously partial painted.
PARTIAL_WRAST_RSKIP	Write to the raster backend if partial painting, do nothing to the band when previously partial painted. This can be used when the raster backend takes responsibility for combining partial paints, and the band is in a known state at the start of a partial paint (e.g., RLE, or if using BAND_ALLOC_SKIN and the client takes responsibility for clearing the band).
PARTIAL_WRAST_RERASE	Write to the raster backend if partial painting, clear the band instead of reading back data when previously partial painted. This can be used when the raster backend takes responsibility for combining partial paints, and the band must start in a known state.

◆ SW_PGB_object_flags

enum SW_PGB_object_flags

Type bits in object map rasters.

More than one object type bit can be set for objects that are overprinted or composited.

Enumerator
SW_PGB_USER_OBJECT	User-settable bit.
SW_PGB_UNUSED	Bit reserved for future use.
SW_PGB_MARKED	Bit reserved for backdrop internal use.
SW_PGB_LW_OBJECT	Object is linework.
SW_PGB_TEXT_OBJECT	Object is text.
SW_PGB_SHFILL_OBJECT	Object is a shaded fill.
SW_PGB_VIGNETTE_OBJECT	Object is a shaded fill (old name for backward compatibility).
SW_PGB_IMAGE_OBJECT	Object is an image.
SW_PGB_COMPOSITED_OBJECT	Object is composited.

◆ SW_PGB_special_handling

enum SW_PGB_special_handling

Special handling values for colorants.

Enumerator
SW_PGB_SPECIALHANDLING_NONE	No special handling of colorant.
SW_PGB_SPECIALHANDLING_OPAQUE	Colorant is opaque.
SW_PGB_SPECIALHANDLING_OPAQUEIGNORE	Colorant is opaque but ignored for trapping.
SW_PGB_SPECIALHANDLING_TRANSPARENT	Colorant traps as transparent.
SW_PGB_SPECIALHANDLING_OBJECTMAP	Colorant represents an object map.

Function Documentation

◆ raster_channel_compare()

raster_layout_match raster_channel_compare	(	const RASTER_CHANNEL *	a,
		const RASTER_CHANNEL *	b,
		HqnResult *	perr
	)

Compare two raster layout channels.

Parameters

[in]	a	One of the raster layout channels to compare.
[in]	b	The other raster layout channels to compare.
[out]	perr	An optional location for an error code. If not `NULL`, on exit perr is set to either HQN_RESULT_SUCCESS or a monitor UID error code. perr will only ever be an error if the return value is zero (nothing matched).

Returns: A bitmask of the raster_layout_match_values, indicating how similar the channels are.

◆ raster_layout_acquire()

RASTER_LAYOUT* raster_layout_acquire ( RASTER_LAYOUT * layout )

Acquire a reference to a raster layout. The raster layout and all of its sub-structures and internal pointers will be remain valid until released. All references acquired must be released using raster_layout_release() before the end of the RIP lifetime.

Parameters

[in] layout The raster layout to acquire a reference on.

Returns: The newly-acquired raster layout pointer.

◆ raster_layout_bandheight()

void raster_layout_bandheight	(	RASTER_LAYOUT *	layout,
		unsigned int	bandheight
	)

Reset layout sizes and band count for a different band height.

Parameters

[in]	layout	The layout to reset the band height in.
[in]	bandheight	The new band height of the layout in pixels. This must be greater than zero, and less than layout->height.

◆ raster_layout_combine()

HqnResult raster_layout_combine	(	RASTER_LAYOUT **	pdst,
		const RASTER_LAYOUT *	src,
		int	interleaving_style,
		int	separation_style,
		unsigned int	width,
		unsigned int	height,
		unsigned int	bandheight
	)

Combine a raster layout with a destination layout, replacing the destination layout. This is used to construct a suitable raster layout for combined eHVD output from the raster layouts of the elements.

Parameters

[out]	pdst	A location of a combined raster layout. This should either point to `NULL`, or to a raster layout previously created by raster_layout_combine(). If this function returns an error (anything except HQN_RESULT_SUCCESS) the original *pdst raster layout reference was not released: it MUST be released using `raster_layout_release(pdst, NULL, NULL)` when the client has finished accessing it.
[in]	src	A source raster layout to combine into *pdst.
	interleaving_style	An indication of how to combine raster layouts when src is not already a subset of dst. The value one of the same values as RASTER_REQUIREMENTS::interleavingStyle, which come from the page device's /InterleavingStyle key, as documented in the extensions manual. It is used in combination with separation_style to determine at what level(s) of the hierarchy new channels/planes/frames/sheets are introduced to represent the combination of layouts.
	separation_style	An indication of how to combine raster layouts when src is not already a subset of dst. The value is one of the pagedevice /SeparationDetail dictionary's /SeparationStyle key, as documented in the Extensions manual. This is used in combination with interleaving_style to determine at what level(s) of the hierarchy new channels/planes/frames/sheets are introduced to represent the combination of layouts.
	width	The pixel width of the combined layout.
	height	The pixel height of the combined layout.
	bandheight	The band height in pixels of the combined layout.

Return values

HQN_RESULT_SUCCESS	The source raster layout was combined into the destination raster layout in pdst, releasing the original reference in pdst. The combined *pdst raster layout MUST be released using `raster_layout_release(pdst, NULL, NULL)` when the client has finished accessing it.
MON_UNDEFINEDRESULT_LAYOUT_COMBINE_MISMATCH	The source raster layout could not be combined into the destination raster layout because of neither layout is a subset or is combinable with the other.
MON_UNDEFINEDRESULT_LAYOUT_INCOMPATIBLE_COLORANTS	Colorants which were required to match are incompatible.
MON_UNDEFINEDRESULT_LAYOUT_INCOMPATIBLE_CHANNELS	Channels which were required to match are incompatible.
MON_UNDEFINEDRESULT_LAYOUT_INCOMPATIBLE_PLANES	Planes which were required to match are incompatible.
MON_UNDEFINEDRESULT_LAYOUT_INCOMPATIBLE_FRAMES	Frames which were required to match are incompatible.
MON_UNDEFINEDRESULT_LAYOUT_INCOMPATIBLE_SHEETS	Sheets which were required to match are incompatible.
MON_VMERROR	There was a memory allocation failure creating the combined layout.

Returns: Any other return value will be greater than MON_CLASS_ERROR, and will be a well-formed error code, according to the rules for sw_mon_type.

New references may be taken to the combined raster layout, however the destination raster layout must be released using raster_layout_release(pdst, NULL, NULL) when done.

◆ raster_layout_copy()

size_t raster_layout_copy	(	const RASTER_LAYOUT *	layout,
		void *	addr,
		int	flags
	)

Copy a raster layout into a contiguous block of memory.

Parameters

[in]	layout	The raster layout to copy.
[in]	addr	An address to copy the raster layout into. If this is `NULL`, this function will return the size of the memory required to copy the raster layout, but without copying it.
[in]	flags	A bitmask of the raster_layout_copy_flags_values values, indicating whether the source raster layout is already serialized, and whether the destination raster layout should be serialized.

While copying raster layouts, the client may serialize or deserialize it. Serialized raster layouts have internal pointers mutated to make them suitable for persistent storage, or communicating through shared memory or RPC channels. Internal pointers in serialized raster layouts must not be dereferenced. It is valid to serialize or deserialize a raster layout in place by passing the same destination and source address, so long as there is only one reference to the layout, and it was originally created using raster_layout_copy(). Raster layouts supplied by the RIP to the client must not be serialized in-place.

It is the client's responsibility to free the memory containing the copied raster layout, either directly or by supplying an appropriate free_fn parameter to raster_layout_release().

The reference count of a new raster layout copy will be set to 1. If a raster layout is serialized or deserialized in-place, the reference count will not be changed.

Returns: The size in bytes of the memory used by the copied raster layout. This will be zero if there was an error (e.g., attempting an invalid in-place serialization or deserialization).

◆ raster_layout_iterate()

HqBool raster_layout_iterate	(	raster_layout_iterator *	iterator,
		raster_layout_iterator_flags	flags
	)

Advance a raster layout iterator to the next requested item, and return an indication whether the item exists.

Parameters

[in,out]	iterator	The raster layout iterator to advance.
	flags	The raster layout items to advance the iteration to.

Return values

TRUE The iterator was advanced to the next requested item. All of the pointers in the iterator point at valid items in the raster layout hierarchy. Frame, plane, and channel pointers in the iterator below the lowest requested item in the raster layout hierarchy are set to point at the first item contained in the requested item of a suitable omission status (i.e., the first non-omitted frame/plane/channel if the request did not include RASTER_LAYOUT_ITERATE_OMITTED; the first frame/plane/channel regardless of omission if the request did contain RASTER_LAYOUT_ITERATE_OMITTED). If RASTER_LAYOUT_ITERATE_COLORANTS was not specified in flags, the colorant pointer will be the first colorant in the selected channel, regardless of its omission status or whether RASTER_LAYOUT_ITERATE_OMITTED was specified.

FALSE There were no more of the items requested to stop at. The iterator may have been modified. All of the pointers in the iterator point at valid items in the raster layout hierarchy.

Note: This function does not acquire or release references on the raster layout in the iterator. It is the responsibility of the caller to ensure that the raster layout remains valid for every call to iterate the layout, and for the duration that the iterator structure is referenced.

◆ raster_layout_release()

void raster_layout_release	(	RASTER_LAYOUT **	playout,
		void()(RASTER_LAYOUT layout, void *data)	free_fn,
		void *	data
	)

Release a reference to a raster layout, freeing the entire structure if the last reference was released.

Parameters

[in,out]	playout	A pointer to a raster layout structure. On exit, this will be set to `NULL`. It is safe to call this function with *playout `NULL` on entry.
[in]	free_fn	A function to free the memory used by the raster layout. This should only be supplied if the raster layout was created in client memory using raster_layout_copy(). This function pointer should be `NULL` for raster layouts supplied by the RIP.
[in]	data	A data pointer that will be supplied to free_fn if it is called.

◆ raster_plane_compare()

raster_layout_match raster_plane_compare	(	const RASTER_PLANE *	a,
		const RASTER_PLANE *	b,
		HqnResult *	perr
	)

Compare two raster layout planes.

Parameters

[in]	a	One of the raster layout planes to compare.
[in]	b	The other raster layout planes to compare.
[out]	perr	An optional location for an error code. If not `NULL`, on exit perr is set to either HQN_RESULT_SUCCESS or a monitor UID error code. perr will only ever be an error if the return value is zero (nothing matched).

Returns: A bitmask of the raster_layout_match_values, indicating how similar the planes are.

◆ raster_sheet_compare()

raster_layout_match raster_sheet_compare	(	const RASTER_SHEET *	a,
		const RASTER_SHEET *	b,
		HqnResult *	perr
	)

Compare two raster layout sheets.

Parameters

[in]	a	One of the raster layout sheets to compare.
[in]	b	The other raster layout sheet to compare.
[out]	perr	An optional location for an error code. If not `NULL`, on exit perr is set to either HQN_RESULT_SUCCESS or a monitor UID error code. perr will only ever be an error if the return value is zero (nothing matched).

Returns: A bitmask of the raster_layout_match_values, indicating how similar the sheets are.

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Raster IOCtl structures

Raster layout structures

Macro Definition Documentation

◆ DeviceIOCtl_BlankPage

◆ DeviceIOCtl_GetBufferForRaster

◆ DeviceIOCtl_RasterBandSize

◆ DeviceIOCtl_RasterRequirements

◆ DeviceIOCtl_RenderingPass

◆ DeviceIOCtl_RenderingReady

◆ DeviceIOCtl_RenderingSheet

Typedef Documentation

◆ raster_layout_iterator

◆ sw_pgb_special_handling

Enumeration Type Documentation

◆ anonymous enum

◆ blank_page_action_t

◆ blank_page_reason_t

◆ raster_format_values

◆ raster_layout_copy_flags_values

◆ raster_layout_iterator_flags_values

◆ raster_layout_match_values

◆ REQUIREMENTS_band_alloc

◆ REQUIREMENTS_band_order

◆ REQUIREMENTS_empty_bands

◆ REQUIREMENTS_render_type

◆ REQUIREMENTS_store_partial

◆ SW_PGB_object_flags

◆ SW_PGB_special_handling

Function Documentation

◆ raster_channel_compare()

◆ raster_layout_acquire()

◆ raster_layout_bandheight()

◆ raster_layout_combine()

◆ raster_layout_copy()

◆ raster_layout_iterate()

◆ raster_layout_release()

◆ raster_plane_compare()

◆ raster_sheet_compare()