The raster store API is a line-based raster store for iHVD, eHVD, PGB partial paint, two-pass compositing band caching and other client use, implemented in the core library. More...

Files
file	rasterstoreapi.h
	Header file defining the Raster store interface.

Data Structures
struct	raster_store_params
	Parameters to control the raster store. More...

struct	raster_store_sizes
	Structure used by raster_store_flush() to return the sizes of different types of memory used. More...

struct	sw_rasterstore_api_20220429
	Raster store API version 20220429. More...

Macros
#define	RASTER_STORE_PARAMS_INIT
	Default initialiser for raster store params.

Typedefs
typedef struct raster_store_t	raster_store_t
	Opaque type of raster store.

typedef struct raster_store_read_t	raster_store_read_t
	Opaque type of raster store reader context.

typedef struct raster_store_params	raster_store_params
	Parameters to control the raster store.

typedef struct raster_store_sizes	raster_store_sizes
	Structure used by raster_store_flush() to return the sizes of different types of memory used.

typedef struct sw_rasterstore_api_20220429	sw_rasterstore_api_20220429
	Raster store API version 20220429.

Enumerations
enum	{ RASTER_USE_UNCOMPRESSED_MEMORY = 1 , RASTER_USE_COMPRESSED_MEMORY = 2 , RASTER_USE_DISK = 4 , RASTER_USE_ALL = RASTER_USE_UNCOMPRESSED_MEMORY \| RASTER_USE_COMPRESSED_MEMORY \| RASTER_USE_DISK }
	Flags for determining how to store the raster data. More...

enum	{ RASTER_COMPRESS_LZ4 , RASTER_COMPRESS_FLATE }
	Type of compression for the raster store. More...

Functions
HqnResult	raster_store_create (const raster_store_params params, raster_store_t *pstore)
	Create a raster store object. More...

void	raster_store_destroy (raster_store_t **pstore)
	Destroy a raster store object. More...

HqnResult	raster_store_write (raster_store_t store, unsigned int startline, unsigned int nlines, const struct RASTER_PLANE plane, const uint8 *buffer)
	Write a range of lines to a raster store. More...

raster_store_read_t *	raster_store_read_open (raster_store_t store, const struct RASTER_PLANE plane, HqnResult *perr)
	Open a context to read data from a raster store. More...

const uint8 *	raster_store_map_lines (raster_store_read_t ctxt, unsigned int pstartline, unsigned int pnlines, const struct RASTER_PLANE playout, HqnResult perr)
	Map the data for a range of lines in a raster store into memory. More...

HqnResult	raster_store_load_lines (raster_store_read_t ctxt, unsigned int pstartline, unsigned int pnlines, uint8 buffer, const struct RASTER_PLANE **playout)
	Load data for a range of lines from a raster store into a client's memory buffer. More...

void	raster_store_read_close (raster_store_read_t **pctxt)
	Close a context previously opened to read data from a raster store. More...

void	raster_store_flush (raster_store_t store, int storage_flags, size_t recover, raster_store_sizes *psizes)
	Compress, decompress, load and/or save data in a raster store to match requested storage tiers, and return a measure of the sizes of the data in different storage tiers. More...

Detailed Description

The raster store API is a line-based raster store for iHVD, eHVD, PGB partial paint, two-pass compositing band caching and other client use, implemented in the core library.

The interface is phrased in terms of lines, because eHVD needs to read data with any offset. Rasters are stored indexed by plane and a range of lines. The data is not understood at less than the line or plane granularity by this interface. A raster store object can store multiple planes of data related to a single raster. Multiple raster stores can exist at the same time.

A raster store API pointer must be discovered using RDR and assigned to a suitably-named API pointer variable before the API macros are used.

A raster store object is created by calling raster_store_create(), and destroyed when no longer needed by calling raster_store_destroy().

Data is copied to the raster store by calling raster_store_write(). Depending on the raster store usage flags, data may be immediately compressed and/or purged to storage, or lazily compressed and/or purged to storage in low memory.

Data may be read from the raster store by opening a reader context by calling raster_store_read_open(). Clients then either load data by calling raster_store_load_lines() (which copies the data to the client's buffer), or map data using raster_store_map_lines() (which presents blocks of data owned by the raster store to the client). The raster store retains ownership of mapped raster data, exposing pointers into buffers that it manages. The client will often iterate over a range of lines, repeating these calls, until they indicate that no more data is available. The reader context may be re-used for multiple data load or map requests, but should ultimately be closed by calling raster_store_read_close().

The client may request that the raster store compress, decompress, purge, or load data by calling raster_store_flush(). This call can be used in low memory to purge data to storage, reducing the raster store's memory footprint. Raster store data that is currently mapped will not be purged or compressed. This call can also be used to prepare a raster store for high speed consumption, by loading and uncompressing data.

A raster store API pointer must be discovered using RDR using class RDR_CLASS_API and type RDR_API_RASTERSTORE and assigned to a suitably-named API pointer variable before the API macros are used. The data API is automatically registered when the Harlequin RIP is started. It is deregistered when the Harlequin RIP is shutdown.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Flags for determining how to store the raster data.

At least one of the RASTER_USE_* flags must be supplied to raster_store_create().

Enumerator
RASTER_USE_UNCOMPRESSED_MEMORY	Data may be kept uncompressed in memory.
RASTER_USE_COMPRESSED_MEMORY	Data may be kept compressed in memory.
RASTER_USE_DISK	Data may be purged to disk.

◆ anonymous enum

anonymous enum

Type of compression for the raster store.

Enumerator
RASTER_COMPRESS_LZ4	Compress rasters using LZ4.
RASTER_COMPRESS_FLATE	Compress rasters using Flate.

Function Documentation

◆ raster_store_create()

HqnResult raster_store_create	(	const raster_store_params *	params,
		raster_store_t **	pstore
	)

Create a raster store object.

Parameters

[in]	params	Parameters for new band store.
[out]	pstore	A location to put the new band store.

Return values

HQN_RESULT_SUCCESS if the raster store was created. In this case, the raster store in *pstore must be released after use with raster_store_destroy().

Returns: Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

◆ raster_store_destroy()

void raster_store_destroy ( raster_store_t ** pstore )

Destroy a raster store object.

Parameters

[in,out] pstore A location to find the raster store to destroy. On exit, *pstore is set to NULL.

This function is safe to call if *pstore is NULL.

◆ raster_store_flush()

void raster_store_flush	(	raster_store_t *	store,
		int	storage_flags,
		size_t *	recover,
		raster_store_sizes *	psizes
	)

Compress, decompress, load and/or save data in a raster store to match requested storage tiers, and return a measure of the sizes of the data in different storage tiers.

Parameters

[in]	store	The raster store to flush.
[in]	storage_flags	A set of storage types that the user would prefer the data in. This is intersected with the storage flags used when the store was created, and any data not in one of those storage types will be compressed, decompressed, saved to disk, or loaded if possible to match the storage types allowed. If there are no storage types possible (either because storage_flags was zero or the intersection with the store's existing storage flags is zero), no action will be taken to change storage type.
[in,out]	recover	An optional location where the amount of memory the flush should attempt to recover is stored. If this is non-`NULL` on entry, the flush will only perform operations that reduce the amount of memory. On exit, *recover will be reduced by the amount of memory recovered, or to zero if more memory was recovered than requested. If this pointer is `NULL` on entry, the flush may increase the footprint in memory of the raster store.
[out]	psizes	A pointer to a size structure. If this is not `NULL`, the size of different types of storage used by the raster store will be written into this structure after any storage type adjustment is done. It is possible that data will still appear in a storage type that was not requested, the adjustment may not be able to change storage type if it is mapped or there was not enough memory.

◆ raster_store_load_lines()

HqnResult raster_store_load_lines	(	raster_store_read_t *	ctxt,
		unsigned int *	pstartline,
		unsigned int *	pnlines,
		uint8 *	buffer,
		const struct RASTER_PLANE **	playout
	)

Load data for a range of lines from a raster store into a client's memory buffer.

Either raster_store_map_lines() or raster_store_load_lines() should be used to access data in a raster store, depending on how the data will be used. raster_store_map_lines() accesses data buffers managed by the raster store, and should be used where the data will need some form of post-processing anyway (e.g., when performing masked blits for eHVD elements). raster_store_load_lines() should be used when the client needs a copy of the data in its own buffers, and does not need any processing while retrieving the data. In either case, raster_store_map_lines() or raster_store_load_lines() may return data for a subset of the lines that the client requested. It is the client's responsibility to re-issue requests for the remaining lines as needed.

Parameters

[in]	ctxt	A raster store reader context previously returned by raster_store_read_open().
[in,out]	pstartline	A pointer to the first line of data requested from the raster store. On a successful exit, this is updated to the first line of data loaded into the client buffer. This may be larger than the first line requested, if the raster store did not have any data stored for the requested first line. If there is no data in the range requested, *pstartline will be updated to the end of the range requested.
[in,out]	pnlines	A pointer to the number of lines of data requested from the raster store. On a successful exit, this is updated to the number of lines of data loaded into the client buffer. This may be smaller than the number of lines requested, if the raster store did not have data stored for all of the requested lines. If there is no data in the range requested, *pnlines will be updated to zero.
[out]	buffer	A buffer to load the raster store data into. Only the portion of the buffer representing the updated pstartline and pnlines range is modified.
[out]	playout	A location to store a pointer to the actual plane layout used by the raster store for these lines. The plane layout pointer remains valid until raster_store_read_close() is called. If this location is `NULL`, the plane layout will not be returned.

Return values

HQN_RESULT_SUCCESS if the data was loaded from the raster store into the client's buffer, for the lines in the updated *pstartline and *pnlines range. Note that if the updated *pstartline is greater than the requested first line, the data will not be at the start of the buffer, but will have been stored at a location adjusted by the difference in the actual and requested start lines. If there was no data in the store for the line range, then *pstartline will be updated to the end of the requested line range, and *pnlines will be update to zero.

Returns: Any other return value greater than MON_CLASS_ERROR is an error UID, indicating an error retrieving data from the raster store. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h. The raster store reader context is still open, and requires closing using raster_store_read_close().

◆ raster_store_map_lines()

const uint8* raster_store_map_lines	(	raster_store_read_t *	ctxt,
		unsigned int *	pstartline,
		unsigned int *	pnlines,
		const struct RASTER_PLANE **	playout,
		HqnResult *	perr
	)

Map the data for a range of lines in a raster store into memory.

Either raster_store_map_lines() or raster_store_load_lines() should be used to access data in a raster store, depending on how the data will be used. raster_store_map_lines() accesses data buffers managed by the raster store, and should be used where the data will need some form of post-processing anyway (e.g., when performing masked blits for eHVD elements). raster_store_load_lines() should be used when the client needs a copy of the data in its own buffers, and does not need any processing while retrieving the data. In either case, raster_store_map_lines() or raster_store_load_lines() may return data for a subset of the lines that the client requested. It is the client's responsibility to re-issue requests for the remaining lines as needed.

Parameters

[in]	ctxt	A raster store reader context previously returned by raster_store_read_open().
[in,out]	pstartline	A pointer to the first line of data requested from the raster store. On a successful exit, this is updated to the first line of data represented in the buffer. This may be larger than the first line requested, if the raster store did not have any data stored for the requested start line. If there is no data in the range requested, *pstartline will be updated to the end of the range requested.
[in,out]	pnlines	A pointer to the number of lines of data requested from the raster store. On a successful exit, this is updated to the number of lines of data represented in the buffer. This may be smaller than the number of lines requested, if the raster store did not have data stored for all of the requested lines. If there is no data in the range requested, *pnlines will be updated to zero.
[out]	playout	A location to store a pointer to the actual plane layout used by the raster store for these lines. The plane layout pointer remains valid until raster_store_read_close() is called. If this location is `NULL`, the plane layout will not be returned.
[out]	perr	A location in which an error code is stored, if data could not be retrieved from the raster store.

Returns: A pointer to data representing the lines in the updated *pstartline and *pnlines range, or NULL if there was either no data or an error getting the data. If the pointer is non-NULL, the data returned is owned by the raster store, and must not be modified by the client. This pointer remains valid until the next call to raster_store_map_lines() using the same reader context, or until raster_store_read_close() is called.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is either HQN_RESULT_SUCCESS, indicating there was no data in the range requested; or it is a code greater than MON_CLASS_ERROR indicating the error that occurred retrieving data from the store. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

If there was no data in the range requested, then NULL is returned, *perr is set to HQN_RESULT_SUCCESS, *pnlines is updated to zero and *pstartline is updated to the end of the requested range.

In all cases the raster store reader context remains open, and requires closing using raster_store_read_close().

◆ raster_store_read_close()

void raster_store_read_close ( raster_store_read_t ** pctxt )

Close a context previously opened to read data from a raster store.

Parameters

[in,out] pctxt The address of a raster store reader context previously returned by raster_store_read_open(). The context will be set to NULL on return. This function is safe to call with a NULL context.

After closing a raster store reader context, any data buffer pointer previously returned by raster_store_map_lines() for this context will be invalid and should not be dereferenced.

◆ raster_store_read_open()

raster_store_read_t* raster_store_read_open	(	raster_store_t *	store,
		const struct RASTER_PLANE *	plane,
		HqnResult *	perr
	)

Open a context to read data from a raster store.

Parameters

[in]	store	The raster store the data should be read from.
[in]	plane	The description of the raster store data to be read. This description may include anonymised channels. If data is stored matching the plane layout for all the non-anonymised channels, then it will be returned, and this plane layout structure will be updated.
[out]	perr	A location in which an error code is stored, if the reader context could not be created.

Returns: A raster store reader context, or NULL on failure. If a raster store reader context was returned, it must be closed by calling raster_store_read_close() after all accesses to raster data using the context are complete.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is 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.

Each reader context can only map one line buffer at a time. The context may be used by any number callers to raster_store_load_lines() simultaneously. However, if a client or clients need to map multiple buffers from the store simultaneously, multiple reader contexts should be opened, one for each thread or mapping required at the same time.

◆ raster_store_write()

HqnResult raster_store_write	(	raster_store_t *	store,
		unsigned int	startline,
		unsigned int	nlines,
		const struct RASTER_PLANE *	plane,
		const uint8 *	buffer
	)

Write a range of lines to a raster store.

Parameters

[in]	store	The raster store the lines should be written to.
[in]	startline	The first line of data represented in buffer.
[in]	nlines	The number of lines of data represented in buffer.
[in]	plane	The description of the raster store data to write.
[in]	buffer	The address of the raster plane data to write.

Return values

HQN_RESULT_SUCCESS if the raster data was stored successfully. This may include compressing and/or writing to disk, if the data cannot be retained uncompressed or in memory.

Returns: Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ raster_store_create()

◆ raster_store_destroy()

◆ raster_store_flush()

◆ raster_store_load_lines()

◆ raster_store_map_lines()

◆ raster_store_read_close()

◆ raster_store_read_open()

◆ raster_store_write()