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	framebuffer_acquire_t
	Parameters to acquire a framebuffer using framebuffer_acquire() or fbassoc_acquire(). 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...

Macros
#define	FBACQUIRE_HAS_FIELD(params_, field_) ((params_)->size >= offsetof(framebuffer_acquire_t, field_) + sizeof((params_)->field_))
	Macro indicating if a framebuffer_acquire_t structure has size sufficient to include a named field.

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 void()	framebuffer_data_release_fn(void *data)
	Type of a function used to release the opaque data pointer from a framebuffer object before it is released. More...

typedef struct framebuffer_t	framebuffer_t
	Type containing a framebuffer instance's data. More...

typedef struct framebuffer_acquire_t	framebuffer_acquire_t
	Parameters to acquire a framebuffer using framebuffer_acquire() or fbassoc_acquire().

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 framebuffer_acquire_t params)
	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...

HqnResult	fbassoc_acquire (uintptr_t key, const framebuffer_acquire_t *params)
	Ensure a framebuffer object exists in the framebuffer association and acquire the frames for it. More...

void	fbassoc_reuse (uintptr_t key, uint32 sheet_id)
	Allow a framebuffer to be reused. More...

void	fbassoc_release (uintptr_t key)
	Release all of the frames in a framebuffer. More...

framebuffer_t *	fbassoc_find (uintptr_t key)
	Find a framebuffer object associated with a key. More...

void	fbassoc_destroy (void)
	Destroy the framebuffer association, releasing all framebuffers and the association itself. 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...

Detailed Description

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 for dynamic separations or separation omission.

A thread-safe framebuffer association is supported, to allow manipulation of multiple framebuffers simultaneously. This is necessary when using eHVD enabled raster backends with framebuffers, outputting the composited eHVD page to a framebuffer may run in parallel with output to an eHVD element framebuffer if Harlequin Parallel Pages is enabled. The thread-safe framebuffer functions require a key to identify calls that should be associated with the same framebuffer. In the raster API functions, the raster layout pointer obtained from the RASTER_REQUIREMENTS, RASTER_DESTINATION, or RasterDescription structures can be used as a key.

The expected usage of these functions are:

framebuffer_acquire() or fbassoc_acquire() are 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 fbassoc_reuse() are called during the raster finish call (RASTER_FINISH_EX) made when completing a separation, if the framebuffer memory should be retained and re-used for another page.

framebuffer_remove() may be called during the raster finish call (RASTER_FINISH_EX) made when completing a separation, to remove responsibility for cleaning up a framebuffer separation from the framebuffer. This is used when transferring responsibility for freeing a raster handle to an eHVD monitor. framebuffer_remove() should not be called if framebuffer_reuse() or fbassoc_reuse() will be called.

framebuffer_release() is called in the raster finish call if the framebuffer will not be reused, or in the job end call (RASTER_JOB_END_EX) if there is only a single framebuffer possible. fbassoc_release() is called in the raster finish call if multiple framebuffers are possible.

fbassoc_destroy() is called in the job end call (RASTER_JOB_END_EX) to destroy all framebuffers in the association, and destroy the association itself.

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.

fbassoc_find() may be used to get the framebuffer object associated with a key. This can be used to read framebuffer object fields, and to find a framebuffer object to pass to framebuffer_destination() or framebuffer_address().

Using local memory framebuffers for raster output

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().

Using shared memory framebuffers for raster output

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.

Typedef Documentation

◆ frame_acquire_fn

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.

Parameters

[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.

Returns: A handle used to access the raster data for the specified frame or sheet, or 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.

◆ frame_raster_fn

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.

Parameters

[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.

Returns: A non-NULL pointer to a buffer of raster data of the size and offset specified.

◆ frame_release_fn

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.

Parameters

[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.

◆ framebuffer_data_release_fn

typedef void() framebuffer_data_release_fn(void *data)

Type of a function used to release the opaque data pointer from a framebuffer object before it is released.

Parameters

[in] data The framebuffer_t::data pointer, originally supplied to framebuffer_acquire() or fbassoc_acquire() in the framebuffer_acquire_t::data field.

◆ framebuffer_t

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.

◆ memfb_framebuffer_data

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.

◆ shmfb_framebuffer_data

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.

Function Documentation

◆ fbassoc_acquire()

HqnResult fbassoc_acquire	(	uintptr_t	key,
		const framebuffer_acquire_t *	params
	)

Ensure a framebuffer object exists in the framebuffer association and acquire the frames for it.

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.

If the framebuffer object already exists, 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 fbassoc_reuse() at the end of outputting each sheet.

Parameters

[in]	key	A key identifying the framebuffer to construct and acquire frames for. The key 0 should not be used by clients: it is used internally when marking a framebuffer for re-use and acquiring framebuffers that may have been re-used.
[in]	params	A pointer to a parameter structure containing callbacks, data, and configuration flags for acquiring the framebuffer.

Return values

HQN_RESULT_SUCCESS (0) if the framebuffer object exists or was constructed and all of the frames were obtained.

Returns: An error code greater than MON_CLASS_ERROR if the framebuffer could not be constructed, if any of the frames could not be obtained, or could not be associated with a handle. Any previously acquired frames are de-associated with a frame or sheet ID and released. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h. The framebuffer_acquire_t::data pointer will not be released if there is an error acquiring the framebuffer.

◆ fbassoc_destroy()

void fbassoc_destroy ( void )

Destroy the framebuffer association, releasing all framebuffers and the association itself.

It is expected that this function will be called in job finish function of a raster backend, to release frame handles and framebuffer objects that are still in the association. It could also be called at the end of the RIP's lifetime, if re-using frame buffers across jobs.

◆ fbassoc_find()

framebuffer_t* fbassoc_find ( uintptr_t key )

Find a framebuffer object associated with a key.

Parameters

[in] key A key identifying the framebuffer to return.

Returns: The framebuffer object associated with key, or NULL if no framebuffer was associated with key.

◆ fbassoc_release()

void fbassoc_release ( uintptr_t key )

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 data field will be released if there is a non-NULL data release function.

The framebuffer object itself will be destroyed.

Parameters

[in] key A key identifying the framebuffer to release.

◆ fbassoc_reuse()

void fbassoc_reuse	(	uintptr_t	key,
		uint32	sheet_id
	)

Allow a framebuffer to be reused.

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. Re-associate the framebuffer with key 0.

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.

Parameters

[in]	key	A key identifying the framebuffer to disassociate the sheet ID from.
[in]	sheet_id	A sheet to disassociate from the framebuffer. All frames for the sheet ID are disassociated. If the 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.

Note: After calling fbassoc_reuse(), the raster backend must call fbassoc_acquire() to re-acquire frames before another render pass.

◆ framebuffer_acquire()

HqnResult framebuffer_acquire	(	framebuffer_t *	framebuffer,
		const framebuffer_acquire_t *	params
	)

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.

Parameters

[in,out]	framebuffer	The framebuffer to acquire frames for.
[in]	params	A pointer to a parameter structure containing callbacks, data, and configuration flags for acquiring the framebuffer.

Return values

HQN_RESULT_SUCCESS (0) if all of the frames were obtained.

Returns: An error code greater than MON_CLASS_ERROR if any of the frames could not be obtained, or could not be associated with a handle. Any previously acquired frames are de-associated with a frame or sheet ID and released. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h. The framebuffer_acquire_t::data pointer will not be released if there is an error acquiring the framebuffer.

◆ framebuffer_address()

uint8* framebuffer_address	(	framebuffer_t *	framebuffer,
		uint32	id
	)

Obtain a pointer to a frame's raster buffer.

Parameters

[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.

Returns: A pointer to the memory for the plane of the framebuffer, or NULL if the frame or sheet was not found.

◆ framebuffer_destination()

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.

Parameters

[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.

Return values

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.

◆ framebuffer_handle()

void* framebuffer_handle	(	framebuffer_t *	framebuffer,
		uint32	id
	)

Retrieve a handle from a frame's raster buffer.

Parameters

[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.

Returns: The frame or sheet handle previously acquired for the sheet or frame selected by the framebuffer::frame_acquire function, or NULL if the frame or sheet was not found.

◆ framebuffer_recalculate()

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.

Parameters

[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).

Return values

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.

◆ framebuffer_release()

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.

If the framebuffer's data_release_fn function pointer and the framebuffer's data pointer are non-NULL, the data release function will be called to release the data.

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.

Parameters

[in,out] framebuffer The framebuffer to release.

◆ framebuffer_remove()

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.

Parameters

[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.

Note: After calling framebuffer_remove(), the raster backend must call framebuffer_acquire() before another render pass.

◆ framebuffer_reuse()

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.

Parameters

[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 the 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.

Note: After calling framebuffer_reuse(), the raster backend must call framebuffer_acquire() before another render pass.

◆ memfb_acquire()

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.

Parameters

[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.

Returns: A handle used to access the raster data for the specified frame or sheet, or 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.

◆ memfb_raster()

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.

Parameters

[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.

Returns: A non-NULL pointer to a buffer of raster data of the size and offset specified.

◆ memfb_release()

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.

Parameters

[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.

◆ shmfb_acquire()

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.

Parameters

[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.

Returns: A handle used to access the raster data for the specified frame or sheet, or 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.

◆ shmfb_raster()

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.

Parameters

[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.

Returns: A non-NULL pointer to a buffer of raster data of the size and offset specified.

◆ shmfb_release()

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.

Parameters

[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.

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

Using local memory framebuffers for raster output

Using shared memory framebuffers for raster output

Typedef Documentation

◆ frame_acquire_fn

◆ frame_raster_fn

◆ frame_release_fn

◆ framebuffer_data_release_fn

◆ framebuffer_t

◆ memfb_framebuffer_data

◆ shmfb_framebuffer_data

Function Documentation

◆ fbassoc_acquire()

◆ fbassoc_destroy()

◆ fbassoc_find()

◆ fbassoc_release()

◆ fbassoc_reuse()

◆ framebuffer_acquire()

◆ framebuffer_address()

◆ framebuffer_destination()

◆ framebuffer_handle()

◆ framebuffer_recalculate()

◆ framebuffer_release()

◆ framebuffer_remove()

◆ framebuffer_reuse()

◆ memfb_acquire()

◆ memfb_raster()

◆ memfb_release()

◆ shmfb_acquire()

◆ shmfb_raster()

◆ shmfb_release()