OpenGL 4.4 (Core Profile) - March 19, 2014 · The OpenGL R Graphics System: A Speciﬁcation...

The OpenGL R© Graphics System:A Specification

(Version 4.4 (Core Profile) - March 19, 2014)

Mark SegalKurt Akeley

Editor (version 1.1): Chris FrazierEditor (versions 1.2-4.4 ): Jon Leech

Editor (version 2.0): Pat Brown

Copyright c© 2006-2014 The Khronos Group Inc. All Rights Reserved.

This specification is protected by copyright laws and contains material proprietaryto the Khronos Group, Inc. It or any components may not be reproduced, repub-lished, distributed, transmitted, displayed, broadcast or otherwise exploited in anymanner without the express prior written permission of Khronos Group. You mayuse this specification for implementing the functionality therein, without altering orremoving any trademark, copyright or other notice from the specification, but thereceipt or possession of this specification does not convey any rights to reproduce,disclose, or distribute its contents, or to manufacture, use, or sell anything that itmay describe, in whole or in part.

Khronos Group grants express permission to any current Promoter, Contributoror Adopter member of Khronos to copy and redistribute UNMODIFIED versionsof this specification in any fashion, provided that NO CHARGE is made for thespecification and the latest available update of the specification for any versionof the API is used whenever possible. Such distributed specification may be re-formatted AS LONG AS the contents of the specification are not changed in anyway. The specification may be incorporated into a product that is sold as long assuch product includes significant independent work developed by the seller. A linkto the current version of this specification on the Khronos Group web-site shouldbe included whenever possible with specification distributions.

Khronos Group makes no, and expressly disclaims any, representations or war-ranties, express or implied, regarding this specification, including, without limita-tion, any implied warranties of merchantability or fitness for a particular purposeor non-infringement of any intellectual property. Khronos Group makes no, andexpressly disclaims any, warranties, express or implied, regarding the correctness,accuracy, completeness, timeliness, and reliability of the specification. Under nocircumstances will the Khronos Group, or any of its Promoters, Contributors orMembers or their respective partners, officers, directors, employees, agents or rep-resentatives be liable for any damages, whether direct, indirect, special or conse-quential damages for lost revenues, lost profits, or otherwise, arising from or inconnection with these materials.

Khronos is a trademark of The Khronos Group Inc. OpenGL is a registered trade-mark, and OpenGL ES is a trademark, of Silicon Graphics International.

Contents

1 Introduction 11.1 Formatting of the OpenGL Specification . . . . . . . . . . . . . . 1

1.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 What is the OpenGL Graphics System? . . . . . . . . . . . . . . 21.2.1 Programmer’s View of OpenGL . . . . . . . . . . . . . . 21.2.2 Implementor’s View of OpenGL . . . . . . . . . . . . . . 21.2.3 Our View . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.4 Fixed-function Hardware and the Compatibility Profile . . 31.2.5 The Deprecation Model . . . . . . . . . . . . . . . . . . 3

1.3 Related APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.1 OpenGL Shading Language . . . . . . . . . . . . . . . . 41.3.2 OpenGL ES . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.3 OpenGL ES Shading Language . . . . . . . . . . . . . . 51.3.4 WebGL . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3.5 Window System Bindings . . . . . . . . . . . . . . . . . 61.3.6 OpenCL . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4 Filing Bug Reports . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 OpenGL Fundamentals 82.1 Execution Model . . . . . . . . . . . . . . . . . . . . . . . . . . 82.2 Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.2.1 Data Conversion For State-Setting Commands . . . . . . 122.2.2 Data Conversions For State Query Commands . . . . . . 14

2.3 Command Execution . . . . . . . . . . . . . . . . . . . . . . . . 152.3.1 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.3.2 Flush and Finish . . . . . . . . . . . . . . . . . . . . . . 182.3.3 Numeric Representation and Computation . . . . . . . . . 182.3.4 Fixed-Point Data Conversions . . . . . . . . . . . . . . . 22

i

CONTENTS ii

2.4 Rendering Commands . . . . . . . . . . . . . . . . . . . . . . . 242.5 Context State . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.5.1 Generic Context State Queries . . . . . . . . . . . . . . . 242.6 Objects and the Object Model . . . . . . . . . . . . . . . . . . . 25

2.6.1 Object Management . . . . . . . . . . . . . . . . . . . . 252.6.2 Buffer Objects . . . . . . . . . . . . . . . . . . . . . . . 262.6.3 Shader Objects . . . . . . . . . . . . . . . . . . . . . . . 272.6.4 Program Objects . . . . . . . . . . . . . . . . . . . . . . 272.6.5 Program Pipeline Objects . . . . . . . . . . . . . . . . . 272.6.6 Texture Objects . . . . . . . . . . . . . . . . . . . . . . . 272.6.7 Sampler Objects . . . . . . . . . . . . . . . . . . . . . . 282.6.8 Renderbuffer Objects . . . . . . . . . . . . . . . . . . . . 282.6.9 Framebuffer Objects . . . . . . . . . . . . . . . . . . . . 282.6.10 Vertex Array Objects . . . . . . . . . . . . . . . . . . . . 282.6.11 Transform Feedback Objects . . . . . . . . . . . . . . . . 292.6.12 Query Objects . . . . . . . . . . . . . . . . . . . . . . . 292.6.13 Sync Objects . . . . . . . . . . . . . . . . . . . . . . . . 292.6.14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3 Dataflow Model 30

4 Event Model 334.1 Sync Objects and Fences . . . . . . . . . . . . . . . . . . . . . . 33

4.1.1 Waiting for Sync Objects . . . . . . . . . . . . . . . . . . 354.1.2 Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 374.1.3 Sync Object Queries . . . . . . . . . . . . . . . . . . . . 37

4.2 Query Objects and Asynchronous Queries . . . . . . . . . . . . . 384.2.1 Query Object Queries . . . . . . . . . . . . . . . . . . . 42

4.3 Time Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

5 Shared Objects and Multiple Contexts 475.1 Object Deletion Behavior . . . . . . . . . . . . . . . . . . . . . . 48

5.1.1 Side Effects of Shared Context Destruction . . . . . . . . 485.1.2 Automatic Unbinding of Deleted Objects . . . . . . . . . 485.1.3 Deleted Object and Object Name Lifetimes . . . . . . . . 48

5.2 Sync Objects and Multiple Contexts . . . . . . . . . . . . . . . . 495.3 Propagating Changes to Objects . . . . . . . . . . . . . . . . . . 49

5.3.1 Determining Completion of Changes to an object . . . . . 505.3.2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 515.3.3 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

OpenGL 4.4 (Core Profile) - March 19, 2014

CONTENTS iii

6 Buffer Objects 536.1 Creating and Binding Buffer Objects . . . . . . . . . . . . . . . . 54

6.1.1 Binding Buffer Objects to Indexed Targets . . . . . . . . . 566.2 Creating and Modifying Buffer Object Data Stores . . . . . . . . 59

6.2.1 Clearing Buffer Object Data Stores . . . . . . . . . . . . 646.3 Mapping and Unmapping Buffer Data . . . . . . . . . . . . . . . 65

6.3.1 Unmapping Buffers . . . . . . . . . . . . . . . . . . . . . 706.3.2 Effects of Mapping Buffers on Other GL Commands . . . 70

6.4 Effects of Accessing Outside Buffer Bounds . . . . . . . . . . . . 716.5 Invalidating Buffer Data . . . . . . . . . . . . . . . . . . . . . . 716.6 Copying Between Buffers . . . . . . . . . . . . . . . . . . . . . . 726.7 Buffer Object Queries . . . . . . . . . . . . . . . . . . . . . . . . 73

6.7.1 Indexed Buffer Object Limits and Binding Queries . . . . 746.8 Buffer Object State . . . . . . . . . . . . . . . . . . . . . . . . . 76

7 Programs and Shaders 777.1 Shader Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 787.2 Shader Binaries . . . . . . . . . . . . . . . . . . . . . . . . . . . 817.3 Program Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 82

7.3.1 Program Interfaces . . . . . . . . . . . . . . . . . . . . . 897.4 Program Pipeline Objects . . . . . . . . . . . . . . . . . . . . . . 108

7.4.1 Shader Interface Matching . . . . . . . . . . . . . . . . . 1117.4.2 Program Pipeline Object State . . . . . . . . . . . . . . . 114

7.5 Program Binaries . . . . . . . . . . . . . . . . . . . . . . . . . . 1147.6 Uniform Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 117

7.6.1 Loading Uniform Variables In The Default Uniform Block 1247.6.2 Uniform Blocks . . . . . . . . . . . . . . . . . . . . . . . 1287.6.3 Uniform Buffer Object Bindings . . . . . . . . . . . . . . 132

7.7 Atomic Counter Buffers . . . . . . . . . . . . . . . . . . . . . . . 1337.7.1 Atomic Counter Buffer Object Storage . . . . . . . . . . 1337.7.2 Atomic Counter Buffer Bindings . . . . . . . . . . . . . . 134

7.8 Shader Buffer Variables and Shader Storage Blocks . . . . . . . . 1347.9 Subroutine Uniform Variables . . . . . . . . . . . . . . . . . . . 1367.10 Samplers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407.11 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417.12 Shader Memory Access . . . . . . . . . . . . . . . . . . . . . . . 142

7.12.1 Shader Memory Access Ordering . . . . . . . . . . . . . 1427.12.2 Shader Memory Access Synchronization . . . . . . . . . 144

7.13 Shader, Program, and Program Pipeline Queries . . . . . . . . . . 1487.14 Required State . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157


CONTENTS iv

8 Textures and Samplers 1598.1 Texture Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 1608.2 Sampler Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648.3 Sampler Object Queries . . . . . . . . . . . . . . . . . . . . . . . 1688.4 Pixel Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

8.4.1 Pixel Storage Modes and Pixel Buffer Objects . . . . . . . 1698.4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708.4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708.4.4 Transfer of Pixel Rectangles . . . . . . . . . . . . . . . . 1708.4.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

8.5 Texture Image Specification . . . . . . . . . . . . . . . . . . . . 1838.5.1 Required Texture Formats . . . . . . . . . . . . . . . . . 1868.5.2 Encoding of Special Internal Formats . . . . . . . . . . . 1878.5.3 Texture Image Structure . . . . . . . . . . . . . . . . . . 191

8.6 Alternate Texture Image Specification Commands . . . . . . . . . 1968.6.1 Texture Copying Feedback Loops . . . . . . . . . . . . . 204

8.7 Compressed Texture Images . . . . . . . . . . . . . . . . . . . . 2048.8 Multisample Textures . . . . . . . . . . . . . . . . . . . . . . . . 2118.9 Buffer Textures . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138.10 Texture Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 2168.11 Texture Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

8.11.1 Active Texture . . . . . . . . . . . . . . . . . . . . . . . 2198.11.2 Texture Parameter Queries . . . . . . . . . . . . . . . . . 2198.11.3 Texture Level Parameter Queries . . . . . . . . . . . . . . 2208.11.4 Texture Image Queries . . . . . . . . . . . . . . . . . . . 222

8.12 Depth Component Textures . . . . . . . . . . . . . . . . . . . . . 2258.13 Cube Map Texture Selection . . . . . . . . . . . . . . . . . . . . 225

8.13.1 Seamless Cube Map Filtering . . . . . . . . . . . . . . . 2268.14 Texture Minification . . . . . . . . . . . . . . . . . . . . . . . . 227

8.14.1 Scale Factor and Level of Detail . . . . . . . . . . . . . . 2278.14.2 Coordinate Wrapping and Texel Selection . . . . . . . . . 2298.14.3 Mipmapping . . . . . . . . . . . . . . . . . . . . . . . . 2348.14.4 Manual Mipmap Generation . . . . . . . . . . . . . . . . 2368.14.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

8.15 Texture Magnification . . . . . . . . . . . . . . . . . . . . . . . . 2378.16 Combined Depth/Stencil Textures . . . . . . . . . . . . . . . . . 2388.17 Texture Completeness . . . . . . . . . . . . . . . . . . . . . . . . 238

8.17.1 Effects of Sampler Objects on Texture Completeness . . . 2398.17.2 Effects of Completeness on Texture Application . . . . . . 2398.17.3 Effects of Completeness on Texture Image Specification . 240


CONTENTS v

8.18 Texture Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2408.19 Immutable-Format Texture Images . . . . . . . . . . . . . . . . . 2448.20 Invalidating Texture Image Data . . . . . . . . . . . . . . . . . . 2498.21 Clearing Texture Image Data . . . . . . . . . . . . . . . . . . . . 2508.22 Texture State and Proxy State . . . . . . . . . . . . . . . . . . . . 2528.23 Texture Comparison Modes . . . . . . . . . . . . . . . . . . . . . 255

8.23.1 Depth Texture Comparison Mode . . . . . . . . . . . . . 2558.24 sRGB Texture Color Conversion . . . . . . . . . . . . . . . . . . 2558.25 Shared Exponent Texture Color Conversion . . . . . . . . . . . . 2568.26 Texture Image Loads and Stores . . . . . . . . . . . . . . . . . . 257

8.26.1 Image Unit Queries . . . . . . . . . . . . . . . . . . . . . 266

9 Framebuffers and Framebuffer Objects 2679.1 Framebuffer Overview . . . . . . . . . . . . . . . . . . . . . . . 2679.2 Binding and Managing Framebuffer Objects . . . . . . . . . . . . 269

9.2.1 Framebuffer Object Parameters . . . . . . . . . . . . . . 2729.2.2 Attaching Images to Framebuffer Objects . . . . . . . . . 2749.2.3 Framebuffer Object Queries . . . . . . . . . . . . . . . . 2759.2.4 Renderbuffer Objects . . . . . . . . . . . . . . . . . . . . 2789.2.5 Required Renderbuffer Formats . . . . . . . . . . . . . . 2819.2.6 Renderbuffer Object Queries . . . . . . . . . . . . . . . . 2819.2.7 Attaching Renderbuffer Images to a Framebuffer . . . . . 2829.2.8 Attaching Texture Images to a Framebuffer . . . . . . . . 284

9.3 Feedback Loops Between Textures and the Framebuffer . . . . . . 2889.3.1 Rendering Feedback Loops . . . . . . . . . . . . . . . . . 2889.3.2 Texture Copying Feedback Loops . . . . . . . . . . . . . 290

9.4 Framebuffer Completeness . . . . . . . . . . . . . . . . . . . . . 2909.4.1 Framebuffer Attachment Completeness . . . . . . . . . . 2919.4.2 Whole Framebuffer Completeness . . . . . . . . . . . . . 2929.4.3 Required Framebuffer Formats . . . . . . . . . . . . . . . 2959.4.4 Effects of Framebuffer Completeness on Framebuffer Op-

erations . . . . . . . . . . . . . . . . . . . . . . . . . . . 2959.4.5 Effects of Framebuffer State on Framebuffer Dependent

Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2959.5 Mapping between Pixel and Element in Attached Image . . . . . . 2969.6 Conversion to Framebuffer-Attachable Image Components . . . . 2979.7 Conversion to RGBA Values . . . . . . . . . . . . . . . . . . . . 2979.8 Layered Framebuffers . . . . . . . . . . . . . . . . . . . . . . . . 297


CONTENTS vi

10 Vertex Specification and Drawing Commands 30010.1 Primitive Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

10.1.1 Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30210.1.2 Line Strips . . . . . . . . . . . . . . . . . . . . . . . . . 30210.1.3 Line Loops . . . . . . . . . . . . . . . . . . . . . . . . . 30210.1.4 Separate Lines . . . . . . . . . . . . . . . . . . . . . . . 30210.1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30310.1.6 Triangle Strips . . . . . . . . . . . . . . . . . . . . . . . 30310.1.7 Triangle Fans . . . . . . . . . . . . . . . . . . . . . . . . 30410.1.8 Separate Triangles . . . . . . . . . . . . . . . . . . . . . 30410.1.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30410.1.10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30410.1.11 Lines with Adjacency . . . . . . . . . . . . . . . . . . . 30410.1.12 Line Strips with Adjacency . . . . . . . . . . . . . . . . . 30610.1.13 Triangles with Adjacency . . . . . . . . . . . . . . . . . 30610.1.14 Triangle Strips with Adjacency . . . . . . . . . . . . . . . 30710.1.15 Separate Patches . . . . . . . . . . . . . . . . . . . . . . 30810.1.16 General Considerations For Polygon Primitives . . . . . . 30910.1.17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

10.2 Current Vertex Attribute Values . . . . . . . . . . . . . . . . . . . 30910.2.1 Current Generic Attributes . . . . . . . . . . . . . . . . . 30910.2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31210.2.3 Vertex Attribute Queries . . . . . . . . . . . . . . . . . . 31210.2.4 Required State . . . . . . . . . . . . . . . . . . . . . . . 312

10.3 Vertex Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31210.3.1 Specifying Arrays for Generic Vertex Attributes . . . . . . 31210.3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31810.3.3 Vertex Attribute Divisors . . . . . . . . . . . . . . . . . . 31810.3.4 Transferring Array Elements . . . . . . . . . . . . . . . . 31910.3.5 Primitive Restart . . . . . . . . . . . . . . . . . . . . . . 31910.3.6 Robust Buffer Access . . . . . . . . . . . . . . . . . . . . 32010.3.7 Packed Vertex Data Formats . . . . . . . . . . . . . . . . 32110.3.8 Vertex Arrays in Buffer Objects . . . . . . . . . . . . . . 32110.3.9 Array Indices in Buffer Objects . . . . . . . . . . . . . . 32210.3.10 Indirect Commands in Buffer Objects . . . . . . . . . . . 323

10.4 Vertex Array Objects . . . . . . . . . . . . . . . . . . . . . . . . 32310.5 Drawing Commands Using Vertex Arrays . . . . . . . . . . . . . 325

10.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33510.6 Vertex Array and Vertex Array Object Queries . . . . . . . . . . . 33510.7 Required State . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337


CONTENTS vii

10.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33810.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33810.10Conditional Rendering . . . . . . . . . . . . . . . . . . . . . . . 338

11 Programmable Vertex Processing 34011.1 Vertex Shaders . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

11.1.1 Vertex Attributes . . . . . . . . . . . . . . . . . . . . . . 34011.1.2 Vertex Shader Variables . . . . . . . . . . . . . . . . . . 34611.1.3 Shader Execution . . . . . . . . . . . . . . . . . . . . . . 351

11.2 Tessellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36211.2.1 Tessellation Control Shaders . . . . . . . . . . . . . . . . 36311.2.2 Tessellation Primitive Generation . . . . . . . . . . . . . 36811.2.3 Tessellation Evaluation Shaders . . . . . . . . . . . . . . 377

11.3 Geometry Shaders . . . . . . . . . . . . . . . . . . . . . . . . . . 38211.3.1 Geometry Shader Input Primitives . . . . . . . . . . . . . 38311.3.2 Geometry Shader Output Primitives . . . . . . . . . . . . 38411.3.3 Geometry Shader Variables . . . . . . . . . . . . . . . . . 38511.3.4 Geometry Shader Execution Environment . . . . . . . . . 385

12 392

13 Fixed-Function Vertex Post-Processing 39313.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39313.2 Transform Feedback . . . . . . . . . . . . . . . . . . . . . . . . 394

13.2.1 Transform Feedback Objects . . . . . . . . . . . . . . . . 39413.2.2 Transform Feedback Primitive Capture . . . . . . . . . . 39613.2.3 Transform Feedback Draw Operations . . . . . . . . . . . 400

13.3 Primitive Queries . . . . . . . . . . . . . . . . . . . . . . . . . . 40213.4 Flatshading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40213.5 Primitive Clipping . . . . . . . . . . . . . . . . . . . . . . . . . . 404

13.5.1 Clipping Shader Outputs . . . . . . . . . . . . . . . . . . 40513.5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

13.6 Coordinate Transformations . . . . . . . . . . . . . . . . . . . . 40613.6.1 Controlling the Viewport . . . . . . . . . . . . . . . . . . 406

13.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

14 Fixed-Function Primitive Assembly and Rasterization 41114.1 Discarding Primitives Before Rasterization . . . . . . . . . . . . 41214.2 Invariance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41314.3 Antialiasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413


CONTENTS viii

14.3.1 Multisampling . . . . . . . . . . . . . . . . . . . . . . . 41414.4 Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

14.4.1 Basic Point Rasterization . . . . . . . . . . . . . . . . . . 41814.4.2 Point Rasterization State . . . . . . . . . . . . . . . . . . 41914.4.3 Point Multisample Rasterization . . . . . . . . . . . . . . 419

14.5 Line Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . 41914.5.1 Basic Line Segment Rasterization . . . . . . . . . . . . . 42014.5.2 Other Line Segment Features . . . . . . . . . . . . . . . . 42214.5.3 Line Rasterization State . . . . . . . . . . . . . . . . . . 42514.5.4 Line Multisample Rasterization . . . . . . . . . . . . . . 425

14.6 Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42514.6.1 Basic Polygon Rasterization . . . . . . . . . . . . . . . . 42514.6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42814.6.3 Antialiasing . . . . . . . . . . . . . . . . . . . . . . . . . 42814.6.4 Options Controlling Polygon Rasterization . . . . . . . . 42914.6.5 Depth Offset . . . . . . . . . . . . . . . . . . . . . . . . 42914.6.6 Polygon Multisample Rasterization . . . . . . . . . . . . 43014.6.7 Polygon Rasterization State . . . . . . . . . . . . . . . . 431

14.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43114.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43114.9 Early Per-Fragment Tests . . . . . . . . . . . . . . . . . . . . . . 432

15 Programmable Fragment Processing 43315.1 Fragment Shader Variables . . . . . . . . . . . . . . . . . . . . . 43315.2 Shader Execution . . . . . . . . . . . . . . . . . . . . . . . . . . 434

15.2.1 Texture Access . . . . . . . . . . . . . . . . . . . . . . . 43515.2.2 Shader Inputs . . . . . . . . . . . . . . . . . . . . . . . . 43615.2.3 Shader Outputs . . . . . . . . . . . . . . . . . . . . . . . 43815.2.4 Early Fragment Tests . . . . . . . . . . . . . . . . . . . . 442

16 443

17 Writing Fragments and Samples to the Framebuffer 44417.1 Antialiasing Application . . . . . . . . . . . . . . . . . . . . . . 44417.2 Multisample Point Fade . . . . . . . . . . . . . . . . . . . . . . . 44417.3 Per-Fragment Operations . . . . . . . . . . . . . . . . . . . . . . 445

17.3.1 Pixel Ownership Test . . . . . . . . . . . . . . . . . . . . 44517.3.2 Scissor Test . . . . . . . . . . . . . . . . . . . . . . . . . 44617.3.3 Multisample Fragment Operations . . . . . . . . . . . . . 44817.3.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450


CONTENTS ix

17.3.5 Stencil Test . . . . . . . . . . . . . . . . . . . . . . . . . 45017.3.6 Depth Buffer Test . . . . . . . . . . . . . . . . . . . . . . 45117.3.7 Occlusion Queries . . . . . . . . . . . . . . . . . . . . . 45217.3.8 Blending . . . . . . . . . . . . . . . . . . . . . . . . . . 45317.3.9 sRGB Conversion . . . . . . . . . . . . . . . . . . . . . 46017.3.10 Dithering . . . . . . . . . . . . . . . . . . . . . . . . . . 46017.3.11 Logical Operation . . . . . . . . . . . . . . . . . . . . . 46117.3.12 Additional Multisample Fragment Operations . . . . . . . 463

17.4 Whole Framebuffer Operations . . . . . . . . . . . . . . . . . . . 46417.4.1 Selecting Buffers for Writing . . . . . . . . . . . . . . . . 46417.4.2 Fine Control of Buffer Updates . . . . . . . . . . . . . . 46817.4.3 Clearing the Buffers . . . . . . . . . . . . . . . . . . . . 47017.4.4 Invalidating Framebuffer Contents . . . . . . . . . . . . . 47317.4.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

18 Reading and Copying Pixels 47518.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47518.2 Reading Pixels . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

18.2.1 Selecting Buffers for Reading . . . . . . . . . . . . . . . 47518.2.2 ReadPixels . . . . . . . . . . . . . . . . . . . . . . . . . 47718.2.3 Obtaining Pixels from the Framebuffer . . . . . . . . . . 47718.2.4 Conversion of RGBA values . . . . . . . . . . . . . . . . 48018.2.5 Conversion of Depth values . . . . . . . . . . . . . . . . 48018.2.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48018.2.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48018.2.8 Final Conversion . . . . . . . . . . . . . . . . . . . . . . 48018.2.9 Placement in Pixel Pack Buffer or Client Memory . . . . . 481

18.3 Copying Pixels . . . . . . . . . . . . . . . . . . . . . . . . . . . 48318.3.1 Blitting Pixel Rectangles . . . . . . . . . . . . . . . . . . 48318.3.2 Copying Between Images . . . . . . . . . . . . . . . . . 487

18.4 Pixel Draw and Read State . . . . . . . . . . . . . . . . . . . . . 489

19 Compute Shaders 49119.1 Compute Shader Variables . . . . . . . . . . . . . . . . . . . . . 493

20 Debug Output 49420.1 Debug Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 49520.2 Debug Message Callback . . . . . . . . . . . . . . . . . . . . . . 49720.3 Debug Message Log . . . . . . . . . . . . . . . . . . . . . . . . 49820.4 Controlling Debug Messages . . . . . . . . . . . . . . . . . . . . 498


CONTENTS x

20.5 Externally Generated Messages . . . . . . . . . . . . . . . . . . . 50020.6 Debug Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50020.7 Debug Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50220.8 Asynchronous and Synchronous Debug Output . . . . . . . . . . 50320.9 Debug Output Queries . . . . . . . . . . . . . . . . . . . . . . . 504

21 Special Functions 50721.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50721.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50721.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50721.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50721.5 Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50721.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

22 Context State Queries 50922.1 Simple Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 50922.2 String Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51122.3 Internal Format Queries . . . . . . . . . . . . . . . . . . . . . . . 513

22.3.1 Supported Operation Queries . . . . . . . . . . . . . . . . 51422.3.2 Other Internal Format Queries . . . . . . . . . . . . . . . 517

23 State Tables 525

A Invariance 600A.1 Repeatability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600A.2 Multi-pass Algorithms . . . . . . . . . . . . . . . . . . . . . . . 601A.3 Invariance Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . 601A.4 Tessellation Invariance . . . . . . . . . . . . . . . . . . . . . . . 603A.5 Atomic Counter Invariance . . . . . . . . . . . . . . . . . . . . . 605A.6 What All This Means . . . . . . . . . . . . . . . . . . . . . . . . 606

B Corollaries 607

C Compressed Texture Image Formats 609C.1 RGTC Compressed Texture Image Formats . . . . . . . . . . . . 609

C.1.1 Format COMPRESSED_RED_RGTC1 . . . . . . . . . . . . 610C.1.2 Format COMPRESSED_SIGNED_RED_RGTC1 . . . . . . . 611C.1.3 Format COMPRESSED_RG_RGTC2 . . . . . . . . . . . . . 611C.1.4 Format COMPRESSED_SIGNED_RG_RGTC2 . . . . . . . . 612

C.2 BPTC Compressed Texture Image Formats . . . . . . . . . . . . 612


CONTENTS xi

C.2.1 Formats COMPRESSED_RGBA_BPTC_UNORM andCOMPRESSED_SRGB_ALPHA_BPTC_UNORM . . . . . . . . 613

C.2.2 Formats COMPRESSED_RGB_BPTC_SIGNED_FLOAT andCOMPRESSED_RGB_BPTC_UNSIGNED_FLOAT . . . . . . 619

C.3 ETC Compressed Texture Image Formats . . . . . . . . . . . . . 621C.3.1 Format COMPRESSED_RGB8_ETC2 . . . . . . . . . . . . 625C.3.2 Format COMPRESSED_SRGB8_ETC2 . . . . . . . . . . . . 632C.3.3 Format COMPRESSED_RGBA8_ETC2_EAC . . . . . . . . . 632C.3.4 Format COMPRESSED_SRGB8_ALPHA8_ETC2_EAC . . . . 635C.3.5 Format COMPRESSED_R11_EAC . . . . . . . . . . . . . . 635C.3.6 Format COMPRESSED_RG11_EAC . . . . . . . . . . . . . 638C.3.7 Format COMPRESSED_SIGNED_R11_EAC . . . . . . . . . 639C.3.8 Format COMPRESSED_SIGNED_RG11_EAC . . . . . . . . 642C.3.9 Format

COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2 . . 642C.3.10 Format

COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2 . 649

D Profiles and the Deprecation Model 650D.1 Core and Compatibility Profiles . . . . . . . . . . . . . . . . . . 651D.2 Deprecated and Removed Features . . . . . . . . . . . . . . . . . 651

D.2.1 Deprecated But Still Supported Features . . . . . . . . . . 651D.2.2 Removed Features . . . . . . . . . . . . . . . . . . . . . 652

E Version 4.2 657E.1 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657E.2 Deprecation Model . . . . . . . . . . . . . . . . . . . . . . . . . 658E.3 Changed Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . 658E.4 Change Log for Released Specifications . . . . . . . . . . . . . . 659E.5 Credits and Acknowledgements . . . . . . . . . . . . . . . . . . 661

F Version 4.3 664F.1 Restructuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664F.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665F.3 Deprecation Model . . . . . . . . . . . . . . . . . . . . . . . . . 666F.4 Changed Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . 666F.5 Change Log for Released Specifications . . . . . . . . . . . . . . 667F.6 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674F.7 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 676


CONTENTS xii

G Version 4.4 677G.1 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677G.2 Deprecation Model . . . . . . . . . . . . . . . . . . . . . . . . . 678G.3 Change Log for Released Specifications . . . . . . . . . . . . . . 678G.4 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689G.5 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 690

H OpenGL Registry, Header Files, and ARB Extensions 691H.1 OpenGL Registry . . . . . . . . . . . . . . . . . . . . . . . . . . 691H.2 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691H.3 ARB and Khronos Extensions . . . . . . . . . . . . . . . . . . . 692

H.3.1 Naming Conventions . . . . . . . . . . . . . . . . . . . . 693H.3.2 Promoting Extensions to Core Features . . . . . . . . . . 693H.3.3 Extension Summaries . . . . . . . . . . . . . . . . . . . 693H.3.4 Bindless Textures . . . . . . . . . . . . . . . . . . . . . . 717H.3.5 Compute Variable Group Size . . . . . . . . . . . . . . . 717H.3.6 Indirect Parameters . . . . . . . . . . . . . . . . . . . . . 717H.3.7 Seamless Cubemap per Texture . . . . . . . . . . . . . . 717H.3.8 Shader Draw Parameters . . . . . . . . . . . . . . . . . . 717H.3.9 Shader Group Vote . . . . . . . . . . . . . . . . . . . . . 717H.3.10 Sparse Textures . . . . . . . . . . . . . . . . . . . . . . . 718


List of Figures

3.1 Block diagram of the GL pipeline. . . . . . . . . . . . . . . . . . 31

8.1 Transfer of pixel rectangles. . . . . . . . . . . . . . . . . . . . . 1708.2 Selecting a subimage from an image . . . . . . . . . . . . . . . . 1758.3 A texture image and the coordinates used to access it. . . . . . . . 1968.4 Example of the components returned for textureGather. . . . . 232

10.1 Vertex processing and primitive assembly. . . . . . . . . . . . . . 30010.2 Triangle strips, fans, and independent triangles. . . . . . . . . . . 30310.3 Lines with adjacency. . . . . . . . . . . . . . . . . . . . . . . . . 30410.4 Triangles with adjacency. . . . . . . . . . . . . . . . . . . . . . . 30610.5 Triangle strips with adjacency. . . . . . . . . . . . . . . . . . . . 307

11.1 Domain parameterization for tessellation. . . . . . . . . . . . . . 36811.2 Inner triangle tessellation. . . . . . . . . . . . . . . . . . . . . . . 37211.3 Inner quad tessellation. . . . . . . . . . . . . . . . . . . . . . . . 37511.4 Isoline tessellation. . . . . . . . . . . . . . . . . . . . . . . . . . 377

14.1 Rasterization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41114.2 Visualization of Bresenham’s algorithm. . . . . . . . . . . . . . . 42114.3 Rasterization of non-antialiased wide lines. . . . . . . . . . . . . 42314.4 The region used in rasterizing an antialiased line segment. . . . . 424

17.1 Per-fragment operations. . . . . . . . . . . . . . . . . . . . . . . 445

18.1 Operation of ReadPixels. . . . . . . . . . . . . . . . . . . . . . . 475

xiii

List of Tables

2.1 GL command suffixes . . . . . . . . . . . . . . . . . . . . . . . . 122.2 GL data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 Summary of GL errors . . . . . . . . . . . . . . . . . . . . . . . 17

4.1 Initial properties of a sync object created with FenceSync. . . . . 34

6.1 Buffer object binding targets. . . . . . . . . . . . . . . . . . . . . 556.2 Buffer object parameters and their values. . . . . . . . . . . . . . 556.3 Buffer object state. . . . . . . . . . . . . . . . . . . . . . . . . . 616.4 Buffer object state set by MapBufferRange. . . . . . . . . . . . 686.5 Indexed buffer object limits and binding queries . . . . . . . . . . 75

7.1 CreateShader type values and the corresponding shader stages. . 797.2 GetProgramResourceiv properties and supported interfaces . . . 997.3 OpenGL Shading Language type tokens . . . . . . . . . . . . . . 1067.4 Query targets for default uniform block storage, in components. . 1187.5 Query targets for combined uniform block storage, in components. 1187.6 GetProgramResourceiv properties used by GetActiveUniformsiv. 1227.7 GetProgramResourceiv properties used by GetActiveUniform-

Blockiv. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1237.8 GetProgramResourceiv properties used by GetActiveAtomic-

CounterBufferiv. . . . . . . . . . . . . . . . . . . . . . . . . . . 1257.9 Interfaces for active subroutines . . . . . . . . . . . . . . . . . . 1387.10 Interfaces for active subroutine uniforms . . . . . . . . . . . . . . 138

8.1 PixelStore* parameters. . . . . . . . . . . . . . . . . . . . . . . 1698.2 Pixel data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738.3 Pixel data formats. . . . . . . . . . . . . . . . . . . . . . . . . . 1748.4 Swap Bytes bit ordering. . . . . . . . . . . . . . . . . . . . . . . 1748.5 Packed pixel formats. . . . . . . . . . . . . . . . . . . . . . . . . 177

xiv

LIST OF TABLES xv

8.6 UNSIGNED_BYTE formats. Bit numbers are indicated for eachcomponent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

8.7 UNSIGNED_SHORT formats . . . . . . . . . . . . . . . . . . . . . 1798.8 UNSIGNED_INT formats . . . . . . . . . . . . . . . . . . . . . . 1808.9 FLOAT_UNSIGNED_INT formats . . . . . . . . . . . . . . . . . . 1818.10 Packed pixel field assignments. . . . . . . . . . . . . . . . . . . . 1828.11 Conversion from RGBA, depth, and stencil pixel components to

internal texture components. . . . . . . . . . . . . . . . . . . . . 1858.12 Sized internal color formats. . . . . . . . . . . . . . . . . . . . . 1908.13 Sized internal depth and stencil formats. . . . . . . . . . . . . . . 1918.14 Generic and specific compressed internal formats. . . . . . . . . . 1928.15 Internal formats for buffer textures . . . . . . . . . . . . . . . . . 2158.16 Texture parameters and their values. . . . . . . . . . . . . . . . . 2188.17 Texture, table, and filter return values. . . . . . . . . . . . . . . . 2248.18 Selection of cube map images. . . . . . . . . . . . . . . . . . . . 2268.19 Texel location wrap mode application. . . . . . . . . . . . . . . . 2308.20 Legal texture targets for TextureView. . . . . . . . . . . . . . . . 2418.21 Compatible internal formats for TextureView . . . . . . . . . . . 2428.22 Depth texture comparison functions. . . . . . . . . . . . . . . . . 2568.23 sRGB texture internal formats. . . . . . . . . . . . . . . . . . . . 2578.24 Mapping of image load, store, and atomic texel coordinate compo-

nents to texel numbers. . . . . . . . . . . . . . . . . . . . . . . . 2618.25 Supported image unit formats, with equivalent format layout qual-

ifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2648.26 Texel sizes, compatibility classes, and pixel format/type combina-

tions for each image format. . . . . . . . . . . . . . . . . . . . . 266

9.1 Framebuffer attachment points. . . . . . . . . . . . . . . . . . . . 2839.2 Layer numbers for cube map texture faces. . . . . . . . . . . . . . 298

10.1 Triangles generated by triangle strips with adjacency. . . . . . . . 30810.2 Vertex array sizes (values per vertex) and data types for generic

vertex attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 31410.3 Packed component layout for non-BGRA formats. . . . . . . . . . 32110.4 Packed component layout for BGRA format. . . . . . . . . . . . . 32110.5 Packed component layout for UNSIGNED_INT_10F_11F_11F_-

REV format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32210.6 Indirect commands and corresponding indirect buffer targets. . . . 323

11.1 Generic attribute components accessed by attribute variables. . . . 341


LIST OF TABLES xvi

11.2 Generic attributes and vector types used by column vectors of ma-trix variables bound to generic attribute index i. . . . . . . . . . . 342

11.3 Scalar and vector vertex attribute types . . . . . . . . . . . . . . . 342

13.1 Transform feedback modes . . . . . . . . . . . . . . . . . . . . . 39813.2 Provoking vertex selection. . . . . . . . . . . . . . . . . . . . . . 403

15.1 Correspondence of filtered texture components to texture basecomponents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

17.1 RGB and alpha blend equations. . . . . . . . . . . . . . . . . . . 45617.2 Blending functions. . . . . . . . . . . . . . . . . . . . . . . . . . 45817.3 Logical operations . . . . . . . . . . . . . . . . . . . . . . . . . 46217.4 Buffer selection for the default framebuffer . . . . . . . . . . . . 46517.5 Buffer selection for a framebuffer object . . . . . . . . . . . . . . 46517.6 DrawBuffers buffer selection for the default framebuffer . . . . . 466

18.1 PixelStore parameters. . . . . . . . . . . . . . . . . . . . . . . . 47818.2 ReadPixels GL data types and reversed component conversion for-

mulas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48218.3 ReadPixels index masks. . . . . . . . . . . . . . . . . . . . . . . 48318.4 Compatible internal formats for copying . . . . . . . . . . . . . . 489

20.1 Sources of debug output messages . . . . . . . . . . . . . . . . . 49520.2 Types of debug output messages . . . . . . . . . . . . . . . . . . 49620.3 Severity levels of messages . . . . . . . . . . . . . . . . . . . . . 49620.4 Object namespace identifiers . . . . . . . . . . . . . . . . . . . . 502

21.1 Hint targets and descriptions . . . . . . . . . . . . . . . . . . . . 508

22.1 Context profile bits . . . . . . . . . . . . . . . . . . . . . . . . . 51222.2 Internal format targets . . . . . . . . . . . . . . . . . . . . . . . . 514

23.1 State Variable Types . . . . . . . . . . . . . . . . . . . . . . . . . 52623.2 Current Values and Associated Data . . . . . . . . . . . . . . . . 52723.3 Vertex Array Object State (cont.) . . . . . . . . . . . . . . . . . . 52823.4 Vertex Array Object State (cont.)

† The ith attribute defaults to a value of i. . . . . . . . . . . . 52923.5 Vertex Array Data (not in Vertex Array objects) . . . . . . . . . . 53023.6 Buffer Object State . . . . . . . . . . . . . . . . . . . . . . . . . 53123.7 Transformation state . . . . . . . . . . . . . . . . . . . . . . . . 53223.8 Coloring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533


LIST OF TABLES xvii

23.9 Rasterization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53423.10Rasterization (cont.) . . . . . . . . . . . . . . . . . . . . . . . . . 53523.11Multisampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53623.12Textures (state per texture unit) . . . . . . . . . . . . . . . . . . . 53723.13Textures (state per texture unit (cont.) . . . . . . . . . . . . . . . 53823.14Textures (state per texture object) . . . . . . . . . . . . . . . . . . 53923.15Textures (state per texture object) (cont.) . . . . . . . . . . . . . . 54023.16Textures (state per texture image) . . . . . . . . . . . . . . . . . . 54123.17Textures (state per texture image) (cont.) . . . . . . . . . . . . . . 54223.18Textures (state per sampler object) . . . . . . . . . . . . . . . . . 54323.19Texture Environment and Generation . . . . . . . . . . . . . . . . 54423.20Pixel Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 54523.21Pixel Operations (cont.) . . . . . . . . . . . . . . . . . . . . . . . 54623.22Framebuffer Control . . . . . . . . . . . . . . . . . . . . . . . . 54723.23Framebuffer (state per target binding point) . . . . . . . . . . . . 54823.24Framebuffer (state per framebuffer object)

† This state is queried from the currently bound read framebuffer.54923.25Framebuffer (state per attachment point) . . . . . . . . . . . . . . 55023.26Renderbuffer (state per target and binding point) . . . . . . . . . . 55123.27Renderbuffer (state per renderbuffer object) . . . . . . . . . . . . 55223.28Pixels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55323.29Pixels (cont.) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55423.30Shader Object State . . . . . . . . . . . . . . . . . . . . . . . . . 55523.31Program Pipeline Object State . . . . . . . . . . . . . . . . . . . 55623.32Program Object State . . . . . . . . . . . . . . . . . . . . . . . . 55723.33Program Object State (cont.) . . . . . . . . . . . . . . . . . . . . 55823.34Program Object State (cont.) . . . . . . . . . . . . . . . . . . . . 55923.35Program Object State (cont.) . . . . . . . . . . . . . . . . . . . . 56023.36Program Object State (cont.) . . . . . . . . . . . . . . . . . . . . 56123.37Program Object State (cont.) . . . . . . . . . . . . . . . . . . . . 56223.38Program Object State (cont.) . . . . . . . . . . . . . . . . . . . . 56323.39Program Object State (cont.) . . . . . . . . . . . . . . . . . . . . 56423.40Program Interface State . . . . . . . . . . . . . . . . . . . . . . . 56523.41Program Object Resource State . . . . . . . . . . . . . . . . . . . 56623.42Program Object Resource State (cont.) . . . . . . . . . . . . . . . 56723.43Vertex and Geometry Shader State (not part of program objects) . 56823.44Query Object State . . . . . . . . . . . . . . . . . . . . . . . . . 56923.45Image State (state per image unit) . . . . . . . . . . . . . . . . . 57023.46Atomic Counter Buffer Binding State . . . . . . . . . . . . . . . 57123.47Shader Storage Buffer Binding State . . . . . . . . . . . . . . . . 572


LIST OF TABLES xviii

23.48Transform Feedback State . . . . . . . . . . . . . . . . . . . . . 57323.49Uniform Buffer Binding State . . . . . . . . . . . . . . . . . . . 57423.50Sync (state per sync object) . . . . . . . . . . . . . . . . . . . . . 57523.51Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57623.52Compute Dispatch State . . . . . . . . . . . . . . . . . . . . . . 57723.53Implementation Dependent Values . . . . . . . . . . . . . . . . . 57823.54Implementation Dependent Values (cont.) . . . . . . . . . . . . . 57923.55Implementation Dependent Values (cont.) . . . . . . . . . . . . . 58023.56Implementation Dependent Version and Extension Support . . . . 58123.57Implementation Dependent Vertex Shader Limits . . . . . . . . . 58223.58Implementation Dependent Tessellation Shader Limits . . . . . . 58323.59Implementation Dependent Tessellation Shader Limits (cont.) . . 58423.60Implementation Dependent Geometry Shader Limits . . . . . . . 58523.61Implementation Dependent Fragment Shader Limits . . . . . . . . 58623.62Implementation Dependent Compute Shader Limits . . . . . . . . 58723.63Implementation Dependent Aggregate Shader Limits . . . . . . . 58823.64Implementation Dependent Aggregate Shader Limits (cont.) . . . 58923.65Implementation Dependent Aggregate Shader Limits (cont.) . . . 59023.66Implementation Dependent Aggregate Shader Limits (cont.)

† The minimum value for each stage isMAX_stage_UNIFORM_BLOCKS × MAX_UNIFORM_BLOCK_SIZE/ 4 + MAX_stage_UNIFORM_COMPONENTS . . . . . . . . . . . 591

23.67Debug Output State† The initial value of DEBUG_OUTPUT is TRUE in a debug con-

text and FALSE in a non-debug context. . . . . . . . . . . . . . . 59223.68Implementation Dependent Debug Output State . . . . . . . . . . 59323.69Implementation Dependent Values (cont.) . . . . . . . . . . . . . 59423.70Implementation Dependent Values (cont.) . . . . . . . . . . . . . 59523.71Internal Format Dependent Values . . . . . . . . . . . . . . . . . 59623.72Implementation Dependent Transform Feedback Limits . . . . . . 59723.73Framebuffer Dependent Values . . . . . . . . . . . . . . . . . . . 59823.74Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

C.1 Mode-dependent BPTC parameters . . . . . . . . . . . . . . . . . 615C.2 Partition table for 2 subset . . . . . . . . . . . . . . . . . . . . . 616C.3 Partition table for 3 subset . . . . . . . . . . . . . . . . . . . . . 617C.4 Anchor index values for the second subset of two-subset partitioning618C.5 Anchor index values for the second subset of three-subset partitioning618C.6 Anchor index values for the third subset of three-subset partitioning 618C.7 Endpoint and partition parameters for block modes . . . . . . . . 621


LIST OF TABLES xix

C.8 Block formats for block modes . . . . . . . . . . . . . . . . . . . 622C.9 Pixel layout for a 8 × 8 texture using four COMPRESSED_RGB8_-

ETC2 compressed blocks. . . . . . . . . . . . . . . . . . . . . . . 624C.10 Pixel layout for an COMPRESSED_RGB8_ETC2 compressed block. 626C.11 Texel Data format for RGB8_ETC2 compressed textures formats . 627C.12 Two 2× 4-pixel subblocks side-by-side. . . . . . . . . . . . . . . 628C.13 Two 4× 2-pixel subblocks on top of each other. . . . . . . . . . . 628C.14 Intensity modifier sets for ‘individual’ and ‘differential’ modes: . . 629C.15 Mapping from pixel index values to modifier values for

COMPRESSED_RGB8_ETC2 compressed textures . . . . . . . . . . 630C.16 Distance table for ‘T’ and ‘H’ modes. . . . . . . . . . . . . . . . 631C.17 Texel Data format for alpha part of COMPRESSED_RGBA8_ETC2_-

EAC compressed textures. . . . . . . . . . . . . . . . . . . . . . . 633C.18 Intensity modifier sets for alpha component. . . . . . . . . . . . . 634C.19 Texel Data format for RGB8_PUNCHTHROUGH_ALPHA1_ETC2

compressed textures formats . . . . . . . . . . . . . . . . . . . . 643C.20 Intensity modifier sets if ‘opaque’ is set and if ‘opaque’ is unset. . 645C.21 Mapping from pixel index values to modifier values for

COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2 compressedtextures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646

E.1 New token names . . . . . . . . . . . . . . . . . . . . . . . . . . 659

F.1 New token names . . . . . . . . . . . . . . . . . . . . . . . . . . 667


Chapter 1

Introduction

This document, referred to as the “OpenGL Specification” or just “Specification”hereafter, describes the OpenGL graphics system: what it is, how it acts, and whatis required to implement it. We assume that the reader has at least a rudimentaryunderstanding of computer graphics. This means familiarity with the essentialsof computer graphics algorithms and terminology as well as with modern GPUs(Graphic Processing Units).

The canonical version of the Specification is available in the official OpenGLRegistry, located at URL

http://www.opengl.org/registry/

1.1 Formatting of the OpenGL Specification

Starting with version 4.3, the OpenGL Specification has undergone major restruc-turing to focus on programmable shading, and to describe important concepts andobjects in the context of the entire API before describing details of their use in thegraphics pipeline.

1.1.1

This subsection is only defined in the compatibility profile.

1.1.2

This subsection is only defined in the compatibility profile.

1

http://www.opengl.org/registry/

1.2. WHAT IS THE OPENGL GRAPHICS SYSTEM? 2

1.2 What is the OpenGL Graphics System?

OpenGL (for “Open Graphics Library”) is an API (Application Programming Inter-face) to graphics hardware. The API consists of a set of several hundred proceduresand functions that allow a programmer to specify the shader programs, objects, andoperations involved in producing high-quality graphical images, specifically colorimages of three-dimensional objects.

Most of OpenGL requires that the graphics hardware contain a framebuffer.Many OpenGL calls control drawing geometric objects such as points, lines, andpolygons, but the way that some of this drawing occurs (such as when antialiasingor multisampling is in use) relies on the existence of a framebuffer and its proper-ties. Some commands explicitly manage the framebuffer.

1.2.1 Programmer’s View of OpenGL

To the programmer, OpenGL is a set of commands that allow the specification ofshader programs or shaders, data used by shaders, and state controlling aspects ofOpenGL outside the scope of shaders. Typically the data represent geometry in twoor three dimensions and texture images, while the shaders control the geometricprocessing, rasterization of geometry and the lighting and shading of fragmentsgenerated by rasterization, resulting in rendering geometry into the framebuffer.

A typical program that uses OpenGL begins with calls to open a window intothe framebuffer into which the program will draw. Then, calls are made to allocatean OpenGL context and associate it with the window. Once a context is allocated,OpenGL commands to define shaders, geometry, and textures are made, followedby commands which draw geometry by transferring specified portions of the geom-etry to the shaders. Drawing commands specify simple geometric objects such aspoints, line segments, and polygons, which can be further manipulated by shaders.There are also commands which directly control the framebuffer by reading andwriting pixels.

1.2.2 Implementor’s View of OpenGL

To the implementor, OpenGL is a set of commands that control the operation ofthe GPU. Modern GPUs accelerate almost all OpenGL operations, storing dataand framebuffer images in GPU memory and executing shaders in dedicated GPUprocessors. However, OpenGL may be implemented on less capable GPUs, or evenwithout a GPU, by moving some or all operations into the host CPU.

The implementor’s task is to provide a software library on the CPU whichimplements the OpenGL API, while dividing the work for each OpenGL command


1.2. WHAT IS THE OPENGL GRAPHICS SYSTEM? 3

between the CPU and the graphics hardware as appropriate for the capabilities ofthe GPU.

OpenGL contains a considerable amount of information including many typesof objects representing programmable shaders and the data they consume andgenerate, as well as other context state controlling non-programmable aspects ofOpenGL. Most of these objects and state are available to the programmer, who canset, manipulate, and query their values through OpenGL commands. Some of it,however, is derived state visible only by the effect it has on how OpenGL oper-ates. One of the main goals of this Specification is to describe OpenGL objectsand context state explicitly, to elucidate how they change in response to OpenGLcommands, and to indicate what their effects are.

1.2.3 Our View

We view OpenGL as a pipeline having some programmable stages and some state-driven fixed-function stages that are invoked by a set of specific drawing opera-tions. This model should engender a specification that satisfies the needs of bothprogrammers and implementors. It does not, however, necessarily provide a modelfor implementation. An implementation must produce results conforming to thoseproduced by the specified methods, but there may be ways to carry out a particularcomputation that are more efficient than the one specified.

1.2.4 Fixed-function Hardware and the Compatibility Profile

Older generations of graphics hardware were not programmable using shaders,although they were configurable by setting state controlling specific details of theiroperation. The compatibility profile of OpenGL continues to support the legacyOpenGL commands developed for such fixed-function hardware, although theyare typically implemented by writing shaders which reproduce the operation ofsuch hardware. Fixed-function OpenGL commands and operations are describedas alternative interfaces following descriptions of the corresponding shader stages.

1.2.5 The Deprecation Model

Features marked as deprecated in one version of the Specification are expected tobe removed in a future version, allowing applications time to transition away fromuse of deprecated features. The deprecation model is described in more detail,together with a summary of the commands and state deprecated from this versionof the API, in appendix D.


1.3. RELATED APIS 4

1.3 Related APIs

Other APIs related to OpenGL are described below. Most of the specifications forthese APIs are available on the Khronos Group websites, although some vendor-specific APIs are documented on that vendor’s developer website.

1.3.1 OpenGL Shading Language

The OpenGL Specification should be read together with a companion documenttitled The OpenGL Shading Language. The latter document (referred to as theOpenGL Shading Language Specification hereafter) defines the syntax and seman-tics of the programming language used to write shaders (see chapter 7). Descrip-tions of shaders later in this document may include references to concepts andterms (such as shading language variable types) defined in the OpenGL ShadingLanguage Specification.

OpenGL 4.4 implementations are guaranteed to support version 4.40 of theOpenGL Shading Language. All references to sections of that specification refer tothat version. The latest supported version of the shading language may be queriedas described in section 22.2.

The core profile of OpenGL 4.4 is also guaranteed to support all previous ver-sions of the OpenGL Shading Language back to version 1.40. In some implemen-tations the core profile may also support earlier versions of the Shading Language,and may support compatibility profile versions of the Shading Language for ver-sions 1.40 and earlier. In this case, errors will be generated when using languagefeatures such as compatibility profile built-ins not supported by the core profileAPI. The #version strings for all supported versions of the OpenGL ShadingLanguage may be queried as described in section 22.2.

The OpenGL Shading Language Specification is available in the OpenGL Reg-istry.

1.3.2 OpenGL ES

OpenGL ES is a royalty-free, cross-platform API for full-function 2D and 3Dgraphics on embedded systems such as mobile phones, game consoles, and ve-hicles. It consists of well-defined subsets of OpenGL. OpenGL ES version 1.1implements a subset of the OpenGL 1.5 fixed-function API, OpenGL ES 2.0 im-plements a subset of the OpenGL 2.0 shader-based API, and OpenGL ES 3.0 imple-ments a subset of OpenGL 3.3. OpenGL ES versions also include some additionalfunctionality taken from later OpenGL versions or specific to OpenGL ES. It is


1.3. RELATED APIS 5

straightforward to port code written for OpenGL ES to corresponding versions ofOpenGL.

OpenGL and OpenGL ES are developed in parallel within the Khronos Group,which controls both standards.

OpenGL 4.3 includes functionality initially defined in OpenGL ES 3.0, forincreased compatibility between OpenGL and OpenGL ES implementations.

The OpenGL ES Specifications are available in the Khronos API Registry atURL

http://www.khronos.org/registry/

1.3.3 OpenGL ES Shading Language

The Specification should also be read together with companion documents titledThe OpenGL ES Shading Language. Both versions 1.00 and 3.00 should be read.These documents define versions of the OpenGL Shading Language designed forimplementations of OpenGL ES 2.0 and 3.0 respectively, but also supported byOpenGL implementations. References to the OpenGL Shading Language Speci-fication hereafter include both OpenGL and OpenGL ES versions of the ShadingLanguage; references to specific sections are to those sections in version 4.40 ofthe OpenGL Shading Language Specification.

OpenGL 4.4 implementations are guaranteed to support both versions 1.00 and3.00 of the OpenGL ES Shading Language.

The #version strings for all supported versions of the OpenGL Shading Lan-guage may be queried as described in section 22.2.

The OpenGL ES Shading Language Specifications are available in the KhronosAPI Registry.

1.3.4 WebGL

WebGL is a cross-platform, royalty-free web standard for a low-level 3D graph-ics API based on OpenGL ES 2.0. Developers familiar with OpenGL ES 2.0 willrecognize WebGL as a shader-based API using a form of the OpenGL ShadingLanguage, with constructs that are semantically similar to those of the underly-ing OpenGL ES 2.0 API. It stays very close to the OpenGL ES 2.0 specification,with some concessions made for what developers expect out of memory-managedlanguages such as JavaScript.

The WebGL Specification and related documentation are available in theKhronos API Registry.


http://www.khronos.org/registry/

1.3. RELATED APIS 6

1.3.5 Window System Bindings

OpenGL requires a companion API to create and manage graphics contexts, win-dows to render into, and other resources beyond the scope of this Specification.There are several such APIs supporting different operating and window systems.

1.3.5.1 GLX - X Window System Bindings

OpenGL Graphics with the X Window System, referred to as the GLX Specificationhereafter, describes the GLX API for use of OpenGL in the X Window System. It isprimarily directed at Linux and Unix systems, but GLX implementations also existfor Microsoft Windows, MacOS X, and some other platforms where X is available.The GLX Specification is available in the OpenGL Registry.

1.3.5.2 WGL - Microsoft Windows Bindings

The WGL API supports use of OpenGL with Microsoft Windows. WGL is docu-mented in Microsoft’s MSDN system, although no full specification exists.

1.3.5.3 MacOS X Window System Bindings

Several APIs exist supporting use of OpenGL with Quartz, the MacOS X windowsystem, including CGL, AGL, and NSOpenGLView. These APIs are documentedon Apple’s developer website.

1.3.5.4 EGL - Mobile and Embedded Device Bindings

The Khronos Native Platform Graphics Interface or “EGL Specification” describesthe EGL API for use of OpenGL ES on mobile and embedded devices. EGL im-plementations supporting OpenGL may be available on some desktop platforms aswell. The EGL Specification is available in the Khronos API Registry.

1.3.6 OpenCL

OpenCL is an open, royalty-free standard for cross-platform, general-purpose par-allel programming of processors found in personal computers, servers, and mobiledevices, including GPUs. OpenCL defines interop methods to share OpenCL mem-ory and image objects with corresponding OpenGL buffer and texture objects, andto coordinate control of and transfer of data between OpenCL and OpenGL. Thisallows applications to split processing of data between OpenCL and OpenGL; forexample, by using OpenCL to implement a physics model and then rendering andinteracting with the resulting dynamic geometry using OpenGL.


1.4. FILING BUG REPORTS 7

The OpenCL Specification is available in the Khronos API Registry.

1.4 Filing Bug Reports

Bug reports on the OpenGL and OpenGL Shading Language Specifications can befiled in the Khronos Public Bugzilla, located at URL

http://www.khronos.org/bugzilla/Please file bugs against Product: OpenGL, Component: Specification, and the

appropriate version of the specification. It is best to file bugs against the most re-cently released versions, since older versions are usually not updated for bugfixes.


http://www.khronos.org/bugzilla/

Chapter 2

OpenGL Fundamentals

This chapter introduces fundamental concepts including the OpenGL executionmodel, API syntax, contexts and threads, numeric representation, context state andstate queries, and the different types of objects and shaders. It provides a frame-work for interpreting more specific descriptions of commands and behavior in theremainder of the Specification.

2.1 Execution Model

OpenGL (henceforth, “the GL”) is concerned only with processing data in GPUmemory, including rendering into a framebuffer and reading values stored in thatframebuffer. There is no support for other input or output devices. Programmersmust rely on other mechanisms to obtain user input.

The GL draws primitives processed by a variety of shader programs and fixed-function processing units controlled by context state. Each primitive is a point,line segment, patch, or polygon. Context state may be changed independently; thesetting of one piece of state does not affect the settings of others (although state andshader all interact to determine what eventually ends up in the framebuffer). Stateis set, primitives drawn, and other GL operations described by sending commandsin the form of function or procedure calls.

Primitives are defined by a group of one or more vertices. A vertex definesa point, an endpoint of a line segment, or a corner of a polygon where two edgesmeet. Data such as positional coordinates, colors, normals, texture coordinates, etc.are associated with a vertex and each vertex is processed independently, in order,and in the same way. The only exception to this rule is if the group of verticesmust be clipped so that the indicated primitive fits within a specified region; in thiscase vertex data may be modified and new vertices created. The type of clipping

8

2.1. EXECUTION MODEL 9

depends on which primitive the group of vertices represents.Commands are always processed in the order in which they are received, al-

though there may be an indeterminate delay before the effects of a command arerealized. This means, for example, that one primitive must be drawn completelybefore any subsequent one can affect the framebuffer. It also means that queriesand pixel read operations return state consistent with complete execution of allpreviously invoked GL commands, except where explicitly specified otherwise. Ingeneral, the effects of a GL command on either GL state or the framebuffer mustbe complete before any subsequent command can have any such effects.

Data binding occurs on call. This means that data passed to a GL commandare interpreted when that command is received. Even if the command requires apointer to data, those data are interpreted when the call is made, and any subsequentchanges to the data have no effect on the GL (unless the same pointer is used in asubsequent command).

The GL provides direct control over the fundamental operations of 3D and 2Dgraphics. This includes specification of parameters of application-defined shaderprograms performing transformation, lighting, texturing, and shading operations,as well as built-in functionality such as antialiasing and texture filtering. It does notprovide a means for describing or modeling complex geometric objects, althoughshaders can be written to generate such objects. In other words, OpenGL providesmechanisms to describe how complex geometric objects are to be rendered, ratherthan mechanisms to describe the complex objects themselves.

The model for interpretation of GL commands is client-server. That is, a pro-gram (the client) issues commands, and these commands are interpreted and pro-cessed by the GL (the server). The server may or may not operate on the samecomputer or in the same address space as the client. In this sense, the GL is net-work transparent. A server may maintain a number of GL contexts, each of whichis an encapsulation of current GL state and objects. A client may choose to bemade current to any one of these contexts.

Issuing GL commands when a program is not current to a context results inundefined behavior.

There are two classes of framebuffers: a window system-provided framebufferassociated with a context when the context is made current, and application-createdframebuffers. The window system-provided framebuffer is referred to as the de-fault framebuffer. Application-created framebuffers, referred to as framebuffer ob-jects, may be created as desired, A context may be associated with two frame-buffers, one for each of reading and drawing operations. The default framebufferand framebuffer objects are distinguished primarily by the interfaces for configur-ing and managing their state.

The effects of GL commands on the default framebuffer are ultimately con-


2.2. COMMAND SYNTAX 10

trolled by the window system, which allocates framebuffer resources, determineswhich portions of the default framebuffer the GL may access at any given time, andcommunicates to the GL how those portions are structured. Therefore, there areno GL commands to initialize a GL context or configure the default framebuffer.Similarly, display of framebuffer contents on a physical display device (includingthe transformation of individual framebuffer values by such techniques as gammacorrection) is not addressed by the GL.

Allocation and configuration of the default framebuffer occurs outside of theGL in conjunction with the window system, using companion APIs described insection 1.3.5.

Allocation and initialization of GL contexts is also done using these companionAPIs. GL contexts can be associated with different default framebuffers, and somecontext state is determined at the time this association is performed.

It is possible to use a GL context without a default framebuffer, in which casea framebuffer object must be used to perform all rendering. This is useful forapplications needing to perform offscreen rendering.

OpenGL is designed to be run on a range of platforms with varying capabilities,memory, and performance. To accommodate this variety, we specify ideal behaviorinstead of actual behavior for certain GL operations. In cases where deviation fromthe ideal is allowed, we also specify the rules that an implementation must obeyif it is to approximate the ideal behavior usefully. This allowed variation in GLbehavior implies that two distinct GL implementations may not agree pixel forpixel when presented with the same input, even when run on identical framebufferconfigurations.

Finally, command names, constants, and types are prefixed in the C languagebinding to OpenGL (by gl, GL_, and GL, respectively), to reduce name clashes withother packages. The prefixes are omitted in this document for clarity.

2.2 Command Syntax

The Specification describes OpenGL commands as functions or procedures usingANSI C syntax. Languages such as C++ and Javascript which allow passingof argument type information permit language bindings with simpler declarationsand fewer entry points.

Various groups of GL commands perform the same operation but differ in howarguments are supplied to them. To conveniently accommodate this variation, weadopt a notation for describing commands and their arguments.

GL commands are formed from a name which may be followed, depending onthe particular command, by a sequence of characters describing a parameter to the



command. If present, a digit indicates the required length (number of values) of theindicated type. Next, a string of characters making up one of the type descriptorsfrom table 2.1 indicates the specific size and data type of parameter values. Afinal v character, if present, indicates that the command takes a pointer to an array(a vector) of values rather than a series of individual arguments. Two specificexamples are:

void Uniform4f( int location, float v0, float v1,float v2, float v3 );

and

void GetFloatv( enum pname, float *data );

In general, a command declaration has the form

rtype Name{�1234}{� b s i i64 f d ub us ui ui64}{�v}( [args ,] T arg1, . . ., T argN [, args] );

rtype is the return type of the function. The braces ({}) enclose a series of typedescriptors (see table 2.1), of which one is selected. � indicates no type descriptor.The arguments enclosed in brackets ([args ,] and [, args]) may or may not bepresent. The N arguments arg1 through argN have type T, which corresponds toone of the type descriptors indicated in table 2.1 (if there are no letters, then thearguments’ type is given explicitly). If the final character is not v, then N is givenby the digit 1, 2, 3, or 4 (if there is no digit, then the number of arguments is fixed).If the final character is v, then only arg1 is present and it is an array of N values ofthe indicated type.

For example,

void Uniform{1234}{if}( int location, T value );

indicates the eight declarations

void Uniform1i( int location, int value );void Uniform1f( int location, float value );void Uniform2i( int location, int v0, int v1 );void Uniform2f( int location, float v0, float v1 );void Uniform3i( int location, int v0, int v1, int v2 );void Uniform3f( int location, float v0, float v1,

float v3 );



Type Descriptor Corresponding GL Typeb bytes shorti int

i64 int64f floatd double

ub ubyteus ushortui uint

ui64 uint64

Table 2.1: Correspondence of command suffix type descriptors to GL argumenttypes. Refer to table 2.2 for definitions of the GL types.

void Uniform4i( int location, int v0, int v1, int v2,int v3 );

void Uniform4f( int location, float v0, float v1,float v2, float v3 );

Arguments whose type is fixed (i.e. not indicated by a suffix on the command)are of one of the GL data types summarized in table 2.2, or pointers to one of thesetypes. Since many GL operations represent bitfields within these types, transferblocks of data in these types to graphics hardware which uses the same data types,or otherwise requires these sizes, it is not possible to implement the GL API on anarchitecture which cannot satisfy the exact bit width requirements in table 2.2.

The types clampf and clampd are no longer used, replaced by floatand double respectively together with specification language requiring param-eter clamping1.

2.2.1 Data Conversion For State-Setting Commands

Many GL commands specify a value or values to which GL state of a specific type(boolean, enum, integer, or floating-point) is to be set. When multiple versions ofsuch a command exist, using the type descriptor syntax described above, any suchversion may be used to set the state value. When state values are specified using

1 These changes are backwards-compatible at the compilation and linking levels, and are beingpropagated to man pages and header files as well.



GL Type DescriptionBit Width

boolean 1 or more Booleanbyte 8 Signed two’s complement binary inte-

gerubyte 8 Unsigned binary integerchar 8 Characters making up stringsshort 16 Signed two’s complement binary inte-

gerushort 16 Unsigned binary integerint 32 Signed two’s complement binary inte-

geruint 32 Unsigned binary integerfixed 32 Signed two’s complement 16.16

scaled integerint64 64 Signed two’s complement binary inte-

geruint64 64 Unsigned binary integersizei 32 Non-negative binary integer sizeenum 32 Enumerated binary integer valueintptr ptrbits Signed twos complement binary inte-

gersizeiptr ptrbits Non-negative binary integer sizesync ptrbits Sync object handle (see section 4.1)bitfield 32 Bit fieldhalf 16 Half-precision floating-point value

encoded in an unsigned scalarfloat 32 Floating-point valueclampf 32 Floating-point value clamped to [0, 1]double 64 Floating-point valueclampd 64 Floating-point value clamped to [0, 1]

Table 2.2: GL data types. GL types are not C types. Thus, for example, GLtype int is referred to as GLint outside this document, and is not necessarilyequivalent to the C type int. An implementation must use exactly the number ofbits indicated in the table to represent a GL type.ptrbits is the number of bits required to represent a pointer type; in other words,types intptr, sizeiptr, and sync must be large enough to store any CPU ad-dress. sync is defined as an anonymous struct pointer in the C language bindingswhile intptr and sizeiptr are defined as integer types large enough to holda pointer.



a different parameter type than the actual type of that state, data conversions areperformed as follows:

• When the type of internal state is boolean, zero integer or floating-point val-ues are converted to FALSE and non-zero values are converted to TRUE.

• When the type of internal state is integer or enum, boolean values of FALSEand TRUE are converted to 0 and 1, respectively. Floating-point values arerounded to the nearest integer. If the resulting value is so large in magnitudethat it cannot be represented by the internal state variable, the internal statevalue is undefined.

• When the type of internal state is floating-point, boolean values of FALSEand TRUE are converted to 0.0 and 1.0, respectively. Integer values are con-verted to floating-point, with or without normalization as described for spe-cific commands.

For commands taking arrays of the specified type, these conversions are per-formed for each element of the passed array.

Each command following these conversion rules refers back to this section.Some commands have additional conversion rules specific to certain state valuesand data types, which are described following the reference.

Validation of values performed by state-setting commands is performed afterconversion, unless specified otherwise for a specific command.

2.2.2 Data Conversions For State Query Commands

Query commands (commands whose name begins with Get) return a value or val-ues to which GL state has been set. Some of these commands exist in multipleversions returning different data types. When a query command is issued that re-turns data types different from the actual type of that state, data conversions areperformed as follows:

• If a command returning boolean data is called, such as GetBooleanv, afloating-point or integer value converts to FALSE if and only if it is zero.Otherwise it converts to TRUE.

• If a command returning integer data is called, such as GetIntegerv or Get-Integer64v, a boolean value of TRUE or FALSE is interpreted as one or zero,respectively. A floating-point value is rounded to the nearest integer, unlessthe value is an RGBA color component, a DepthRange value, or a depth


2.3. COMMAND EXECUTION 15

buffer clear value. In these cases, the query command converts the floating-point value to an integer according to the INT entry of table 18.2; a valuenot in [−1, 1] converts to an undefined value.

• If a command returning floating-point data is called, such as GetFloatv orGetDoublev, a boolean value of TRUE or FALSE is interpreted as 1.0 or0.0, respectively. An integer value is coerced to floating-point. Single- anddouble-precision floating-point values are converted as necessary.

If a value is so large in magnitude that it cannot be represented by the returneddata type, then the nearest value representable using the requested type is returned.

When querying bitmasks (such as SAMPLE_MASK_VALUE or STENCIL_-WRITEMASK) with GetIntegerv, the mask value is treated as a signed integer, sothat mask values with the high bit set will not be clamped when returned as signedintegers.

Unless otherwise indicated, multi-valued state variables return their multiplevalues in the same order as they are given as arguments to the commands that setthem. For instance, the two DepthRange parameters are returned in the order nfollowed by f.

2.3 Command Execution

Most of the Specification discusses the behavior of a single context bound to asingle CPU thread. It is also possible for multiple contexts to share GL objectsand for each such context to be bound to a different thread. This section introducesconcepts related to GL command execution including error reporting, commandqueue flushing, and synchronization between command streams. Using these toolscan increase performance and utilization of the GPU by separating loosely relatedtasks into different contexts.

Methods to create, manage, and destroy CPU threads are defined by the hostCPU operating system and are not described in the Specification. Binding of GLcontexts to CPU threads is controlled through a window system binding layer suchas those described in section 1.3.5.

2.3.1 Errors

The GL detects only a subset of those conditions that could be considered errors.This is because in many cases error checking would adversely impact the perfor-mance of an error-free program.

The command



enum GetError( void );

is used to obtain error information. Each detectable error is assigned a numericcode. When an error is detected, a flag is set and the code is recorded. Furthererrors, if they occur, do not affect this recorded code. When GetError is called,the code is returned and the flag is cleared, so that a further error will again recordits code. If a call to GetError returns NO_ERROR, then there has been no detectableerror since the last call to GetError (or since the GL was initialized).

To allow for distributed implementations, there may be several flag-code pairs.In this case, after a call to GetError returns a value other than NO_ERROR eachsubsequent call returns the non-zero code of a distinct flag-code pair (in unspecifiedorder), until all non-NO_ERROR codes have been returned. When there are no morenon-NO_ERROR error codes, all flags are reset. This scheme requires some positivenumber of pairs of a flag bit and an integer. The initial state of all flags is clearedand the initial value of all codes is NO_ERROR.

Table 2.3 summarizes GL errors. Currently, when an error flag is set, resultsof GL operation are undefined only if an OUT_OF_MEMORY error has occurred. Inother cases, there are no side effects unless otherwise noted; the command whichgenerates the error is ignored so that it has no effect on GL state or framebuffercontents. Except as otherwise noted, if the generating command returns a value, itreturns zero. If the generating command modifies values through a pointer argu-ment, no change is made to these values.

These error semantics apply only to GL errors, not to system errors such asmemory access errors. This behavior is the current behavior; the action of theGL in the presence of errors is subject to change, and extensions to OpenGL maydefine behavior currently considered as an error.

Several error generation conditions are implicit in the description of every GLcommand.

• If a command that requires an enumerated value is passed a symbolic con-stant that is not one of those specified as allowable for that command, anINVALID_ENUM error is generated. This is the case even if the argument isa pointer to a symbolic constant, if the value or values pointed to are notallowable for the given command.

• If a negative number is provided where an argument of type sizei orsizeiptr is specified, an INVALID_VALUE error is generated.

• If memory is exhausted as a side effect of the execution of a command, anOUT_OF_MEMORY error may be generated.



Error Description Offending com-mand ignored?

INVALID_ENUM enum argument out of range YesINVALID_VALUE Numeric argument out of range YesINVALID_OPERATION Operation illegal in current state YesINVALID_FRAMEBUFFER_OPERATION Framebuffer object is not com-

pleteYes

OUT_OF_MEMORY Not enough memory left to exe-cute command

Unknown

STACK_OVERFLOW Command would cause a stackoverflow

Yes

STACK_UNDERFLOW Command would cause a stackunderflow

Yes

Table 2.3: Summary of GL errors

The Specification attempts to explicitly describe these implicit error conditions(with the exception of OUT_OF_MEMORY2) wherever they apply. However, they ap-ply even if not explicitly described, unless a specific command describes differentbehavior. For example, certain commands use a sizei parameter to indicate thelength of a string, and also use negative values of the parameter to indicate a null-terminated string. These commands do not generate an INVALID_VALUE error,because they explicitly describe different behavior.

Otherwise, errors are generated only for conditions that are explicitly describedin the Specification.

When a command could potentially generate several different errors (for ex-ample, when it is passed separate enum and numeric parameters which are bothout of range), the GL implementation may choose to generate any of the applicableerrors.

When an error is generated, the GL may also generate a debug output messagedescribing its cause (see chapter 20). The message has source DEBUG_SOURCE_-API, type DEBUG_TYPE_ERROR, and an implementation-dependent ID.

Most commands include a complete summary of errors at the end of their de-scription, including even the implicit errors described above.

2 OUT_OF_MEMORY is not described because it can potentially be generated by any GL com-mand, even those which do not explicitly allocate GPU memory.



Such error summaries are set in a distinct style, like this sentence.

In some cases, however, errors may be generated for a single command forreasons not directly related to that command. One such example is that deferredprocessing for shader programs may result in link errors detected only when at-tempting to draw primitives using vertex specification commands. In such cases,errors generated by a command may be described elsewhere in the specificationthan the command itself.

2.3.2 Flush and Finish

Implementations may buffer multiple commands in a command queue before send-ing them to the GL server for execution. This may happen in places such as thenetwork stack (for network transparent implementations), CPU code executing aspart of the GL client or the GL server, or internally to the GPU hardware. Coarsecontrol over command queues is available using the command

void Flush( void );

which causes all previously issued GL commands to complete in finite time (al-though such commands may still be executing when Flush returns).

The command

void Finish( void );

forces all previously issued GL commands to complete. Finish does not returnuntil all effects from such commands on GL client and server state and the frame-buffer are fully realized.

Finer control over command execution can be expressed using fence commandsand sync objects, as discussed in section 4.1.

2.3.3 Numeric Representation and Computation

The GL must perform a number of floating-point operations during the course ofits operation.

Implementations normally perform computations in floating-point, and mustmeet the range and precision requirements defined under ”Floating-Point Com-putation” below.

These requirements only apply to computations performed in GL operationsoutside of shader execution, such as texture image specification and sampling, and



per-fragment operations. Range and precision requirements during shader execu-tion differ and are specified by the OpenGL Shading Language Specification.

In some cases, the representation and/or precision of operations is implicitlylimited by the specified format of vertex, texture, or renderbuffer data consumedby the GL. Specific floating-point formats are described later in this section.

2.3.3.1 Floating-Point Computation

We do not specify how floating-point numbers are to be represented, or the detailsof how operations on them are performed.

We require simply that numbers’ floating-point parts contain enough bits andthat their exponent fields are large enough so that individual results of floating-point operations are accurate to about 1 part in 105. The maximum representablemagnitude for all floating-point values must be at least 232. x · 0 = 0 · x = 0 forany non-infinite and non-NaN x. 1 · x = x · 1 = x. x + 0 = 0 + x = x. 00 =1. (Occasionally further requirements will be specified.) Most single-precisionfloating-point formats meet these requirements.

The special values Inf and −Inf encode values with magnitudes too large tobe represented; the special value NaN encodes “Not A Number” values resultingfrom undefined arithmetic operations such as 00 . Implementations are permitted,but not required, to support Inf s and NaN s in their floating-point computations.

Any representable floating-point value is legal as input to a GL command thatrequires floating-point data. The result of providing a value that is not a floating-point number to such a command is unspecified, but must not lead to GL interrup-tion or termination. In IEEE arithmetic, for example, providing a negative zero or adenormalized number to a GL command yields pre

OpenGL 4.4 (Core Profile) - March 19, 2014 · The OpenGL R Graphics System: A Speciﬁcation...

Documents

Transcript of OpenGL 4.4 (Core Profile) - March 19, 2014 · The OpenGL R Graphics System: A Speciﬁcation...