This file implements the interface between the "push" model of the SwLe
example skin functions, and the natural "pull" model of the core Harlequin RIP interface. It does this by synchronizing the thread on which the RIP is running with the calling application thread.
More...
#include "skinkit.h"
#include "skinmon.h"
#include "kit.h"
#include "sync.h"
#include "ripthread.h"
#include "file.h"
#include "paths.h"
#include "mem.h"
#include "hqmemcpy.h"
#include "hqmemcmp.h"
#include "devparam.h"
#include "threadapi.h"
#include "swevents.h"
#include "probelog.h"
#include "swtrace.h"
#include "skintimeline.h"
#include "timer.h"
#include "skindevs.h"
#include "inputq.h"
#include "inputqprv.h"
#include "hotfolderprv.h"
#include "tiling_methods.h"
#include "zlibrdr.h"
#include "swhtm.h"
#include "antialias.h"
#include "swdataapi.h"
#include "apis.h"
#include "rasthand.h"
#include "timelineerrors.h"
#include "swcopyf.h"
#include <stdlib.h>
#include <stdio.h>
#include <stdarg.h>
#include <stddef.h>
#include <string.h>
#include <errno.h>
#include "zlibapi.h"
Data Structures | |
struct | RasterData |
Data used by raster backend calls. More... | |
struct | ControlData |
Gathers together various data involved in controlling the RIP and recording its current state. More... | |
Macros | |
#define | SwLeASSERT(condition_, message_) |
Enumerations | |
enum | rip_state_t { UNSTARTED = 1 , INITIALISING , WAITING_FOR_JOB_START , PROCESSING_JOB_START , PROCESSING_PS , PROCESSING_JOB_END , EXITING , EXITED } |
Used to implement a simple state machine representing the lifecycle of the RIP. More... | |
enum | raster_state_t { RASTER_UNSTARTED = 1 , RASTER_STARTED , RASTER_WRITE_ERROR , RASTER_FINISHED } |
Used to implement a simple state machine representing the lifecycle of the raster output. More... | |
Functions | |
API_VERSIONED (sw_zlib_api, ZLIB_API_VERSION) | |
Used to implement a simple state machine representing the host application's calls to the high-level SwLe RIP controller functions, SwLeStart(), SwLeJobStart(), SwLePs() and SwLeJobEnd(). This state machine is used to assert that the application is calling into the SwLe interface in the correct order. More... | |
void | KSwLeStop (void) |
Called as part of the RIP's exit procedure. More... | |
static void | PYieldToRIP (void) |
This function should only be called by the main application thread when it wants to yield to the RIP thread. | |
static void | PYieldToApp (void) |
This function should only be called by the RIP thread when it wants to yield to the main application thread. | |
static HqBool | SkinDynamicBufferExtend (SkinDynamicBuffer *buffer, size_t needs) |
static void | SwLeFAIL (const char *message) |
static sw_event_result | skin_job_number (void *context, sw_event *event) |
HqBool | SwLeInitRuntime (void *pContext) |
Initializes skinkit variables prior to starting the RIP. More... | |
HqBool | SwLeSDKStart (size_t *RIP_maxAddressSpaceInBytes, size_t *RIP_workingSizeInBytes, void *pMemory, SysMemFns *pSysMemFns, uint8 **reasonText) |
Initialise SDK support libraries for the RIP. More... | |
void | SwLeSDKEnd (int32 exitCode) |
Shutdown the SDK support libraries. More... | |
sw_tl_ref | SkinTimeline (void) |
Return the top-level skin timeline, created by SwLeSDKStart(). | |
void | SwLeMemInit (size_t RIP_maxAddressSpaceInBytes, size_t RIP_workingSizeInBytes, size_t RIP_emergencySizeInBytes, void *pMemory) |
Pre-initializes the RIP, giving it the memory arena prepared by SwLeSDKStart(). More... | |
HqBool | SwLeStart (size_t RIP_maxAddressSpaceInBytes, size_t RIP_workingSizeInBytes, size_t RIP_emergencySizeInBytes, void *pMemory, SwLeMONITORCALLBACK *pfnMonitor) |
Starts the Harlequin RIP, giving it the memory arena prepared by SwLeSDKStart(). More... | |
int32 | SwLeStop (void) |
Request that the RIP shutdown. More... | |
void | SwLeShutdown (void) |
Performs shutdown operations when the application exits. More... | |
void | SwLeSetRipExitFunction (SwLeRIPEXITCALLBACK *pfnRipExit) |
Supply a callback function to be called when the RIP exits. More... | |
void | SwLeSetRipRebootFunction (SwLeRIPREBOOTCALLBACK *pfnRipReboot) |
Supply a callback function to be called when the RIP reboots. More... | |
void | SwLeSetRasterAPI (sw_raster_api_20230105 *api) |
Sets the API structure that the RIP will call back to present raster data to the skin. More... | |
HqBool | SwLeSetJobName (const uint8 *name, size_t namelen) |
Low-level function to set the job name used by the next job invoked by SwLeJobStart(). More... | |
void | SwLeSetJobNumber (int32 jobno) |
Low-level function to set the job number used by the next job invoked by SwLeJobStart(). More... | |
HqBool | SwLeJobStart (uint32 cbBuffer, uint8 *pBuffer, void *pJobContext) |
Low-level function to prepare the Harlequin RIP to receive a PostScript language job. More... | |
HqBool | SwLePs (uint32 cbBuffer, uint8 *pBuffer) |
Low-level function to pass a chunk of PostScript language data to the Harlequin RIP. More... | |
HqBool | SwLeJobEnd (void) |
Low-level function to terminate the current job. More... | |
sw_data_api * | GetDataAPI (void) |
Get and cache the data API pointer. More... | |
void | SkinDynamicBufferReset (SkinDynamicBuffer *buffer) |
Reset a dynamic buffer to contain no data, but preserve the existing allocated memory. More... | |
void | SkinDynamicBufferFree (SkinDynamicBuffer *buffer) |
Free any memory allocated for dynamic buffer data. More... | |
HqBool | SkinDynamicBufferAdd (SkinDynamicBuffer *buffer, const char *format,...) |
Helper function to write formatted string (using swncopyf()) to the end of a dynamic buffer, extending the buffer as necessary. More... | |
int32 | SwLeProcessInputQueue (void) |
Process a job from the skin's input queue implementation. More... | |
int32 | SwLeProcessJobs (SwLeDoParams *params) |
Process jobs from the input queue using SwLeProcessInputQueue() until there are no more jobs and (optionally) no more input sources. More... | |
int32 | SwLeDo (int32 op, SwLeDoParams *params) |
Perform required operations to reach the requested SDK and RIP state. More... | |
HqBool | SwLeInJob (void) |
Low-level function to indicate if the skin is within a job. More... | |
HqBool | SwLeProcessingError (void) |
Low-level function to indicate whether an error occurred in the most recent chunk of job data that was processed by the RIP. More... | |
void | SkinExit (int32 n, uint8 *text) |
Called when the RIP exits. More... | |
void | SkinReboot (void) |
Called when RIP reboots. More... | |
int32 | SwLeExitCode (void) |
Returns the exit status of the RIP. More... | |
void | SwLeSetMonitorFunction (SwLeMONITORCALLBACK *pfnMonitor) |
Set the default monitor information callback function for the SDK. More... | |
void | SkinMonitorl (int32 cbData, const uint8 *pszMonitorData) |
Display a message through the monitor callback, if provided. More... | |
void | RIPMonitorl (int32 cbData, const uint8 *pszMonitorData) |
Display a message through the monitor callback, if provided. More... | |
void | SkinVEMonitorf (sw_tl_ref tl, sw_mon_channel channel, sw_mon_type type, const char *format, va_list vlist) |
Similar to SkinEMonitorf(), but with an explicit vararg list. More... | |
void | SkinEMonitorf (sw_tl_ref tl, sw_mon_channel channel, sw_mon_type type, const char *format,...) |
Display a formatted message through the event system. More... | |
void | SkinMonitorf (const char *format,...) |
Display a formatted message through monitor events, or the monitor callback, if provided. More... | |
int32 | KGetConfigAvailable (void) |
This method is called from the RIP thread by the config device to determine how much config data, if any is available. This data would then be obtained by the RIP via KGetConfigData(). More... | |
void * | KGetConfigJobContext (void) |
Method called from the RIP thread by the config device to get the opaque job context pointer supplied by the user to SwLeJobStart(). More... | |
HqBool | KGetConfigJobFailed (sw_mon_type *monuid, const char **detail) |
Method called from the RIP thread by the config device to get the error status of a job for ending a RIP timeline. More... | |
HqBool | KGetConfigData (int32 cbMax, uint8 **ppData, uint32 *pcbData) |
This method is called from the RIP thread by the config device when it is ready for the config data for next job. Config data is provided by the app via SwLeJobStart(). More... | |
HqBool | KGetJobData (int32 cbMax, uint8 **ppData, uint32 *pcbData) |
This method is called from the RIP thread by the monitor device when it is ready for data from the current job. This data is provided by the app via SwLePs(). More... | |
RASTER_result | KCallRasterStart (RasterDescription *pRasterDescription) |
This function informs the raster callback implementation that raster data for is about to be written for a separation. More... | |
RASTER_result | KCallRasterWriteData (RasterDescription *pRasterDescription, uint8 *pBuffer) |
This function hands a band of raster data generated from the current job page to the raster callback implementation, if any, that the application has registered. More... | |
RASTER_result | KCallRasterFinish (RasterDescription *pRasterDescription, HqBool ok) |
This function informs the raster callback implementation that raster data for a separation is complete. More... | |
void | KCallRasterJobEnd (RasterDescription *pRasterDescription) |
This function informs the raster callback implementation that raster data for a job is complete. More... | |
RASTER_result | KCallRasterBandSize (RASTER_BANDSIZE *pBandSize) |
A callback function which allows the skin to affect the band size calculation. More... | |
int32 | KCallParamCallback (SwLeParamCallback *skin_hook, const void *param) |
This function informs the skin whenever a monitored parameter changes. If no callback has been registered, nothing happens. More... | |
HqBool | KParamSetCallback (PARAM params[], size_t n_params, const char *paramname, int32 paramtype, SwLeParamCallback *pfnParamCallback) |
Utility function to set skin callbacks. More... | |
RASTER_result | KCallRasterRequirements (RASTER_REQUIREMENTS *pRasterRequirements, RasterDescription *pRasterDescription) |
A callback function which gives the skin the details of the raster it is about to be handed, and gives the skin an opportunity to allocate memory to contain it. More... | |
RASTER_result | KCallRasterDestination (RASTER_DESTINATION *pRasterDestination, int32 separationIndex) |
A callback function which asks the skin to provide a memory address range into which to render. More... | |
RASTER_result | KCallBlankPage (RASTER_BLANK *pBlank, RasterDescription *pRasterDescription) |
This function tells the raster backend implementation that a page is blank, and allows it to determine how to handle the page. More... | |
HqBool | KSetSystemErrorLevel (int32 errlevel) |
Set system error record level. More... | |
int32 | KGetSystemErrorLevel (void) |
Get system error record level set by KSetSystemErrorLevel(). | |
Variables | |
struct { | |
SkinDynamicBuffer jobname | |
int32 jobno | |
} | job_details |
static sw_data_api * | dataapi = ((void*)0) |
The cached Data API pointer. | |
This file implements the interface between the "push" model of the SwLe
example skin functions, and the natural "pull" model of the core Harlequin RIP interface. It does this by synchronizing the thread on which the RIP is running with the calling application thread.
#define SwLeASSERT | ( | condition_, | |
message_ | |||
) |
Similar to HQASSERT, but call SwLeFAIL() if the condition is not true. This is only used in this file for checking the SwLe* call state machine so that OEMs can debug problems in the calling sequence by using the monitor callbacks.
enum raster_state_t |
Used to implement a simple state machine representing the lifecycle of the raster output.
enum rip_state_t |
Used to implement a simple state machine representing the lifecycle of the RIP.
API_VERSIONED | ( | sw_zlib_api | , |
ZLIB_API_VERSION | |||
) |
Used to implement a simple state machine representing the host application's calls to the high-level SwLe
RIP controller functions, SwLeStart(), SwLeJobStart(), SwLePs() and SwLeJobEnd(). This state machine is used to assert that the application is calling into the SwLe
interface in the correct order.
< No SwLe
functions called yet.
< SwLeInitRuntime() called.
< SwLeSDKStart() called.
< SwLeMemInit() called.
< SwLeStart() has been legally called.
< SwLeJobStart() has been legally called.
< SwLePs() has been legally called.
< SwLeJobEnd() has been legally called.
< SwLeStop has been called.
< SwLeSDKEnd has been called.
RASTER_result KCallBlankPage | ( | RASTER_BLANK * | pBlank, |
RasterDescription * | rasterDescription | ||
) |
This function tells the raster backend implementation that a page is blank, and allows it to determine how to handle the page.
The RASTER_BLANK::action field indicates on entry the default action that will be taken if there is no error. This action may be changed by the callee.
[in,out] | pBlank | Structure providing the reason for the blank page call, and the action to take for the blank page. This is initialised to contain the default action for the reason for the blank page call. The handler may just set RASTER_BLANK::handled to TRUE and return if it wants to use the default action. |
rasterDescription | Description of the blank page. If called because all separations were omitted, there will be no colorants in the raster description. |
int32 KCallParamCallback | ( | SwLeParamCallback * | pfnParamCallback, |
const void * | param | ||
) |
This function informs the skin whenever a monitored parameter changes. If no callback has been registered, nothing happens.
pfnParamCallback | The callback function registered for the parameter. |
param | The parameter address. |
RASTER_result KCallRasterBandSize | ( | RASTER_BANDSIZE * | pBandSize | ) |
A callback function which allows the skin to affect the band size calculation.
[in,out] | pBandSize | Structure providing details of the raster stride (byte offset between the start address of successive * raster lines), and some parameters for the skin to indicate to the RIP whether to limit band size and whether to allocate dynamic bands for asynchronous processing. |
RASTER_result KCallRasterDestination | ( | RASTER_DESTINATION * | pRasterDestination, |
int32 | separationIndex | ||
) |
A callback function which asks the skin to provide a memory address range into which to render.
pRasterDestination | Structure providing the band number the RIP is about to render, and pointers to the memory range that the RIP should use. |
separationIndex | The separation index. |
RASTER_result KCallRasterFinish | ( | RasterDescription * | rasterDescription, |
HqBool | ok | ||
) |
This function informs the raster callback implementation that raster data for a separation is complete.
[in] | rasterDescription | Description of the raster data. |
[in] | ok | A boolean indicating whether the rendering and delivery of the separation proceeded normally (TRUE) or whether an error occurred during rendering or delivery of data (FALSE). |
void KCallRasterJobEnd | ( | RasterDescription * | rasterDescription | ) |
This function informs the raster callback implementation that raster data for a job is complete.
[in] | rasterDescription | Description of the raster data. |
RASTER_result KCallRasterRequirements | ( | RASTER_REQUIREMENTS * | pRasterRequirements, |
RasterDescription * | rasterDescription | ||
) |
A callback function which gives the skin the details of the raster it is about to be handed, and gives the skin an opportunity to allocate memory to contain it.
pRasterRequirements | Structure providing details of the raster which the RIP will be providing, and some parameters for the skin to indicate to the RIP how it will proceed. |
rasterDescription | A pointer to a description of the raster data. This will be NULL when this function is being called as a result of a change to the page device which means a difference in the raster structure. It will be non-NULL when no further such changes are possible and rendering is beginning very soon, and will contain the finalised description of the raster data. |
RASTER_result KCallRasterStart | ( | RasterDescription * | rasterDescription | ) |
This function informs the raster callback implementation that raster data for is about to be written for a separation.
[in] | rasterDescription | Description of the raster data. |
RASTER_result KCallRasterWriteData | ( | RasterDescription * | rasterDescription, |
uint8 * | pBuffer | ||
) |
This function hands a band of raster data generated from the current job page to the raster callback implementation, if any, that the application has registered.
[in] | rasterDescription | Description of the raster data. |
[in] | pBuffer | The raster data itself. |
int32 KGetConfigAvailable | ( | void | ) |
This method is called from the RIP thread by the config device to determine how much config data, if any is available. This data would then be obtained by the RIP via KGetConfigData().
This method is called from the RIP thread by the config device when it is ready for the config data for next job. Config data is provided by the app via SwLeJobStart().
cbMax | The maximum amount of data which should be provided |
ppData | Where to copy the data to |
pcbData | The actual amount of data copied |
TRUE
if some data was provided, and FALSE
otherwise. void* KGetConfigJobContext | ( | void | ) |
Method called from the RIP thread by the config device to get the opaque job context pointer supplied by the user to SwLeJobStart().
The opaque job context pointer is attached to the SWTLT_SKIN_JOB timeline as its primary context, to give skin modules the ability to correlate jobs and manipulate job-specific data.
HqBool KGetConfigJobFailed | ( | sw_mon_type * | monuid, |
const char ** | detail | ||
) |
Method called from the RIP thread by the config device to get the error status of a job for ending a RIP timeline.
[out] | monuid | If an error caused the job to fail, its UID. |
[out] | detail | If an error caused the job to fail, a reason. |
The reason string must be copied by the caller if it wishes to preserve it.
TRUE | The most recent job submitted by SwLeJobStart() failed. |
FALSE | The most recent job submitted by SwLeJobStart() succeeded. |
This method is called from the RIP thread by the monitor device when it is ready for data from the current job. This data is provided by the app via SwLePs().
cbMax | The maximum amount of data which should be provided |
ppData | Where to copy the data to |
pcbData | The actual amount of data copied |
TRUE
if some data was provided, and FALSE
otherwise. HqBool KParamSetCallback | ( | PARAM | params[], |
size_t | n_params, | ||
const char * | paramname, | ||
int32 | paramtype, | ||
SwLeParamCallback * | pfnParamCallback | ||
) |
Utility function to set skin callbacks.
This function should be called through a trampoline function that passes in the parameter array and size. To remove a callback hook, call this function with a NULL
function pointer.
params | Array of PARAM structures in which to add a hook. |
n_params | The number of parameters in params. |
paramname | The parameter name to monitor. |
paramtype | The type of the parameter name to monitor. The callback functions use a generic pointer to pass the changed parameter value. Passing the expected type in with the hook function lets the skinkit check that the hook function will be passed the type it expects. |
pfnParamCallback | Pointer to a function though which the RIP informs the skin of parameter changes. |
FALSE | If the callback could not be set (either the name of the parameter was not found, or the type of the parameter is incorrect). |
TRUE | If the callback was set. |
void KSwLeStop | ( | void | ) |
Called as part of the RIP's exit procedure.
This function releases any remaining resources allocated during RIP initialization.
|
static |
Attach the job number to the skin timeline.
|
static |
Internal function to extend a dynamic buffer to at least the required size.
Called when the RIP exits.
n | The exit code |
text | Reason for exit |
This function is called by the RIP when it exits. It is responsible for calling the function registered by SwLeSetRipExitFunction().
void SkinReboot | ( | void | ) |
Called when RIP reboots.
This function is called by the RIP when it reboots. It is responsible for calling the function registered by SwLeSetRipRebootFunction().
|
static |
Report an SDK programming protocol failure. This will attempt to use SkinMonitorl() if the application state is suitable, and will also use HQFAIL() to throw an assertion. This should only be used for genuine programming protocol errors that should be corrected by altering the client code.
struct { ... } job_details |
Job details are set by SwLeSetJobName() and SwLeSetJobNumber(), and then consumed by the skin job timeline handler.
SkinDynamicBuffer jobname |
The name of the next job.
int32 jobno |
The number of the next job.