Harlequin RIP SDK
skinkit.c File Reference

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 "lsgrace.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_apiGetDataAPI (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_apidataapi = ((void*)0)
 The cached Data API pointer.
 

Detailed Description

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.

Macro Definition Documentation

◆ SwLeASSERT

#define SwLeASSERT (   condition_,
  message_ 
)
Value:
MACRO_START \
if ( !(condition_) ) { \
SwLeFAIL(message_) ; \
} \
MACRO_END

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.

Enumeration Type Documentation

◆ raster_state_t

Used to implement a simple state machine representing the lifecycle of the raster output.

Enumerator
RASTER_UNSTARTED 

Raster output has not been started.

RASTER_STARTED 

Raster start has been called.

RASTER_WRITE_ERROR 

Raster write data error.

RASTER_FINISHED 

Raster finish has been called, but not job end.

◆ rip_state_t

Used to implement a simple state machine representing the lifecycle of the RIP.

Enumerator
UNSTARTED 

No attempt has been made to boot the RIP.

INITIALISING 

The RIP thread is preparing to boot the RIP.

WAITING_FOR_JOB_START 

The RIP has been booted, and is now waiting for the application thread to submit a job.

PROCESSING_JOB_START 

The RIP is processing initial job configuration.

PROCESSING_PS 

The RIP is processing a PostScript job.

PROCESSING_JOB_END 

The RIP has finished processing the job, either successfully or with an error.

EXITING 

The RIP is in the process of exiting.

EXITED 

The RIP has exited.

Function Documentation

◆ API_VERSIONED()

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.

◆ KCallBlankPage()

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.

Parameters
[in,out]pBlankStructure 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.
rasterDescriptionDescription of the blank page. If called because all separations were omitted, there will be no colorants in the raster description.
Returns
RASTER_noErr (0) or a positive value less than MON_CLASS_ERROR if successful; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error. If there was no error, but the value of the RASTER_BLANK::handled field return value is FALSE, the function will be called again until it sets the field to TRUE or an error is reported.

◆ KCallParamCallback()

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.

Parameters
pfnParamCallbackThe callback function registered for the parameter.
paramThe parameter address.
Returns
One of the Param* enumeration values from swdevice.h.

◆ KCallRasterBandSize()

RASTER_result KCallRasterBandSize ( RASTER_BANDSIZE pBandSize)

A callback function which allows the skin to affect the band size calculation.

Parameters
[in,out]pBandSizeStructure 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.
Returns
RASTER_noErr (0) or a positive value less than MON_CLASS_ERROR if successful; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error. If there was no error, but the value of the RASTER_BANDSIZE::handled field return value is FALSE, the function will be called again until it sets the field to TRUE or an error is reported.

◆ KCallRasterDestination()

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.

Parameters
pRasterDestinationStructure providing the band number the RIP is about to render, and pointers to the memory range that the RIP should use.
separationIndexThe separation index.
Returns
RASTER_noErr (0) or a positive value less than MON_CLASS_ERROR if successful; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error. If there was no error, but the value of the RASTER_DESTINATION::handled field return value is FALSE, the function will be called again until it sets the field to TRUE or an error is reported.

◆ KCallRasterFinish()

RASTER_result KCallRasterFinish ( RasterDescription rasterDescription,
HqBool  ok 
)

This function informs the raster callback implementation that raster data for a separation is complete.

Parameters
[in]rasterDescriptionDescription of the raster data.
[in]okA 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).
Returns
RASTER_noErr if this function was called in sequence, and either no raster callback was registered or a registered raster callback succeeded. Otherwise, one of the RASTER_RESULT error codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type and UID.

◆ KCallRasterJobEnd()

void KCallRasterJobEnd ( RasterDescription rasterDescription)

This function informs the raster callback implementation that raster data for a job is complete.

Parameters
[in]rasterDescriptionDescription of the raster data.

◆ KCallRasterRequirements()

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.

Parameters
pRasterRequirementsStructure 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.
rasterDescriptionA 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.
Returns
RASTER_noErr (0) or a positive value less than MON_CLASS_ERROR if successful; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error. If there was no error, but the value of the RASTER_REQUIREMENTS::handled field return value is FALSE, the function will be called again until it sets the field to TRUE or an error is reported.

◆ KCallRasterStart()

RASTER_result KCallRasterStart ( RasterDescription rasterDescription)

This function informs the raster callback implementation that raster data for is about to be written for a separation.

Parameters
[in]rasterDescriptionDescription of the raster data.
Returns
RASTER_noErr if this function was called in sequence, and either no raster callback was registered or a registered raster callback succeeded. Otherwise, one of the RASTER_RESULT error codes, or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type and UID.

◆ KCallRasterWriteData()

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.

Parameters
[in]rasterDescriptionDescription of the raster data.
[in]pBufferThe raster data itself.
Returns
RASTER_noErr if this function was called in sequence, and either no raster callback was registered or a registered raster callback succeeded. Otherwise, one of the RASTER_RESULT error codes, or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type and UID.

◆ KGetConfigAvailable()

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

Returns
The number of bytes of config data available, or -1 if a protocol error occurs.

◆ KGetConfigData()

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

Parameters
cbMaxThe maximum amount of data which should be provided
ppDataWhere to copy the data to
pcbDataThe actual amount of data copied
Returns
TRUE if some data was provided, and FALSE otherwise.

◆ KGetConfigJobContext()

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.

Returns
The job context pointer set by the most recent SwLeJobStart() call.

◆ KGetConfigJobFailed()

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.

Parameters
[out]monuidIf an error caused the job to fail, its UID.
[out]detailIf an error caused the job to fail, a reason.

The reason string must be copied by the caller if it wishes to preserve it.

Return values
TRUEThe most recent job submitted by SwLeJobStart() failed.
FALSEThe most recent job submitted by SwLeJobStart() succeeded.

◆ KGetJobData()

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

Parameters
cbMaxThe maximum amount of data which should be provided
ppDataWhere to copy the data to
pcbDataThe actual amount of data copied
Returns
TRUE if some data was provided, and FALSE otherwise.

◆ KParamSetCallback()

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.

Parameters
paramsArray of PARAM structures in which to add a hook.
n_paramsThe number of parameters in params.
paramnameThe parameter name to monitor.
paramtypeThe 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.
pfnParamCallbackPointer to a function though which the RIP informs the skin of parameter changes.
Return values
FALSEIf the callback could not be set (either the name of the parameter was not found, or the type of the parameter is incorrect).
TRUEIf the callback was set.

◆ KSwLeStop()

void KSwLeStop ( void  )

Called as part of the RIP's exit procedure.

This function releases any remaining resources allocated during RIP initialization.

◆ skin_job_number()

static sw_event_result skin_job_number ( void *  context,
sw_event event 
)
static

Attach the job number to the skin timeline.

◆ SkinDynamicBufferExtend()

static HqBool SkinDynamicBufferExtend ( SkinDynamicBuffer buffer,
size_t  needs 
)
static

Internal function to extend a dynamic buffer to at least the required size.

◆ SkinExit()

void SkinExit ( int32  n,
uint8 text 
)

Called when the RIP exits.

Parameters
nThe exit code
textReason for exit

This function is called by the RIP when it exits. It is responsible for calling the function registered by SwLeSetRipExitFunction().

◆ SkinReboot()

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

◆ SwLeFAIL()

static void SwLeFAIL ( const char *  message)
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.

Variable Documentation

◆ 

struct { ... } job_details

Job details are set by SwLeSetJobName() and SwLeSetJobNumber(), and then consumed by the skin job timeline handler.

◆ jobname

The name of the next job.

◆ jobno

int32 jobno

The number of the next job.