EGL _Assignment1 Mac OS

Pegl is a binding to EGL 1.4, written in native Python 3 through the ctypes library. It provides comprehensive access to EGL functions, while offering a very Pythonic API. EGL is a specification from the Khronos Group that provides an intermediate layer between other Khronos specifications (OpenGL, OpenGL ES, OpenVG), called 'client APIs', and the native graphics system. It supports Windows, Mac OS X, Linux, and FreeBSD. Note: GL3W loads core OpenGL only by default. All OpenGL extensions will be loaded if the -ext flag is specified to gl3wgen.py.

EGL uses build scripts to manage the preparation process for z/OS®. The build scripts perform the following tasks. Compile and link for a COBOL program, including the code generated from an EGL program, library, service, FormGroup, or DataTable part. DB2® precompile and bind if a program, library or service performs SQL I/O.

Fourth Edition

Abstract

Records guidelines to be followed by implementers of Khronos Group APIs.

Table of Contents

1. Introduction

2. Header Files and Libraries

2.1. Uncontrolled Platforms (e.g. GNU^®/Linux^®, Windows^®, Windows CE)

2.2. Vendor Controlled Platforms (e.g. Android, BREW, iOS, Mac OS X)

3. Implementation Notes

3.1. OpenCL

3.2. EGL

4. Conformance Testing

A. Glossary

B. Document History

C. Acknowledgements

List of Tables

1. Header File Names and Locations

2. Recommended Library Names

3. GL on GNU/Linux, Unix and other platforms using the X Window System

4. GL on Mac OS X

5. GL on Microsoft Windows

This document provides guidelines for implementers of OpenGL ES, OpenVG and other API standards specified by the Khronos Group. The aim of these hints is to provide commonality between implementations to ease the logistical problems faced by developers using multiple different implementations of an API.

One of the primary goals is to allow an application binary to run on top of multiple different implementations of an API on the same platform.

Implementers are strongly urged to comply with these guidelines.

This document contains links to several Khronos specifications and header files at versions current at the time of publication. Readers may wish to check the Khronos registry for post-publication updates to these files.

When providing implementations for platforms where the platform vendor does not provide or has not yet established a standard for an API, implementers are strongly urged to comply with the following recommendations. Vendors newly establishing ABI specifications for their platforms are also strongly urged to comply with these recommendations.

• Implementers are strongly encouraged to use the standard header files (egl.h, gl.h, kd.h, etc.) for each specification that are provided by Khronos and listed in Table 1, 'Header File Names and Locations'. Links are provided there.

• Portable and non-portable definitions are separated into .h and platform.h files, e.g., gl.h and glplatform.h. Implementers should not need to change the former; they are strongly discouraged from doing so. They should rarely need to change the latter as it already contains definitions for most common platforms.

• Khronos provides a common underlying khrplatform.h defining sets of base types, linkage specifications and function-call specifications covering most common platforms. Many Khronos-provided platform.h and other header files include khrplatform.h and use its definitions as the basis for their own. Implementers should rarely need to change this file.

• For most APIs, functions and enumerants for extensions registered with the Khronos Extension Registry are declared and defined in a Khronos-provided ext.h file, e.g, glext.h. Exceptions are noted below. These header files can be used even if the implementation doesn't provide a particular extension since applications must query the presence of extensions at run time.

• Functions and enumerants for unregistered implementer extensions should be declared and defined in an implementer's own header file. Follow the extension writing and naming rules given in How to Create Khronos API Extensions. Use enumerant values obtained from the Khronos Extension Registry, as explained in OpenGL Enumerant Allocation Policies. Implementers are strongly encouraged to register their extensions even if they are the only vendor.

• Some APIs define optional utility libraries. Functions and enumerants for these are declared and defined in Khronos-provided header files, e.g., glu.h. For some other APIs, header file names are reserved for use by future utility libraries.

• Header files for a given API are packaged in an API-specific folder, e.g., GLES. Folder names are listed in Table 1, 'Header File Names and Locations' All API specific folders should be placed in a common parent folder.

• Consider contributing any header file changes back to Khronos so that others may benefit from your expertise. Contact the relevant working group and, on approval, update the files in the Khronos Subversion tree.

• Use the function-call convention defined for the platform in the Khronos-provided platform.h, if a definition exists for the platform in question.

• If you make your own header files use the names given in Table 1, 'Header File Names and Locations'.

• If the platform is Windows or WindowsCE, make sure your header files are suitable for use with MFC. Make sure that any base API types referred to are preceded by ::. For example you need to refer to ::GetDC(0) because several Microsoft Foundation Classes have their own GetDC(void) methods.

• When including one header in another, include the parent directory name. For example when including eglplatform.h in egl.h use #include . Do not use #include because it forces application makefiles to specify 2 different -I options to find both include files.

Table 1. Header File Names and Locations

^[a] A file declaring the functions used to integrate OpenCL and OpenGL objects.

^[b] Early EGL implementations used egltypes.h instead of the now recommended eglplatform.h .

^[c] Required, if the OpenGL utility library is provided.

^[d] Includes only interfaces for the Core profile of OpenGL and ARB extensions.

^[e] Does not currently exist as there are no known vendor extensions to the Core profile.

^[f] glplatform.h does not exist in many early implementations of OpenGL ES 1.x. Platform dependent declarations were included directly in gl.h .

^[g] This file contains unique interface IDs for all API interfaces. These IDs have been automatically generated. Neither implementers nor application developers should edit these interface IDs.

^[h] Required, if the OpenVG utility library is provided.

• To find the include files, use appropriate compiler options in the makefiles for your sample programs; e.g. -I (gcc, linux) or /I (Visual C++).

• Given the different IDEs & compilers people use, especially on Windows, it is not possible to recommend a system location in which to place these include files. Where obvious choices exist Khronos recommends implementers take advantage of them.

• In particular, GNU/Linux implementations should follow the Filesystem Hierarchy Standard for the location of headers and libraries.

• Implementers may need to modify eglplatform.h. In particular the eglNativeDisplayType, eglNativeWindowType, and eglNativePixmapType typedefs must be defined as appropriate for the platform (typically, they will be typedef'ed to corresponding types in the native window system). Developer documentation should mention the correspondence so that developers know what parameters to pass to eglCreateWindowSurface, eglCreatePixmapSurface, and eglCopyBuffers. Documentation should also describe the format of the display_id parameter to eglGetDisplay, since this is a platform-specific identifier. See Section 3.2.1, 'EGLDisplay' for more details.

• Do not include gl.h in egl.h.

• For historical reasons both Windows and GNU/Linux include an old version of gl.h, that is beyond the control of Khronos, containing OpenGL 1.2 interfaces. All post-OpenGL 1.2 interfaces of the Compatibility profile of the most recent version of OpenGL are defined in the Khronos-provided glext.h.

• glcorearb.h defines all the interfaces of the most recent core profile of OpenGL and any ARB extensions to it. It does not include interfaces that have been deprecated and removed from core OpenGL. Vendor extensions to the Core profile should be defined in glcoreext.h but implementers should keep in mind that people using the Core profile probably have more concern about portability than most coders and may want to avoid using extensions.

• Implementations supporting only the Core profile should provide the header files listed for OpenGL 3.1+ . Implementations supporting the Compatibility profile should provide the header files listed for OpenGL 3.x & 4.x following the conventions documented in Section 2.2.2, 'OpenGL'.

• When introducing OpenGL to a platform for the first time, only the Core profile is required. The Compatibility profile is optional and not recommended.

• Khronos recommends using EGL as the window abstraction layer, when introducing OpenGL to a platform. Follow the EGL guidelines given herein.

• For compatibility with GLES 1.0 implementations, include in GLES a special egl.h containing the following:

  This is because many early OpenGL ES 1.0 implementations included gl.h in egl.h so many existing applications only include egl.h .

• The name glu.h is reserved for future use by the Khronos Group.

• The names glu{,2}.h are reserved for future use by the Khronos Group.

• The names glu{,3}.h are reserved for future use by the Khronos Group.

• As noted earlier, implementers are strongly encouraged to use the Khronos provided header files. Implementers, who are creating their own kd.h or need to modify kdplatform.h, are urged to code them such that they include as few as possible of the platform's include files, and to avoid declaring C and POSIX standard functions. This will ease the creation of portable OpenKODE applications, and help stop non-portable code being added accidentally.

• Each OpenKODE extension is defined in its own header file. Khronos provided header files for each ratified extension are available in the Extension Headers subsection of the OpenKODE registry.

• The OpenWF API is divided into two parts: Composition and Display Control. Separate header files must be provided for each part as indicated in Table 1, 'Header File Names and Locations'.

• It is highly desirable to implement all API entry points as function calls. However in OpenKODE Core, macros or in-lines may be used instead of function calls provided the rules in Section 4.3 OpenKODE Core functions of the OpenKODE specification are followed:

  • When calling a function or macro, each argument must be evaluated exactly once (although the order of evaluation is undefined).

  • It must be possible to take the address of a function.

  These rules apply except where individually noted in the specification.

• Except in cases where macros are allowed or versioned symbol naming is recommended (e.g., OpenCL symbol naming), ensure the API function names exported by your lib & dll files match the function names specified by the Khronos standard for the API you are implementing.

• The entry points for each API must be packaged in separate libraries. Recommended library names are given in Table 2, 'Recommended Library Names'.

• However to provide backward compatibility for existing applications, two OpenGL ES 1.1 libraries should be provided: one with and one without the EGL entry points.

  Note: There are extant implementations of the dual OpenGL ES libraries demonstrating this is possible on Symbian, GNU/Linux, Win32 and WinCE.

  For OpenGL ES 2.x and 3.x, only a library without EGL entry points is needed.

• To allow interoperability through EGL with other Khronos APIs, implementers may want to provide an additional OpenGL library, that can be used with EGL, on platforms having existing GL ABI conventions. In such a case, use the name recommended below for the OpenGL library without EGL.

• When introducing OpenGL to a platform, implementers are recommended to provide two OpenGL libraries similarly to the OpenGL ES 1.1 case.

Khronos recommends the library names shown in Table 2, 'Recommended Library Names'. The table lists the names developers would typically supply to a link command. The actual file names may vary according to the platform and tools in use.

• The ld command on GNU/Linux and Unix systems prefaces the base name with lib and appends the extensions .so and .a in that order when searching for the library. So the full name of the library file must be lib.{so,a} depending on whether it is a shared or static library.

• Neither the Microsoft Visual Studio linker nor the ARM RealView linker offer any special treatment for library names; the extension for a standard library or import library on Windows is .lib, while that for a dynamic link library is .dll.

• On Windows, if the implementer will provide both 32- and 64-bit libraries, it is necessary to disambiguate by adding a suffix of 32 or 64 to the base name.

Khronos therefore recommends that library names be of the form lib[].; being possibly needed only on the Windows platform.

Table 2. Recommended Library Names

^[a] May contain Core or Compatibilty profile. See Section 2.2.2, 'OpenGL' below.

^[b] These names are required for OpenGL ES 1.0 and the libraries must contain the EGL entry points as detailed in Chapter 8, Packaging, of the OpenGL ES 1.0 specification.

^[c] These names are deprecated for OpenGL ES 1.1 and beyond and should only be used for a library that includes the EGL entry points in order to support legacy applications.

^[d] These alternate names for GL ES libraries that do not contain the EGL entry points were introduced starting at revision 1.1.09 of the OpenGL ES 1.1 specification.

^[e] These names are reserved for future use by the Khronos Group.

^[f] This is not a typo! The v2 name is retained in order that existing applications will continue to run after a system is upgraded to OpenGL ES 3 and avoid a myriad of potential linking issues when developing applications for both v2 & v3.

Vendors of controlled platforms are strongly urged to follow the recommendations given above for Uncontrolled Platforms when adding a Khronos Group API to their platform.

Implementers should follow any linkage specifications established by the platform vendor .

• Use the header files, (e.g., for OpenGL ES, gl.h, glext.h & egl.h) provided by the platform vendor.

• Package header files in the same containing folder used by the platform vendor.

• Use the function names specified in those header files.

• Use the function-call convention specified in those header files.

• Implement all API entry points in the same way as in the vendor-provided ABI. That is, functions should be functions, in-line functions should be in-line functions and macros should be macros.

• Use the library names specified by the platform vendor.

Because of OpenGL's long history, a series of conventions have been established, even for platforms which are not strictly controlled by their vendors. This section documents the established conventions for all common platforms. They should be followed by Implementers supporting the Compatibility profile in order to provide the least surprises to application developers. Implementers supporting only the Core profile of OpenGL 3.1+ are encouraged to follow the guidelines given in the preceding sections.

Platform SDKs typically come with 2 OpenGL-related header files pre-installed: gl.h, which defines the OpenGL interfaces, and a header file that defines the interfaces to that platform's window abstraction layer (e.g. glx.h) . These files are commonly outdated, often having only OpenGL 1.2 interfaces. As these files are outside the control of Khronos, Khronos provides *ext.h files which define newly added functions and enums, such as those specified by OpenGL 4.x. Some platform SDKs may also include *ext.h files. These can also be outdated. Implementers are advised to use the Khronos provided *ext.h files and supply these with their SDKs.

Implementers can choose to provide their own up-to-date gl.h. Developer documentation should explain how to ensure the compiler finds any updated or implementation specific files.

With the exceptions noted in the tables below, all files are packaged in the folder GL.

The following sections give details for each platform.

In order to allow interaction with other Khronos APIs, implementers may wish to provide an EGL implementation, that supports OpenGL, in addition to a platform's standard window abstraction layer. In this case, EGL should be packaged in a separate library following the guidelines given in Section 2.1, 'Uncontrolled Platforms (e.g. GNU^®/Linux^®, Windows^®, Windows CE)' above. Implementers must ensure that an application can link with both the OpenGL library and the EGL library without any errors arising from the OpenGL library having entry points for the platform's standard window abstraction layer.

Those implementing OpenGL on GNU/Linux or Unix systems should follow the OpenGL Application Binary Interface for Linux which has been approved by the Linux Standard Base Workgroup. The file and library names given below apply to any platform using the X Window System.

Table 3. GL on GNU/Linux, Unix and other platforms using the X Window System

^[a] Per the above referenced ABI, libGL.so.1 contains a minimum of OpenGL 1.2, GLX 1.3 and ARB_multitexture.

^[b] The following is subject to change; it will be confirmed at the X.Org Developers Conference in Sep. 2012. Tank my bug mac os. libGL.so.[34] should contain only the OpenGL 3.x or 4.x entry points. Applications must link with libEGL for the abstraction layer.

OpenGL is the primary 3D rendering API for Mac OS X so is a core part of the system. Information is presented here more for completeness than from any expectation that third party implementations will appear. For a complete description of Apple's implementation see the OpenGL Programming Guide for Mac OS X. Primarily aimed at developers, it provides a good description of the structure of OpenGL in Mac OS X.

Apple's SDK includes up-to-date gl.h and glext.h header files that track their implementation. These headers contain all GL 3.x features and are used regardless of the vendor of the underlying GPU. The headers are packaged together with the libraries in the OpenGL Framework.

Table 4. GL on Mac OS X

^[b] Packaged in AGL.framework

Those creating an implementation for Windows will need to provide an Installable Client Driver (ICD). See Loading an OpenGL Installable Client Driver and OpenGL and Windows Vista^™ for more information.

Table 5. GL on Microsoft Windows

^[a] winGDI.h is a standard Windows' header file so is not packaged in the GL folder.

OpenCL implementations may optionally include an off-line compiler. When such a compiler is provided, the compiler must accept the same options as the on-line compiler. These are specified in the OpenCL specification. In addition, the compiler must support a -o option for specifying the name of the output file and a -b option for specifying the target machine. Khronos recommends that the string 'clc' be used as the last part of the compiler name as in, e.g., openclc or clc.

OpenCL implementations on GNU/Linux should decorate the symbol names in shared libraries with version numbers in the form @@OPENCL_ where is the version of the OpenCL specification in which the symbol first appeared, e.g. 1.0, 1.1 or 2.0.

The EGL specification (Section 2.1.2 Displays) describes what an EGLDisplay represents. It states that,'In most environments a display corresponds to a single physical screen.'In reality most environments have only one EGLDisplay even when multiple physical screens are supported. Many vendors match the EGLDisplay to the display driver implementation. So if there is only one display driver on the system then the system has only one EGLDisplay (even though that one driver may be capable of driving more than 1 physical screen). For example, in the X Window System an EGLDisplay is likely to correspond to an X Display, not to an X Screen.

The implementer is free to choose what an EGLDisplay represents. There could be one EGLDisplay per physical screen. There could be one EGLDisplay per graphics chip or graphics card. There could be one EGLDisplay per graphics driver vendor. Or there could be one EGLDisplay per system which abstracts all available graphics hardware on the system into a single EGLDisplay handle.

While the implementer is free to choose the abstraction for the EGLDisplay, there are advantages to choosing the latter approach where only a single EGLDisplay exists on the system. For example EGLImages and EGLContexts can only be shared within a single EGLDisplay. If there is more than one EGLDisplay on a system (e.g. one per physical screen) it makes sharing resources between the two displays difficult or impossible. Another example is that most applications are written to use a single EGLDisplay (the one corresponding to EGL_DEFAULT_DISPLAY), and those apps will not generally be able to take full advantage of systems with multiple EGLDisplays.

Recommendation: Have only one EGLDisplay per system, even if the system has multiple physical screens.

If there is only one EGLDisplay on a system, how does that work with multiple physical screens? This is up to the native window system (or OpenKODE). When an application wants to render to a window on a particular physical screen, it should ensure that the window it creates is displayed on that physical screen. The mechanism is specific to the native window system (or possibly OpenKODE if using kdCreateWindow()). NOTE: There is currently no way to tell OpenKODE upon which screen to open a KDWindow. An extension to allow this (by setting a 'which screen' window attribute between calling kdCreateWindow() and kdRealizeWindow()) may be available in the future.

The various EGLImage specifications describe how EGLImages can be created and used. Some of the implications made by the spec. are not immediately obvious. This section attempts to clarify what choices may need to be made by an implementation, and how an implementation addresses those choices. The discussion in this section assumes that the reader has read at least the EGL_KHR_image_base specification.

EGLImages are created with the eglCreateImageKHR command. They can be created from a variety of source image objects (e.g. OpenGL ES textures, OpenVG VGImages, native pixmaps, etc).

Regardless of what type of object the EGLImage is created from, the specifications allow an implementation to reallocate the memory which backs the EGLImage. However, there are a number of issues which make this very difficult. For example, when one API is rendering to an EGLImage in one thread, another API is reading the same EGLImage in another thread, and a third thread calls a function which creates a sibling object from the same EGLImage, then it is not clear that reallocation is possible. If an implementation performs reallocation, it is likely that it will have to do expensive locking around the use of EGLImages which will hurt performance. Therefore implementations may benefit from not performing reallocation once an EGLImage has been created.

Recommendation: Implementations should avoid reallocating the memory backing the EGLImage after the EGLImage has been created.

When an EGLImage is created from a client API object, the context that contains the object is current to the thread that called eglCreateImageKHR(). Therefore there are fewer issues with reallocating the memory at the time the EGLImage is created than when a sibling is created from the EGLImage.

Implementations of client APIs may have special requirements for the memory accessed by the API. For example, there may be alignment requirements, or requirements that memory come from a specific range of physical addresses. These requirements may not be the same for all client APIs on a particular system. An OpenGL ES texture may have different alignment requirements than a VGImage, for example.

In addition, there may be constraints on what internal formats are accessible to certain APIs. An implementation may choose to change the internal representation of the image when an EGLImage is created or when a sibling is created from the EGLImage, so long as this is transparent to the application. For example, when an EGLImage is created from an OpenGL ES texture which was specified as RGBA 4444, the implementation may choose to represent the EGLImage internally as an RGBA 8888 image even if the texture was originally internally represented as RGBA 4444. However, in this case the implementation must continue to treat the original texture as an RGBA 4444 texture. This means that glTexSubImage2D with type=GL_UNSIGNED_BYTE must fail and glTexSubImage2D with type=GL_UNSIGNED_SHORT_4_4_4_4 must succeed. An implementation may choose to do this if, for example, its OpenMAX renderer can support RGBA 8888 but not RGBA 4444. Alternatively, an implementation may choose to simply fail to allow an EGLImage represented internally as RGBA 4444 to be used as an OpenMAX buffer.

Generally an implementation may discard the contents of an EGLImage (and all associated client API objects) when the EGLImage is created or when any sibling object is created from the EGLImage. Therefore there is no need to copy and/or convert the contents of a buffer, if the memory backing the EGLImage gets reallocated. Note that, if the EGLImage PRESERVED attribute is set to TRUE when the EGLImage is created, then the contents of the EGLImage (and all associated client API objects) do have to be preserved when the EGLImage is created and when a sibling object is created from that EGLImage. An implementation may still reallocate the memory backing the EGLImage so long as it copies the contents of the old memory to the new memory. An implementation may also opt to fail creation of the EGLImage or the sibling object if the PRESERVED attribute is set to true.

If an implementation chooses not to reallocate the memory backing the EGLImage after it has been created, then it must take extra care when first creating the EGLImage to ensure compatibility among APIs. For example, if the backing memory is allocated using an alignment that is incompatible with an OpenGL ES texture's requirements then that EGLImage cannot be used to create an OpenGL ES texture sibling. An implementation has several choices for addressing this issue:

• Fail to create the sibling object.

• Reallocate the memory with the required alignment.

• Ensure the allocation performed when the EGLImage is created is compatible with all (or as many as possible) types of API objects.

The third choice is the most desirable.

Recommendation: When creating an EGLImage, an implementation should allocate (or reallocate) memory backing the EGLImage in such a way that the memory is compatible with the largest possible set of API objects.

As mentioned above, an implementation is free to reallocate memory backing an EGLImage whenever an EGLImage sibling is created from the EGLImage (or at any other time). The only requirement is that any such reallocation be transparent to the application (other than discarding the pixel values, if the PRESERVED attribute is not set to TRUE). As discussed above, performing such reallocation when a sibling is created from an EGLImage may be very difficult to implement robustly. Therefore the recommendation is to avoid such reallocations when creating siblings.

An implementation which never reallocates must fail any attempt to create a sibling from an EGLImage which has an allocation incompatible with the sibling object being created. This failure is acceptable according to the spec, but is still undesirable. This is why it is important for the original memory allocation to be compatible with as many types of API sibling objects as possible.

Another option for allocating memory to back an EGLImage is to delay the allocation until one of the EGLImage sibling objects is actually used. This may allow an implementation to be more flexible and/or perform better. Since the pixels in an EGLImage can be discarded when any sibling object is created, it is advisable for applications using EGLImages to create all sibling objects before using (e.g. rendering to) any of the sibling objects. Delaying the allocation of memory until one of the sibling objects is first used allows the implementation to take into account what type of sibling objects the EGLImage has, and to allocate memory appropriate to all of those sibling objects. Once any of the siblings is actually used (e.g. rendered to) it becomes much more difficult to reallocate the memory.

An application may still request that a sibling object be created from the EGLImage after one of the siblings has been used, but an implementation may choose to fail to create the sibling at this time, if the already allocated memory is incompatible with the requested sibling. Such an implementation would be maximally flexible about what siblings can be created, and maximally efficient in its memory allocation, before any siblings are used. After siblings are used the implementation may be less flexible, but that is a less important case.

Creation of an EGLImage and its sibling objects is not intended to be an operation which is performed frequently (e.g. per frame). It is far more important to optimize the use of EGLImage siblings (binding sibling objects, rendering to sibling objects, and reading from sibling objects (e.g. as textures)) than to optimize their creation and destruction. Where tradeoffs can be made between use performance and creation/destruction performance, it is recommended that the choice be made in favor of optimizing the use of sibling objects even if at the expense of creation/destruction performance (within reason).

Developer documentation should describe which types of EGLImage can be used for which types of API objects in the implementation. For example, what are the restrictions (if any) on a GLES texture in order for an EGLImage, that is created with it, to be used to create a VGImage sibling from that EGLImage? Are there any additional restrictions which will guarantee optimal performance?

The documentation should also describe which operations are likely to be slow (e.g. creating EGLImages or creating EGLImage siblings).

To claim your product is compliant with an API specification or use its trademark and logo to market that product, your implementation must pass the API's conformance test and the results must be submitted to the Khronos Group. To do this, you must join Khronos as an Adopter which requires a fee and a legal agreement. More information about the conformance process and fees can be found on the Khronos Adopters page. Adopters will receive an account giving them access to the relevant API-specific Adopters area of the Khronos web site.

No fee or agreement is needed to implement a Khronos API or use it in a product but you may not claim compliance and may not use its trademark and logo.

API-specific Adopters areas provide links for downloading test packages and submitting results. The test packages contain instructions detailing the format and and required content of a Submission Package.

A. Glossary

The low-level interface between a compiled application program and the operating system or its libraries.

The source-code level interface between an application program and the operating system or its libraries.

An OpenGL driver for Microsoft Windows that is identified by a renderer string. The OpenGL runtime decides which ICD to run by reading the contents of a specific registry entry. More details can be found here.

A tool for the purpose of software development in which, at a minimum, an editor, compiler and debugger are integrated together for ease of use.

A company or person who implements a Khronos API.

A set of C++ utility classes provided by Microsoft Corporation.

A kit containing the header files, libraries and documentation required to develop software for some device or environment.

A company providing an operating system platform that includes an ABI specification for one or more Khronos APIs. E.g., Google (OpenGL ES & EGL on Android) and Qualcomm (OpenGL ES on BREW). A Vendor may also be an Implementer.

B. Document History

C. Acknowledgements

Thanks to all the members of the Khronos Group for their input and in particular to the following:

Important:OpenGL was deprecated in macOS 10.14. To create high-performance code on GPUs, use the Metal framework instead. See Metal.

You can tell that Apple has an implementation of OpenGL on its platform by looking at the user interface for many of the applications that are installed with OS X. The reflections built into iChat (Figure 1-1) provide one of the more notable examples. The responsiveness of the windows, the instant results of applying an effect in iPhoto, and many other operations in OS X are due to the use of OpenGL. OpenGL is available to all Macintosh applications.

OpenGL for OS X is implemented as a set of frameworks that contain the OpenGL runtime engine and its drawing software. These frameworks use platform-neutral virtual resources to free your programming as much as possible from the underlying graphics hardware. OS X provides a set of application programming interfaces (APIs) that Cocoa applications can use to support OpenGL drawing.

This chapter provides an overview of OpenGL and the interfaces your application uses on the Mac platform to tap into it.

OpenGL Concepts

To understand how OpenGL fits into OS X and your application, you should first understand how OpenGL is designed.

OpenGL Implements a Client-Server Model

OpenGL uses a client-server model, as shown in Figure 1-2. When your application calls an OpenGL function, it talks to an OpenGL client. The client delivers drawing commands to an OpenGL server. The nature of the client, the server, and the communication path between them is specific to each implementation of OpenGL. For example, the server and clients could be on different computers, or they could be different processes on the same computer.

A client-server model allows the graphics workload to be divided between the client and the server. For example, all Macintosh computers ship with dedicated graphics hardware that is optimized to perform graphics calculations in parallel. Figure 1-3 shows a common arrangement of CPUs and GPUs. With this hardware configuration, the OpenGL client executes on the CPU and the server executes on the GPU.

OpenGL Commands Can Be Executed Asynchronously

A benefit of the OpenGL client-server model is that the client can return control to the application before the command has finished executing. An OpenGL client may also buffer or delay execution of OpenGL commands. If OpenGL required all commands to complete before returning control to the application, then either the CPU or the GPU would be idle waiting for the other to provide it data, resulting in reduced performance.

Some OpenGL commands implicitly or explicitly require the client to wait until some or all previously submitted commands have completed. OpenGL applications should be designed to reduce the frequency of client-server synchronizations. See OpenGL Application Design Strategies for more information on how to design your OpenGL application.

OpenGL Commands Are Executed In Order

OpenGL guarantees that commands are executed in the order they are received by OpenGL.

OpenGL Copies Client Data at Call-Time

When an application calls an OpenGL function, the OpenGL client copies any data provided in the parameters before returning control to the application. For example, if a parameter points at an array of vertex data stored in application memory, OpenGL must copy that data before returning. Therefore, an application is free to change memory it owns regardless of calls it makes to OpenGL.

The data that the client copies is often reformatted before it is transmitted to the server. Copying, modifying, and transmitting parameters to the server adds overhead to calling OpenGL. Applications should be designed to minimize copy overhead.

OpenGL Relies on Platform-Specific Libraries For Critical Functionality

OpenGL provides a rich set of cross-platform drawing commands, but does not define functions to interact with an operating system's graphics subsystem. Instead, OpenGL expects each implementation to define an interface to create rendering contexts and associate them with the graphics subsystem. A rendering context holds all of the data stored in the OpenGL state machine. Allowing multiple contexts allows the state in one machine to be changed by an application without affecting other contexts.

Associating OpenGL with the graphic subsystem usually means allowing OpenGL content to be rendered to a specific window. When content is associated with a window, the implementation creates whatever resources are required to allow OpenGL to render and display images.

OpenGL in OS X

OpenGL in OS X implements the OpenGL client-server model using a common OpenGL framework and plug-in drivers. The framework and driver combine to implement the client portion of OpenGL, as shown in Figure 1-4. Dedicated graphics hardware provides the server. Although this is the common scenario, Apple also provides a software renderer implemented entirely on the CPU.

OS X supports a display space that can include multiple dissimilar displays, each driven by different graphics cards with different capabilities. In addition, multiple OpenGL renderers can drive each graphics card. To accommodate this versatility, OpenGL for OS X is segmented into well-defined layers: a window system layer, a framework layer, and a driver layer, as shown in Figure 1-5. This segmentation allows for plug-in interfaces to both the window system layer and the framework layer. Plug-in interfaces offer flexibility in software and hardware configuration without violating the OpenGL standard.

The window system layer is an OS X–specific layer that your application uses to create OpenGL rendering contexts and associate them with the OS X windowing system. The NSOpenGL classes and Core OpenGL (CGL) API also provide some additional controls for how OpenGL operates on that context. See OpenGL APIs Specific to OS X for more information. Finally, this layer also includes the OpenGL libraries—GL, GLU, and GLUT. (See Apple-Implemented OpenGL Libraries for details.)

The common OpenGL framework layer is the software interface to the graphics hardware. This layer contains Apple's implementation of the OpenGL specification.

The driver layer contains the optional GLD plug-in interface and one or more GLD plug-in drivers, which may have different software and hardware support capabilities. The GLD plug-in interface supports third-party plug-in drivers, allowing third-party hardware vendors to provide drivers optimized to take best advantage of their graphics hardware.

Accessing OpenGL Within Your Application

The programming interfaces that your application calls fall into two categories—those specific to the Macintosh platform and those defined by the OpenGL Working Group. The Apple-specific programming interfaces are what Cocoa applications use to communicate with the OS X windowing system. These APIs don't create OpenGL content, they manage content, direct it to a drawing destination, and control various aspects of the rendering operation. Your application calls the OpenGL APIs to create content. OpenGL routines accept vertex, pixel, and texture data and assemble the data to create an image. The final image resides in a framebuffer, which is presented to the user through the windowing-system specific API.

OpenGL APIs Specific to OS X

OS X offers two easy-to-use APIs that are specific to the Macintosh platform: the NSOpenGL classes and the CGL API. Throughout this document, these APIs are referred to as the Apple-specific OpenGL APIs.

Cocoa provides many classes specifically for OpenGL:

Egl Assignment 1 Mac Os X

• The NSOpenGLContext class implements a standard OpenGL rendering context.

• The NSOpenGLPixelFormat class is used by an application to specify the parameters used to create the OpenGL context.

• The NSOpenGLView class is a subclass of NSView that uses NSOpenGLContext and NSOpenGLPixelFormat to display OpenGL content in a view. Applications that subclass NSOpenGLView do not need to directly subclass NSOpenGLPixelFormat or NSOpenGLContext. Applications that need customization or flexibility, can subclass NSView and create NSOpenGLPixelFormat and NSOpenGLContext objects manually.

• The NSOpenGLLayer class allows your application to integrate OpenGL drawing with Core Animation.

• The NSOpenGLPixelBuffer class provides hardware-accelerated offscreen drawing.

The Core OpenGL API (CGL) resides in the OpenGL framework and is used to implement the NSOpenGL classes. CGL offers the most direct access to system functionality and provides the highest level of graphics performance and control for drawing to the full screen. CGL Reference provides a complete description of this API.

Apple-Implemented OpenGL Libraries

OS X also provides the full suite of graphics libraries that are part of every implementation of OpenGL: GL, GLU, GLUT, and GLX. Two of these—GL and GLU—provide low-level drawing support. The other two—GLUT and GLX—support drawing to the screen.

Your application typically interfaces directly with the core OpenGL library (GL), the OpenGL Utility library (GLU), and the OpenGL Utility Toolkit (GLUT). The GL library provides a low-level modular API that allows you to define graphical objects. It supports the core functions defined by the OpenGL specification. It provides support for two fundamental types of graphics primitives: objects defined by sets of vertices, such as line segments and simple polygons, and objects that are pixel-based images, such as filled rectangles and bitmaps. The GL API does not handle complex custom graphical objects; your application must decompose them into simpler geometries.

The GLU library combines functions from the GL library to support more advanced graphics features. It runs on all conforming implementations of OpenGL. GLU is capable of creating and handling complex polygons (including quartic equations), processing nonuniform rational b-spline curves (NURBs), scaling images, and decomposing a surface to a series of polygons (tessellation).

The GLUT library provides a cross-platform API for performing operations associated with the user windowing environment—displaying and redrawing content, handling events, and so on. It is implemented on most UNIX, Linux, and Windows platforms. Code that you write with GLUT can be reused across multiple platforms. However, such code is constrained by a generic set of user interface elements and event-handling options. This document does not show how to use GLUT. The GLUTBasics sample project shows you how to get started with GLUT.

GLX is an OpenGL extension that supports using OpenGL within a window provided by the X Window system. X11 for OS X is available as an optional installation. (It's not shown in Figure 1-6.) See OpenGL Programming for the X Window System, published by Addison Wesley for more information.

This document does not show how to use these libraries. For detailed information, either go to the OpenGL Foundation website http://www.opengl.org or see the most recent version of 'The Red book'—OpenGL Programming Guide, published by Addison Wesley.

Terminology

There are a number of terms that you'll want to understand so that you can write code effectively using OpenGL: renderer, renderer attributes, buffer attributes, pixel format objects, rendering contexts, drawable objects, and virtual screens. As an OpenGL programmer, some of these may seem familiar to you. However, understanding the Apple-specific nuances of these terms will help you get the most out of OpenGL on the Macintosh platform.

Renderer

A renderer is the combination of the hardware and software that OpenGL uses to execute OpenGL commands. The characteristics of the final image depend on the capabilities of the graphics hardware associated with the renderer and the device used to display the image. OS X supports graphics accelerator cards with varying capabilities, as well as a software renderer. It is possible for multiple renderers, each with different capabilities or features, to drive a single set of graphics hardware. To learn how to determine the exact features of a renderer, see Determining the OpenGL Capabilities Supported by the Renderer.

Renderer and Buffer Attributes

Your application uses renderer and buffer attributes to communicate renderer and buffer requirements to OpenGL. The Apple implementation of OpenGL dynamically selects the best renderer for the current rendering task and does so transparently to your application. If your application has very specific rendering requirements and wants to control renderer selection, it can do so by supplying the appropriate renderer attributes. Buffer attributes describe such things as color and depth buffer sizes, and whether the data is stereoscopic or monoscopic.

Renderer and buffer attributes are represented by constants defined in the Apple-specific OpenGL APIs. OpenGL uses the attributes you supply to perform the setup work needed prior to drawing content. Drawing to a Window or View provides a simple example that shows how to use renderer and buffer attributes. Choosing Renderer and Buffer Attributes explains how to choose renderer and buffer attributes to achieve specific rendering goals.

Pixel Format Objects

A pixel format describes the format for pixel data storage in memory. The description includes the number and order of components as well as their names (typically red, blue, green and alpha). It also includes other information, such as whether a pixel contains stencil and depth values. A pixel format object is an opaque data structure that holds a pixel format along with a list of renderers and display devices that satisfy the requirements specified by an application.

Each of the Apple-specific OpenGL APIs defines a pixel format data type and accessor routines that you can use to obtain the information referenced by this object. See Virtual Screens for more information on renderer and display devices.

OpenGL Profiles

OpenGL profiles are new in OS X 10.7. An OpenGL profile is a renderer attribute used to request a specific version of the OpenGL specification. When your application provides an OpenGL profile as part of its renderer attributes, it only receives renderers that provide the complete feature set promised by that profile. The render can implement a different version of the OpenGL so long as the version it supplies to your application provides the same functionality that your application requested.

Rendering Contexts

A rendering context, or simply context, contains OpenGL state information and objects for your application. State variables include such things as drawing color, the viewing and projection transformations, lighting characteristics, and material properties. State variables are set per context. When your application creates OpenGL objects (for example, textures), these are also associated with the rendering context.

Although your application can maintain more than one context, only one context can be the current context in a thread. The current context is the rendering context that receives OpenGL commands issued by your application.

Drawable Objects

A drawable object refers to an object allocated by the windowing system that can serve as an OpenGL framebuffer. A drawable object is the destination for OpenGL drawing operations. The behavior of drawable objects is not part of the OpenGL specification, but is defined by the OS X windowing system.

A drawable object can be any of the following: a Cocoa view, offscreen memory, a full-screen graphics device, or a pixel buffer.

Note: A pixel buffer (pbuffer) is an OpenGL buffer designed for hardware-accelerated offscreen drawing and as a source for texturing. An application can render an image into a pixel buffer and then use the pixel buffer as a texture for other OpenGL commands. Although pixel buffers are supported on Apple's implementation of OpenGL, Apple recommends you use framebuffer objects instead. See Drawing Offscreen for more information on offscreen rendering.

Before OpenGL can draw to a drawable object, the object must be attached to a rendering context. The characteristics of the drawable object narrow the selection of hardware and software specified by the rendering context. Apple's OpenGL automatically allocates buffers, creates surfaces, and specifies which renderer is the current renderer.

The logical flow of data from an application through OpenGL to a drawable object is shown in Figure 1-7. The application issues OpenGL commands that are sent to the current rendering context. The current context, which contains state information, constrains how the commands are interpreted by the appropriate renderer. The renderer converts the OpenGL primitives to an image in the framebuffer. (See also Running an OpenGL Program in OS X .)

Virtual Screens

The characteristics and quality of the OpenGL content that the user sees depend on both the renderer and the physical display used to view the content. The combination of renderer and physical display is called a virtual screen. This important concept has implications for any OpenGL application running on OS X.

A simple system, with one graphics card and one physical display, typically has two virtual screens. One virtual screen consists of a hardware-based renderer and the physical display and the other virtual screen consists of a software-based renderer and the physical display. OS X provides a software-based renderer as a fallback. It's possible for your application to decline the use of this fallback. You'll see how in Choosing Renderer and Buffer Attributes.

The green rectangle around the OpenGL image in Figure 1-8 surrounds a virtual screen for a system with one graphics card and one display. Note that a virtual screen is not the physical display, which is why the green rectangle is drawn around the application window that shows the OpenGL content. In this case, it is the renderer provided by the graphics card combined with the characteristics of the display.

Because a virtual screen is not simply the physical display, a system with one display can use more than one virtual screen at a time, as shown in Figure 1-9. The green rectangles are drawn to point out each virtual screen. Imagine that the virtual screen on the right side uses a software-only renderer and that the one on the left uses a hardware-dependent renderer. Although this is a contrived example, it illustrates the point.

It's also possible to have a virtual screen that can represent more than one physical display. The green rectangle in Figure 1-10 is drawn around a virtual screen that spans two physical displays. In this case, the same graphics hardware drives a pair of identical displays. A mirrored display also has a single virtual screen associated with multiple physical displays.

The concept of a virtual screen is particularly important when the user drags an image from one physical screen to another. When this happens, the virtual screen may change, and with it, a number of attributes of the imaging process, such as the current renderer, may change. With the dual-headed graphics card shown in Figure 1-10, dragging between displays preserves the same virtual screen. However, Figure 1-11 shows the case for which two displays represent two unique virtual screens. Not only are the two graphics cards different, but it's possible that the renderer, buffer attributes, and pixel characteristics are different. A change in any of these three items can result in a change in the virtual screen.

When the user drags an image from one display to another, and the virtual screen is the same for both displays, the image quality should appear similar. However, for the case shown in Figure 1-11, the image quality can be quite different.

OpenGL for OS X transparently manages rendering across multiple monitors. A user can drag a window from one monitor to another, even though their display capabilities may be different or they may be driven by dissimilar graphics cards with dissimilar resolutions and color depths.

Egl Assignment 1 Mac Os Download

OpenGL dynamically switches renderers when the virtual screen that contains the majority of the pixels in an OpenGL window changes. When a window is split between multiple virtual screens, the framebuffer is rasterized entirely by the renderer driving the screen that contains the largest segment of the window. The regions of the window on the other virtual screens are drawn by copying the rasterized image. When the entire OpenGL drawable object is displayed on one virtual screen, there is no performance impact from multiple monitor support.

Applications need to track virtual screen changes and, if appropriate, update the current application state to reflect changes in renderer capabilities. See Working with Rendering Contexts.

Offline Renderer

An offline renderer is one that is not currently associated with a display. For example, a graphics processor might be powered down to conserve power, or there might not be a display hooked up to the graphics card. Offline renderers are not normally visible to your application, but your application can enable them by adding the appropriate renderer attribute. Taking advantage of offline renderers is useful because it gives the user a seamless experience when they plug in or remove displays.

For more information about configuring a context to see offline renderers, see Choosing Renderer and Buffer Attributes. To enable your application to switch to a renderer when a display is attached, see Update the Rendering Context When the Renderer or Geometry Changes.

Running an OpenGL Program in OS X

Figure 1-12 shows the flow of data in an OpenGL program, regardless of the platform that the program runs on.

Per-vertex operations include such things as applying transformation matrices to add perspective or to clip, and applying lighting effects. Per-pixel operations include such things as color conversion and applying blur and distortion effects. Pixels destined for textures are sent to texture assembly, where OpenGL stores textures until it needs to apply them onto an object.

OpenGL rasterizes the processed vertex and pixel data, meaning that the data are converged to create fragments. A fragment encapsulates all the values for a pixel, including color, depth, and sometimes texture values. These values are used during antialiasing and any other calculations needed to fill shapes and to connect vertices.

Egl Assignment 1 Mac Os Catalina

Per-fragment operations include applying environment effects, depth and stencil testing, and performing other operations such as blending and dithering. Some operations—such as hidden-surface removal—end the processing of a fragment. OpenGL draws fully processed fragments into the appropriate location in the framebuffer.

The dashed arrows in Figure 1-12 indicate reading pixel data back from the framebuffer. They represent operations performed by OpenGL functions such as glReadPixels, glCopyPixels, and glCopyTexImage2D.

Egl Assignment 1 Mac Os 11

So far you've seen how OpenGL operates on any platform. But how do Cocoa applications provide data to the OpenGL for processing? A Mac application must perform these tasks:

• Set up a list of buffer and renderer attributes that define the sort of drawing you want to perform. (See Renderer and Buffer Attributes.)

• Request the system to create a pixel format object that contains a pixel format that meets the constraints of the buffer and render attributes and a list of all suitable combinations of displays and renderers. (See Pixel Format Objects and Virtual Screens.)

• Create a rendering context to hold state information that controls such things as drawing color, view and projection matrices, characteristics of light, and conventions used to pack pixels. When you set up this context, you must provide a pixel format object because the rendering context needs to know the set of virtual screens that can be used for drawing. (See Rendering Contexts.)

• Bind a drawable object to the rendering context. The drawable object is what captures the OpenGL drawing sent to that rendering context. (See Drawable Objects.)

• Make the rendering context the current context. OpenGL automatically targets the current context. Although your application might have several rendering contexts set up, only the current one is the active one for drawing purposes.

• Issue OpenGL drawing commands.

• Flush the contents of the rendering context. This causes previously submitted commands to be rendered to the drawable object and displays them to the user.

The tasks described in the first five bullet items are platform-specific. Drawing to a Window or View provides simple examples of how to perform them. As you read other parts of this document, you'll see there are a number of other tasks that, although not mandatory for drawing, are really quite necessary for any application that wants to use OpenGL to perform complex 3D drawing efficiently on a wide variety of Macintosh systems.

Making Great OpenGL Applications on the Macintosh

OpenGL lets you create applications with outstanding graphics performance as well as a great user experience—but neither of these things come for free. Your application performs best when it works with OpenGL rather than against it. With that in mind, here are guidelines you should follow to create high-performance, future-looking OpenGL applications:

• Ensure your application runs successfully with offline renderers and multiple graphics cards.

  Apple ships many sophisticated hardware configurations. Your application should handle renderer changes seamlessly. You should test your application on a Mac with multiple graphics processors and include tests for attaching and removing displays. For more information on how to implement hot plugging correctly, see Working with Rendering Contexts

• Avoid finishing and flushing operations.

  Pay particular attention to OpenGL functions that force previously submitted commands to complete. Synchronizing the graphics hardware to the CPU may result in dramatically lower performance. Performance is covered in detail in OpenGL Application Design Strategies.

• Use multithreading to improve the performance of your OpenGL application.

  Many Macs support multiple simultaneous threads of execution. Your application should take advantage of concurrency. Well-behaved applications can take advantage of concurrency in just a few line of code. See Concurrency and OpenGL.

• Use buffer objects to manage your data.

  Vertex buffer objects (VBOs) allow OpenGL to manage your application's vertex data. Using vertex buffer objects gives OpenGL more opportunities to cache vertex data in a format that is friendly to the graphics hardware, improving application performance. For more information see Best Practices for Working with Vertex Data.

  Similarly, pixel buffer objects (PBOs) should be used to manage your image data. See Best Practices for Working with Texture Data

• Use framebuffer objects (FBOs) when you need to render to offscreen memory.

  Framebuffer objects allow your application to create offscreen rendering targets without many of the limitations of platform-dependent interfaces. See Rendering to a Framebuffer Object.

• Generate objects before binding them.

  Earlier version of OpenGL allowed your applications to create its own object names before binding them. However, you should avoid this. Always use the OpenGL API to generate object names.

• Migrate your OpenGL Applications to OpenGL 3.2

  The OpenGL 3.2 Core profile provides a clean break from earlier versions of OpenGL in favor of a simpler shader-based pipeline. For better compatibility with future hardware and OS X releases, migrate your applications away from legacy versions of OpenGL. Many of the recommendations listed above are required when your application uses OpenGL 3.2.

• Harness the power of Apple's development tools.

  Apple provides many tools that help create OpenGL applications and analyze and tune their performance. Learning how to use these tools helps you create fast, reliable applications. Tuning Your OpenGL Application describes many of these tools.

Copyright © 2004, 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-06-04