path: root/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/feedbackbuffer.gl

_C_ License Applicability. Except to the extent portions of this file are
_C_ made subject to an alternative license as permitted in the SGI Free
_C_ Software License B, Version 1.1 (the "License"), the contents of this
_C_ file are subject only to the provisions of the License. You may not use
_C_ this file except in compliance with the License. You may obtain a copy
_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
_C_ 
_C_ http://oss.sgi.com/projects/FreeB
_C_ 
_C_ Note that, as provided in the License, the Software is distributed on an
_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
_C_ 
_C_ Original Code. The Original Code is: OpenGL Sample Implementation,
_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics,
_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc.
_C_ Copyright in any portions created by third parties is as indicated
_C_ elsewhere herein. All Rights Reserved.
_C_ 
_C_ Additional Notice Provisions: The application programming interfaces
_C_ established by SGI in conjunction with the Original Code are The
_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released
_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version
_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X
_C_ Window System(R) (Version 1.3), released October 19, 1998. This software
_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation
_C_ published by SGI, but has not been independently verified as being
_C_ compliant with the OpenGL(R) version 1.2.1 Specification.
_C_
_C_ The first character in this file must be an '_'!
_C_ Anything on a line after _C_ is ignored
_define(_filters,tbl|eqn)_C_
_C_      eqn is automatically replaced with neqn for nroff
_header(FeedbackBuffer,controls feedback mode)
_names(FeedbackBuffer)
.EQ
delim $$
.EN
.SH PARAMETERS
_phead(_param1)
Specifies the maximum number of values that can be written into _param3.
_phead(_param2) 
Specifies a symbolic constant that describes the information
that will be returned for each vertex.
_const(2D),
_const(3D),
_const(3D_COLOR),
_const(3D_COLOR_TEXTURE), and
_const(4D_COLOR_TEXTURE) are accepted.
_phead(_param3)
Returns the feedback data.
.SH DESCRIPTION
The _cmnd function controls feedback.
Feedback, like selection, is a GL mode.
The mode is selected by calling
_cmnd(RenderMode) with _const(FEEDBACK).
When the GL is in feedback mode,
no pixels are produced by rasterization.
Instead, information about primitives that would have been
rasterized is fed back to the application using the GL.
.P
_cmnd has three arguments:
_param3 is a pointer to an array of floating-point values
into which feedback information is placed.
_param1 indicates the size of the array.
_param2 is a symbolic constant describing the information
that is fed back for each vertex.
_cmnd must be issued before feedback mode is enabled
(by calling _cmnd(RenderMode) with argument _const(FEEDBACK)).
Setting _const(FEEDBACK) without establishing the feedback buffer,
or calling _cmnd while the GL is in feedback mode,
is an error.
.P
When _cmnd(RenderMode) is called while in feedback mode, it returns the number of entries
placed in the feedback array, and resets the feedback array pointer to the base
of the feedback buffer. The returned value never exceeds _param1. If the feedback
data required more room than was available in _param3, 
_cmnd(RenderMode) returns a negative value.
To take the GL out of feedback mode, call
_cmnd(RenderMode) with a parameter value other than _const(FEEDBACK).
.P
While in feedback mode,
each primitive, bitmap, or pixel rectangle that would be rasterized
generates a block of values that are copied into the feedback array.
If doing so would cause the number of entries to exceed the maximum,
the block is partially written so as to fill the array
(if there is any room left at all),
and an overflow flag is set.
Each block begins with a code indicating the primitive type,
followed by values that describe the primitive's vertices and
associated data.
Entries are also written for bitmaps and pixel rectangles.
Feedback occurs after polygon culling and _cmnd(PolygonMode) interpretation
of polygons has taken place,
so polygons that are culled are not returned in the feedback buffer.
It can also occur after polygons with more than three edges are broken up
into triangles,
if the GL implementation renders polygons by performing this decomposition.
.P
The _cmnd(PassThrough) command can be used to insert a marker
into the feedback buffer.
See _cmnd(PassThrough).
.P
Following is the grammar for the blocks of values written
into the feedback buffer.
Each primitive is indicated with a unique identifying value
followed by some number of vertices.
Polygon entries include an integer value indicating how many vertices follow.
A vertex is fed back as some number of floating-point values,
as determined by _param2.
Colors are fed back as four values in RGBA mode and one value
in color index mode. 
.RS
.na
.sp
feedbackList \(<- feedbackItem feedbackList | feedbackItem
.sp
feedbackItem \(<- point | lineSegment | polygon | bitmap | pixelRectangle | passThru
.sp
point \(<- _const(POINT_TOKEN) vertex
.sp
lineSegment \(<- _const(LINE_TOKEN) vertex vertex | _const(LINE_RESET_TOKEN) vertex vertex
.sp
polygon \(<- _const(POLYGON_TOKEN) n polySpec
.sp
polySpec \(<- polySpec vertex | vertex vertex vertex
.sp
bitmap \(<- _const(BITMAP_TOKEN) vertex 
.sp
pixelRectangle \(<- _const(DRAW_PIXEL_TOKEN) vertex | _const(COPY_PIXEL_TOKEN) vertex
.sp
passThru \(<- _const(PASS_THROUGH_TOKEN) value
.sp
vertex \(<- 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture
.sp
2d \(<- value value
.sp
3d \(<- value value value
.sp
3dColor  \(<- value value value color
.sp
3dColorTexture \(<- value value value color tex
.sp
4dColorTexture \(<- value value value value color tex
.sp
color \(<- rgba | index
.sp
rgba \(<- value value value value
.sp
index \(<- value
.sp
tex \(<- value value value value
.sp
.RE
.P
.I value
is a floating-point number, 
and
.I n
is a floating-point integer giving the number of vertices in the polygon.
_const(POINT_TOKEN), 
_const(LINE_TOKEN),
_const(LINE_RESET_TOKEN),
_const(POLYGON_TOKEN),
_const(BITMAP_TOKEN),
_const(DRAW_PIXEL_TOKEN),
_const(COPY_PIXEL_TOKEN) and
_const(PASS_THROUGH_TOKEN) are symbolic floating-point constants.
_const(LINE_RESET_TOKEN) is returned whenever the line stipple pattern
is reset.
The data returned as a vertex depends on the feedback _param2.
.P
The following table gives the correspondence between _param2
and the number of values per vertex.
\f2k\fP is 1 in color index mode and 4 in RGBA mode.
.sp
.ne
.TS
center tab(:);
lb lb cb cb cb
l l c c c.
_
Type:Coordinates:Color:Texture:Total Number of Values
_
_const(2D):\f2x\fP, \f2y\fP:::2
_const(3D):\f2x\fP, \f2y\fP, \f2z\fP:::3
_const(3D_COLOR):\f2x\fP, \f2y\fP, \f2z\fP:$k$::$3 ~+~ k$
_const(3D_COLOR_TEXTURE):\f2x\fP, \f2y\fP, \f2z\fP,:$k$:4:$7 ~+~ k$
_const(4D_COLOR_TEXTURE):\f2x\fP, \f2y\fP, \f2z\fP, \f2w\fP:$k$:4:$8 ~+~ k$
_
.TE

.P
Feedback vertex coordinates are in window coordinates,
except \f2w\fP,
which is in clip coordinates.
Feedback colors are lighted, if lighting is enabled.
Feedback texture coordinates are generated,
if texture coordinate generation is enabled.
They are always transformed by the texture matrix.
.SH NOTES
_cmnd, when used in a display list, is not compiled into the display list 
but is executed immediately. 
.P
When the _arbstring(multitexture) extension is supported, _cmnd
returns only the texture coordinates of texture unit _arbconst(TEXTURE0).
.SH ERRORS
_const(INVALID_ENUM) is generated if _param2 is not an accepted value.
.P
_const(INVALID_VALUE) is generated if _param1 is negative.
.P
_const(INVALID_OPERATION) is generated if _cmnd is called while the
render mode is _const(FEEDBACK),
or if _cmnd(RenderMode) is called with argument _const(FEEDBACK) before
_cmnd is called at least once.
.P
_const(INVALID_OPERATION) is generated if _cmnd
is executed between the execution of _cmnd(Begin)
and the corresponding execution of _cmnd(End).
.SH ASSOCIATED GETS
_cmnd(Get) with argument _const(RENDER_MODE)
.br
_cmnd(Get) with argument _const(FEEDBACK_BUFFER_POINTER)
.br
_cmnd(Get) with argument _const(FEEDBACK_BUFFER_SIZE)
.br
_cmnd(Get) with argument _const(FEEDBACK_BUFFER_TYPE)
.SH SEE ALSO
_cmnd(Begin),
_cmnd(LineStipple),
_cmnd(PassThrough),
_cmnd(PolygonMode),
_cmnd(RenderMode),
_cmnd(SelectBuffer)