## Introduction

This is the Platform Optimization SDK for use with Receiver for Linux Version 13.10. The primary purpose of the SDK is to support developers who are creating plug-in extensions for the ICA engine component (wfica) of Citrix Receiver for Linux. Plugins are built as shareable libraries that are dynamically loaded by wfica.There are separate versions of the SDK for each of the released architectures (X86, X86_64, ARMel and ARMhf) that differ only in the included binaries.

There are two flavours of wfica, the standard wfica which is built with support to output to X11 displays, and wfica_for_plugins which has no input/output support built in, and is intended for non X11 environments.

The table below summarises the plugins which can be developed, a fuller description is given in the text that follows.

Plugin type | Applicable to wfica | Applicable to wfica_for_plugins | Notes
--- | --- | --- | ---
Accelerated H264 decoders | Yes | Yes | Separate implementations may be needed for each variant of wfica
Accelerated JPEG decoders | Yes | Yes | The same decoder will work with both variants of wfica
KVME.so plugins | Yes | Yes | Includes the memory allocator and this type of plugin may be needed for that alone, to support a JPEG or H.264 plugin. When used with wfica does not handle input events.
UIDialogs plugins | Yes | No. |

The Receiver can also exploit additional plugins for accelerated audio and video codecs, by configuring it to use GStreamer for audio, camera and multimedia functions. Such plugins are standard GStreamer components, and are not covered in the document.

## Plugins for accelerating X11 based wfica

### Plugins for H.264-based session graphics

XenDesktop version 6 and later support a protocol for presenting the remote session's graphics that uses a combination of H.264 and a proprietary lossless graphics encoding. For maximum flexibility in exploiting on-chip decoders and hardware rendering support, plugins take full control of the decoding, overlay and rendering process.

The details of the interface for these plugins are documented as comments in the relevant header file, H264_decode.h, with an unaccelerated sample implementation in the H264_sample directory. The sample code (H264_sample) is based on what was wfica's fallback implementation that is used when no accelerated plugin is available, and for that reason builds a plugin named ctxh264_fb.so. This plugin will need to be renamed to ctxh264.so and placed in $ICAROOT/lib to override other H264 plugins. The decoder provided contains stub functions which do no decoding. It is intended as a template to begin work with.

The sample code (H264_Pi_sample) is a Raspberry Pi implementation and is provided as a reference hardware implementation.

### Plugins for accelerated JPEG decoding.

All currently supported versions of XenDesktop and XenApp for Unix can use JPEG to compress portions of the session image. Plugins that support hardware-accelerated JPEG decoding can give a large improvement in graphics performance for sessions not using H.264 session graphics. At startup, wfica looks for a plugin named ctxjpeg.so in $ICAROOT/lib to handle JPEG decoding.

The interface JPEG decoding plugins is in the jpeg_decode.h header file. The sample code (jpeg_sample) is that of wfica's fallback implementation that is used when no accelerated plugin is available, and for that reason builds a plugin named ctxjpeg_fb.so

### Plugins for memory allocation.

Hardware-accelerated plugins for H.264 or JPEG decoding may need to allocate memory buffers with special characteristics, for example using physically contiguous pages. A single plugin component, KVMEPlugin.so is used for both straightforward memory allocation and for taking control of drawing the session image. When memory allocation is the purpose of the plugin, only two functions need to be supplied.

The header file for these plugins is mainloop.h and the two entry points that must be implemented are special_allocate() and special_free(). The example code is in the allocation_sample directory. Before using this code as a model, pay careful attention to the comments, as parts of the code are there purely for backward compatability with decoder plugins developed for now-obsolete versions of Receiver.

### Plugins for accelerated drawing in X11 environments.

In some environments using X11, there may be drawing methods that are faster than the calls to XShmPutImage() that are used by default. An implementation of KVMEPlugin.so can use an alternative drawing method by providing the draw() entry point, which is used to push the session image to the screen. The optional draw_complete() entry point may also be provided. When these are used, there is no requirement to also implement the memory allocation functions.

The allocation_sample example includes an implementation of draw() that is almost identical to the default drawing code for X11.

## Plugins for non-X11 wfica_for_plugins.

This SDK includes a separate version of the Receiver engine, wfica_for_plugins that is not linked with any X11 libraries. The program requires a KVMEPlugin.so that provides video output, mouse and keyboard input, and timer and event detection services. The KVMEPlugin.so binary needs to be placed in the $ICAROOT dirctory to take effect. Some features of the X11 version are not yet available: clipboard, sessions with multiple windows ("Seamless Windows"), multimedia and Flash support.

Two example KVMEPlugin.so implementations are included in this SDK. One can only use the framebuffer as it's output, the other can optionally use the framebuffer. When using the framebuffer graphics run the program from a text console: it is usually necessary to run as the superuser, or change the permissions on the /dev/fb0 and /dev/input/mice

### SDL plugin

The directory SDL_plugin contains an implementation based on the SDL library.

The environments supported with SDL depend on how the library is built, but usually X11 and frame buffer graphics are supported. Obviously the preferred means of X11 support is the standard wfica, but taking advantage of any X11 support available in your SDL could speed development.

### FB_plugin

The FB_plugin directory contains a version using Linux system calls and device files, using the raw frame buffer for display.

### Important caveat

A bug has been raised for this issue, and we hope to resolve it before the next release. wfica_for_plugins does not work when the sound virtual channel is configured to run in a private thread (the default). Before testing, disable the channel ('ClientAudio=Off" under "[ICA 3.0]") or the thread ("UseThread=Off" under "[ClientAudio]") in the module.ini configuration file.

### Using the test harness for KVME plugins

The SDK includes a simple test harness for testing early versions of KVMEPlugin.so for non-X11 environments. The program is built in the plugin_test directory. When run, it will load a plugin from the current directory, initialise video output and log mouse and keyboard input events to standard output.

Timer support can be verified by specifying a command argument of 1. Larger values of the first command argument will build a chain of data-passing stages that use pipes with timers and I/O readiness detection (select_fd() function) to transfer data in response to events. A second optional argument sets the initial timer value, for stress testing.

## HDX Multimedia with KVME plugins.

The HDX Multimedia feature can be used with accelerated plugins for X11 and plugins for non-X11 environments. Support is enabled by the configuration entry UseSubwindows=Off, placed under the [WFClient] heading. The draw_overlay() entry point to the plugin will be called to merge video output into the session image.

The Sub-window Interface of the Virtual Channel API supports use of this mechanism in externally-developed Virtual Channels. The relevent header file, subwindow.h, is also included in this SDK.

## UI Dialog Library

The UI Dialog Library (UIDialogLib.so) implements an abstraction layer for the display of dialogs. A dialog's contents is dependent on the contents of the C formsElement structures passed (The formsElement structures are declared in UI_if.h in the toplevel inc directory). The dialog is built dynamically according to the given information in these structures and rendered. The formsElements themselves are essentially label and widget pairs, where the widget can be a text entry box, check box, set of radio buttons, combo box, multi combo box, button, hyperlink, expander, scrolled view, selection table, button box or another label.

The UI Dialog Library is used for the majority of dialogs within the Linux Receiver processes, including the X11 based wfica. The processes storebrowse, AuthManager, PrimaryAuthManager, and ServiceRecord use it for all of their UI. The purpose is to ensure that the UI of these essential processes can be replaced with a toolkit and event loop of your choosing by re-implementing the library. The current implementation of the UI Dialog Library distributed with the Linux Receiver is GTK+. The code for this implementation is provided under the UIDialogLib/GTK directory in this SDK as an example.

The selfservice, configmgr, and X11 wfica binaries require GTK+ for other aspects of their UI other than dialogs and therefore cannot be used with a different implementation of the UI Dialog Library than the provided GTK+ implementation. However, all of their functionality is available via the storebrowse command line interface and the configuration files.

A selection of examples are provided under the UIDialogLib/test directory to showcase some of the widgets and dialogs that may be seen.

For information on the interface itself please read the UIDialogLib.h header in the UIDailogLib/inc directory.

## Change history

Version 13.5:
Reworked to make clearer.
Minor update to the H.264 decoder (2 -> 2.1) which allows for optional show/hide cursor commands.
Plug-in can request a full Thinwire renegotiation on a server initiated CMD_TW2_INIT.

Version 13.4:
Remove references to FFMPEG.

Version 13.3:
Documentation updates.

Version 13.2:
Re-organise H264_sample code and Makefile changes.

Version 13.1 Release 2:
Bug fixes and addition of this change history.

Version 13.1:
Add source code for the H.264 decoder plugin for Raspberry Pi.
Add support for HDX Multimedia output with non-X11 graphics.
Add additional UI elements and a interface version number to UIDialogLib.
Rename structure members from private to priv for C++ compatability.

Version 13.0:
The original release of this SDK. Earlier versions of the KVME plugin, JPEG and H.264 interfaces had been previously available to Citrix partners for use with the 12.2 and 12.5 Receivers.