From 89cfab41fc41637a804b29fb582a7dc406f503d8 Mon Sep 17 00:00:00 2001
From: dcnieho
Date: Mon, 2 Jun 2014 13:25:25 +0000
Subject: [PATCH] updated api doc
git-svn-id: https://svn.code.sf.net/p/freeglut/code/trunk@1693 7f0cb862-5218-0410-a997-914c9d46530a
---
freeglut/web-src/docs/api.php | 103 ++++++++++++++++++++++++----------
1 file changed, 74 insertions(+), 29 deletions(-)
diff --git a/freeglut/web-src/docs/api.php b/freeglut/web-src/docs/api.php
index fba7fd4..5a7e1de 100644
--- a/freeglut/web-src/docs/api.php
+++ b/freeglut/web-src/docs/api.php
@@ -200,6 +200,8 @@ will thus not work with the currently available 2.8.1 release.
glutWireRhombicDodecahedron, glutSolidRhombicDodecahedron
glutWireTeapot, glutSolidTeapot, glutWireTeacup,
glutSolidTeacup, glutWireTeaspoon, glutSolidTeaspoon
+ glutSetVertexAttribCoord3, glutSetVertexAttribNormal,
+ glutSetVertexAttribTexCoord2
Game Mode Functions
@@ -378,10 +380,10 @@ of the new callbacks are listed in the GLUT Version 4 "glut.h" header file
but did not make it into the documentation. The new callbacks consist
of regular and special key release callbacks, a joystick callback, a menu
state callback (with one argument, distinct from the menu status callback
-which has three arguments), and a window status callback
- (also with one argument). Unsupported callbacks are the two Tablet
-callbacks. If the user has a need for an unsupported callback he should
-contact the freeglut development team.
+which has three arguments), a window status callback (also with one
+argument), and a window position callback. Unsupported callbacks are
+the two Tablet callbacks. If the user has a need for an unsupported
+callback he should contact the freeglut development team.
3.4.5 String Rendering
@@ -397,7 +399,17 @@ pixels for bitmapped fonts and in OpenGL units for the stroke fonts.
Two functions have been added to render a wireframe and a solid rhombic
-dodecahedron.
+dodecahedron. Furthermore, solid and wireframe versions of the original
+teacup and teaspoon that accompanied the famous Newell teapot. As these
+geometry functions are often used for teaching purposes,
+glutSetOption(GLUT_GEOMETRY_VISUALIZE_NORMALS,true/false) can
+now be used to visualize the normal vectors for each vertex. Lastly, to
+support drawing these objects with shaders, three functions have been
+added with which users can provide the addresses of the Coordinate,
+Normal and Texture Coordinate vertex attribs:
+glutSetVertexAttribCoord3, glutSetVertexAttribNormal,
+and glutSetVertexAttribTexCoord2. Texture coordinates are only
+generated for the teaset.
3.4.7 Extension Function Queries
@@ -481,8 +493,8 @@ glutInitDisplayString support is limited: any of the tokens recognized
by GLUT are also recognized by FreeGLUT, but any statements with
comparators cannot (yet: do help develop
this!) be handled. Any spec (comparator and value) after the token
-is ignored. Many of these values can however be set with glutSetOption
-for now however...
+is ignored. However, many of these values can be set with glutSetOption
+for now...
4.5 glutInitErrorFunc, glutInitWarningFunc
@@ -954,8 +966,12 @@ callback; programs with multiple windows or menus must explicitly set the
and not rely on its current setting.
The amount of computation and rendering done in an idle
callback should be minimized to avoid affecting the program's interactive
- response. In general, no more than a single frame of rendering should
- be done in a single invocation of an idle callback.
+response. In general, no more than a single frame of rendering should
+be done in a single invocation of an idle callback. Note that no actual
+drawing to the framebuffer should be done from the idle callback, this
+is not supported. While it might work on some platforms, it will not on
+others or might stop working in the future. Drawing should be done in
+the glutDisplayFunc callback.
Calling glutIdleFunc with a NULL argument
disables the call to an idle callback.
@@ -994,7 +1010,7 @@ repositioned/moved programatically or by the user.
Usage
void glutPositionFunc ( void
-(* callback)( int x, int y) );
+(* func)( int x, int y) );
Description
@@ -2022,7 +2038,7 @@ are designed such that all characters have (nominally) the same height.
15. Geometric Object Rendering Functions
-Freeglut includes eighteen routines for generating
+Freeglut includes twenty two routines for generating
easily-recognizable 3-d geometric objects. These routines are
effectively the same ones that are included in the GLUT library, and
reflect the functionality available in the aux toolkit described
@@ -2036,7 +2052,10 @@ note that depth testing (GL_LESS) should be enabled for the correct
drawing of the nonconvex objects, i.e., the glutTorus,
glutSierpinskiSponge, glutTeapot, glutTeacup and glutTeaspoon.
Also see the GLUT_GEOMETRY_VISUALIZE_NORMALS option that can be
-set with glutSetOption.
+set with glutSetOption. Lastly, see
+glutSetVertexAttribCoord3, glutSetVertexAttribNormal,
+and glutSetVertexAttribTexCoord2 if you wish to use these
+objects with shaders.
15.1 glutWireSphere, glutSolidSphere
@@ -2395,6 +2414,32 @@ should use:
GLUT only has the teapot and misses the rest of the teaset.
+15.12 glutSetVertexAttribCoord3, glutSetVertexAttribNormal, glutSetVertexAttribTexCoord2
+
+To draw shapes with shaders (OpenGL 2 and later), one need to upload
+vertices and associated normal vectors and texture coordinates to
+vertex attributes of your shaders. Use these functions to set the
+indices (addresses) of the vertex attributes in your currently active
+shaders before calling the above geometry functions, and FreeGLUT
+will upload the object geometry there. Texture coordinates are only
+generated for the teapot, teacup and teaspoon.
+
+
+Definition
+
+
+void glutSetVertexAttribCoord3 (GLint attrib);
+void glutSetVertexAttribNormal (GLint attrib);
+void glutSetVertexAttribTexCoord2(GLint attrib);
+
+Arguments
+attrib The index (address) of the vertex
+attribute
+
+Changes From GLUT
+
+GLUT does not include these functions.
+
16. Game Mode Functions
16.1 glutGameModeString
@@ -2485,16 +2530,16 @@ glutStopVideoResizing
18.2 glutCopyColormap
-MultiTouch Functions
+19. MultiTouch Functions
MultiTouch callbacks are used to handle environments with multiple
inputs, such as a multi-touch screen, multi-touch touchpad, or
multiple mouses.
-glutMultiEntryFunc ← id, GLUT_ENTERED|GLUT_LEFT
-glutMultiButtonFunc ← id, x, y, button, GLUT_DOWN|GLUT_UP
-glutMultiMotionFunc ← id, x, y
-glutMultiPassiveFunc ← id, x, y
+19.1 glutMultiEntryFunc ← id, GLUT_ENTERED|GLUT_LEFT
+19.2 glutMultiButtonFunc ← id, x, y, button, GLUT_DOWN|GLUT_UP
+19.3 glutMultiMotionFunc ← id, x, y
+19.4 glutMultiPassiveFunc ← id, x, y
These functions work like their non-multi variants, with an additional
'deviceid' parameter describing the current input device (mouse or
@@ -2532,7 +2577,7 @@ desirable to get the device id as well in the following situations:
considering
whether/how to implement it.
-Mobile Functions
+20. Mobile Functions
These new callbacks were added:
@@ -2556,9 +2601,9 @@ the Android page.
BlackBerry 10/BlackBerry PlayBook
-19. Miscellaneous Functions
+21. Miscellaneous Functions
-19.1 glutSetKeyRepeat, glutIgnoreKeyRepeat
+21.1 glutSetKeyRepeat, glutIgnoreKeyRepeat
The glutSetKeyRepeat and glutIgnoreKeyRepeat functions
@@ -2598,11 +2643,11 @@ the windows for which you don't want it.
glutSetKeyRepeat, but FreeGLUT's behavior should conform on all
platforms to GLUT's behavior on X11.
-19.2 glutForceJoystickFunc
+21.2 glutForceJoystickFunc
-19.3 glutReportErrors
+21.3 glutReportErrors
-20. Usage Notes
+22. Usage Notes
The following environment variables
are recognized by freeglut:
@@ -2622,16 +2667,16 @@ Furthermore, on windows, there is a resource file identifier GLUT_ICON
that you can specify for your executable file. It specifies the icon
that goes in the upper left-hand corner of the freeglut windows.
Your application's resource file should contain the line:
-GLUT_ICON ICON DISCARDABLE "icon.ico"
, where
+GLUT_ICON ICON DISCARDABLE "icon.ico"
where
icon.ico is the filename of your icon. The One demo includes such an
icon as an example.
-21. Implementation Notes
+21.1 Implementation Notes
-22. GLUT State
+21.2 GLUT State
-23. "freeglut.h" Header File
+21.3 "freeglut.h" Header File
Application programmers who are porting their GLUT programs to freeglut may continue
@@ -2673,8 +2718,8 @@ if (glutGet(GLUT_VERSION) < 20001) {
}
-
24. References
+21.4 References
-25. Index
+21.5 Index