.. _js-device-config: JavaScript Rendering Extensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Rendering support ----------------- function okular.RenderImage() """"""""""""""""""""""""""""" Renders the complete viewport and sends it to device(s) display(s). .. _my-okular-RenderRectangles-label: function okular.RenderRectangles(rectanglesArray) """"""""""""""""""""""""""""""""""""""""""""""""" .. code-block:: javascript 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 :ref:`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 :ref:`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. .. code-block:: javascript 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: .. code-block:: javascript 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: .. code-block:: javascript //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; .. csv-table:: :header: "Update type", "rectangleUpdateOption" :widths: 50, 50 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. .. _support: support@visionect.com - *rectangleOptions (optional)* - extra rectangle options, or *undefined* if we want to keep the old value. .. code-block:: javascript 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. .. code-block:: javascript 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* .. code-block:: javascript 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* .. code-block:: javascript //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); .. _my-okular-setup-label: 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 :ref:`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: .. code-block:: javascript 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 :download:`Okular_API_example.zip <_static/Okular_API_example.zip>`. .. _img_event_successfully_rendered: 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``) .. code-block:: javascript function handleImageACK(e) { console.log("device-image-ack", e.detail.device, e.detail.checksum, e.detail.mode); } document.addEventListener("device-image-ack", handleImageACK, true); .. _my-rendering-performance-and-optimizations-label: 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 :ref:`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.