|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
A simple streaming abstraction to handle RIP I/O when using the Reference API. More...
Data Structures | |
| struct | _HqnReadStream |
| This structure encapsulates the functions required to implement an input stream. More... | |
| struct | _HqnWriteStream |
| This structure encapsulates the functions required to implement an output stream. More... | |
Typedefs | |
| typedef int32(* | StreamCloseFn) (void *pPrivate) |
| Called by the RIP to close the stream. The implementation may perform any cleanup actions that are required by the underlying streaming protocol. More... | |
| typedef int32(* | StreamBytesFn) (void *pPrivate, Hq32x2 *pBytes, int32 reason) |
| Determine the bytes available or the total size of the stream. More... | |
| typedef int32(* | ReadStreamSeekFn) (void *pPrivate, Hq32x2 *pos, int32 flag) |
| Perform a seek on the input stream. More... | |
| typedef int32(* | ReadStreamReadFn) (void *pPrivate, uint8 *pBuffer, int32 cbRequested) |
| Read some bytes from the input stream. More... | |
| typedef int32(* | WriteStreamSeekFn) (void *pPrivate, Hq32x2 *pPos, int32 flag) |
| Perform a seek on the output stream. More... | |
| typedef int32(* | WriteStreamWriteFn) (void *pPrivate, uint8 *pBuffer, int32 cbAvailable) |
| Write some bytes to the output stream. More... | |
| typedef struct _HqnReadStream | HqnReadStream |
| This structure encapsulates the functions required to implement an input stream. | |
| typedef struct _HqnWriteStream | HqnWriteStream |
| This structure encapsulates the functions required to implement an output stream. | |
A simple streaming abstraction to handle RIP I/O when using the Reference API.
The Reference API permits jobs to be submitted as static files on disk, and for the output to be written to disk in various supported formats. However, it is also possible for the input and output to be handled via arbitrary streams, provided that those streams are implemented by the caller. This header file provides the signatures for such implementations.
To implement an input stream, the calling code must supply an implementation of StreamCloseFn, StreamBytesFn, ReadStreamSeekFn and ReadStreamReadFn. The seeking function must be implemented, although it is permitted to return an error in cases where random access is not supported. These four implementations must be packaged into a HqnReadStream object structure, also defined in this file.
To implement an output stream, the calling code must supply an implementation of StreamCloseFn, StreamBytesFn, WriteStreamSeekFn and WriteStreamWriteFn. These are then packaged into a HqnWriteStream structure.
A stream is per-job. There is no call to open a stream, or to reset it, either for input or output. A close call is provided in case the implementation needs to perform cleanup actions at the end of a job.
Read some bytes from the input stream.
| pPrivate | The private data pointer from the stream structure. This must be supplied to every function call made on the stream, in order for the implementation to access any internal state that it needs to store. |
| pBuffer | Pointer to a byte buffer, into which the stream implementation should copy the next chunk of input data. This buffer memory is managed by the RIP. The stream implementation should not attempt to free this memory, nor should it ever store away the pointer for later use. |
| cbRequested | Maximum number of bytes that should be copied. |
Perform a seek on the input stream.
If random access is not supported by the stream implementation, the RIP may still call this function as a way of obtaining the current value of the stream pointer. It does this by requesting a seek of zero, relative to the current file position.
A seek of zero relative to the end of the stream must be interpreted as a flush operation. For a seekable stream this will simply be a seek to the end of the stream. For a non-seekable stream it requires all pending input to be discarded.
| pPrivate | The private data pointer from the stream structure. This must be supplied to every function call made on the stream, in order for the implementation to access any internal state that it needs to store. |
| pos | A signed 64-bit value indicating the target movement. The implementation should always update this value with the current stream pointer after performing the seek. |
| flag | One of STREAM_POSITION_START, STREAM_POSITION_CURRENT or STREAM_POSITION_END. The pPos argument is then interpreted as being relative to the start of the stream, relative to the current location, or relative to the end of the stream respectively. |
Determine the bytes available or the total size of the stream.
| pPrivate | The private data pointer from the stream structure. This must be supplied to every function call made on the stream, in order for the implementation to access any internal state that it needs to store. |
| pBytes | A signed 64-bit value to be updated with the bytes available or total size as appropriate. |
| reason | Either STREAM_BYTES_AVAILABLE or STREAM_BYTES_TOTAL to indicate what pBytes should be set to. |
| typedef int32( * StreamCloseFn) (void *pPrivate) |
Called by the RIP to close the stream. The implementation may perform any cleanup actions that are required by the underlying streaming protocol.
| pPrivate | The private data pointer from the stream structure. This must be supplied to every function call made on the stream, in order for the implementation to access any internal state that it needs to store. |
Perform a seek on the output stream.
If random access is not supported by the stream implementation, the RIP may still call this function as a way of obtaining the current value of the stream pointer. It does this by requesting a seek of zero, relative to the current file position.
| pPrivate | The private data pointer from the stream structure. This must be supplied to every function call made on the stream, in order for the implementation to access any internal state that it needs to store. |
| pPos | A signed 64-bit value indicating the target movement. The implementation should always update this value with the current stream pointer after performing the seek. |
| flag | One of STREAM_POSITION_START, STREAM_POSITION_CURRENT or STREAM_POSITION_END. The pPos argument is then interpreted as being relative to the start of the stream, relative to the current location, or relative to the end of the stream respectively. |
Write some bytes to the output stream.
| pPrivate | The private data pointer from the stream structure. This must be supplied to every function call made on the stream, in order for the implementation to access any internal state that it needs to store. |
| pBuffer | Pointer to a byte buffer, from which the stream implementation should copy the next chunk of output data. This buffer memory is managed by the RIP. The stream implementation should not attempt to free this memory, nor should it ever store away the pointer for later use. |
| cbAvailable | Maximum number of bytes that should be copied. |