This file suggests three changes to the PTB:
1- Internally we represent color values as normalized doubles in the range 0-1
2- Internally we represent video display modes with enumerated types instead of structs.
3- We migrate Screen to accepting normalized pixel values in the range 0-1 instead of actual register values by providing a preference switch for that.  

Internally, the OS X PTB represents the video mode in an overcomplicated way, using a struct with separate fields holding numeric values describing color and depth resolution. It encodes the resolution but fails to capture the format- the order of planes within a pixel, for example GBRA vs. RGBA.  We can improve on that by representing a pixel formats using an enumerted type instead of a struct of values, though the transition would require major surgery.

The ugliness of the present system is that we end up passing the pixel format stuff around a lot, partly because Screen subfunctions accept ambiguous arguments which are resolved using the pixel format.  Pixel format information must accompany a color triplet if we use non-normalized color values, for example 4 is ambigous, being either 4/256 or 4/1024.  OpenGL wants the normalized value.  So it would be much cleaner also if we used normalized pixel values internally throughout.  If we normalize input color values upon receipt from MATLAB into the Screen we never (or rarely) need to resolve those to non-normalized values to register values because unlike QuickDraw, OpenGL wants normalized values in the range 0-1.  

Various random To Do comments:    

• Create a surface descriptor of enumerated types with each constant denoting attributes depth, plane size and order.   For examle: kPsych_R8_G8_B8_A8.  This covers order, size, and number of planes and it's a single constants, so we only need to pass one value around when that is required.   If we want to get fancy we can write a layer of extractors, for example:

PsychGetNumPlanes(kPsych_R8_G8_B8_A8)

would return 4

Othewise we would need big conditional statements all over the place.  

• Internally pass around all RGB values as values normalized to the range 0-1.  OpenGL accepts such normalized values as floats or doubles, so we don't lose anything or introduce sloppyness by doing this in the PTB also.    Convert them to this format and store them this way as soon as they received by the PTB from MATLAB.   Write functions to munge the normalized values into the values in the range appropriate for the depth mode constants.  

• Normalizing stuff should prevent us from needing the depth every time we want to do something with the color, so we don't need to tie depth information to color information, which saves a bunch of work.  
  
• Include a preference flag for when using RBG values in the range of 0-1 or 0-2^bitDepth and use it when allocating in values.  Note that there is an interaction with 8-bit indexed mode here.      

• We could provide a preference for the PTB in MATLAB for accepting normalized values and interpret numeric values immediately upon receipt, in functions which read in color arguments passed to screen from MATLAB.  There would be little work in doing this.  The gripe about this is that the color precision is not explicit and may be forgotten, but so long as it can be queried, what's the problem?  Plus, changing the numeric range of values in your program based on color resolution of the hardware is a real headache.   Importanly, it allows  us to interact OpenGL more transparently.  The system of non-normalized color values will aggravate anyone with an OpenGL background who is trying to use the PTB. 

• I think the reasons that the OS 9 PTB does not use normalized color values are 1. Its based on QuickDraw which does not.  2. Doing so forces the user to be aware of the underlying resolution.  With OpenGL, 1 No longer applies and I don't believe that 2 works for the people who need it or is useful for the people who do not.  If you are not aware of the issue of false resolution and hidden quantization, is explicit quantization going to clue you in to the problem?   Quantized resolution should be easily queryable in the PTB but do we need to inconvenience the user to make the point?

Allen Ingling
28 October 2004