|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
SDK support for framebuffer raster output backends. More...
Files | |
| file | framebuffer.h |
| Common support for framebuffer raster output backends. | |
| file | hvdmemfb.h |
| Support for local memory framebuffers for eHVD elements. | |
| file | hvdshmfb.h |
| Support for shared memory framebuffers for eHVD elements. This allows a Scalable RIP to share eHVD elements across the entire RIP farm, without needing coordination from a raster manager or central controller. | |
| file | framebuffer.c |
| Common support for framebuffer raster output backends. | |
| file | hvdmemfb.c |
| Support for local memory framebuffers for eHVD elements. | |
| file | hvdshmfb.c |
| Support for shared memory framebuffers for eHVD elements. This allows a Scalable RIP to share eHVD elements across the entire RIP farm, without needing coordination from a raster manager or central controller. | |
Data Structures | |
| struct | framebuffer_t |
| Type containing a framebuffer instance's data. More... | |
| struct | memfb_framebuffer_data |
| Structure type for use as type for data pointer when using framebuffer support to manage local memory rasters. More... | |
| struct | shmfb_framebuffer_data |
| Structure type for use as type for data pointer when using framebuffer support to manage shared memory rasters. More... | |
Typedefs | |
| typedef struct frame_descriptor_t | frame_descriptor_t |
| Opaque reference to frame to raster association structure. | |
| typedef void *() | frame_acquire_fn(size_t size, uint32 id, void *data, HqnResult *perr) |
| Type of a function used to allocate a handle when new frames are acquired by the framebuffer. More... | |
| typedef void() | frame_release_fn(void *handle, size_t size, void *data) |
| Type of a function used to release a frame handle. More... | |
| typedef uint8 *() | frame_raster_fn(void *handle, size_t offset, size_t size) |
| Type of a function used to get the base address of the raster data from a frame or sheet handle. More... | |
| typedef struct framebuffer_t | framebuffer_t |
| Type containing a framebuffer instance's data. More... | |
| typedef struct memfb_framebuffer_data | memfb_framebuffer_data |
| Structure type for use as type for data pointer when using framebuffer support to manage local memory rasters. More... | |
| typedef struct shmfb_framebuffer_data | shmfb_framebuffer_data |
| Structure type for use as type for data pointer when using framebuffer support to manage shared memory rasters. More... | |
Functions | |
| HqBool | framebuffer_recalculate (framebuffer_t *framebuffer, const RasterDescription *rd) |
| Calculate the size parameters for a framebuffer from a raster description and layout. More... | |
| HqnResult | framebuffer_acquire (framebuffer_t *framebuffer, const RasterDescription *rd, frame_acquire_fn *acquire_fn, frame_release_fn *release_fn, frame_raster_fn *raster_fn, void *data) |
| Acquire the frames for a framebuffer. More... | |
| HqnResult | framebuffer_destination (framebuffer_t *framebuffer, RASTER_DESTINATION *destination, int32 sheetIndex) |
| Set up the raster memory destination and ceiling for a frame. More... | |
| uint8 * | framebuffer_address (framebuffer_t *framebuffer, uint32 id) |
| Obtain a pointer to a frame's raster buffer. More... | |
| void * | framebuffer_handle (framebuffer_t *framebuffer, uint32 id) |
| Retrieve a handle from a frame's raster buffer. More... | |
| void | framebuffer_reuse (framebuffer_t *framebuffer, uint32 sheet_id) |
| Forget associations between frame and sheet IDs and the handles they were assigned to, allowing the handle to be re-used for a different frame or sheet. More... | |
| void | framebuffer_remove (framebuffer_t *framebuffer, void *handle) |
| Take ownership of a frame handle away from the framebuffer. More... | |
| void | framebuffer_release (framebuffer_t *framebuffer) |
| Release all of the frames in a framebuffer. More... | |
| void * | memfb_acquire (size_t size, uint32 id, void *data, HqnResult *perr) |
| Function to use as frame_acquire_fn when using framebuffer support to manage local memory rasters. More... | |
| void | memfb_release (void *handle, size_t size, void *data) |
| Function to use as frame_release_fn when using framebuffer support to manage local memory rasters. More... | |
| uint8 * | memfb_raster (void *handle, size_t offset, size_t size) |
| Function to use as frame_raster_fn when using framebuffer support to manage local memory rasters. More... | |
| void * | shmfb_acquire (size_t size, uint32 id, void *data, HqnResult *perr) |
| Function to use as frame_acquire_fn when using framebuffer support to manage shared memory rasters. More... | |
| void | shmfb_release (void *handle, size_t size, void *data) |
| Function to use as frame_release_fn when using framebuffer support to manage shared memory rasters. More... | |
| uint8 * | shmfb_raster (void *handle, size_t offset, size_t size) |
| Function to use as frame_raster_fn when using framebuffer support to manage shared memory rasters. More... | |
SDK support for framebuffer raster output backends.
The framebuffer functionality supported by these functions is used in the FRAMETIFF and HVDRAW raster backends, to support a single memory buffer for each frame of a page. All frames for the entire page must be stored for all render passes of a page, to cope with partial painting and 2-pass transparency compositing.
This framebuffer support allows for custom allocators for the actual frame raster buffers, and also for optionally re-using existing buffers when the page raster size changes. The default allocators use malloc() and free() to store a each raster frame separately.
These framebuffer functions support either allocating a buffer for each frame in the page, or a buffer for each sheet in a page. These are the same when outputting separations, but are different when outputting frame-interleaved composite pages. Allocating a single buffer for the entire page means that the separations cannot change between passes, so this allocation mode is not appropriate when partial painting or 2-pass transparency compositing is used with for dynamic separations or separation omission.
The expected usage of these functions are:
framebuffer_acquire() is called during the raster requirements call (SwLeRASTERREQUIREMENTS) made before rendering a separation.
framebuffer_destination() is called from the raster backend's raster destination call (SwLeRASTERDESTINATION) to set up the address of the buffer to render into.
framebuffer_address() is called during the raster finish call (RASTER_FINISH_EX) to find the addresses of the frames to output.
framebuffer_reuse() or framebuffer_remove() are called during the raster finish call (RASTER_FINISH_EX) made when completing a separation.
framebuffer_release() is called in the job end call (RASTER_JOB_END_EX).
framebuffer_recalculate() can be called to update the sizes required for the framebuffer, but without acquiring any frames. It may be useful if there are other requirements to prepare for acquiring frame handles. It may release existing frames if the new sizes differ, so should be used with caution.
To use the local memory framebuffer support in a raster output backend, a memfb_framebuffer_data structure should be initialised, and the framebuffer_acquire() function called with the memfb_acquire function pointer as its frame_acquire_fn parameter, the memfb_release function pointer as its frame_release_fn parameter, the memfb_raster function pointer as its frame_raster_fn parameter, and a pointer to the memfb_framebuffer_data structure as its data parameter. The memfb_framebuffer_data structure pointer must remain valid until the framebuffer has been released by calling framebuffer_release().
To use the shared memory framebuffer support in a raster output backend, a shmfb_framebuffer_data structure should be initialised, and the framebuffer_acquire() function called with the shmfb_acquire function pointer as its frame_acquire_fn parameter, the shmfb_release() function pointer as its frame_release_fn parameter, the shmfb_raster function pointer as its frame_raster_fn parameter, and a pointer to the shmfb_framebuffer_data structure as its data parameter. The shmfb_framebuffer_data structure pointer must remain valid until the framebuffer has been released.
Type of a function used to allocate a handle when new frames are acquired by the framebuffer.
| [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.
| typedef uint8*() frame_raster_fn(void *handle, size_t offset, size_t size) |
Type of a function used to get the base address of the raster data from a frame or sheet handle.
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. | typedef void() frame_release_fn(void *handle, size_t size, void *data) |
Type of a function used to release a frame handle.
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. |
| typedef struct framebuffer_t framebuffer_t |
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.
| typedef struct memfb_framebuffer_data memfb_framebuffer_data |
Structure type for use as type for data pointer when using framebuffer support to manage local memory rasters.
When using the framebuffer interface functions memfb_acquire() and memfb_release(), a structure pointer of this type must be supplied as the data parameter in each call to framebuffer_acquire(), and must remain valid for the lifetime of the framebuffer.
| typedef struct shmfb_framebuffer_data shmfb_framebuffer_data |
Structure type for use as type for data pointer when using framebuffer support to manage shared memory rasters.
When using the framebuffer interface functions shmfb_acquire() and shmfb_release(), a structure pointer of this type must be supplied as the data parameter in each call to framebuffer_acquire(), and must remain valid for the lifetime of the framebuffer.
| HqnResult framebuffer_acquire | ( | framebuffer_t * | framebuffer, |
| const RasterDescription * | rd, | ||
| frame_acquire_fn * | acquire_fn, | ||
| frame_release_fn * | release_fn, | ||
| frame_raster_fn * | raster_fn, | ||
| void * | data | ||
| ) |
Acquire the frames for a framebuffer.
It is expected that this function will be called from a raster requirements function of the raster backend, when the raster description for rendering a sheet is known.
This function may release previously-acquired frames, if any of the callback functions differs, or if the number of frames or frame size parameters differ from previous uses.
As well as acquiring frame handles, this function will associate frame handles with the frame IDs in the page. Frame IDs must be deassociated from handles if the raster backend wants to re-use frame buffers between pages. This can be done by calling framebuffer_reuse() at the end of outputting each sheet.
| [in,out] | framebuffer | The framebuffer to update parameters for. |
| [in] | rd | A raster description prepared for rendering a sheet. This raster description must be unpacked (the raster layout pointer must be valid). |
| [in] | acquire_fn | A callback function to acquire frame handles for each frame. If this function pointer is NULL, then both the release_fn and raster_fn pointers must also be NULL, and the frames will be acquired using malloc() and released using free(). |
| [in] | release_fn | A callback function to release frame handles acquired using acquire_fn. If this function pointer is NULL, then both the acquire_fn and raster_fn pointers must also be NULL, and the frames will be acquired using malloc() and released using free(). |
| [in] | raster_fn | A callback function to get the raster data address from frame handles acquired using acquire_fn. If this function pointer is NULL, then both the acquire_fn and release_fn pointers must also be NULL, and the frames will be acquired using malloc() and released using free(). |
| [in] | data | An opaque pointer supplied to the acquire_fn, release_fn, and raster_fn callbacks. Changing the data pointer between calls to framebuffer_acquire() will not release existing frames: this should be used with caution. |
| HQN_RESULT_SUCCESS | (0) if all of the frames were obtained. |
| uint8* framebuffer_address | ( | framebuffer_t * | framebuffer, |
| uint32 | id | ||
| ) |
Obtain a pointer to a frame's raster buffer.
| [in] | framebuffer | The framebuffer to find the frame in. |
| [in] | id | The ID of the requested frame or sheet. If allocating a raster per sheet (framebuffer->handle_per_sheet is TRUE), and a sheet ID is supplied, the base address of the sheet's raster data will be returned. If allocating a raster per frame (framebuffer->handle_per_sheet is FALSE), then a frame ID must be supplied. In either case, supplying a frame ID will retrieve the address of the raster data for that frame. |
NULL if the frame or sheet was not found. | HqnResult framebuffer_destination | ( | framebuffer_t * | framebuffer, |
| RASTER_DESTINATION * | destination, | ||
| int32 | sheetIndex | ||
| ) |
Set up the raster memory destination and ceiling for a frame.
It is expected that this function will be the only call in the raster backend's raster destination function. The raster destination function is used as a trampoline to find the framebuffer pointer to pass to this function.
| [in,out] | framebuffer | The framebuffer to find the raster destination in. |
| [in,out] | destination | The raster destination pointer used to set the memory base and ceiling. |
| [in] | sheetIndex | The zero-based index of the sheet being rendered, before separation omission. This may be used to index directly into the destination->raster_layout->sheets[] array. |
| 0 | The frame was found, and the memory base and ceiling were successfully set. |
| MON_UNDEFINED_FRAMEBUFFER_DESTINATION | The frame could not be found. Either the current sheet or band is out of range, framebuffer_acquire() was not called or failed, or some other error has occurred. |
| void* framebuffer_handle | ( | framebuffer_t * | framebuffer, |
| uint32 | id | ||
| ) |
Retrieve a handle from a frame's raster buffer.
| [in] | framebuffer | The framebuffer to find the frame or sheet in. |
| [in] | id | The ID of the requested frame or sheet. If allocating a raster per sheet (framebuffer->handle_per_sheet is TRUE), then a sheet ID must be is supplied, and the handle for that sheet will be returned. If allocating a raster per frame (framebuffer->handle_per_sheet is FALSE), then a frame ID must be supplied, and the handle for that frame will be returned. |
NULL if the frame or sheet was not found. | HqBool framebuffer_recalculate | ( | framebuffer_t * | framebuffer, |
| const RasterDescription * | rd | ||
| ) |
Calculate the size parameters for a framebuffer from a raster description and layout.
On exit, the number of frames, sheet size, frame size, band size, band height and bytes per line fields of the framebuffer are updated. If these parameters are different from existing parameters, any frame handles currently owned may be released by the framebuffer. No new frames will be acquired.
| [in,out] | framebuffer | The framebuffer to update parameters for. |
| [in] | rd | A raster description prepared for rendering a sheet. This raster description must be unpacked (the raster layout pointer must be valid). |
| TRUE | The framebuffer sizes were recalculated successfully. Existing frames will have been released if they do not match the new sizes. |
| FALSE | There was an error recalculating the framebuffer sizes. This is a permanent fatal error, meaning that this raster description cannot be used with the framebuffer support code. For example, this code cannot support different data sizes in each frame, or different line sizes in different planes of the raster layout. |
| void framebuffer_release | ( | framebuffer_t * | framebuffer | ) |
Release all of the frames in a framebuffer.
It is expected that this function will be called in job finish function of a raster backend, to release frame handles that are no longer needed. It could also be called at the end of the RIP's lifetime, if re-using frame buffers across jobs, or in the raster finish function (but only after finishing the last frame of the last separation of a page), if frame handles are not going to be re-used by different pages.
All frame/sheet handles currently owned by the framebuffer will have their release function called. All memory used by the framebuffer itself will be freed.
The framebuffer's frames array and n_frames count of frames are cleared, however other parameters may not be changed on release. The raster backend must call framebuffer_acquire() before attempting to render another page.
| [in,out] | framebuffer | The framebuffer to release. |
| void framebuffer_remove | ( | framebuffer_t * | framebuffer, |
| void * | handle | ||
| ) |
Take ownership of a frame handle away from the framebuffer.
It is expected that this function would be called in the raster finish function of a raster backend, to move responsibility for frames of raster data from the framebuffer to the raster backend. For example, if an output page queue is implemented, this function would be used to move rendered pages to the queue, where they will be processed later.
After calling this function with a frame handle, it is the caller's responsibility to free the frame handle.
| [in,out] | framebuffer | The framebuffer to remove a frame or sheet handle from. |
| [in] | handle | A frame or sheet handle previously acquired using the framebuffer::frame_acquire function to remove from the framebuffer. If this handle is NULL, ownership of all frames is taken by the client. Be careful about calling this function with handle NULL unless all sheets of the page have completed: this would lose any already-rendered content from separations of the page that have not yet been output. |
| void framebuffer_reuse | ( | framebuffer_t * | framebuffer, |
| uint32 | sheet_id | ||
| ) |
Forget associations between frame and sheet IDs and the handles they were assigned to, allowing the handle to be re-used for a different frame or sheet.
It is expected that this function would be called in the raster finish function of a raster backend, to disassociate all frames of the current sheet with frame handles.
| [in,out] | framebuffer | The framebuffer to remove the associations in. |
| [in] | sheet_id | A sheet to disassociate from the framebuffer. All frames for the sheet ID are disassociated. If id is zero, all associations are removed. Be careful about calling this function with ID zero unless all sheets of the page have completed: this would lose any already-rendered content from separations of the page that have not yet been output. |
Function to use as frame_acquire_fn when using framebuffer support to manage local memory rasters.
| [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.
| uint8* memfb_raster | ( | void * | handle, |
| size_t | offset, | ||
| size_t | size | ||
| ) |
Function to use as frame_raster_fn when using framebuffer support to manage local memory rasters.
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. | void memfb_release | ( | void * | handle, |
| size_t | size, | ||
| void * | data | ||
| ) |
Function to use as frame_release_fn when using framebuffer support to manage local memory rasters.
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. |
Function to use as frame_acquire_fn when using framebuffer support to manage shared memory rasters.
| [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.
| uint8* shmfb_raster | ( | void * | handle, |
| size_t | offset, | ||
| size_t | size | ||
| ) |
Function to use as frame_raster_fn when using framebuffer support to manage shared memory rasters.
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. | void shmfb_release | ( | void * | handle, |
| size_t | size, | ||
| void * | data | ||
| ) |
Function to use as frame_release_fn when using framebuffer support to manage shared memory rasters.
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. |