Difference between revisions of "GLAPI/glDrawBuffers"

From OpenGL.org
Jump to: navigation, search
m (Renaming category: 'API Reference 4' to 'Core API Reference'.)
m (Bot: Adding better formatting.)
Line 8: Line 8:
 
== Function Definition ==
 
== Function Definition ==
  
   void '''glDrawBuffers'''(GLsizei ''n'', const GLenum *''bufs'');
+
   void '''glDrawBuffers'''(GLsizei {{param|n}}, const GLenum *{{param|bufs}});
  
 
; n
 
; n
: Specifies the number of buffers in ''bufs''.
+
: Specifies the number of buffers in {{param|bufs}}.
 
; bufs
 
; bufs
 
: Points to an array of symbolic constants specifying the buffers into which fragment colors or data values will be written.
 
: Points to an array of symbolic constants specifying the buffers into which fragment colors or data values will be written.
Line 17: Line 17:
 
== Description ==
 
== Description ==
  
'''glDrawBuffers''' defines an array of buffers into which outputs from the fragment shader data will be written. If a fragment shader writes a value to one or more user defined output variables, then the value of each variable will be written into the buffer specified at a location within ''bufs'' corresponding to the location assigned to that user defined output. The draw buffer used for user defined outputs assigned to locations greater than or equal to ''n'' is implicitly set to {{code|GL_NONE}} and any data written to such an output is discarded.
+
'''glDrawBuffers''' defines an array of buffers into which outputs from the fragment shader data will be written. If a fragment shader writes a value to one or more user defined output variables, then the value of each variable will be written into the buffer specified at a location within {{param|bufs}} corresponding to the location assigned to that user defined output. The draw buffer used for user defined outputs assigned to locations greater than or equal to {{param|n}} is implicitly set to {{code|GL_NONE}} and any data written to such an output is discarded.
  
The symbolic constants contained in ''bufs'' may be any of the following:
+
The symbolic constants contained in {{param|bufs}} may be any of the following:
  
 
; {{code|GL_NONE}}
 
; {{code|GL_NONE}}
Line 33: Line 33:
 
; {{code|GL_COLOR_ATTACHMENT''n''}}
 
; {{code|GL_COLOR_ATTACHMENT''n''}}
 
: The fragment shader output value is written into the ''n''th color attachment of the current framebuffer. ''n'' may range from 0 to the value of {{code|GL_MAX_COLOR_ATTACHMENTS}}.
 
: The fragment shader output value is written into the ''n''th color attachment of the current framebuffer. ''n'' may range from 0 to the value of {{code|GL_MAX_COLOR_ATTACHMENTS}}.
Except for {{code|GL_NONE}}, the preceding symbolic constants may not appear more than once in ''bufs''. The maximum number of draw buffers supported is implementation dependent and can be queried by calling [[GLAPI/glGet|glGet]] with the argument {{code|GL_MAX_DRAW_BUFFERS}}.
+
Except for {{code|GL_NONE}}, the preceding symbolic constants may not appear more than once in {{param|bufs}}. The maximum number of draw buffers supported is implementation dependent and can be queried by calling {{apifunc|glGet}} with the argument {{code|GL_MAX_DRAW_BUFFERS}}.
  
 
== Notes ==
 
== Notes ==
  
The symbolic constants {{code|GL_FRONT}}, {{code|GL_BACK}}, {{code|GL_LEFT}}, {{code|GL_RIGHT}}, and {{code|GL_FRONT_AND_BACK}} are not allowed in the ''bufs'' array since they may refer to multiple buffers.
+
The symbolic constants {{code|GL_FRONT}}, {{code|GL_BACK}}, {{code|GL_LEFT}}, {{code|GL_RIGHT}}, and {{code|GL_FRONT_AND_BACK}} are not allowed in the {{param|bufs}} array since they may refer to multiple buffers.
  
If a fragment shader does not write to a user defined output variable, the values of the fragment colors following shader execution are undefined. For each fragment generated in this situation, a different value may be written into each of the buffers specified by ''bufs''.
+
If a fragment shader does not write to a user defined output variable, the values of the fragment colors following shader execution are undefined. For each fragment generated in this situation, a different value may be written into each of the buffers specified by {{param|bufs}}.
  
 
== Errors ==
 
== Errors ==
  
{{code|GL_INVALID_ENUM}} is generated if one of the values in ''bufs'' is not an accepted value.
+
{{code|GL_INVALID_ENUM}} is generated if one of the values in {{param|bufs}} is not an accepted value.
  
{{code|GL_INVALID_ENUM}} is generated if the GL is bound to the default framebuffer and one or more of the values in ''bufs'' is one of the {{code|GL_COLOR_ATTACHMENT''n''}} tokens.
+
{{code|GL_INVALID_ENUM}} is generated if the GL is bound to the default framebuffer and one or more of the values in {{param|bufs}} is one of the {{code|GL_COLOR_ATTACHMENT''n''}} tokens.
  
{{code|GL_INVALID_ENUM}} is generated if the GL is bound to a framebuffer object and one or more of the values in ''bufs'' is anything other than {{code|GL_NONE}} or one of the {{code|GL_COLOR_ATTACHMENTS''n''}} tokens.
+
{{code|GL_INVALID_ENUM}} is generated if the GL is bound to a framebuffer object and one or more of the values in {{param|bufs}} is anything other than {{code|GL_NONE}} or one of the {{code|GL_COLOR_ATTACHMENTS''n''}} tokens.
  
{{code|GL_INVALID_ENUM}} is generated if ''n'' is less than 0.
+
{{code|GL_INVALID_ENUM}} is generated if {{param|n}} is less than 0.
  
{{code|GL_INVALID_OPERATION}} is generated if a symbolic constant other than {{code|GL_NONE}} appears more than once in ''bufs''.
+
{{code|GL_INVALID_OPERATION}} is generated if a symbolic constant other than {{code|GL_NONE}} appears more than once in {{param|bufs}}.
  
{{code|GL_INVALID_OPERATION}} is generated if any of the entries in ''bufs'' (other than {{code|GL_NONE}} ) indicates a color buffer that does not exist in the current GL context.
+
{{code|GL_INVALID_OPERATION}} is generated if any of the entries in {{param|bufs}} (other than {{code|GL_NONE}} ) indicates a color buffer that does not exist in the current GL context.
  
{{code|GL_INVALID_VALUE}} is generated if ''n'' is greater than {{code|GL_MAX_DRAW_BUFFERS}}.
+
{{code|GL_INVALID_VALUE}} is generated if {{param|n}} is greater than {{code|GL_MAX_DRAW_BUFFERS}}.
  
 
== Associated Gets ==
 
== Associated Gets ==
  
[[GLAPI/glGet|glGet]] with argument {{code|GL_MAX_DRAW_BUFFERS}}
+
{{apifunc|glGet}} with argument {{code|GL_MAX_DRAW_BUFFERS}}
  
[[GLAPI/glGet|glGet]] with argument {{code|GL_DRAW_BUFFER''i''}} where {{code|''i''}} indicates the number of the draw buffer whose value is to be queried
+
{{apifunc|glGet}} with argument {{code|GL_DRAW_BUFFER''i''}} where {{code|''i''}} indicates the number of the draw buffer whose value is to be queried
  
 
== See Also ==
 
== See Also ==
  
[[GLAPI/glBlendFunc|glBlendFunc]], [[GLAPI/glColorMask|glColorMask]], [[GLAPI/glDrawBuffers|glDrawBuffers]], [[GLAPI/glLogicOp|glLogicOp]], [[GLAPI/glReadBuffer|glReadBuffer]]
+
{{apifunc|glBlendFunc}}, {{apifunc|glColorMask}}, {{apifunc|glDrawBuffers}}, {{apifunc|glLogicOp}}, {{apifunc|glReadBuffer}}
  
 
== Copyright ==
 
== Copyright ==

Revision as of 21:16, 28 April 2012

glDrawBuffers
Core in version 4.5
Core since version 2.0

glDrawBuffers: Specifies a list of color buffers to be drawn into

Function Definition

 void glDrawBuffers(GLsizei n​, const GLenum *bufs​);
n
Specifies the number of buffers in bufs​.
bufs
Points to an array of symbolic constants specifying the buffers into which fragment colors or data values will be written.

Description

glDrawBuffers defines an array of buffers into which outputs from the fragment shader data will be written. If a fragment shader writes a value to one or more user defined output variables, then the value of each variable will be written into the buffer specified at a location within bufs​ corresponding to the location assigned to that user defined output. The draw buffer used for user defined outputs assigned to locations greater than or equal to n​ is implicitly set to GL_NONE​ and any data written to such an output is discarded.

The symbolic constants contained in bufs​ may be any of the following:

GL_NONE​
The fragment shader output value is not written into any color buffer.
GL_FRONT_LEFT​
The fragment shader output value is written into the front left color buffer.
GL_FRONT_RIGHT​
The fragment shader output value is written into the front right color buffer.
GL_BACK_LEFT​
The fragment shader output value is written into the back left color buffer.
GL_BACK_RIGHT​
The fragment shader output value is written into the back right color buffer.
GL_COLOR_ATTACHMENTn
The fragment shader output value is written into the nth color attachment of the current framebuffer. n may range from 0 to the value of GL_MAX_COLOR_ATTACHMENTS​.

Except for GL_NONE​, the preceding symbolic constants may not appear more than once in bufs​. The maximum number of draw buffers supported is implementation dependent and can be queried by calling glGet with the argument GL_MAX_DRAW_BUFFERS​.

Notes

The symbolic constants GL_FRONT​, GL_BACK​, GL_LEFT​, GL_RIGHT​, and GL_FRONT_AND_BACK​ are not allowed in the bufs​ array since they may refer to multiple buffers.

If a fragment shader does not write to a user defined output variable, the values of the fragment colors following shader execution are undefined. For each fragment generated in this situation, a different value may be written into each of the buffers specified by bufs​.

Errors

GL_INVALID_ENUM​ is generated if one of the values in bufs​ is not an accepted value.

GL_INVALID_ENUM​ is generated if the GL is bound to the default framebuffer and one or more of the values in bufs​ is one of the GL_COLOR_ATTACHMENTn tokens.

GL_INVALID_ENUM​ is generated if the GL is bound to a framebuffer object and one or more of the values in bufs​ is anything other than GL_NONE​ or one of the GL_COLOR_ATTACHMENTSn tokens.

GL_INVALID_ENUM​ is generated if n​ is less than 0.

GL_INVALID_OPERATION​ is generated if a symbolic constant other than GL_NONE​ appears more than once in bufs​.

GL_INVALID_OPERATION​ is generated if any of the entries in bufs​ (other than GL_NONE​ ) indicates a color buffer that does not exist in the current GL context.

GL_INVALID_VALUE​ is generated if n​ is greater than GL_MAX_DRAW_BUFFERS​.

Associated Gets

glGet with argument GL_MAX_DRAW_BUFFERS​

glGet with argument GL_DRAW_BUFFERi where i indicates the number of the draw buffer whose value is to be queried

See Also

glBlendFunc, glColorMask, glDrawBuffers, glLogicOp, glReadBuffer

Copyright

Copyright © 2003-2005 3Dlabs Inc. Ltd. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.