How to use the Apex Evaluation Compatibility Header

Introduction

The Apex build of Mako 8.1 (due for release at the end of June 2025) features a new header to simplify integration of Apex into an existing Mako project. All you need to do is make a small code change when creating the IJawsRenderer class, as follows:

Before

CPP

#include <jawsmako/jawsmako.h>
...
const auto jawsMako = IJawsMako::create();
...
const auto renderer = IJawsRenderer::create(jawsMako);

After

CPP

#include <jawsmako/apexeval.h>
...
const auto renderer = createApexEvalRenderer(jawsMako);

That’s it! You can now rebuild your project against the Apex-enabled Mako distribution, and you are good to go.

Not all APIs are supported, and not all parameters for all render functions are supported.

In particular, the following are not supported:

Screening: Halftone and EDS (Error Diffusion Screens) are not available
IJawsRenderer::render() does not support maskToInterestingNodes being set to true
IJawsRenderer::renderSeparations() and IJawsRenderer::renderSeparationsToFrameBuffers(): The bandMemorySize parameter is ignored.
IJawsRenderer::renderSeparations() and IJawsRenderer::renderSeparationsToFrameBuffers(): The processColorNames parameter is ignored. Instead, the ICC profile of any extended gamut target color space is consulted, and that profile must have a colorant (clrt) table describing the colorants. Further, if an extended gamut color space is used, rendering will be performed via CMYK before expanding to the final color space. For extended gamut rendering, it is best to use the Apex renderer directly and configure appropriately.
IJawsRenderer::renderSeparations() and IJawsRenderer::renderSeparationsToFrameBuffers() do not support anti aliased values greater than 4.
IJawsRenderer::renderSeparationsToFrameBuffers(): The bandMemorySize parameter is ignored.
IJawsRenderer::renderAntiAliased() supports a maximum quality of 3

Images returned by render APIs will have a resolution of 96dpi, however the images will have correct pixel dimensions

You can expect rendering code built with native Apex calls will be more performant than using this class with code optimized for Jaws

This compatibility header presents the same API as IJawsRenderer, but internally will use Apex. This is useful for evaluation purposes only, and in general it’s best to use Apex directly. In addition to the restrictions noted above, Apex offers additional features that are not available through this evaluation method.

In general, Apex will be faster when rendering to frame buffers, as there are more opportunities for parallelism. It is also common to create multiple IJawsRenderer instances to take advantage of parallel rendering on multiple threads to exploit multicore CPUs. This, while good for the Jaws renderer, is generally bad for Apex as some objects may be repeatedly uploaded to GPU memory needlessly, and GPU memory is a finite resource. Apex itself is reentrant, and while a GPU may only work on a single render at a time (though parts of renders will be interleaved), Apex can prepare content for the GPU in parallel, and this helps ensure the GPU is well utilized.

Taking this into account, this evaluation class creates a single Apex renderer internally, and all instances of this class will issue renders to that shared instance of Apex.