Branch: Tag:

2002-06-28

2002-06-28 16:53:12 by Martin Nilsson <mani@lysator.liu.se>

AutoDoc

Rev: lib/modules/GLU.pmod:1.11

1:   /* -  * $Id: GLU.pmod,v 1.10 2002/02/13 02:59:53 nilsson Exp $ +  * $Id: GLU.pmod,v 1.11 2002/06/28 16:53:12 nilsson Exp $    *    * GL Utilities module.    */      #pike __REAL_VERSION__    -  + //! The GL Utilities module is a partial implementation of the + //! GLU library. This module only contains functions that someone + //! at some point actually needed to get his work done. If you + //! need a GLU function that isn't in here, copy the C code from + //! the GLU library (Mesa was used last time), tweak it so that + //! it compiles as Pike code and then check it in into the CVS. +    #if constant(GL.glGet)   import GL; - import Math; +       #ifndef M_PI   #define M_PI 3.1415926536   #endif    - //! @fixme - //! Document this function. + //! @decl void gluLookAt(float eyex, float eyey, float eyez,@ + //! float centerx, float centery, float centerz,@ + //! float upx, float upy, float upz) + //! @decl void gluLookAt(Math.Matrix eye, Math.Matrix center, Math.Matrix up) + //! + //! gluLookAt creates a viewing matrix derived from an @[eye] point, + //! a reference point indicating the @[center] of the scene, and an + //! @[up] vector. The matrix maps the reference point to the negative + //! z axis and the eye point to the origin, so that, when a typical + //! projection matrix is used, the center of the scene maps to the + //! center of the viewport. Similarly, the direction described by the + //! up vector projected onto the viewing plane is mapped to the positive + //! y axis so that it points upward in the viewport. The up vector must + //! not be parallel to the line of sight from the eye to the reference + //! point. + //! + //! The matrix generated by gluLookAt postmultiplies the current matrix. + //! + //! The relation between the matrix objects and the float values are + //! @code{ Math.Matrix eye = Math.Matrix( ({ eyex, eyey, eyez }) ); @} + //! + //! @seealso + //! @[GL.glFrustum], @[gluPerspective]   void gluLookAt(float|object eye,float|object center,float|object up,    float ... old_api)   { -  Matrix x,y,z; +  Math.Matrix x,y,z;    float mag;       if (!objectp(eye))    { -  eye=Matrix( ({eye,center,up }) ); -  center=Matrix( old_api[..2] ); -  up=Matrix( old_api[3..5] ); +  eye=Math.Matrix( ({eye,center,up }) ); +  center=Math.Matrix( old_api[..2] ); +  up=Math.Matrix( old_api[3..5] );    }       /* Make rotation matrix */
55:    glTranslate( ((array)(-1*eye))[0] );   }    + //! gluOrtho2D sets up a two-dimensional orthographic viewing region. + //! This is equivalent to calling + //! @code{ glOrtho(left, right, bottom, top, -1.0, 1.0); @}   //! @fixme - //! Document this function. + //! The GLU manual says glOrtho(a,b,c,d, 0, 1). + //! @seealso + //! @[GL.glOrtho], @[gluPerspective]   void gluOrtho2D(float left, float right,    float bottom, float top)   {    glOrtho( left, right, bottom, top, -1.0, 1.0 );   }    - //! @fixme - //! Document this function. + //! gluPerspective specifies a viewing frustum into the world coordinate + //! system. In general, the aspect ratio in gluPerspective should match + //! the aspect ratio of the associated viewport. For example, aspect = + //! 2.0 means the viewer's angle of view is twice as wide in x as it is + //! in y. If the viewport is twice as wide as it is tall, it displays the + //! image without distortion. + //! + //! The matrix generated by gluPerspective is multipled by the current + //! matrix, just as if @[GL.glMultMatrix] were called with the generated + //! matrix. To load the perspective matrix onto the current matrix stack + //! instead, precede the call to gluPerspective with a call to + //! @[GL.glLoadIdentity].   void gluPerspective(float fovy, float aspect,    float zNear, float zFar)   {
79:    glFrustum( xmin, xmax, ymin, ymax, zNear, zFar );   }    + //! gluPickMatrix creates a projection matrix that can be used to + //! restrict drawing to a small region of the viewport. This is + //! typically useful to determine what objects are being drawn + //! near the cursor. Use gluPickMatrix to restrict drawing to a + //! small region around the cursor. Then, enter selection mode + //! (with @[GL.glRenderMode] and rerender the scene. All primitives + //! that would have been drawn near the cursor are identified and + //! stored in the selection buffer. + //! + //! The matrix created by gluPickMatrix is multiplied by the current + //! matrix just as if @[GL.glMultMatrix] is called with the generated + //! matrix. To effectively use the generated pick matrix for picking, + //! first call @[GL.glLoadIdentity] to load an identity matrix onto + //! the perspective matrix stack. Then call gluPickMatrix, and + //! finally, call a command (such as @[gluPerspective]) to multiply + //! the perspective matrix by the pick matrix. + //! + //! When using gluPickMatrix to pick NURBS, be careful to turn off the + //! NURBS property GLU_AUTO_LOAD_MATRIX. If GLU_AUTO_LOAD_MATRIX is not + //! turned off, then any NURBS surface rendered is subdivided + //! differently with the pick matrix than the way it was subdivided + //! without the pick matrix. + //! + //! @param viewport + //! The viewport is an array with four integers. + //!   //! @fixme - //! Document this function. + //! Does the NURB remark apply? + //! + //! @seealso + //! @[GL.glGet], @[gluLoadIdentity], @[gluMultMatrix], @[gluRenderMode], + //! @[gluPerspective]   void gluPickMatrix(float x, float y,    float width, float height,    array(int) viewport)
115:   #undef M   }    - //! @fixme - //! Document this function. + //! gluProject transforms the specified object coordinates into window + //! coordinates using @[model], @[proj], and @[viewport]. The result is + //! returned in a three valued array.   array(float) gluProject(float objx, float objy,    float objz, array(float) model,    array(float) proj, array(int) viewport)