glFeedbackBuffer.3gl

Name

  glFeedbackBuffer - controls feedback mode

C Specification

  void glFeedbackBuffer( GLsizei size,
			 GLenum	type,
			 GLfloat *buffer )

Parameters

  size	  Specifies the	maximum	number of values that can be written into
	  buffer.

  type	  Specifies a symbolic constant	that describes the information that
	  will be returned for each vertex.  GL_2D, GL_3D, GL_3D_COLOR,
	  GL_3D_COLOR_TEXTURE, and GL_4D_COLOR_TEXTURE are accepted.

  buffer  Returns the feedback data.

Description

  The glFeedbackBuffer function	controls feedback.  Feedback, like selection,
  is a GL mode.	 The mode is selected by calling glRenderMode with
  GL_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.

  glFeedbackBuffer has three arguments:	buffer is a pointer to an array	of
  floating-point values	into which feedback information	is placed.  size
  indicates the	size of	the array.  type is a symbolic constant	describing
  the information that is fed back for each vertex.  glFeedbackBuffer must be
  issued before	feedback mode is enabled (by calling glRenderMode with
  argument GL_FEEDBACK).  Setting GL_FEEDBACK without establishing the
  feedback buffer, or calling glFeedbackBuffer while the GL is in feedback
  mode,	is an error.

  The GL is taken out of feedback mode by calling glRenderMode with a
  parameter value other	than GL_FEEDBACK.  When	this is	done while the GL is
  in feedback mode, glRenderMode returns the number of entries placed in the
  feedback array.  The returned	value never exceeds size. If the feedback
  data required	more room than was available in	buffer,	glRenderMode returns
  a negative value.

  While	in feedback mode, each primitive that would be rasterized generates a
  block	of values that get 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 glPolyMode
  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.


  The glPassThrough command can	be used	to insert a marker into	the feedback
  buffer.  See glPassThrough.

  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 type.  Colors are fed
  back as four values in RGBA mode and one value in color index	mode.

       feedbackList <- feedbackItem feedbackList | feedbackItem

       feedbackItem <- point | lineSegment | polygon | bitmap |
       pixelRectangle |	passThru

       point <-	GL_POINT_TOKEN vertex

       lineSegment <- GL_LINE_TOKEN vertex vertex | GL_LINE_RESET_TOKEN
       vertex vertex

       polygon <- GL_POLYGON_TOKEN n polySpec

       polySpec	<- polySpec vertex | vertex vertex vertex

       bitmap <- GL_BITMAP_TOKEN vertex

       pixelRectangle <- GL_DRAW_PIXEL_TOKEN vertex | GL_COPY_PIXEL_TOKEN
       vertex

       passThru	<- GL_PASS_THROUGH_TOKEN value

       vertex <- 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture

       2d <- value value

       3d <- value value value

       3dColor	<- value value value color

       3dColorTexture <- value value value color tex

       4dColorTexture <- value value value value color tex

       color <-	rgba | index

       rgba <- value value value value

       index <-	value

       tex <- value value value	value


  value	is a floating-point number, and	n is a floating-point integer giving
  the number of	vertices in the	polygon.  GL_POINT_TOKEN, GL_LINE_TOKEN,
  GL_LINE_RESET_TOKEN, GL_POLYGON_TOKEN, GL_BITMAP_TOKEN,
  GL_DRAW_PIXEL_TOKEN, GL_COPY_PIXEL_TOKEN and GL_PASS_THROUGH_TOKEN are
  symbolic floating-point constants.  GL_LINE_RESET_TOKEN is returned
  whenever the line stipple pattern is reset.  The data	returned as a vertex
  depends on the feedback type.

  The following	table gives the	correspondence between type and	the number of
  values per vertex.  k	is 1 in	color index mode and 4 in RGBA mode.



------------------------------------------------------------------------------
|       type         | coordinates | color | texture | total number of values |
------------------------------------------------------------------------------
|	GL_2D	     |	  x, y	   |	   |	     |		 2	      |
|	GL_3D	     |	 x, y, z   |	   |	     |		 3	      |
|    GL_3D_COLOR     |	 x, y, z   |   k   |	     |		3+k	      |
|GL_3D_COLOR_TEXTURE |	x, y, z,   |   k   |	4    |		7+k	      |
|GL_4D_COLOR_TEXTURE | x, y, z,	w  |   k   |	4    |		8+k	      |
------------------------------------------------------------------------------

  Feedback vertex coordinates are in window coordinates, except	w, 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.

Notes

  glFeedbackBuffer, when used in a display list, is not	compiled into the
  display list but rather is executed immediately.

Errors

  GL_INVALID_ENUM is generated if type is not an accepted value.

  GL_INVALID_VALUE is generated	if size	is negative.

  GL_INVALID_OPERATION is generated if glFeedbackBuffer	is called while	the
  render mode is GL_FEEDBACK, or if glRenderMode is called with	argument
  GL_FEEDBACK before glFeedbackBuffer is called	at least once.

  GL_INVALID_OPERATION is generated if glFeedbackBuffer	is executed between
  the execution	of glBegin and the corresponding execution of glEnd.

Associated Gets

  glGet	with argument GL_RENDER_MODE

See Also

  glBegin, glLineStipple, glPassThrough, glPolygonMode,	glRenderMode,
  glSelectBuffer

Introduction | Alphabetic | Specification

Last Edited: Fri Dec 6 11:18:03 EST 1996 by AFV
Look here for legal stuff: Legal