How to use the Apex Evaluation Compatibility Header

Introduction

Before following this guide, please read this section regarding the Vulkan SDK on the Apex Getting Started page.

Mako 8.1 adds a new C++ 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. However, with some other small changes, you may be able to improve performance still further. Make sure you read the section Increase band or tile size for best performance below.

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.

Increase band or tile size for best performance

A potential bottleneck is a small rendering buffer. If your Jaws code divides a page into several bands or tiled areas, rendering each with a separate IJawsRenderer instance on a thread, this actually will be detrimental to Apex performance, for the reasons described above. Instead, increase the buffer size to a much higher value, for example one large enough for the entire page. This will reduce the number of rendering calls made, and Apex is much happier with a large buffer, which it can manage internally without difficulty.