/docs/MyDocs

Basic Definitions

=================

 - Front-facing - Polygons whose vertices appear in counterclockwise order on 

 the screen are called front-facing.

 

 - Field of view (angle of view). ���� ����� ����� ������������� ��������� 

 �������� �����, �������, ������ � ���������� � ���������� x-y, ������ ��� 

 ������.

 

    Functions coding scheme

    -----------------------

    - example function prototype: glColor[234][u][dfis][v]()

        [234] - defines number of properties (2D, 3D, ...)

        [u][dfis] - defines supported types

            u[unsigned],d[double],f[float],i[int,s[short],b[byte]

        [v] - specifies an vector format

 

    4D coordinate system

    ---------------------

      Coordinates are (x,y,z,w). Where 'w' is some kind of perespective 

    coefficient (basically dummy) added to simplify matrix transformations.

    Consider following 2D example: to convert vector (x,y) to (x+a,y+b) the

    following matrix multiplication may be used.

            1 0 a     x     x + a

            0 1 b  *  y  =  y + b

            0 0 1     1       1

    this would be not possible with only two dimensions. Therefore 3rd dummy "1"

    is added to the vector. Exactly, the same is happening with vector.

    

Defining Primitives

===================

    glBegin(primitive_type);

        ... code ...

    glEnd();

 

 - Primtives:

    GL_POINTS

    GL_LINES (�� ����������) GL_LINE_STRIP (�������), GL_LINE_LOOP (���������)

    GL_TRIANGLES, GL_QUADS

    GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_QUAD_STRIP (���������)

    GL_POLYGON (convex, without intersections)      

 

 - Basic code

    glColor[234][dfis][v](r,g,b)        - setting local color

    glVertex[234][dfis][v](x,y,z)       - setting primitive vertex

    glNormal[234][dfis][v](x,y,z)       - defines a normal vector at next vertex

 

  - Various aspects, functions should be stated before 'glBegin'

    * glPointSize(float)                        - 1.0 is default

    * glLineWidth(float)                        - 1.0 is default

    * glPolygonMode(GL_FRONT, GL_FILL)          - Polygon filling mode

        GL_FRONT, GL_BACK 

        GL_FILL, GL_LINE, GL_POINT

 

    Colors

    ------

    glColor[34][bsifd](r,g,b,a)         - setting color, values expected to be

                                        between 0.0 and 1.0

    glShadeModel (<mode>)               - shading mode

        GL_SMOOTH       color of one vertex of a primitive is duplicated across

                        all the primitive's vertices.

        GL_FLAT         color at each vertex is treated individually. the colors 

                        for the interior of the polygon are interpolated between

                        the vertex colors.

                                    

    Bit planes: GL_RED_BITS, GL_GREEN_BITS, GL_BLUE_BITS, GL_ALPHA_BITS, and

    GL_INDEX_BITS.

    

    - The alpha value (the A in RGBA) has no direct effect on the color 

    displayed on the screen. It can be used for many things, including blending

    and transparency, and it can have an effect on the values of R, G, and B 

    that are written.

    

    - Dithering: increasing amount of supported colors by mixing pixels of two

    different tones in checkboard manner. Depending on proportion of pixels of

    each color, a new combined tone would be seen by an user if hi is far away 

    from display and can't distinguish separate pixels.

        glEnable(GL_DITHER)             - enables dithering

 

    - Gamma correction: Color intensities on most computer screens aren't 

    perceived as linear by the human eye. The question is, does 0.5 look like 

    halfway between 0.0 and 1.0? 

     * To test this, write a program that draws alternate pixels in a 

    checkerboard pattern to intensities 0.0 and 1.0, and compare it with 

    a region drawn solidly in color 0.5. OpenGL assumes they're the same. 

     * Many systems have a table to adjust intensities so that 0.5 appears to 

    be halfway between 0.0 and 1.0. The mapping usually used is an exponential

    one, with the exponent referred to as gamma. 

 

 

    Display Lists

    -------------

    A display list is a group of OpenGL commands that have been stored for later

    execution. When a display list is invoked, the commands in it are executed 

    in the order in which they were issued.

    glNewList(<id>, GL_COMPILE);

        ... glBegin/glEnd blocks ... 

    glEndList()

    

    glCallList(<id>)                            - Execute List, id>=1

    

    - ID's should start from 1!

    - Some time it is wise to save-and-restore transformation matrixes and GL

    context:

        glPushMatrix();

        glPushAttrib(GL_CURRENT_BIT);

            ... list coomands

        glPopAttrib();

        glPopMatrix();

    - Nesting is allowed. The called threads should not be defined prior to 

    calls and may be defined later in the program (but, obvious, before call to

    encompassing list)

    - Other commands

        firstid = glGenList(<num>)      - allocates contiguous range of still

                                        unallocated list indecis

        glListBase(<firstid>)           - set display-list base, see glCallLists

                                        for example usage

        gCallLists(n, type, lists)      

            Executes 'n' display lists. The indices of the lists to be executed

            are computed by adding the offset indicated by the current 

            display-list base (specified with glListBase()) to the values in 

            the 'lists' array of type 'type.

            Types: GL_BYTE, GL_SHORT, GL_INT, GL_4_BYTES, GL_3_BYTES, ...

 

        glIsList(<id>)                  - is list existing

        glDeleteLists(...);             - delete lists

 

 

Viewing

=======

 [object coordintates] 

    -- Viewing Transformation (modelview) -->

 [eye coordinates]

    -- Projection Transformation (projection) -->

 [clip coordinates]

    -- Perespective Division -->

 [normolized device coordinates]

    -- Viewport Transofrmation

 [window coordinates]

 

 - Coordinate system (and default view):

        y^

         |

         |   x

         .--->

        / 

      z* 

        

 - Approach:

    * The camera is Initialy located at (0,0,0) and points at negative z-axis

    * Actually, all transformations are performed using 4 x 4 matrix (M), which

    is then multiplied by coordinates of each vertex (v): v' = Mv

    * Last transformation command called in your program is actually the first 

    one applied to the vertices.

 

 - Defining transformations:

    glMatrixMode(mode)          - Selecting  appropriate transofrmation matrix

        GL_PROJECTION, GL_MODELVIEW

    glLoadIdentity()            - Clear Matrix

    

    ... defining transformations ...

 

    ... adding objects ...

 

    ... defining additional transformations ...

 

    ... adding objects ...

 

    ......................

    

 - Enabling ray tracing (removing hiddent parts from screen)

    glEnable(GL_DEPTH_TEST);

 

 - Defining transformations:

    glLoadMatrix(arr)           - Defining transformation matrices

    glMultMatrix(arr)           - Adds transformation matrix to sequence

        arr - is 1D array defining matrix 4x4 (fastest indecis change on vert.)

    

    glPushMatrix()              - Saves current matrix in stack

    glPopMatrix()               - Popes matrix from stack

    

 - MODELVIEW transformations: 

    glTranslate[fd](x,y,z)      - moves camera by the specified vector

    glRotate[fd](angle,x,y,z)   - rotates object (counterclockwise) arround 

                                the ray from the origin through specified point

    glScale[fd](x,y,z)          - scale object along axis

 

    gluLookAt(fx,fy,fz,tx,ty,tz,vx,vy,vz);

        we are looking from (fx,fy,fz) to (tx,ty,tz) with an up vector (vx,vy,vz)

    

 - PROJECTION transformations:

    glFrustum(left,right,bottom,top,near,far)   - perespective projection

            left,right,bottom,top - defines sizes of near clipping plane

            near, far - defines distance to near and far planes

 

           /|

          / |far

        ./| |plan

         \| |

     near \ |

      plan \|

            

            only objects between near plan and far plan are displayed

 

 

    gluPerespective(fovy,aspect,zNear,zFar)

        fovy - field of view (degrees) in the 'y' direction

        aspect - x-y aspect ratio (of project planes)

        zNear - distance from viewer to the near clipping plane

        zFar - distance from viewer to the far clipping plane

 

 

    glOrtho(left,right,bottom,top,near,far)     - orthographic projection

    

 - Clipping planes

    glClipPlane(plane, equation)                - Defines additional planes, 

                                                clipping part of output

        * plane - is plane index, should be enabled or disabled by calling

            glEnable(GL_CLIP_PLANE<plane>);

            glDisable(GL_CLIP_PLANE<plane>);

        * equation is double array (a,b,c,d) defining plane ax+by+cz+d=0

        

 - VIEWPORT transformations:

    glViewport (x, y, w, h)     - in pixels

    glDepthRange(near, far)     - in pixels, must be within (0,1)

 

 - Perespective division:  (x,y,z,w) -> (x/w, y/w, z/w, 1)

 

 

Light

=====

    Theory

    ------

    - The OpenGL lighting model makes the approximation that a material's color 

    depends on the percentages of the incoming red, green, and blue light it 

    reflects. For example, a perfectly red ball reflects all the incoming red 

    light and absorbs all the green and blue light that strikes it. If you view

    such a ball in white light (composed of equal amounts of red, green, and 

    blue light), all the red is reflected, and you see a red ball. If the ball 

    is viewed in pure red light, it also appears to be red. 

    If, however, the red ball is viewed in pure green light, it appears black 

    (all the green is absorbed, and there's no incoming red, so no light is 

    reflected).

 

    - The light on the scene is a combination of global ambient light and light

    produced by each of light sources. The object on the scene do not act as

    a secondary light sources: The reflected light only defines a color of 

    object itself but not involved in lighting of other nearby objects.

    

    - The light source is defined by position, color and attenuation. Optionally,

    the direction (cone) may be specified (normally, it propogates spherically).

    

    - The OpenGL light subsystem assums that is that the normals it has are 

    vectors of length 1.0. However, if, for example, glScalef is used to resize

    primitives, the normals will be also resized. To automatically keep size

    of normals, the following command is used:

        glEnable(GL_NORMALIZE);

    

    Light - Matterial Interaction

    -----------------------------

    So, the color of each vertex on the scene is defined by its color 

    properties and light sources defined on the scene. OpenGL assumes what

    light of each source is consisting of three components: Ambient, Diffuse, 

    Specular. Each of these components may have a color associated (i.e. it is 

    posssible what diffuse and specular compoents had different colors).

    

    Correspondingly materials are characterized by ambient, diffuse and 

    specular reflectances. This defines percentage of light which is reflected 

    by surface. Following formula is used for computations: 

        (RR,RG,RB) = (LR*MR, LG*MG, LB*GB)

    where is Light(LR,LG,LB), Material(MR,MG,MB), Reflected(RR,RG,RB)

 

    Finally, the matterial may define "emmitted" light component. Which is 

    unnafected by light sources and adds directly to the matterial color (still

    it is not shining on other objects on the scene).

 

    Components: 

        Ambient         - just uniformly scattered light, comming from all 

                        directions and reflected equally in all directions

                        [������� ����]

        Diffuse         - the main component of light, it comes directly from

                        the light source and, then it hits surface, is scattered

                        equally in all directions

        Specular        - comes from the light source, and reflected off the 

                        surface in a certain direction [�����]

        Emitted         - originates from object and is unnaffected by any 

                        light source [���� ������� � �������]

 

    * In a real world ambient and diffuse components always have the same 

    colors and define a color of object. Specular reflectance is usually white 

    or gray, so that specular highlights end up being the color of the light 

    source's specular intensity. If you think of a white light shining on a 

    shiny red plastic sphere, most of the sphere appears red, but the shiny 

    highlight is white.

 

    * Light calculations don't take into account the possibility of one object 

    blocking light from another, so shadows aren't automatically created.

    

    Color computation

    -----------------

    All light sources are calculated independently. Then arriving on eyes every-

    thing is just summed up. Everything what is out of [0, 1] range is just 

    clamped to 1.

 

    - General formula is:    

     vertex color = the material emission at that vertex + the global ambient

     light scaled by the material's ambient property at that vertex + the 

     ambient, diffuse, and specular contributions from all the light sources, 

     properly attenuated

 

    - The colors of polygons are interpolated basing on vertex colors as usual.

    

    Lighting Model

    --------------

     glEnable(GL_LIGHTING)                      - Enabling lighting

 

     glLightModelfv(GL_LIGHT_MODEL_AMBIENT, {r,g,b,a})

        Adds constant ambient light to the system. It will be summed with

        ambient light emitted by each of sources.

 

     glLightModeli(GL_LIGHT_MODEL_LOCAL_VIEWER, GL_TRUE/GL_FALSE)

        Defines if viewer is somewhere arround or looking from infinity. It

        affects calculation of highlights produced by specular reflectance.

        When turned off, the position of viewer is not taken into the account

        which significantly optimizes calculation speed, but slightly decreasing

        precision.

 

    glLightModeli(GL_LIGHT_MODEL_TWO_SIDE, GL_TRUE/GL_FALSE);

        Enables special calculation of illumination for backfacing polygons. If

        turned on OpenGL reverses the surface normals for back-facing polygons;

        typically, this means that the surface normals of visible back- and 

        front-facing polygons face the viewer, rather than pointing away. 

        As a result, all polygons are illumnated correctly.

 

 

    Managing light sources

    -----------------------

    - All OpenGL implementations are mandatory supporting at least 8 light 

    sources. The particular implementation may support more but it's not

    required.

    

    The light sources are accessed by 'source ids' whiach are just a constansts

    in the form GL_LIGHT0, GL_LIGHT1, ...

     glEnable(GL_LIGHT0)                        - Enabling first light source

     glLight[if][v](<sid>, <propid>, value)     - Defining source properties

        GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR = {r,g,b,a} - Setting source colors

 

    Light positioning

    -----------------

        There is two kinds of light: directional and positional. Directional,

        means what source of light is somewhere at infinitity and, hence, all

        rays of light are parallel and covering whole scene (Sun).

        The positional light is located near scene and propogates by default in 

        spherical form around this point (Lamp). 

            GL_POSITION={x,y,z,1}       - positional source,  (x,y,z) is point

            GL_POSITION={x,y,z,0}       - directional source, (x,y,z) is vector

        * The positional source location is transformed by the modelview matrix.

        

        * Alternatively, it is possible to configure connical positional light 

        source:

            GL_SPOT_DIRECTION={x,y,z}   - Vector defining the light direction

            GL_SPOT_CUTOFF=[0-90]       - Angle between axis of cone and a ray

                                        along the edge of cone (special value of 

                                        180 disables SPOT feature, default).

            GL_SPOT_EXPONENT=<value>    - Defines how concerated the light is.

                                        The light's intensity is highest in the 

                                        center of the cone. It's attenuated 

                                        toward the edges of the cone by the 

                                        cosine of the angle between the direction 

                                        of the light and the direction from the 

                                        light to the vertex being lighted, raised 

                                        to the power of the spot exponent.

        

        * Light attenuation (for positional sources) is calculated using 

        Constant (C), Linear (L), and Quadratic (Q) attenuation factors using 

        following formula:

            A = O / (C + L*d + Q*d*d)

        where, A - attenuated light intensity, O - light intensity at the source

        and d is distance to the source.

            GL_CONSTANT_ATTENUATION = value             - Factor

            GL_LINEAR_ATTENUATION = value               - Factor

            GL_QUADRATIC_ATTENUATION = value            - Factor

        

        * The colors across the face of a smooth-shaded polygon are determined 

        by the colors calculated for the vertices. Therefore, it's important to

        avoid using large polygons with local lights. Otherwise, if light is

        located near the middle of the polygon, the vertices might be too far 

        away to receive much light, so the whole polygon will look darker than 

        intended. 

        

    Matterial Properties

    --------------------

    glMaterial{if}[v](<face>, prop, value)              - Matterial properties

     face: GL_FRONT, GL_BACK, GL_FRONT_AND_BACK

     setting colors:

        props: GL_AMBIENT, GL_DIFFUSE, GL_AMBIENT_AND_DIFFUSE, GL_SPECULAR, 

        GL_EMISSION

        value: {r,g,b,a}

     setting specular light concentration: the higher the value, the smaller 

     and brighter (more focused) the highlight is:

        prop: GL_SHININESS

        value: exponent [0-128]

    

    glColorMaterial(<face>, <prop>);

        Causes the material properties to track the value of the current color 

        at all times. A change to the current color (using glColor*()) 

        immediately updates the specified material properties.

        Needs enabling: glEnable(GL_COLOR_MATERIAL)

        

        

Blending

========

 Definitions

    - "Source" is front object and "Destination" is back object.

    - (SR,SG,SB,SA) - source color, before blending

    - (DR,DG,DB,DA) - destination color, before blending

    - Blend factors are 4D vectors defining color mixing formula

    

  glEnable(GL_BLEND)                                    - Enable blending

  glBlndFunc(source_factor, destination_factor)         - Defining blend factors

    GL_ZERO                     (0,0,0,0)

    GL_ONE                      (1,1,1,1)

    GL_DST_COLOR                (DR,DG,DB,DA)           - src. factor only

    GL_SRC_COLOR                (SR,SG,SB,SA)           - dst. factor only

    GL_ONE_MINUS_DST_COLOR      (1-DR,1-DG,1-DB,1-DA)   - src. factor only

    GL_ONE_MINUS_SRC_COLOR      (1-SR,1-SG,1-SB,1-SA)   - dst. factor only

    GL_SRC_ALPHA                (SA,SA,SA,SA)

    GL_ONE_MINUS_SRC_ALPHA      (1-SA,1-SA,1-SA,1-SA)

    GL_DST_ALPHA                (DA,DA,DA,DA)

    GL_ONE_MINUS_DST_ALPHA      (1-DA,1-DA,1-DA,1-DA)

    GL_SRC_ALPHA_SATURATE       (f,f,f,1); f=min(SA,1-DA) - src. factor only

  Function:

   Let FS and FD be source and destination factors, then each component of 

   blended color could be calculated using: min(1,FS*S + FD*D)

  Standard Applications:

    glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA)   - transparency

 

 Blending & Z-Buffer:

  - Since the order in which polygons are drawn greatly affects the blended 

  result, you can get different appearances depending on whether you draw the 

  polygons from back to front or from front to back. 

  

  - You also need to consider the effect of the depth buffer when determining 

  the correct order. The solution is to enable depth-buffering but make the 

  depth buffer read-only while drawing the translucent objects. 

   a) First you draw all the opaque objects, with the depth buffer in normal 

   operation. 

   b) Then, you preserve these depth values by making the depth buffer 

   read-only: glDepthMask(GL_FALSE)

   c) When the translucent objects are drawn, their depth values are still 

   compared to the values established by the opaque objects, so they aren't 

   drawn if they're behind the opaque ones. 

   If they're closer to the viewpoint, however, they don't eliminate the opaque 

   objects, since the depth-buffer values can't change. Instead, they're blended

   with the opaque objects. 

 

 - Another consideration is different matterials properties. For example, if

 GL_EMMISION is used to color object and GL_AMBIENT_AND_DIFFUSE is 0. Still,

 alfa value of AMBIENT_AND_DIFFUSE is taken into the consideration while

 blending.

 

Antialiasing

------------

    Since the pixels are not ideal points, most of stright lines are drawn 

 jagged. OpenGL may perform antialising (����������) of these lines to neglect 

 such visual effect. 

 

. In fact, when performing antialiasing, OpenGL calculates a coverage value for each fragment based on the fraction of the pixel square on the screen that it would cover.

OpenGL multiplies the fragment's alpha value by its coverage. You can then use the resulting alpha value to blend the fragment with the corresponding pixel already in the framebuffer.

 

 Enabling:

    a) glEnable(GL_POINT_SMOOTH) 

    b) glEnable(GL_LINE_SMOOTH) 

    c) glEnable(GL_POLYGON_SMOOTH)

    d) Blending should be enabled, with following factors

        for lines: GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA

        polygons in GL_FILL mode: GL_SRC_ALPHA_SATURATE, GL_ONE

 

Fog

---

 Hides objects which are to far away from the viewer.

    glEnable(GL_FOG)

    glFog{if}{v}(<prop>, <value>);

 Properties:

    GL_FOG_MODE = <mode>        - selects mode: GL_LINEAR, GL_EXP, or GL_EXP2

    GL_FOG_DENSITY, GL_FOG_START, GL_FOG_END = <value> - mode parameters

    GL_FOG_COLOR {r,g,b,a}      - sets fog color

 

 formula 

  GL_LINEAR:  f = (end - z) / (end - start)

  GL_EXP: f = exp(-density*z)

  GL_EXP2: f = exp(-(density*z)^2)

  

  Here 'z' is is distance between viewer and fragment center. Then using 'f'

  coefficient the each result color component is calculated by formula:

     f * C + (1 - f ) * F

  here 'C' is unfogged color, and F is color of FOG

 

 

Bitmaps, Images

===============

 Getting / Setting current raster position

    glRasterPos{234}{sifd}{v}(x,y,z,w)          - Sets current raster position

    glGetFloatv(GL_CURRENT_RASTER_POSITION, float v[4]) - Get current position

     - All transformations which are applied to the vertices, are also applied 

     to the raster positions.

 Drawing bitmap:

    glBitmap (width, height, xbo, ybo, xbi, ybi, GLubyte *bitmap)

        - (xbo, ybo) are added to the current raster position and that would

        be lower-left corner of bitmap. (xbi, ybi) are added to the current

        raster position after bitmap is placed.

        - each pixel of bitmap is encoded by bits of bitmap array (there is no

        byte sharing between rows. If width is not multiple of 8, unused bits

        of last byte of each row is just ignored)

        - The bitmap just specifies positions where the pixels are set, the 

        color of pixels are defined by current glColor.

 Drawing/Reading images:

  glReadPixels(x,y,width,height,target,data_type,pixels)

    * Reads pixel data from the framebuffer rectangle whose lower left corner

    is at (x, y) and whose dimensions are width and height, and stores it in 

    the array pointed to by 'pixels'.

  glDrawPixels(width, height, target, data_type, pixels)

    * The pixel rectangle is drawn with its lower left corner at the current 

    raster position.

  glCopyPixels(x,y,width,height,target)

    * Copies pixel data from the framebuffer rectangle whose lower left corner 

    is at (x, y) and whose dimensions are width and height. The data is copied 

    to a new position whose lower left corner is given by the current raster 

    position. 

 

  Targets for Read/Draw:

    GL_RGB, GL_RGBA     - red, green, blue, alpha color components. 3 or 4 

                        <datatype> values are returned (sequentially) per pixel.

    GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA - single <datatype> per pixel

    GL_LUMINANCE

    GL_LUMINANCE_ALPHA  - two <datatype>'s per pixel

    GL_STENCIL_INDEX

    GL_DEPTH_COMPONENT  - z-index of pixel

  Targets for Copy:

    GL_COLOR            - color information

    GL_DEPTH            - z-buffer

    GL_STENCIL          - ?

  Data Types:

    GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT (16 bit), GL_SHORT, 

    GL_UNSIGNED_INT (32bit), GL_INT, GL_FLOAT

    GL_BITMAP - single bits in unsigned 8-bit integers (bit per pixel)

 

 Magnifying or Reducing an Image:

    glPixelZoom(zoomx, zoomy)

        Sets the magnification or reduction factors for pixel-write operations, 

        in the x- and y-dimensions. For example, If they're both 2.0, each 

        image pixel is drawn to 4 screen pixels.

        * Fractional magnification or reduction factors are allowed 

        

 Other commands:

    glPolygonStipple()

    

 Controlling data conversion:

    * glPixelStore*() - defines how pixel data is/should aligned, byte ordered, 

    and other things in that direction.

    * glPixelTransfer*() - defines transformations which would be applied while

    the data is moved from/to framebuffer.

    This includes: scaling, biasing, etc.

    * glPixelMap{isf}v(maptype, mapsize, values) - defines a lookup table which

    is used to modify color componetns, stencil indices, etc. before puting

    them into the memory.

 

 Textures

 --------

 - Texture mapping ensures that all the right things happen as the polygon is 

 transformed and rendered: When the wall is viewed in perspective, for example,

 the bricks decrease in size along with the wall as the wall gets farther from 

 the viewpoint.

 

 

 Using an advanced technique, called mipmapping, you can specify a single texture at many different resolutions; this allows you to avoid mapping a full-resolution image of a brick wall on a wall that's so far away from the viewer that it appears on the screen as a single pixel, for example.

 

 Enabling texturing

    glEnable(GL_TEXTURE_1D)

    glEnable(GL_TEXTURE_2D)

 

 Only single texture could be active at the same time. The basic proceeding is

 following.

    a) Enable texturing, load current texture, set properties.

    b) Apply texture to

 

 glTexImage2D(target, level, components, width, height, border, target_type, data_type, pixels)

    target = GL_TEXTURE_1D, GL_TEXTURE_2D

    level               - texture resolution level (for mipmapping),

                        0 - for single resolution textures

    components          - defines which color components are used for modulating

                        or blanding: 1 - L; 2 - L,A; 3 - R,G,B; 4 - R,G,B,A

                        L - is luminance

    border              - width of border (normally 0)

    width, height       - should be multiple of 2 and should include border

    target_type,data_type,pixels        - the same meaning as for glDrawPixels

                        glPixelStore*() calls are applicable as well

 - Maximal size of texture map depends on OpenGL implementation, but it should

 be at least 64x64 (66x66 with borders).

 

 glTexImage1D(target,level,components,width,border,target_type, data_type, pixels)

    Loading 1D texture, if all variations is in one direction only

 

 glGetTexImage(target, level, components, data_type, GLvoid *img)

    Get's currently set texture image

 

 glTexParameterf(target, prop, val)

    GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T = <mod> - defines computation to be

    applied if pixel outside of texture is requested

    'S' - defines how to extend texture horizontally and 'T' - vertically

        GL_REPEAT       - the texture is continiously repeating

        GL_CLAMP        - the texture border colors are used outside of texture

                    if texture have no border defined, GL_TEXTURE_BORDER_COLOR

                    is used (see next property, in this function description)

 

    [ABC]       [ABC][ABC][ABC]         [ABC]]]]]]]]]]]

    [DEF]       [DEF][DEF][DEF]         [DEF]]]]]]]]]]]

    [GIJ]       [GIJ][GIJ][GIJ]         [GIJ]]]]]]]]]]]

                    GL_REPEAT               GL_CLAMP

 

    GL_TEXTURE_BORDER_COLOR = {r,b,a}   - defines default color for GL_CLAMP

    GL_TEXTURE_MAG_FILTER = <filter>    - defines magnification filter

        GL_NEAREST (speed), GL_LINEAR (quality)

    GL_TEXTURE_MIN_FILTER = <filter>    - defines minification filter

        L_NEAREST, GL_LINEAR (mimaps are not used)

        GL_NEAREST_MIPMAP_NEAREST, GL_NEAREST_MIPMAP_LINEAR, 

        GL_LINEAR_MIPMAP_NEAREST, or GL_LINEAR_MIPMAP_LINEAR

    

 glTexEnv{if}{v}(target, prop, value)

    targets: GL_TEXTURE_ENV

    GL_TEXTURE_ENV_MODE = <mode>        - blending mode

        GL_DECAL                - texture is just drawn on the polygon,

                                no blending is performed (original (polygon)

                                alfa is used if 3 component texture is specifed)

        GL_MODULATE             - The original (polygon) color components are

                                multiplied by corespondent texture components.

                                In 1 and 2 component mode, the luminance is used 

                                in place of all color components, but alpha.

        GL_BLEND                COLOR = (1-L)*C + L*Ce, ALPHA = At*A

                                    L - texture luminance

                                    At - texture alpha or 1 (if not specified)

                                    Ce - color component assigned by call to

                                        GL_TEXTURE_ENV_COMPONENT

                                    C - original/untextured color

                                    A - original/untextured alpha

                                - only applicable to luminace texture modes

    GL_TEXTURE_ENV_COLOR = {r,g,b,a} - defines color to be used in GL_BLEND

                                blending mode

 

 glTexCoords{234}{sif}[v](s,t,r,q) - assigns texture coordinates, see below

    S,T,R,Q is standard terminology for texture coordinates and are used in 

    place of X,Y,Z,W in order to make it easy to distinguish between texture 

    and scene coordinates.

 

 Applying textures

 -----------------

    glTexCoord2f(s, q); glVertex3f(x,y,z) - sets correspondance between coors.

    of texture (s, q) and vertex. Such correspondance should be specified for

    all vertices of polygon.

    - If floating-point function call is used, then the whole texture is mapped

    to the [0,1]. This means [0,0] is address of left-botom corner of texture 

    and [1,1] - top right corner. However, if integer call is used, then the

    texture coordinates are not translated: [0,0] again is left-bottom corner,

    and right-up depends on texture height and width.

    - In exactly the same way that colors are interpolated between two vertices 

    of shaded polygons and lines, texture coordinates are linearly interpolated

    between vertices. 

 

 Auto-computed coordinates

 -------------------------

    glTexGen{ifd}{v}(coord, prop, value)

        coord: GL_S, GL_T, GL_R, GL_Q

        GL_TEXTURE_GEN_MODE = <mode>    - defines coordinate generation alg.

            GL_OBJECT_LINEAR: coordinate_value = p1*x + p2*y + p3*z + p4*w

                p1,p2,p3,p4 are defined by the GL_OBJECT_PLANE call, below

            GL_PLANE_LINEAR: coordinate_value = p1'*x + p2'*y + p3'*z + p4'*w

                (p1',p2',p3',p4') = (p1,p2,p3,p4)M^(-1), where M is MODELVIEW

                transformation matrix and p1,p2,p3,p4 are defined by the

                GL_EYE_PALNE call, below

                Similliar to the GL_OBJECT_LINEAR, but the x,y,z,w are supplied

                after applying MODELVIEW transformations (i.e. calculations 

                would be performed relative to the eye's coordinate system)

            GL_SPHERE_MAP

                Used to simulate reflections of shiny objects. Assumes that the

                 items in the environment are far away compared to the surfaces

                 of the shiny object. Hence, to find the color of a point on 

                 the surface, take the ray from the eye to the surface, and 

                 reflect the ray off the surface. The direction of the reflected 

                 ray completely determines the color to be painted there. 

                 Encoding a color for each direction on a flat texture map is 

                 equivalent to putting a polished perfect sphere in the middle 

                 of the environment and taking a picture of it with a camera that

                 has a lens with a very long focal length placed far away.

        GL_OBJECT_PLANE = {p1,p2,p3,p4} - parameters to coord. generation func.

        GL_EYE_PLANE = {p1,p2,p3,p4}    - parameters to coord. generation func.

 

    - GL_OBJECT_LINEAR, GL_PLANE_LINEAR is intended to draw contours using

    texture (normally 1D) and GL_SPHERE_MAP to simulate reflections.

 

    The coordinate generation should be enabled:

        glEnable(GL_TEXTURE_GEN_S);

        glEnable(GL_TEXTURE_GEN_T);

        glEnable(GL_TEXTURE_GEN_R);

        glEnable(GL_TEXTURE_GEN_Q);

 

 Mipmapping

 ----------

    - Textured objects can be viewed, like any other objects in a scene, at 

 different distances from the viewpoint. As a textured object moves farther 

 from the viewpoint, the texture map must decrease in size along with the size 

 of the projected image. Therefore, OpenGL has to filter the texture map down 

 to an appropriate size for mapping onto the object, without introducing 

 visually disturbing artifacts. To avoid such artifacts, you can specify a 

 series of prefiltered texture maps of decreasing resolutions, called mipmaps. 

    - Mipmapping requires some extra computation, but, when it's not used, 

 textures that are mapped onto smaller objects might shimmer and flash as the 

 objects move.

    - To use mipmapping, you provide all sizes of your texture in powers of 2 

 between the largest size and a 1x1 map. For example, if the highest-resolution

 map is 64x16, you must also provide maps of size: 

     32x8, 16x4, 8x2, 4x1, 2x1, and 1x1. 

    - Functions:

  * gluBuild1DMipmaps() and gluBuild2DMipmaps() functions from OpenGL Utility

  library may be used to construct pyramid of mipmaps from the original 

  (largest) image and to load them using glTexImage calls.

  * glTexImage1D, glTexImage2D - are called to load sequence of mipmaps. 

  Level = 0 should be used for the largest image, and, then, sequentially 

  increase by one for each smaller mipmap.

 

 Texture Transformations

 -----------------------

 Just as a model coordinates are transformed by a matrix before being rendered,

 texture coordinates are multiplied by a 4x4 matrix before any texture mapping 

 occurs. By default, the texture matrix is the identity, so the texture coords.

 (explicitly assigned or auto-generated) remain unchanged. 

 By modifying the texture matrix while redrawing an object, however, it is

 possible to get various effects, like: texture sliding over the surface, 

 rotation, stretching and shrinking, etc.

    glMatrixMode(GL_TEXTURE);

    glRotate(...); 

    ...

 

 Notes

 -----

 - In some cases, it isn't obvious whether magnification or minification is 

 called for. If the mipmap needs to be stretched (or shrunk) in both the x and 

 y directions, then magnification (or minification) is needed. If the mipmap 

 needs to be stretched in one direction and shrunk in the other, however, 

 OpenGL makes a choice between magnification and minification that in most 

 cases gives the best result possible. It's best to try to avoid these 

 situations by using texture coordinates that map without such distortion;

 

 

 Limiting draw area

 ------------------

    glStencilFunc(test, refval, mask)

    test: GL_NEVER, GL_LESS, GL_LEQUAL, GL_GREATER, GL_GEQUAL, GL_EQUAL, 

    GL_NOTEQUAL, and GL_ALWAYS

    refval: reference value, to compare with the data in the stencil buffer

    mask: is bitwise ANDed with both the reference value and the stored 

    stencil value

 

  You fill the stencil buffer, then render geometry and images, usingthe 

  stencil planes to mask out portions of the screen.  Stenciling is typically 

  usedin multipass rendering algorithms to achieve specialeffects, such as 

  decals, outlining, and constructive solid geometry rendering.

 

  Enabling: glEnable(GL_STENCIL_TEST)

  

  Example: GL_LEQUAL test, a pixel is drawn if (refval&mask)<(stencil&mask)

  

 - It is possible to modify data in stencil buffer depending on fail-or-success

 of test:

  void glStencilOp(GLenum fail, GLenum zfail, GLenum zpass)

    'fail' is applied if stencil test is failed

    'zfail' is applied if stencil test is passed and depth test is failed

    'zpass' is applied if both stencil and depth test are passed

   GL_KEEP, GL_ZERO, GL_REPLACE (with refval), GL_INCR, GL_DECR, or 

   GL_INVERT (bitwise)

 

 - Filling stencil buffer

    a) set stencil test to GL_ALWAYS

    b) set zpass to GL_REPLACE

    c) In the loop

        1) set refval

        2) draw into the color area where this refval should be used

  

 - glScissor(GLint x, GLint y, GLsizei width, GLsizei height)

    another to define the only (rectangular) area where the drawing is allowed

  

  Enabling: glEnable(GL_SCISSOR)

  

    

Frame buffers

=============

 * color buffers - there could be multiple color buffers. One is just contains

 color information for display, others may be used for image preparation, etc.

 * depth (z) buffer - used to skip objects beyond the scene

 * stencil buffer - restrict drawing to certain portions of the screen

 * accumulation buffer - is storing color information and is used to accumulate

 series of images to produce (after needed amount of images received) super-

 sampled image

 

 Clearing buffers (reinitializing to default values)

  - setting default values

    glClearColor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha); 

    glClearDepth(GLclampd depth); 

    glClearStencil(GLint s);

    glClearAccum(GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha);

 - issuing clear command

    glClear(GLbitfield mask)

        mask is combination of  GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, 

        GL_STENCIL_BUFFER_BIT, and GL_ACCUM_BUFFER_BIT bits

 

 Selecting current color buffers 

  glDrawBuffer(<buffer>)        - here the draw commands are sent

  glReadBuffer(<buffer>)        - the read commands are accessing this buffer

    GL_FRONT (on display), GL_BACK (if double buffering is supported buffer where

    we perepare data), sterescopic buffers (GL_RIGHT, GL_LEFT, GL_FRONT_RIGHT,

    GL_FRONT_LEFT, GL_BACK_RIGHT, GL_BACK_LEFT), auxiliary buffers (GL_AUX<i>)

    GL_FRONT_AND_BACK, GL_NONE

 

 Masking data prior to writing it to the buffers

    glColorMask(GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha); 

    glDepthMask(GLboolean flag)

    glStencilMask(GLuint mask)

    - boolean flags just enables-or-disable writing, interger value (for stencil

    mask) allows to enable/disable wrtiting to the certain bits.

 

 Setting test functions

    glAlphaFunc()

    glDepthFunc(GLenum func);

    glStencilFunc(GLenum func, GLint ref, GLuint mask)

    functions: GL_NEVER, GL_ALWAYS, GL_LESS, GL_LEQUAL, GL_EQUAL, GL_GEQUAL, 

    GL_GREATER, or GL_NOTEQUAL

    

 Usage of accomulation buffer

    OpenGL graphics operations don't write directly into the accumulation 

    buffer. Typically, a series of images is generated in one of the standard 

    color buffers, and these are accumulated, one at a time, into the 

    accumulation buffer. When the accumulation is finished, the result is 

    copied back into a color buffer for viewing. To reduce rounding errors, 

    the accumulation buffer may have higher precision (more bits per color) 

    than the standard color buffers.

    

    glAccum(<operation>, <value>)

    operations:

     GL_ACCUM - reads data from the current ReadBuffer, multiplies the R, G, B,

     and Alpha values by 'value', and adds the result to the accumulation buffer

     GL_LOAD - the same but replaces values currently in the acc. buffer

     GL_RETURN - takes values from the accumulation buffer, multiplies them by 

     'value', and places the result in the current DrawBuffer

     GL_ADD, GL_MULT - add/multiply the value of each pixel in the accumulation 

     buffer by value

     

    Example usage:

    * Antialising: loop 'n' times through code that draws image in a slightly 

    different position, accumulating the data with glAccum(GL_ACCUM, 1.0/n)

    and then get result with: glAccum(GL_RETURN, 1.0)

    

 

Rendering Modes

===============

 glRenderMode(<mode>)

    GL_RENDER - Default mode, rendering scene in the frame buffer

    GL_SELECT - Mode to find out objects near the specified screen location

                + glSelectBuffer - should be called prior to setting this mode

    GL_FEEDBACK - Mode to perform calculations and get back results, without

                actually rendering them

                + glFeedbackBuffer - should be called prior to setting this mode

 

 - glRenderMode is returning amount of records placed in the Selection or

 Feedback buffer if called while OpenGL is in selection or feedback modes.

 

 Enumerating Objects (only working in selection mode)

 -------------------

    glInitNames()       - Clearing the name stack

 

    glLoadName(1);      - Setting ID of object to be rendered

    ... rendering primitives ...

 

    glLoadName(2);      - Setting ID of object to be rendered

    ... rendering primitives ...

    

    

    - Normally, all work is perfomed on the stack of objects, not just a single

    name. This allows to address items better, for example, the top object

    is robot, then goes hand of robot, and at the head of stack is finger

    of robot. The stack is used like that:

    

    glPushName(<id>)            - Setting ID of objects to render

      ... render primitives

    glPopName()                 - Restoring old ID

    

    The stack depth is  at least 64 different objects. Actual depth could be 

    obtained with glGetIntegerv(GL_NAME_STACK_DEPTH)

 

 

 Selection Mode

 --------------

    In the selection mode, the OpenGL engine instead of drawing primitives will

    return a list of objects (enumerated) which are visible in the current 

    viewpoint. The full name stack of

 

    * glSelectBuffer(GLsizei size, GLuint *buffer) - defines a buffer where the

    list of objects would be returned. Should be set before entering selection

    mode ('size' defines size of buffer in GLuint elements). 

    

        - Depth of name stack when hit occured [GLuint]

        - Minimum z-index of objects in view [GLuint]                 /|    

        - Maximum z-index of objects in view [GLuint]                / |far  

          * The z-coord of all objects is mapped to [0,1] where    ./| |plan

            0 - corresponds to the depth of near projection plane   \| |    

            1 - correspnds to the depth of far projection plane  near\ |

          then the resulting values are multiplied by MAXINT and  plan\|    

          minimum and maxumu is stored in provided buffer.

          * This allows to find closest and farest visible object.

        - The names stack, bottommost object first [array of GLuint]

     

 

    * Usage:

        selectBuf = malloc(BUFSIZE*sizeof(GLuint));     - Allocating buffer

        glSelectBuffer(BUFSIZE, selectBuf);     - Passing it to OpneGL

        glRenderMode(GL_SELECT);                - Entering selection mode

        ... Rendering objects ....

        

        hits = glRenderMode (GL_RENDER);        - Switching to rendering mode

                                        and obtaining number of records which 

                                        are placed in the selection buffer

 

        ... Processing hits in selectBuf (a selectBuf is only acccesable 

        after that point) ...

        

    - If only object near to mouse position (or whatever) are of interest, the

        gluPickMatrix(x,y,width,height, GLint viewport[4])

    may be ised to limit selection area.

        x,y - center of region

        width,height - rectangle dimensions

        viewport - indicates the current viewport boundaries and can be obtained

        by calling: glGetIntegerv(GL_VIEWPORT, GLint *viewport).

    This is done during configuration of Projection matrix:

        glLoadIdentity();

        gluPickMatrix();

        glFrustum();;

        ... Draw Commands ...

        

 Feedback Mode

 -------------

    In the selection mode, the OpenGL engine instead of rendering primitives 

    just applies all specified transformations and return information about

    resulting values.

    The information is returned about

        a) All primitves (vertix by vertix) defined in the glBegin, glEnd 

        sections

        b) Pixel regions created with 'glBitmap', 'glCopyPixels' calls

        c) Pass through markers specified using 'glPassThrough' function

 

    - Feedback occurs after transformations, lighting, polygon culling, and 

    interpretation of polygons by glPolygonMode(). It might also occur after 

    polygons with more than three edges are broken up into triangles (if your 

    particular OpenGL implementation renders polygons by performing this 

    decomposition).

 

 glFeedbackBuffer(size, type, GLfloat *buffer) 

    size - size of buffer in GLfloat's

    type - specifies which information will be returned in buffer for each 

           vertex:

            GL_2D: x,y [2]

            GL_3D: x,y,z [3]

            GL_3D_COLOR: x,y,z, r,g,b,a [7]

            GL_3D_COLOR_TEXTURE: x,y,z, r,g,b,a, s,t,r,q [11]

            GL_4D_COLOR_TEXTURE: x,y,z,w, r,g,b,a, s,t,r,q [12]

    buffer - allocated memory to return results in. The results are stored

    record by record. Each record consists of

        a) Primitive type [GLfloat]: 

            - GL_POINT_TOKEN                            - single vertix

            - GL_LINE_TOKEN, GL_LINE_RESET_TOKEN,       - two vertices

            - GL_POLYGON_TOKEN,                 - vertix count [GLfloat],followed 

                                                by appropriate number of vertices

            - GL_BITMAP_TOKEN, GL_DRAW_PIXEL_TOKEN, GL_COPY_PIXEL_TOKEN,

                                        - single vertix describing bitmap area,

                                        I think it is vertex on the left-bottom

                                        corner, but have not checked.

                

            - GL_PASS_THROUGH_TOKEN     - only a single GLfloat value, passed by 

                                        glPassThrough command, is stored in the 

                                        buffer for this record

 

        b) The record data, normally describing all vertices of primitive. So,

        the size of record is depending on feedback type and the primitive 

        described by record. For example, for GL_LINE_TOKEN primitive and GL_3D

        feedback type the 6 values (x1,y1,z1), (x2,y2,z2) reporting coordinates 

        of begining and end of the line will be stored in the buffer.

    

    - The primitives which are filtered out of view (by z-buffer, etc.) is not

    reported and not returned.

        

 glPassThrough(GLfloat token)

    This is quite difficult to distinguish the originating primitives of 

    records in feedback buffer. The passthrough markers are inteneded to

    help.

    - Should not be called within glBegin/glEnd block

 

    

 Usage:

        feedBuf = malloc(BUFSIZE*sizeof(GLfloat));      - Allocating buffer

        glFeedbackBuffer(BUFSIZE, <mode>, feedBuf);     - Passing it to OpneGL

        glRenderMode(GL_FEEDBACK);              - Entering selection mode

        ... Rendering objects ....

        

        recs = glRenderMode (GL_RENDER);        - Switching to rendering mode

                                        and obtaining number of records which 

                                        are placed in the selection buffer

 

        ... Processing information in feedBuf (a feedBuf is only acccesable 

        after that point) ...

 

    

Performance

===========

 glHint(<target>, <hint>)       - hints OpenGL engine about desired quality / 

                                performance tradeoff 

 Antialising: GL_POINT_SMOOTH_HINT, GL_LINE_SMOOTH_HINT, GL_POLYGON_SMOOTH_HINT

 Fog: GL_FOG_HINT

 Perespective: GL_PERSPECTIVE_CORRECTION_HINT

 Tradeoffs: GL_NICEST, GL_FASTEST, GL_DONT_CARE

 

 

Misc

====

 1. Skipps processing of front or back faces. Just nothing is drawn for 

 correspondent face

    glEnable(GL_CULL_FACE);

    glCullFace(GL_BACK|GL_FRONT)

 

 2. Redefining front and back faces

    glFrontFace(GL_CW|GL_CCW);

        CW - clockwise

        CCW - counter clockwise (default)