|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
Raster store API version 20220429. More...
#include "rasterstoreapi.h"
Data Fields | |
| HqnResult(* | store_create )(const raster_store_params *params, raster_store_t **pstore) |
| Create a raster store object. More... | |
| void(* | store_destroy )(raster_store_t **pstore) |
| Destroy a raster store object. More... | |
| HqnResult(* | 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 *(* | read_open )(raster_store_t *store, const struct RASTER_PLANE *plane, HqnResult *perr) |
| Open a context to read data from a raster store. More... | |
| void(* | read_close )(raster_store_read_t **pctxt) |
| Close a context previously opened to read data from a raster store. More... | |
| const uint8 *(* | 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(* | 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(* | 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... | |
Raster store API version 20220429.
| void(* sw_rasterstore_api_20220429::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.
| [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. |
| HqnResult(* sw_rasterstore_api_20220429::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.
| [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. |
| 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. |
| const uint8*(* sw_rasterstore_api_20220429::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.
| [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. |
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().
| void(* sw_rasterstore_api_20220429::read_close) (raster_store_read_t **pctxt) |
Close a context previously opened to read data from a raster store.
| [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_t*(* sw_rasterstore_api_20220429::read_open) (raster_store_t *store, const struct RASTER_PLANE *plane, HqnResult *perr) |
Open a context to read data from a raster store.
| [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. |
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.
| HqnResult(* sw_rasterstore_api_20220429::store_create) (const raster_store_params *params, raster_store_t **pstore) |
Create a raster store object.
| [in] | params | Parameters for new band store. |
| [out] | pstore | A location to put the new band store. |
| 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(). |
| void(* sw_rasterstore_api_20220429::store_destroy) (raster_store_t **pstore) |
Destroy a raster store object.
| [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.
| HqnResult(* sw_rasterstore_api_20220429::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.
| [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. |
| 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. |