JavaScript Rendering Extensions

Rendering support

function okular.RenderImage()

Renders the complete viewport and sends it to device(s) display(s).

function okular.RenderRectangles(rectanglesArray)

var rectanglesArray = [{x: integer, y: integer, width: integer[, encoding: integer] [, dithering: integer]
[, rectangleUpdateOptions: integer][, rectangleOptions: integer]}, ...]

Limits the rendering of the next viewport change to specified rectangle regions only. After a change, the HTML rendering backend will wait for a short period before rendering. We have a limited amount of time before rendering to provide those regions, otherwise the full screen view will be rendered. (For details see Display options, rendering and ghosting).

This function is different from okular.RenderImage(). Firstly, it does not trigger rendering by itself and secondly, the function accepts rectangle information.

The information about the rectangles we want to dissect and display is provided with the argument list of the function call, together with some other options, such as the bit-depth that is to be used.

Be careful not to overlay various rectangles as this will slow down the screen refresh.

For the possible encoding and dithering options check okular.Setup()

• Encoding - any value from below, or undefined if we want to keep the old value. The JavaScript API generally accepts the encoding values 1, 4 and 0. Display images may be encoded using 1 bit or with 4 bits per pixel. The value 0 means you are using the default session encoding.

okular.EncodingDefault = 0;
okular.Encoding1Bit    = 1;
okular.Encoding4bit    = 4;

• Dithering (optional) - any value from below, or undefined if we want to keep the old value. For better image quality, the Visionect Software Suite supports the following device display images dithering options and constants:

okular.DitheringDefault = 0; // Use session default dithering.
okular.DitheringNone = 1; //Do not use dithering at all.
okular.DitheringBayer = 2; // Use Bayer dithering.
okular.DitheringFloydSteinberg = 3; // Use Floyd-Steinberg dithering.

• rectangleUpdateOptions (optional) - rectangle image options, or undefined if we want to keep the old value. This is a 16 bit value, where the byte with the higher weight sets up the display update type (region, full, …), and the second byte selects the display drawing waveform (some waveforms work only with certain encodings). The options are:

//update mode: Select which update mode should be used. Following update modes are available:
    okular.RectangleUpdateFull          = 0x0000;
    okular.RectangleUpdateFullArea      = 0x0100;
    okular.RectangleUpdateFullArea      = 0x0200;
    okular.RectangleUpdatePart          = 0x0300;
    okular.RectangleUpdatePartArea      = 0x0400;
//waveform_mode: Select which waveform mode should be used by display. Following waveform modes are available:
    okular.RectangleUpdateWaveformINIT  = 0x0000;
    okular.RectangleUpdateWaveformDU    = 0x0001;
    okular.RectangleUpdateWaveformGC16  = 0x0002;
    okular.RectangleUpdateWaveformGC4   = 0x0003;
    okular.RectangleUpdateWaveformA2    = 0x0004;

Update type	rectangleUpdateOption
FULL SCREEN	2
FULL AREA	258
PART SCREEN	514
PART AREA	770

Warning

Because of the technical characteristics of electronic paper technology it is strongly recommended to use the fullscreen update approximately after every 10th image change.

Note

The use of waveform and update method is display-specific. Contact our support for additional information and the correct use.

• rectangleOptions (optional) - extra rectangle options, or undefined if we want to keep the old value.

okular.RectangleEnableTransperency = 0x1; // Enable transparency for current image
okular.RectangleDisableInverse     = 0x2; // Disable image inverse

• imageUpdateOptions (optional) - rectangle image container options, or undefined if we want to keep the old value. You should set this only if you really know what you are doing.

okular.ImageUpdateClearScreen  = 0x01; // Clean screen before update
okular.ImageUpdateBorderUpdate = 0x02; // Enable border update on displays which supports this feature. The color bit specifies the border color
okular.ImageUpdateBorderWhite  = 0x04; // If border update is enabled. This sets white color of the border, otherwise it's black

Example 1

okular.RenderRectangles([{x:400, y:0, width: 200, height: 300, encoding: 1, dithering: okular.DitheringBayer}, {x:0, y:0, width: 200, height: 300, encoding: 1, dithering: okular.DitheringDefault}]);

Warning

You should not mix 1-bit and 4-bit encoding in the same image packet, as this can cause problems with updating content and could result in a fullscreen refresh. Also, make sure that the “Force Rectangle Support” setting in the Management Interface (Settings -> Default Device Settings) is enabled.

Example 2

//uses jQuery library.
//render a popup
var my_popup = $("#mypopup"); //get the div you want to render
var my_popup2 = $("#mypopup2"); //get the second div you want to render

list = new Array(); //create a list for rectangles

//first rectangle
list.push({x: my_popup.offset().left, y: my_popup.offset().top,
   width: my_popup.outerWidth(), height: my_popup.outerHeight(), encoding: 1, dithering: okular.DitheringDefault});

//second rectangle
list.push({x: my_popup2.offset.left, y: my_popup2.offset().top,
    width: my_popup2.outerWidth(), height: my_popup2.outerHeight(), encoding: 4, dithering: okular.DitheringNone});

 okular.RenderRectangles(list);

function okular.Setup(encoding, dithering, rectangleUpdateOptions,rectangleOptions, imageUpdateOptions)

Sets the global default settings for all subsequent screen renders for the current session. The settings will trump the default settings set by Management Interface. For more details see server configuration.

Warning

Some of the rendering-related settings might not work correctly on first generation Visionect Signs or if your client device is running on an older version of Visionect firmware. Please contact our support for more details.

Example:

okular.Setup(okular.Encoding1Bit, okular.DitheringBayer);
okular.Setup(okular.Encoding4Bit, undefined, undefined, undefined, okular.ImageUpdateBorderUpdate );

A working example of rendering rectangles can be found at Okular_API_example.zip.

Device has successfully rendered image event

Whenever a device successfully renders an image, it informs the server of the success with an ACK response. This can be hooked up to a special JS event that sends out a notification whenever an image is successfully rendered.

The event is called the device-image-ack. It provides the following details:

• The updated device UUID string (e.detail.device)
• The updated mode string (e.detail.mode)

• One of the following values:

  • "update" - a classical update
  • "virtual display update" - the update is a part of a greater virtual display update. You may want to wait for all devices that are part of the virtual screen to get updated.

• The encoded device image checksum number (xxash) (e.detail.checksum)

function handleImageACK(e)
{
    console.log("device-image-ack", e.detail.device, e.detail.checksum, e.detail.mode);
}
document.addEventListener("device-image-ack", handleImageACK, true);

Rendering performance and optimizations

The Visionect Software Suite should be able to answer a client device request approximately in hundredth of a millisecond. In order to enable the best Software Suite performance, you should make sure that:

• your web application is responsive enough (which includes all possible back-end requests/responses and resource loading), and that
• you have a low network latency and a stable wireless connection

You can fine-tune the responsiveness by changing the RenderTimeout in the Visionect Software Suite. Lower values mean a faster response time from a click to the screen refresh, but can cause partial renderings (e.g. missing images) as the page might not have been rendered completely when the ‘snapshot’ for the device display was taken. Your success will depend on how performant your web application is.