% ProceduralShadingAPI - Documentation useful for procedural shading:
%
% Parameters for procedural shading:
%
% There are three ways to pass data to a procedural shader for drawing of
% parameterized textures or texture-like stimuli:
%
% 1. Texture data: If you create the procedural texture via
% Screen('MakeTexture', ...., shader); by attaching a GLSL shader to a
% texture matrix, then you can pass image data or other 2D data, e.g.,
% matrices with whatever data makes sense, e.g., precomputed lookup tables.
% The shader can access that matrices/images at arbitrary texel locations.
% This makes sense for static data - content that doesn't change, so it can
% be encoded into the texture image matrix. Such textures or lookup tables
% can be large, but they consume a lot of memory and bandwidth.
%
% 2. Infrequently changing parameters: Parameters that do change, but don't
% change too often, e.g., change only once per trial or maybe once per
% stimulus frame, can be passed as uniforms to the shader via the
% glUniform() low-level OpenGL command. Uniforms values can be changed
% anytime on the fly, but changing them incurs some overhead, so doing it
% too often may significantly degrade stimulus drawing speed.
%
% 3. Frequently changing parameters: Parameters that do change once per
% drawn texture (per-gabor parameters for drawing a large number of gabor
% patches per image) can be passed as so called vertex attributes. These
% parameters are passed directly to the Screen('DrawTexture(s)') and
% efficiently transferred to the hardware. However, the number of such
% attributes is limited to a small value. E.g., ATI Radeon X1600 allows for
% a maximum of 16 such attributes. To keep your code portable to a variety
% of graphics hardware, you should use this option sparingly.
%
% The following vertex attributes are accessible from within a vertex
% shader:
%
% Vertex attributes and their meaning, sorted by corresponding
% Screen('DrawTexture(s)') parameters:
%
% 'srcRect':
%
% vec4 gl_TexCoord : (x,y,z,w) location of the corner(s) of the source
% texture to be drawn by Screen('DrawTexture(s)') before rotation or scaling
% transforms (ie. before TEXTURE_MATRIX). Depending on the current vertex,
% the (x,y) components encode either the top-left, top-right, bottom-left or
% bottom-right position as given by the 'srcRect' parameter. The (z,w)
% components are currently unused, default to (0,1).
%
% attribute vec4 srcRect : The 'srcRect' parameter as passed to the
% 'DrawTexture' command: srcRect.xyzw = [left top right bottom].
%
%
% 'dstRect':
%
% vec4 gl_Vertex : (x,y,z,w) location of the corner(s) of the "textured" quad
% to be drawn by Screen('DrawTexture(s)') before rotation or scaling
% transforms (ie. before MODELVIEW_MATRIX). Depending on the current vertex,
% the (x,y) components encode either the top-left, top-right, bottom-left or
% bottom-right position as given by the 'dstRect' parameter. The (z,w)
% components are currently unused, default to (1,1).
%
% attribute vec4 dstRect : The 'dstRect' parameter as passed to the
% 'DrawTexture' command: dstRect.xyzw = [left top right bottom].
%
%
% Size of the texture:
%
% attribute vec4 sizeAngleFilterMode : sizeAngleFilterMode.xy contains the
% width and height of the underlying texture or virtual texture in texels.
%
%
% 'rotationAngle':
%
% attribute vec4 sizeAngleFilterMode : sizeAngleFilterMode.z contains the
% 'rotationAngle' parameter in degrees (ie. 0-360).
%
%
% 'filterMode':
% attribute vec4 sizeAngleFilterMode : sizeAngleFilterMode.w contains the
% 'filterMode' parameter.
%
%
% 'modulateColor' or 'globalAlpha':
%
% vec4 gl_Color : Contains the color as passed by the fixed function
% pipeline. These values may be clamped to the 0.0 - 1.0 range on some
% systems, e.g., MacOS/X 10.4.x and earlier.
%
% attribute vec4 modulateColor : Contains the color/alpha unclamped. This
% is the same as gl_Color, but guaranteed to be not clamped to the 0-1
% range on any system.
%
% The .r .g and .b components contain either the RGB values of the
% 'modulateColor' argument, or (1,1,1) if none specified. The .a component
% contains either the A alpha value of 'modulateColor' if specified, or the
% 'globalAlpha' value if no 'modulateColor' is specified but 'globalAlpha',
% or 1.0 if neither 'modulateColor' nor 'globalAlpha' was set.
%
% Please note that the "color" values are affected by the color range
% remapping as set by Screen('ColorRange') if 'modulateColor' is specified.
% If one wants to use 'modulateColor' to pass generic (non-color kind)
% parameters, one should probably set the color range to 0.0-1.0 for
% consistent results.
%
% 
% 'auxParameters':
%
% attribute vec4 auxParameters0 : Contains the first four components of the
% 'auxParameters' vector or matrix passed to 'DrawTexture(s)' if any. These
% values are passed as is without any conversion - a good way to pass
% additional parameters to a shader in an efficient way.
%
% Further components of the 'auxParameters' matrix get assigned to:
% attribute vec4 auxParameters1
% attribute vec4 auxParameters2
% attribute vec4 auxParameters3
% attribute vec4 auxParameters4
% attribute vec4 auxParameters5
% attribute vec4 auxParameters6
% attribute vec4 auxParameters7
%
% The current number of such parameters is limited by PTB to 8*4 = 32 floating
% point values, but old graphics hardware may have lower limits on the
% number of allowed parameters.