Standard disclaimer: This is not copy-n-paste. This was all written from memory and then corrected as necessary using the relevant references.
Standard(s): OpenGL (introduced in 1.0)
Language(s): C (this function is also supported by all interfaces from other languages)
Header File: "GL/gl.h"
See also: glEnd, OpenGL rendering pipeline.
void glBegin(GLenum mode)
Description
This function needs to be called before you can start passing details of graphics primitives to the rendering pipeline. It essentially tells OpenGL how to process the data which is subsequently passed to it.
Between it and the corresponding glEnd call, you are only allowed to call the following OpenGL functions/function groups (in actual fact, most current OpenGL implementations allow you to also call other functions, but this is not guaranteed behaviour): glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glMaterial, and glEdgeFlag. You can also call glCallList or glCallLists as long as the display list you are calling only contains the preceding commands.
Parameters
mode
The type of primitives which will be created from the data passed to the rendering pipeline between this function call and the following glEnd call. The constants which represent different primitive types are listed below, along with details of what data you need to pass to OpenGL.
GL_POINTS
The primitives consist of a set of points.
The data should consist of one vertex for each point, and one point will be rendered for each vertex.
GL_LINES
The primitives consist of a set of unconnected lines.
The data should consist of two vertices for each line, and one line will be rendered for every two vertices.
GL_LINE_STRIP
The primitives consist of a set of connected lines, where each vertex is connected to the next.
The data should consist of an initial vertex and a set of vertices, and one line will be rendered for each vertex in the set, connected in order. Evidently, if N vertices are passed, N - 1 vertices will be rendered.
GL_LINE_LOOP
The primitives consist of a set of connected lines, with the last vertex connected to the first.
The data should consist of vertices, and one line will be rendered for each vertex, assuming there is more than one.
GL_TRIANGLES
The primitives consist of a set of triangles.
The data should consist of sets of three vertices, and each set of three vertices is used to render a triangle whose points consist of the provided vertices.
GL_TRIANGLE_STRIP
The primitives consist of a connected set of triangles (a triangle strip), which share edges.
The data should consist of two initial vertices and then an extra vertex for each triangle.
GL_TRIANGLE_FAN
The primitives consist of a connected set of triangles (a triangle fan), all of which share a single point.
The data should consist of a shared vertex, a starting vertex and then an extra vertex for each triangle.
GL_QUADS
The primitives consist of a set of quadrilaterals.
The data should consist of sets of four vertices, and each set of four vertices is used to render a quadrilateral whose points consist of the provided vertices.
GL_QUAD_STRIP
The primitives consist of a connected set of quadrilaterals which share edges.
The data should consist of two initial vertices and then an extra pair of vertices for each quadrilateral.
GL_POLYGON
The primitive is a single convex polygon.
The data should consist of a set of points which specify the points which make up the polygon.
You can always pass as many vertices in the data as you want; if there aren't enough to make up a complete primitive, the unused vertices are just ignored.
Examples
All examples are in C++, and are just examples of usage, they're not guaranteed to do anything useful.
The following example code produces two points, one at the coordinates (1, 1, 1) and one at the coordinates (1, -1, 0).
glBegin(GL_POINTS);
glVertex3f(1.0f, 1.0f, 1.0f);
glVertex3f(1.0f, -1.0f, 0.0f);
glEnd();
The following example code produces two triangles, one with the points (20, 10), (10, 30) and (20, 50) and one with the points (40, 50), (50, 30) and (40, 10).
glBegin(GL_TRIANGLES);
glVertex2f(20.0f, 10.0f);
glVertex2f(10.0f, 30.0f);
glVertex2f(20.0f, 50.0f);
glVertex2f(40.0f, 50.0f);
glVertex2f(50.0f, 30.0f);
glVertex2f(40.0f, 10.0f);
glEnd();
The following example code produces a single convex polygon with four points and specified texture coordinates.
glBegin(GL_POLYGON);
glTexCoord2f(0.0f, 0.0f);
glVertex3f(-1.0f, -1.0f, -1.0f);
glTexCoord2f(0.0f, 1.0f);
glVertex3f(-1.0f, 1.0f, -1.0f);
glTexCoord2f(1.0f, 1.0f);
glVertex3f(-1.0f, 1.0f, -2.0f);
glTexCoord2f(1.0f, 0.0f);
glVertex3f(-1.0f, -1.0f, -2.0f);
glEnd();
For further examples, see OpenGL rendering pipeline.
Possible Errors
Please see OpenGL error handling for an explanation of what this means.
GL_INVALID_ENUM is generated if the mode parameter is set to a number which doesn't relate to a constant the OpenGL implementation you're using understands. This either means you're not passing a constant from the list above, or the constant you're passing is from a version of OpenGL which is newer than the implementation your programing is using.
GL_INVALID_OPERATION is generated if you call this function inside another glBegin/glEnd block (ie, you have already called glBegin but haven't called glEnd since).
GL_INVALID_OPERATION should also be generated (but isn't always) after you call any function before the glEnd call which isn't in the list of allowed functions above.
part of the codenode project; edited by: insanefuzzie