Load the gamma table of the specified screen or window
'windowPtrOrScreenNumber'. You need to pass the new hardware gamma table 'table'
as a 256 rows by 3 columns matrix. Each row corresponds to a single color index
value in the framebuffer and contains the Red- green- and blue values to use for
output. Column 1 is the red value, column 2 is the green value and column 3 is
the blue value. Values have to be in range between 0.0 (for dark pixel) and 1.0
(for maximum intensity). Example: table(127,1)=0.67 would mean that the red
color value 127 should be displayed with 67% of the maximum red-gun intensity,
table(32, 3)=0.11 means that blue color value 32 should be displayed with 11% of
the maximum blue-gun intensity. The range of values 0-1 gets mapped to the
hardware with the accuracy attainable by the hardwares DAC's, typically between
8 and 10 bits. On OS-X you can also pass 512, 1024, 2048, ..., 65535 rows
instead of 256 rows, although this only makes sense for a few selected
applications, e.g., setup for the Bits++ box. If you provide the index of an
onscreen window as '
ScreenNumber' and you set the (optional) flag
'loadOnNextFlip' to 1, then update of the gamma table will not happen
immediately, but only at execution of the
Screen('
Flip',
windowPtrOrScreenNumber) command. This allows to synchronize change of both the
visual stimulus and change of the gamma table with each other and to the
vertical retrace. If the flag is set to its default value of zero then update of
the gamma table will happen at the next vertical retrace (or immediately if the
graphics driver doesn't support sync to vertical retrace). A 'loadOnNextFlip'
flag of 2 will load the provided table not into the hardware tables of your
graphics card, but into the hardware tables of special display devices, like
e.g., the Bits++ box.
On
MacOS-X, the optional 'physicalDisplay' flag can be set to 1, zero is the
default. In this case, the 'windowPtrOrScreenNumber' argument (which then must
be a real screen number, not a window index) selects among physically present
display devices, instead of logical devices. This is important if you want to
assign different gamma-tables to multiple displays in a 'clone' or 'mirror mode'
configuration, as there is only one logical display, but multiple physical
displays, mirroring each other. Please note that screen numbering is different
for physical vs. logical displays. For a list of physical display indices, call
Screen('Screens', 1);
On
MacOS-X, this function takes arbitrary gamma-tables which makes it suitable
for fast CLUT animation. On Microsoft Windows, only tables with monotonically
increasing values are considered valid. Other tables get rejected by the
operating system -- there's nothing we can do about this incredibly wise
decision of the Microsoft system designers :( , so this is not suitable for CLUT
animation, but only for linearizing or calibrating display devices. The function
returns the old gamma table as optional return argument.