Upgrading from Harlequin Core SDK 13 to 14

Before upgrading your integration from Harlequin Core v13 to a v14 base please familiarise yourself with the Harlequin Core v14 Release Notes 

These notes will help you transition from Harlequin 13 to Harlequin 14. These are based on experience with OEMs during our Beta cycle..

A lot has changed in the Harlequin RIP SDK between Hqn 13 and Hqn 14. We apologise for any difficulty this causes in integrating Hqn 14, but believe that the changes are a necessary step to simplifying the integration for new customers and upgrades for existing customers in the future. Please read the Doxygen-generated RIP documentation starting at doc/hqnripsdk-html/index.html in the distribution, even if you have looked at it before. The documentation has been improved with the intention it can be read as an integration guide. It replaces the now withdrawn API manual and SDK manual. This documentation is also available on-line at https://api.globalgraphics.com/harlequin/, but the version in your distribution will be most relevant. Notes for OEMs performing deep integrations (where you are not just calling the clrip application directly):  

1. The SDK is now built as a static library, called hhrsdklib We strongly recommend that you link your executable with hhrsdklib, rather than incorporate the SDK files into your own build system. hhrsdklib is supplied as a pre-built library in the distribution, you may also build it on your hardware using the Makefiles and/or Visual Studio solution provided. 
2. The SDK is now nearly all accessible through a single include file, called "hhrsdk.h" We recommend that you include just this file from the SDK in your own source files. 
3. The number of header file directories has been reduced in Hqn 14. Your build system only needs to include lib/interface, lib/skinkit/export, and lib/pthreads/export (if building on Windows) If you are using the libripfarm API, you only need include files in lib/ripfarm/interface. 
4. If you do wish to build the SDK library from source code in your integration, we recommend calling our Makefiles to build it, or adding the separate Visual Studio projects for the interface and hhrsdklib to your solution, rather than re-creating the entire SDK library build system yourself. 
5. The calls to initialize the SDK library, initialize the RIP, process jobs, shutdown the RIP and shutdown the SDK are now managed through a single function, SwLeDo() This takes a structure of parameters, and a target state You initialize the structure before the first call to SwLeDo(), and then pass through the same structure pointer to all subsequent calls This function manages all of the necessary state transitions to move from the current state to the target state The legacy calls to SwLeSDKStart(), etc., still work, but we recommend converting to SwLeDo() for simplicity and future proofing. 
6. The new SwLeDo() interface allows you to drive the RIP as a state machine using a single thread, feeding one or more jobs to it on each call to SwLeDo() to process jobs Alternatively, you can let the SDK block and wait for input, returning when the RIP is shut down. 
7. The raster backend interface is now collected into a single structure containing the method calls If you are using a single raster backend, you can call SwLeSetRasterAPI() to set this backend If you are using multiple raster backends, you should use the same method as the clrip source code in skintest/src/skintest.c, registering a PGB parameter callback for /PageBufferType, and selecting a raster backend API structure discovered using RDR in the callback. 
8. The raster backend interface builds on the clrip application's interface, providing raster start, raster write, raster finish, and job end callbacks The raster write callback may be called with one line of data at a time (if the width of the raster does not match the raster padding required by the RIP), unless you set the RasterDescription's line_data_may_be_padded field to TRUE. 
9. The PGB device will be removed from the SDK in a future version of the Harlequin RIP If you are providing custom parameters for raster backends to use, you should use the RasterParams interface. This is documented in the Doxygen integration guide. 
10. The RasterDescription structure has been modified extensively. This is the largest incompatible change in the Hqn 14 SDK A lot of obsolete fields have been removed Most of the information about the raster layout is now accessed through the RASTER_LAYOUT structure, there are a couple of copies of high-level information from RASTER_LAYOUT in the RasterDescription for convenience A RASTER_LAYOUT structure pointer is provided in the RasterDescription structure, it's also provided to the raster backend's raster requirements calls, allowing raster layout information to be discovered much earlier in the interpretation and rendering process than was previously possible The RASTER_LAYOUT structure and sub-structures replace the use of the pColorants pointer in RasterDescription, and also contain pre-computed values of a number of memory sizes and dimensions that we have found inconsistent and incorrect re-computations in SDK and client code. It represents the entire raster layout, including all separations and omitted colorants, so you can understand how the raster data for a render pass relates to the configuration. 
11. The RasterColorant structure does not exist any more This structure is replaced by the RASTER_CHANNEL and RASTER_COLORANT sub-structures of RASTER_LAYOUT These sub-structures separate out the two different functions that were being conflated in RasterColorant before RASTER_CHANNEL represents one of possibly many data streams within a raster RASTER_COLORANT indicates which colorant(s), if any, are mapped onto that data stream. 
12. The function RasterSheetFromDescription() provides access to the RASTER_LAYOUT sub-structure for the current separation (sheet). This is used extensively in the SDK and clrip application The RASTER_LAYOUT structure now provides information about all separations in a configuration, this function narrows the layout down to just the current separation, which is similar to the information provided in RasterDescription previously The current separation number can be retrieved by calling RasterSheetFromDescription() and then looking at the (zero-based) index_omitted or index_non_omitted field of the RASTER_SHEET structure, as desired See the Doxygen integration guide for details. 
13. The RASTER_LAYOUT can be iterated using raster_layout_iterate(). Iteration over the channels or colorants of a sheet is a replacement for iterating through the RasterDescription's pColorants list There are examples of using raster_layout_iterate() throughout the SDK and clrip source code provided In general, you will want to initialize a raster_layout_iterator structure with the raster layout field from RasterDescription, and the current sheet extracted using RasterSheetFromDescription(), and then call raster_layout_iterate() with flags indicating whether you are interested in channels, colorants, or planes, and usually a flag indicating that you are only interested in channels, colorants, or planes in the same sheet See the Doxygen integration guide for details. 
14. The RASTER_LAYOUT sub-structures contain both an index_omitted and index_non_omitted field These indices allow you to determine whether a particular sub-structure was omitted by the renderer; what the order of this sub-structure is; where the sub-structure appears in the order when colorants are not omitted; and allow locating this sub-structure in its parent structure. 
15. The RASTER_LAYOUT sub-structures include pre-computed counts and sizes that we found inconsistently and incorrectly handled by SDK and client code These include the number of bands per frame; the total amount of data rendered for each separation, frame, and band (both with and without separation omission); the total number of lines in all frames (both with and without separation omission); the stride between successive lines of data in a data buffer; the number of channels in a data buffer (both with and without separation omission); and the bit offsets and sizes of data for each channel within a buffer You should use these pre-computed counts and sizes rather than re-computing values in your code See the Doxygen integration guide for details. 
16. The RASTER_LAYOUT structure can be retained and released to keep safe references in your code by calling raster_layout_acquire() and raster_layout_release() It can be copied, serialized, and deserialized for storage, shared memory, or to move into a separate memory allocation using raster_layout_copy() See the Doxygen integration guide for details. 
17. The RasterDescription structure can be safely serialized and de-serialized for saving to storage or shared memory using the RasterDescriptionPack(), RasterDescriptionUnpack() and RasterDescriptionFreeUnpacked() functions See the Doxygen integration guide for details. 
18. Some of the third-party libraries are now built into corelib and exposed through RDR, rather than being built into the SDK source code If you want to use the RIP's built-in version of any of the third-party libraries, include "hhrsdk.h", and use the API exposed via RDR.