|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
Type containing a framebuffer instance's data. More...
#include "framebuffer.h"
Data Fields | |
| frame_descriptor_t * | frames |
| unsigned int | n_frames |
| unsigned int | n_frames_needed |
| size_t | alloc_size |
| size_t | frame_size |
| size_t | sheet_size |
| size_t | band_size |
| size_t | band_height |
| size_t | bytes_per_line |
| frame_acquire_fn * | acquire_fn |
| frame_release_fn * | release_fn |
| frame_raster_fn * | raster_fn |
| framebuffer_data_release_fn * | data_release_fn |
| void * | data |
| HqBool | exact_buffer_sizes |
| HqBool | handle_per_sheet |
Type containing a framebuffer instance's data.
Each raster backend using a framebuffer must instantiate one of these structures, either globally, or in a structure that will last at least through all of the render passes for each page. The raster backend should initialize the framebuffer structure to zero before the first call to any of the framebuffer functions.
The raster backend may read field values from this structure for information, but should not modify any of the fields directly unless explicitly documented.
| frame_acquire_fn* framebuffer_t::acquire_fn |
The frame handle acquire function. The raster backend should not manipulate this field: it is modified through framebuffer_acquire().
| [in] | size | The size of the raster data required. If the framebuffer_t::exact_buffer_sizes field is FALSE, then this may be larger than the required size for the data. A page with dynamic separations may require additional frames for a final paint. All frames within the framebuffer are allocated with the same size, so if exact sizing is not used, the additional frames may be larger than is strictly necessary for the raster. |
| [in] | id | The frame ID (or sheet ID if allocating a buffer per sheet) for which this buffer is being acquired. This allows placement of raster data for different colorants or channel types in particular locations. It will only be useful if the client is releasing or taking ownership of all of the buffers after each page is rendered, otherwise buffers will be re-used by the framebuffer code for different frames or sheets without re-allocation. The client can determine how to place buffers by looking up the ID in the raster layout. The raster layout could be referenced through a structure supplied as the data pointer to framebuffer_acquire(). |
| [in] | data | The data pointer supplied by the caller to framebuffer_acquire(). |
| [out] | perr | A location in which an error code is stored, if the frame could not be acquired. |
NULL if an error occurred and the handle could not be acquired. The handles returned may be the raster data address if there is no management of the handle required. They can also be complex structures containing other metadata required to manage the framebuffer's raster data. A separate callback (of frame_raster_fn type) is used to derive the base address of the raster data from the handle.If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr may be set to a code greater than MON_CLASS_ERROR indicating the error that occurred creating the reader context. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.
| size_t framebuffer_t::alloc_size |
The allocated size used for rasters in the framebuffer. The raster backend should not manipulate this field: it is modified through framebuffer_acquire() and framebuffer_recalculate().
| size_t framebuffer_t::band_height |
The band height of each band in frames in the framebuffer. The raster backend should not manipulate this field: it is modified through framebuffer_acquire() and framebuffer_recalculate().
| size_t framebuffer_t::band_size |
The number of bytes in each band of a sheet in the framebuffer. The raster backend should not manipulate this field: it is modified through framebuffer_acquire() and framebuffer_recalculate().
| size_t framebuffer_t::bytes_per_line |
The number of bytes in each line in frames in the framebuffer. The raster backend should not manipulate this field: it is modified through framebuffer_acquire() and framebuffer_recalculate().
| void* framebuffer_t::data |
The frame handle client data pointer. The raster backend should not manipulate this field: it is modified through framebuffer_acquire(). The lifetime of the data should be at least as long as the framebuffer object. If the framebuffer_t::data_release_fn function pointer is non-NULL, it will be called to release framebuffer_t::data during framebuffer_release(). The data pointer is not released when a framebuffer is reused with framebuffer_reuse().
| framebuffer_data_release_fn* framebuffer_t::data_release_fn |
The frame handle client data release function. The raster backend should not manipulate this field: it is modified through framebuffer_acquire().
If this pointer is non-NULL, the function is called during framebuffer_release().
| [in] | data | The framebuffer_t::data pointer, originally supplied to framebuffer_acquire() or fbassoc_acquire() in the framebuffer_acquire_t::data field. |
| HqBool framebuffer_t::exact_buffer_sizes |
If the framebuffer is used for a larger raster size, and then a smaller raster is requested, should the framebuffer re-allocate the buffers? The client can set this field to TRUE to force re-allocation if a new buffer size is less than the existing size.
| size_t framebuffer_t::frame_size |
The number of bytes in each frame of a sheet in the framebuffer. The raster backend should not manipulate this field: it is modified through framebuffer_acquire() and framebuffer_recalculate().
| frame_descriptor_t* framebuffer_t::frames |
An array of structures associating frames with raster buffers. The raster backend should not manipulate this field: it is modified through framebuffer_acquire(), framebuffer_release(), and framebuffer_recalculate().
| HqBool framebuffer_t::handle_per_sheet |
Is the framebuffer is being used to manage one raster for the whole sheet, rather than one raster per frame? The client can change this field value, but only before using any framebuffer functions. It should not be changed if a framebuffer is in use.
| unsigned int framebuffer_t::n_frames |
The number of frames stored in the framebuffer. This may be larger than the number of rendered frames, if frames stored for partial paint are not used in a final render pass, or frame handles are not released between pages. The raster backend should not manipulate this field: it is modified through framebuffer_acquire() and framebuffer_release().
| unsigned int framebuffer_t::n_frames_needed |
The number of frames needed by the framebuffer. This may differ from the number of stored frames, if framebuffer_recalculate() has been called since the last framebuffer_acquire() or framebuffer_release(). The raster backend should not manipulate this field: it is modified through framebuffer_recalculate().
| frame_raster_fn* framebuffer_t::raster_fn |
The frame handle raster function. The raster backend should not manipulate this field: it is modified through framebuffer_acquire().
Frame handles need not be the data address themselves. They can be complex structures containing other metadata required to manage the framebuffer's raster data. This function type is used when the address of the framebuffer's raster data is required by the framebuffer functions.
| [in] | handle | A frame handle returned by the framebuffer::frame_acquire function. |
| [in] | offset | An offset into the frame or sheet raster data for the start of the data to be returned. This must be within the size acquired using the framebuffer::frame_acquire function. |
| [in] | size | The size of the data window in the frame or sheet raster data for the data returned. The end of the data window must be at or below the size acquire using framebuffer::frame_acquire function. |
NULL pointer to a buffer of raster data of the size and offset specified. | frame_release_fn* framebuffer_t::release_fn |
The frame handle release function. The raster backend should not manipulate this field: it is modified through framebuffer_acquire().
This function will be called by the framebuffer functions when they need to release a previously-allocated frame. After this function is called by the framebuffer functions, the framebuffer will make no more reference to the handle.
| [in] | handle | A frame handle returned by the framebuffer::acquire_fn function. |
| [in] | size | The raster size originally supplied to the framebuffer::frame_acquire function. |
| [in] | data | The data pointer originally supplied to the framebuffer::frame_acquire function. |
| size_t framebuffer_t::sheet_size |
The number of bytes in each sheet in the framebuffer. The raster backend should not manipulate this field: it is modified through framebuffer_acquire() and framebuffer_recalculate().