JointSpace API Documentation

Introduction to the ambilight interface

Pixels

The LEDs of the ambilight system are called pixels.

A colour can be set for each pixel by means of an RGB value.

Individual pixels are address by specifying the side (left, top, right, bottom) and pixel number and layer

Per side pixels are numbered clockwise starting from 0. E.g. the pixel on the top left is pixel 0. In a system with four pixels on the right, the bottom pixel on the right side is pixel 3.

In a system with multiple layers, layer 1 contains the pixels projecting colour closest to the frame of the TV. Layer 2 projects colour more outward and so on.

Topology

The topology describes the number of pixels on each side and the number of layers.

The ambilight algorithm

The ambilight algorithm calculates the pixel colour values based on measurements from the video displayed on the screen. The algorithm e.g. takes care of smoothing the colour transition between adjacent pixels and between successive scenes. The behaviour of the algorithm is depending on configurable values in the TV menu.

The behaviour of the ambilight algorithm can be observed by reading two sets of pixels.

• The measured pixels: The measurements that serve as input to the algorithm. These are taken directly from the video.
• The processed pixels: The pixels after processing by the ambilight algorithm. These are the colours that are effectively shown.

Pixel cache

The pixel cache contains the custom pixel colour values that are set through the JointSpace API.

How the pixels in the cache are used by the ambilight algorithm depends on the mode.

Modes

The ambilight algorithm has three modes:

• Internal mode (default): The pixel cache is ignored. The ambilight colour is fully based on internal measurements and processing.
• User mode: The output colours are taken from the pixel cache instead of from the algorithm. Note that one still can read the processed pixel set, which will contain the colours calculated by the algorithm.
• Expert mode: The input colours for the algorithm are taken from the pixel cache instead of from the measurement. The effective output colours are the result of running the ambilight algorithm on the pixel cache.

Functionality

The JointSpace ambilight API provides methods for following functionality:

• Reading the measured and processed pixel colours.
• Setting pixel colours in the cache.
• Changing the mode as to activate or deactivate custom ambilight colours.