PROPixx Demo 7 -- Understanding CLUTs,  M16 Mode, and Color Transparency 
===========================================================================================

Color look-up tables (CLUTs) are a part of the video pipeline. You can have CLUTs for color correction, gamma correction, color removal, etc.
A CLUT is usually a 256 by 3 matrix, where each column represents a color channel (Red, green, blue (RGB)) and each row represents an operation
or a new color value for that color. A non modifying CLUT is defined as follow in MatLab: ``linspace(0, 1, 256)' * [1, 1, 1]``. Colors in MatLab are usually
represented as a double going from 0 (no color) to 1 (full intensity). Colors usually have an 8 bits representation, and therefore can vary from 0 to 1 in 256 steps.

In this demo, we use CLUTs to define a transparency color and to have different colors on the console display from the main display. 

The transparency color is useful if you want to display a message to yourself but having it invisible to the subject.  Different colors on the two displays
can be useful if you want different shades or a different gamma on the two displays.

As stated before, colors are usually represented using 8 bits of information. Our device are capable of displaying 10-12 bits of colors. However,
a video signal can only send 24 bits (8 per color) of information. To overcome this limitation, we have to manipulate the data and interpret it differently in our device.

In mode M16, we calculate a 16-bit shade of gray and send that information using the 8 bits of red and 8 bits of green. The VPixx device combines
it to display a 10-12 bit closest value if the blue component is zero. If the blue component of the pixel is not zero, then it is used as an index to a CLUT to display the pixel as an overlay. 
That overlay will have the color defined in the CLUT.

There are two look-up tables on our device, one for the main device and one for the console display. This means you can have different color overlays on the
console and on the main device.

It is also possible to define a transparency color to the device. If the CLUT table has that color at the given blue index, there will not be an overlay, the pixel will be drawn
as if the blue value had been zero (using the gray color provided by the combined Red and Green).

This demo uses the ``PsychImaging`` pipeline and sets it up to use 32 bits precision for calculations, enables the M16 video mode with overlay, 
and sets a simple gamma correction. We specify the color correction gamma to be 1/2.2, such that this example has a gamma of 1. 

``Screen('LoadNormalizedGammaTable', win, linspace(0, 1, 256)' * [1, 1, 1]);`` is run to prevent a bug on MAC which always require a CLUT loaded on the graphic card.

Since we set up the M16 mode with an overlay, we must create the overlay and set its CLUT. ``Datapixx('SetVideoClutTransparencyColor', transparencyColor);`` sets 
up the device to use a certain color as transparent (green in this case), and we must enable the transparency color mode ``Datapixx('EnableVideoClutTransparencyColorMode');``. 

To use this transparency color in M16, we create two CLUTs that only contain the transparency color. ``clutTestDisplay = repmat(transparencyColor, [256,1]);``. After that,
we must change the index of the color we do not want to be transparent to a color we choose. ``clutTestDisplay(242:246,:) = repmat([1, 0, 0], [5,1]);`` defines 
that anything with a blue index from 243 to 247** will be drawn as red ([1,0,0]). 

We must then load the CLUTs on the device ``Datapixx('SetVideoClut', [clutTestDisplay;clutConsoleDisplay]);`` (We load the main display CLUT then the console CLUT).

The range of color that was changed on the main display CLUT will not be transparent, but it will be transparent on the console display, since the range was not modified
and it leads to the transparent color.

** On some devices, there is rescaling of the color, in which case we use a 242 to 246 range instead of just the value 247. This varies from system to system and, for example, 
our test window machine for 247 we had to set the color to 246, while on the Mac it was 245. With range 242 to 246, you should aim to use color 243.

.. literalinclude:: ../DatapixxToolbox/DatapixxDemos/DatapixxM16Demo.m
   :language: matlab
   :emphasize-lines: 17-19, 36, 50, 54-58, 62-77,  79, 89-91
   :linenos: