As you integrate the Harlequin RIP into your own application, you may need to develop and add your own raster backends, color management modules, halftone modules, configuration devices, or other devices, or call Harlequin RIP SDK functions from your application code. To do this, you will need to add the Harlequin header file locations to your build system, include the appropriate header files in your C or C++ code, and link with the Harlequin RIP SDK library.

Header files

There are two main directories containing header files for the Harlequin RIP SDK, and additional header file directories for examples, extra libraries, and the Scalable RIP interface.

If you are integrating the Harlequin RIP into your application using the Scalable RIP interface (see Integrating by linking to the RIP Farm API), then there is just one header file directory that you need to add to your build system:

lib/ripfarm/interface: This directory contains header files for the Scalable RIP library (see Linking libraries for Scalable RIP). The Scalable RIP interface is self-contained, it does not need definitions from the core library or SDK library.

If you are modifying the application layer, integrating the Harlequin RIP into your application as a library (see Integrating by linking to the Harlequin RIP SDK), then these are the header file directories that you need to add to your build system:

lib/skinkit/export

This directory contains header files for the SDK library component (see SDK library and Linking the SDK library). The SDK library provides a number of devices and functions to integrate the core library with the operating system.

There are a large number of header files in this directory, specific to the functions and definitions they provide. It can be difficult to determine which header files are required for the functions that you may need to call. To make this easier, there is a single combined header file called hhrsdk.h which includes all of the other functional header files in this directory. Global Graphics recommend that you include hhrsdk.h in your application code if you are directly using SDK library functions or definitions, instead of including each header file separately.

The hhrsdk.h header file also includes the corresponding hhrcore.h header file for the core library. If you include hhrsdk.h, you do not need to include hhrcore.h or most other Harlequin SDK header files. See hhrsdk.h for the full list of files included.

lib/lib/interface

This directory contains header files for the core library component (see Core library and Linking corelib). The core library contains the core of the Harlequin RIP, but also a number of utility functions that you may find useful in your code.

The Harlequin RIP SDK shares a set of standard type definitions used by the core library, the SDK library and the application layers. These type definitions, and functions that manipulate them, are defined appropriately for each platform in this directory.

There are a large number of header files in this directory, specific to the functions and definitions they provide. It can be difficult to determine which header files are required for the functions that you may need to call. To make this easier, there is a single combined header file called hhrcore.h which includes nearly all of the other header files in this directory. Global Graphics recommend that you include hhrcore.h in your code if you are directly using core library features, instead of including each header file separately.

A few header files are not included in hhrcore.h, and you may need to include these separately if you use functionality they provide. The header files not included in hhrcore.h are:

Some files containing static inlined functions for error translation or hash function construction. These are required to be included in each source file that uses them.
On Windows, the hqwindows.h header that safely includes the subset of the Windows API that the Harlequin RIP SDK uses.
Interface headers for libraries that are built into the core library, such as Zlib, libpng, libjpeg, and expat. Some of these interface headers have type definitions that conflict with each other or application code. These libraries are exposed through RDR (see Priorities, overriding, hiding, and filtering), so the function definitions may not be generally useful anyway.

See hhrcore.h for the full list of files included.

lib/pthreads/export

On Windows, this include directory contains the header files for the Pthreads library. On Windows, the pthreads library must be loaded explicitly (see Linking pthreads). On Linux and MacOS, this directory will not be provided in the distribution, because pthreads is built-in to the operating system.

The Pthreads library is used to provide a uniform interface to thread creation, mutexes, condition variables, and thread-local storage. The Harlequin RIP SDK calls a subset of pthreads through a threading API (see Threads interface). However, this header directory is still needed on the include path when compiling functions that use the threading API.

If you are modifying or replacing the application layer (see Application layer), and are using the color management module examples, halftone module examples, or the TIFF raster output backend, there are some additional header file directories you may need to add to your build system. For the color management and halftone module examples, you may consider copying the code into your application directories and modifying it there instead of adding these directories:

lib/cmmeg/export, lib/cmmeg/pc/export: These header file directories provide the declarations of the example color management modules supplied by Global Graphics, built into the "clrip" application layer. If you do not need these in your application, you will not need to add this include directory to your build system. If you are modifying "clrip" rather than replacing it completely, you can define the symbol NO_CMMEG to exclude these examples from your build.

lib/htmeg/export: This header file directory provides the declarations of the example halftone modules supplied by Global Graphics, built into the "clrip" application layer. If you do not need these in your application, you will not need to add this include directory to your build system. If you are modifying "clrip" rather than replacing it completely, you can define the symbol NO_HTMEG to exclude these examples from your build.

lib/libtiff/export: This header file directory contains the include files for the libtiff library, used by the TIFF raster output backends. If you do not need TIFF output in your application, you will not need to add this directory to your build system. If you are modifying "clrip" raster than replacing it completely, you will need to edit skintest.c to remove the TIFF raster backend preprocessor include directives and registration function calls.

Harlequin standard types

The Harlequin RIP defines a set of standard sized integer and boolean types and generic handle and result types (see Standard integer and Bool types). These will be made available to your code by including the hhrsdk.h or hhrcore.h header files. As well as the ubiquitous sized-integer type definitions, these definitions include HqBool, HqnFileDescriptor, HqnIdent, and HqnResult.

The HqnResult type is an important type to understand. It is used as a base type for success and error return values by many of the interfaces in the Harlequin RIP SDK. Many API-specific result types are based on HqnResult, but add a set of API-specific result values. Interfaces using API-specific result values also provide an error translation function that can be used to convert the API-specific values to the base HqnResult type, which can then be used to signal errors to the RIP or application layer.

The core library interface also provides:

64-bit compatibility types for non-performance critical use, such as file positions, in hq32x2.h.
A parameterised bitvector type, with operations to index, set, clear, and iterate bits individually or in groups, in hqbitvector.h. The bitvector type uses macros for parameterisation to allow bitvectors of known sizes to be stack or statically allocated.
A binary tree type in Harlequin standard Red-Black binary trees. This tree structure is used widely in the Harlequin core library and SDK. There is a specialisation of it for generating Huffman codes in rbthuff.h.
An open addressed hash map in Harlequin standard Robin Hood hash map.
Atomic operations and spinlocks on an integral type and pointers in Harlequin standard atomic operations..
Harlequin SIMD (Single Instruction Multiple Data) operations provides a consistent set of type definitions and macro or function interfaces for SIMD vector instructions.

Calling conventions

Four calling-convention macro labels are used in the Harlequin interfaces:

HQNCALL: Some function calls provided by SDK library and non-core components are annotated with this label.

RIPCALL: This is used on calls into the core library.

RIPFASTCALL: This is used on some more recently introduced calls into the core library, especially those with small numbers of parameters.

MPS_CALL: This is used for calls into the MPS memory library.

These calling convention macros use the same definitions, but are separate textually because of library reuse and modularity boundaries.

The calling-convention labels are mostly obsolete, and are not applied to new interfaces. They were relevant on 32-bit Windows to indicate the correct method for marshalling parameters in registers. The calling convention labels should be used for consistency when defining callback functions that are declared with them, but otherwise ignored.

Harlequin assert and trace handlers

The Harlequin RIP has a set of custom assert and trace macros, used by Global Graphics to ensure code quality by testing for invalid states. These are described in Harlequin standard "assert" and "trace" macros. The assertion and traces macros are ultimately handled through a pair of handler functions, set by the application using the SDK library SwLeSetHqAssertHandlers() function. The assertion macros and their interface are in hqassert.h, the handler function interface in hqcstass.h.

Neither the assert nor trace handler functions will be called unless the RIP is built with assertions enabled. This is not normally the case for customer distributions, but Global Graphics may provide assertion enabled builds on occasion to help diagnose difficult problems. Assertion enabled builds should not be used in production. It is possible to rebuild the skin (Harlequin SDK library and application layers) with assertions enabled by defining ASSERT in the Makefile (to set the C compiler symbol ASSERT_BUILD), even if the core library was not built with assertions enabled. In this case, only assertions in the skin layers will be evaluated.

Harlequin core library utility functions

The Harlequin core library provides some utility functions that the SDK and application layers use. You may find these useful in your code.

The Harlequin standard bit and byte operations are bit-wise and byte-wise operations that provide a consistent interface to bit and byte extraction, packing, counting, and swapping or rotating, with platform-specific optimisations.
Harlequin standard memory set, copy, move, and compare functions are memory manipulation interfaces. These are cross-platform interfaces to memory comparison, copying, setting, and moving functions. The implementations may be through macros, intrinsics, or functions, depending on what Global Graphics have found to work best for each individual platform.
Some string-manipulation functions are provided in hqstr.h for copying strings, with and without truncation, and also variants of some of the standard C library functions with type conversion casts and assertion checks to convert between the Harlequin RIP string type and standard C strings. The Harlequin RIP and SDK has used unsigned char arrays and pointers for representing strings since before the C language was standardized. Using these variants isolates type casting to these few functions and macros, where it can be checked.
Harlequin standard hash functions are inlined implementations of some hash functions that are used within the Harlequin RIP and SDK. These header files are not included in the combined hhrcore.h header file, because they define static inline functions:
- The file pjwhash.h defines an implementation of Peter Weinberger's non-cryptographic hash. This is a non-incremental hash implementation, operating on a number of bytes, yielding a 32-bit hash result.
- The file hsiehhash32.h defines an implementation of Paul Hsieh's SuperFastHash. This is an incremental hash implementation, operating on a number of 32-bit integer values, yielding a 32-bit hash result.
- The file murmurhash3.h defines an implementation of Austin Appleby's MurmurHash3 algorithm. There are both non-incremental and incremental implementations provided, yielding either a 32-bit or 128-bit hash result. The 128-bit hash function is useful where a large and well-dispersed result is required.
String formatting functions provide string and time formatting functions similar to the sprintf() family, but supporting the types and conventions used in the Harlequin RIP.
Core raster delivery control and interface defines the interface between the Harlequin core library and the SDK library. There are functions provided to acquire, release, copy, compare and combine raster layouts that may be useful in raster backend and eHVD processing (see eHVD API). The raster interface types passed from the core library to the SDK library are presented to the application layer through a different set of functions (see Raster backend API).
Miscellaneous functions include:
- SwGetRIPBuildVersion() to return the RIP build version string.
- SwOften() to poll for interrupts.
- SwThreadIndex() to return the zero-based index of a RIP thread executing a callback function.
- HqCatchExceptions() sets up a last-resort exception handler to output crash dump information.
The Scalable RIP controller API and Farm RIP API define functions that are required if integrating the SDK in an application layer that will be used as a Scalable RIP.

Low level core library interfaces

The interfaces to the common core are documented in Low-level Harlequin Core RIP interfaces. The interfaces to the library integration layer are documented in Core RIP Entry Point Interfaces. You should not have need to call these interfaces directly.

Harlequin core library APIs

The Harlequin core library provides some callback APIs, packaged as structures of function pointers that the SDK or application layer can call. These are described in separate sections:

Harlequin SDK library utility functions

The Harlequin SDK library also provides utility functions that the application layer may use:

File and path manipulation functions describes the functions provided to set and retrieve the RIP's data directory paths, functions for decomposing and composing filenames and for converting between platform-specific filenames and "PostScript" filenames.
DEVICETYPE implementations provided by the SDK describes the DEVICE interface implementations provided by the Harlequin SDK library and some support functions to make implementing new devices easier. The SDK supplies the skindevices_last_error() and skindevices_set_last_error() functions for thread-safe support of the DEVICE interface last error protocol.
SDK support for framebuffer raster output describes support functions for using framebuffers in raster output backends. Process-memory framebuffers and shared memory framebuffers for raster output and eHVD raster elements are supported.
SDK support for eHVD output describes support functions for adding eHVD output to raster backends.
Hot folder support describes the functions the SDK library provides to monitor hot folders for input jobs.
Harlequin SDK input queue describes the functions the SDK library provides to consume jobs submitted through the Input queue and source API.
In-memory virtual file system describes the functions provided to support in-memory file systems. These functions are used to implement the SDK library's RAM filing system device (RAM_Device_Type).
SDK memory handling functions describes the functions provided to support memory allocation and de-allocation from the SDK's memory pool, the RIP's memory pools, and system memory, and inquiry functions the SDK provides to determine current and peak memory usage.
Harlequin RIP SDK describes the SDK and RIP control functions, along with some utility functions used to construct configurations, record system errors, and API discovery.
Functions for outputting messages from the skin describes how fixed and formatted messages can be output by the SDK and application layers, and the callbacks and channels used to output them.
Miscellaneous functions include:
- aa_get_instance() to return the singleton instance of a halftone module that implements anti-aliasing. If you register this instance, then the RIP will support the /ResamplingFactor pagedevice key for anti-aliasing during raster output.
- PKMilliSleep() to wait for a specified number of milliseconds.
- progevts_suppress_types() suppresses progress reporting for some types of information.
- PKSetCtrlCHandler() registers a callback to handle interrupts from the operating system.
- SkinTimeline() returns the top-level skin timeline reference. This is useful for constructing timeline hierarchies, or for monitoring SDK shutdown.
- SwLePgbSetCallback() sets a callback function triggered when a page buffer parameter is modified. This function is nearly obsolete, but is currently still required by the "clrip" application layer to change the raster backend selected when the PageBufferType name is changed in the page device configuration. Global Graphics does not recommend using this function for anything except this purpose.

Harlequin SDK library APIs

The Harlequin SDK library provides some callback APIs, packaged as structures of function pointers that the core library, SDK or application layer can call. These are described in separate sections: