There are three methods to use the Harlequin RIP in your application. The more complex integration methods give you more control over the operation of the RIP, and tend to give better overall performance, but require more programming.

In all of these integration methods, if you need data in a format not supported by the Harlequin RIP SDK by default, you may need to develop and add your own raster backend. You may also need to develop and add your own color management modules, halftone modules, configuration device or other devices (see DEVICE interface) to pass data to and from the RIP.

Integrating the Harlequin RIP as a process

The simplest method of integrating the Harlequin RIP into your application is to simply call the "clrip" application as a sub-process. The Harlequin RIP SDK provides no specific support for this integration method. This method would typically be performed by constructing a command line for "clrip" and calling CreateProcess() on Windows, or fork() and one of the exec() family of calls on Linux or MacOS.

When constructing a command line to call "clrip", your application should be careful about quoting arguments, and about handling file name encodings correctly. The Windows version of "clrip" is built as a Unicode console application, and so can be started with CreateProcessW() if non-ASCII characters are required. On Linux and MacOS, "clrip" uses UTF-8 encoding for the command-line parameters.

This documentation does not explain how to use all of the "clrip" command line arguments. Run clrip -h to see the built-in documentation on command-line arguments, or clrip -l to list the built-in raster backends, output targets, and configurations installed.

If your application calls "clrip" as a sub-process, there are two built-in methods to pass jobs to it. Jobs can be passed on the command line, or through hot folders. Both methods can be combined: the RIP puts all jobs identified on the command line onto its input queue first, and then will process jobs from any hot folders until told to quit (see Inputting data).

Command-line jobs

Jobs may be passed to the "clrip" application in one of three forms:

An absolute filename (starting with / on Unix or MacOS, C:\ or another drive letter on Windows, or \\host\share\ for a UNC path on Windows). UNC paths will be mounted as needed by the RIP. On Windows, a trailing wild-card pattern is also supported, allowing multiple files in a directory to be submitted at once.
A relative filename (not an absolute filename, and not starting with %). Relative filenames are resolved in relation to the working directory. This will normally be the directory in which the "clrip" process was started, but it can be changed using the -S command-line option.
A PostScript device-relative filename. This is a normalized form of filename used internally by the RIP. These filenames start with a device name between % characters, followed by the path to the file, using forward slash / as a separator. Unqualified PostScript filenames without the device name may be used internally by the RIP, but only fully-qualified names are recognized on the command line.

Similar rules apply to RIP configurations applied via the command line. Configurations for the Harlequin RIP historically used PostScript as a scripting language, with operators extending the language to manage the page, color, and output configurations. The Harlequin RIP also contains a JSON configuration device that converts declarative JSON configurations to PostScript configurations automatically. JSON configurations are recommended for customers not familiar with PostScript programming.

RIP configurations may be supplied on the command line as:

An absolute filename.
A PostScript relative filename. These are located relative to the %psconfig% device (see PS configuration). This is normally a file system device referring to the SW/TestConfig sub-directory of the RIP's data directory, but may be overridden or remounted on a different device (see Configuring the Harlequin RIP for more information).
A PostScript device-relative filename.

In all of these cases, if the configuration name ends with .json or .JSON, it will be treated as a declarative JSON configuration, and the JSON configuration device will automatically be used to translate it to PostScript (see JSON configuration).

Finally, configuration overrides called Page Features may also be supplied on the command line. These are small sections of PostScript configuration code that may be used to modify the RIP configuration. Multiple page features may be used at once to modify different aspects of the RIP's configuration.

Page Features may be supplied on the command line as:

An absolute filename.
A PostScript relative filename. These are located relative to the SW/Page Features sub-directory of the RIP's data directory.
A PostScript device-relative filename.

The behavior determining how to handle absolute filenames, relative filenames, or device-relative names for jobs, configurations, and page features are implemented in the source code supplied by Global Graphics, either in the Harlequin RIP SDK library or the application layer.

Hot folders and other input methods

The "clrip" application supports hot folders for input. Hot folders will be monitored for job files copied into them, and will submit the job files to the RIP for processing. When the RIP has completed the job, the files will be deleted from the hot folder.

Multiple hot folders may be started. Each hot folder is associated with a configuration and one or more page features. The configuration and/or page features may differ for each hot folder, providing an easy way to submit jobs if there are a limited number of configurations used by the application.

If one or more hot folders are started, the clrip process will continue to run until it is explicitly stopped. This may be done either by interrupting it, or submitting a special stop job. See Stopping the Harlequin RIP and SDK for more information.

The "clrip" hot folder support is implemented in the SDK Library, and so is available for other RIP integration methods to use. The hot folder support uses the inputs API (see Input queue and source API) to submit jobs. This API can be used to construct other persistent input sources for jobs, as your application requires.

Integrating by linking to the RIP Farm API

If Scalable RIP support is required for high-volume PDF output, the preferred method to integrate the RIP is to use the Scalable RIP API to manage the RIP processes, and link your application with the "libripfarm" library. This API and library provide support for running a farm of multiple RIPs, on multiple host machines, and managing input to and output from the farm. The API supports starting and stopping the RIP farm (including spawning and terminating the Scalable RIP processes), submitting and managing jobs, managing raster output, and requesting and monitoring farm, job, and raster output status.

The RIP Farm API is normally configured through the ripfarm_global.json JSON configuration file, found in the SW/RIPFarmConfig sub-directory of the RIP's data directory. An alternate JSON configuration may be supplied as a file, a JSON string, or a JSON object when the interface is initialized, or from a central blade controller if running multiple machines.

When using the RIP Farm API, the Scalable RIP sub-processes may either be explicitly started by your application, or automatically spawned by the rf_send_farm_start() call to the RIP Farm API. Global Graphics recommends automatically spawning the processes using the API. This is achieved by changing the JSON configuration SpawnBeforeFarmStart object. This object contains a path to an executable, a working directory name, and an array of command-line arguments to pass to the executable. These key-value pairs may be configured as suggested in the distributed ripfarm_global.json file to point at the "clrip" application, or they may be configured to point at an intermediate script or process of your own that starts "clrip".

If you need to replace "clrip" as the RIP process spawned by the Scalable RIP API, then the replacement RIP application must support certain arguments and capabilities. See Integrating for use as a Scalable RIP for more information.

You may submit jobs to the Scalable RIP using the RIP Farm API's rf_send_job_start() call, or by using hot folders or any other persistent input source built into "clrip" or its replacement RIP application.

The RIP Farm API is relatively small, and operates at quite a high level, but is capable of managing most application integration functions. See RIP Farm: API and Library to split jobs across multiple RIPs for more information about using this interface.

If a data output format is required that is not supported by the RIP, then you may need to develop and add your own raster backend to "clrip". If you use the Scalable RIP raster output management, your raster backend is required to implement the functionality described in Enabling the Scalable RIP raster manager.

Integrating by linking to the Harlequin RIP SDK

Linking the Harlequin RIP into your own application will give you the greatest control over operation of the RIP. There are many reasons that this may be your preferred integration method, including:

Security. Your license may require that the Harlequin RIP SDK is statically linking to your application, if your application is providing security for the Harlequin RIP. (This is referred to as the "LE" security model.)
Data sharing. Linking the Harlequin RIP into your application allows you to share data buffers for raster output, input, or configuration with your application directly.
Control. Linking the Harlequin RIP into your application allows you to make direct function calls to the SDK APIs, without having to communicate parameters and results to or from a different application.
Deployment. A single process for your application may be simplify deployment and management of your application.

There should only be one instance of the Harlequin RIP running in your process at a time. Global Graphics does not support support running more than one instance of the Harlequin RIP in multiple threads of the same process. If you need to run multiple RIPs to perform different tasks simultaneously (for example, thumbnailing or preflighting whilst also rendering jobs), and your license covers this case, you may use multiple RIPs hosted in different processes. If you wish to use multiple RIPs to speed up rendering of a single job at a time, please talk to Global Graphics about using the Scalable RIP.

Integrating as a single RIP

The recommended method of integrating the Harlequin RIP into your application is to add the RIP's include directories to your application's include paths (see Header files), and link to the SDK static library (see Linking the SDK library). The simplest way to do this is to add the include directories, the pre-built static SDK library, and the other required libraries to your source control system, and add them into your build system. If you wish to include the Harlequin RIP SDK source code as part of your application's build process, it may be simplest to call the Makefiles in the distribution as sub-processes in your build system, or add the Harlequin RIP SDK library project files to your solution if using Visual Studio on Windows. This method of integrating the Harlequin RIP into your application does not use the application layer, so the skintest/ and skinmin/ directories in the distribution do not need to be added to your build system (however, they may still provide useful examples of how to integrate your own application code with the Harlequin RIP SDK).

You may wish to create a proxy interface or class, so that you do not need to expose the RIP's include files in all of your application code. The include files and library may be used with either C or C++ code.

The Harlequin RIP is designed so it can run as a persistent service within its host process. On start, the Harlequin SDK will reserve a memory allowance for its sub-allocation arena, and the core RIP will start a number of threads to use when running the RIP. The RIP will run until shut down. Your application may either submit jobs to the RIP, and then continue to perform other useful work while these jobs are processed, or it may submit jobs and synchronously wait for those jobs to be completed.

The Harlequin RIP SDK and core may be started and shut down multiple times within the lifetime of your application. Some critical parameters, such as the size of the memory arena, may only be changed when starting the SDK. If your application has periods of time when it does not require the RIP running, but requires a lot of memory to perform a task, you may wish to shut down the RIP while the task is running.

The Harlequin RIP can be started, stopped, and jobs processed in your application by calling the SwLeDo() function.

Details of which libraries to link and what functions should be called to integrate the RIP into your application are explained in Linking the Harlequin RIP SDK components.

Integrating for use as a Scalable RIP

In rare cases, you may want to run the Scalable RIP for performance, but can not use the "clrip" application, and can not extend the "clrip" application layer to contain functionality you need. In these cases, you may need to integrate the Harlequin RIP into your own application, but have it able to perform as a Scalable RIP.

Integrating the Harlequin RIP SDK for use as a Scalable RIP is similar to integrating it for use as a single RIP (see Integrating as a single RIP), with the addition that:

The executable must be capable of self-spawning. The Scalable RIP controller loops use operating system calls to start new instances of the same executable for use as farm RIPs, with modified command lines to indicate the role they will take.
Some command-line arguments to the application must be processed as specified below.
There are some additional libraries that must be linked to the application.
The application must implement the Input queue and source API (this will be the case if using the Harlequin SDK library).
The function to call to have the application behave as a Scalable RIP component is different from the non-Scalable RIP.

The Scalable RIP is implemented as single executable which can perform several different roles. These different roles are selected using command-line options. The Scalable RIP starts with a single process, which will spawn multiple processes from the same executable as necessary to perform the different roles, modifying the command line used to spawn the executable to indicate the roles and options required. This self-spawning method means that certain command-line options must be supported by the application hosting a Scalable RIP, and these command-line options must have the expected behavior in the application.

There are three main roles that the Scalable RIP application is expected to perform:

Controller RIP. The controller RIP component acts as the coordination point for the Scalable RIP, accepting input jobs, extracting metadata, and scheduling jobs on the Farm RIPs. This component also contains the Central Blade Controller (CBC), which manages a set of Farm RIPs on the same machine. The controller RIP component is run by initializing the SDK, calling the sw_sr_server_loop() function, then shutting down the SDK after that function exits. In the "clrip" application, this is configured by using the -nrip command-line option to indicate the number of RIPs to run, but without the -cbc command-line option. See Scalable RIP controller API.
Farm RIP. Farm RIP processes perform the interpretation and rendering of pages or tiles from jobs. A job sent to a Scalable RIP may be split into multiple chunks, each of which are sent to a different Farm RIP for processing. A farm RIP component is run by initializing the SDK, calling the sw_fr_server_loop() function, then shutting down the SDK after that function exits. In the "clrip" application, this is configured by using the -frid command-line option. See Farm RIP API.
Satellite Blade Controller. A satellite blade controller manages a set of Farm RIPs, and may be used to expand the number of RIPs in a Scalable RIP, usually on a different physical machine than the Controller RIP. Satellite blade controllers may also be used to dynamically add and remove Farm RIPs from a Scalable RIP farm. A satellite blade controller component is run by initializing the SDK, calling the sw_bc_server_loop() function, then shutting down the SDK after that function exits. In the "clrip" application, this is configured by using the -nrip command-line option to indicate the number of RIPs to run, and also the -cbc command-line option to indicate the address of the central blade controller. See Scalable RIP controller API.

The command-line options that a Scalable RIP application is required to implement are:

-X: This option is passed to Farm RIPs if the Scalable RIP requested to save output in a log file. See SW_SR_PARAMS::logfile_in_sw. If your application only sets this field to FALSE, then you need not implement this command-line option.

-m memory

This option is passed to Farm RIPs to indicate how much memory they may use. The memory parameter is an integer, indicating the size to use in MB. This parameter should be used by the application to initialize the memory size when starting the SDK. See SW_SR_PARAMS::mem_working_size, SwLeDoParams::RIP_workingSizeInBytes and SW_FR_PARAMS::arena.

You must implement this command-line option.

-p nthreads: Set the number of threads to use in each Farm RIP. Your license may restrict the number of threads available per RIP. This parameter should be used to initialize the number of threads available for a Farm RIP. See SW_SR_PARAMS::threads_per_rip and SwLeSetRipRendererThreads(). If your application only sets SW_SR_PARAMS::threads_per_rip to zero, then you need not implement this command-line option.

-n progesstypes: An integer, indicating which progress messages Farm RIPs should suppress. See SW_SR_PARAMS::suppressProgressTypes and progevts_suppress_types(). If your application only sets this field to zero, then you need not implement this command-line option.

-D drivetypes: This option is only used on Windows, to control which drive types the Farm RIP may mount automatically (this is sometimes necessary to prevent network mapped drive letters and CD-ROM drives from taking excessive time at startup). The drivetypes value is an integer, indicating which drive types to mount automatically. See SW_SR_PARAMS::driveTypes. If your application only sets this field to zero, then you need not implement this command-line option.

-f format: This option is passed to Farm RIPs to override the filename when "clrip" is outputting to files. The format pattern is used to generate a filename. See SW_SR_PARAMS::filename_format. If your application only sets this field to NULL, then you need not implement this command-line option.

-C: This option is always passed to Farm RIPs. It is used by "clrip" to indicate that the RIP should continue processing jobs even if there is an error in a previous job. This behavior is advised for all RIPs run as persistent processes, including the Scalable RIP components. See SwLeDoParams::fContinueAfterError.

: You must implement this command-line option.

-cbc address:port

This option is passed to Farm RIPs to indicate the address and base port of the central blade controller. The address is either a machine name or an IP address, port is an integer port number. The "clrip" application also uses this option to configure satellite blade controllers to communicate with the central blade controller.

The parameter passed to the Farm RIP should be used to set the SW_FR_PARAMS::central_bc_tcpip field before calling sw_fr_server_loop(). See SW_SR_PARAMS::central_bc_tcpip and SW_FR_PARAMS::central_bc_tcpip.

You must implement this command-line option.

-frid id

This option is passed to Farm RIPs to indicate the Farm RIP's identity. The id parameter is an integer, it should be used to set the SW_FR_PARAMS::rip_id field before calling sw_fr_server_loop(). See SW_FR_PARAMS::rip_id.

You must implement this command-line option.

-W directory

This option is passed to Farm RIPs to set the writable SW data directory. Farm RIPs use the Union device (device type 40) to direct any temporary files or log files they may write to a unique location for each RIP. The directory parameter is a directory name which the Farm RIP should pass to PKSetSWWriteDir() before calling sw_fr_server_loop().

You must implement this command-line option.

When acting as a Scalable RIP, the Harlequin RIP needs to be linked with some additional libraries. Details of the additional libraries to link to are explained in Linking libraries for Scalable RIP.