FindOpenGL

Finds the OpenGL and OpenGL Utility Library (GLU), for using OpenGL in a CMake project:

find_package(OpenGL [COMPONENTS <components>...] [...])

OpenGL (Open Graphics Library) is a cross-platform API for rendering 2D and 3D graphics. It is widely used in CAD, games, and visualization software.

  • GL refers to the core OpenGL library, which provides the fundamental graphics rendering API.

  • GLU (OpenGL Utility Library) is a companion library that offers utility functions built on top of OpenGL, such as tessellation and more complex shape drawing.

Changed in version 3.2: X11 is no longer added as a dependency on Unix/Linux systems.

Added in version 3.10: GLVND (GL Vendor-Neutral Dispatch library) support on Linux. See the Linux-specific section below.

Components

This module supports optional components which can be specified with the find_package() command:

find_package(OpenGL [COMPONENTS <components>...])

Supported components are:

EGL

Added in version 3.10.

The EGL interface between OpenGL, OpenGL ES and the underlying windowing system.

GLX

Added in version 3.10.

An extension to X that interfaces OpenGL, OpenGL ES with X window system.

OpenGL

Added in version 3.10.

The cross platform API for 3D graphics.

GLES2

Added in version 3.27.

A subset of OpenGL API for embedded systems with limited capabilities.

GLES3

Added in version 3.27.

A subset of OpenGL API for embedded systems with more capabilities.

Imported Targets

This module provides the following Imported Targets:

OpenGL::GL

Added in version 3.8.

Target encapsulating the usage requirements of platform-specific OpenGL libraries, available if OpenGL is found.

OpenGL::GLU

Added in version 3.8.

Target encapsulating the OpenGL Utility Library (GLU) usage requirements, available if GLU is found.

Additionally, the following GLVND-specific library imported targets are provided:

OpenGL::OpenGL

Added in version 3.10.

Target encapsulating the libOpenGL usage requirements, available if system is GLVND-based and OpenGL is found.

OpenGL::GLX

Added in version 3.10.

Target encapsulating the usage requirements of the OpenGL Extension to the the X Window System (GLX), available if OpenGL and GLX are found.

OpenGL::EGL

Added in version 3.10.

Target encapsulating the EGL usage requirements, available if OpenGL and EGL are found.

OpenGL::GLES2

Added in version 3.27.

Target encapsulating the GLES2 usage requirements, available if OpenGL and GLES2 are found.

OpenGL::GLES3

Added in version 3.27.

Target encapsulating the GLES3 usage requirements, available if OpenGL and GLES3 are found.

Result Variables

This module defines the following variables:

OpenGL_FOUND

Added in version 3.3.

Boolean indicating whether the OpenGL and all requested components are found.

OPENGL_XMESA_FOUND

Boolean indicating whether OpenGL XMESA is found.

OPENGL_GLU_FOUND

Boolean indicating whether GLU is found.

OpenGL_OpenGL_FOUND

Added in version 3.10.

Boolean indicating whether GLVND OpenGL library is found.

OpenGL_GLX_FOUND

Added in version 3.10.

Boolean indicating whether GLVND GLX is found.

OpenGL_EGL_FOUND

Added in version 3.10.

Boolean indicating whether GLVND EGL is found.

OpenGL_GLES2_FOUND

Added in version 3.27.

Boolean indicating whether GLES2 is found.

OpenGL_GLES3_FOUND

Added in version 3.27.

Boolean indicating whether GLES3 is found.

OPENGL_INCLUDE_DIRS

Added in version 3.29.

Paths to the OpenGL include directories.

OPENGL_EGL_INCLUDE_DIRS

Added in version 3.10.

Path to the EGL include directory.

OPENGL_LIBRARIES

Paths to the OpenGL library, windowing system libraries, and GLU libraries. On Linux, this assumes GLX and is never correct for EGL-based targets. Clients are encouraged to use the OpenGL::* imported targets instead.

Cache Variables

The following cache variables may also be set:

OPENGL_INCLUDE_DIR

The path to the OpenGL include directory. The OPENGL_INCLUDE_DIRS variable is preferred.

OPENGL_GLU_INCLUDE_DIR

Added in version 3.29.

Path to the OpenGL GLU include directory.

OPENGL_egl_LIBRARY

Added in version 3.10.

Path to the GLVND EGL library.

OPENGL_glu_LIBRARY

Path to the GLU library.

OPENGL_glx_LIBRARY

Added in version 3.10.

Path to the GLVND GLX library.

OPENGL_opengl_LIBRARY

Added in version 3.10.

Path to the GLVND OpenGL library

OPENGL_gl_LIBRARY

Path to the OpenGL library.

OPENGL_gles2_LIBRARY

Added in version 3.27.

Path to the OpenGL GLES2 library.

OPENGL_gles3_LIBRARY

Added in version 3.27.

Path to the OpenGL GLES3 library.

Hints

This module accepts the following variables:

OpenGL_GL_PREFERENCE

Added in version 3.10.

This variable is supported on Linux systems to specify the preferred way to provide legacy GL interfaces in case multiple choices are available. The value may be one of:

GLVND

If the GLVND OpenGL and GLX libraries are available, prefer them. This forces OPENGL_gl_LIBRARY to be empty.

Changed in version 3.11: This is the default, unless policy CMP0072 is set to OLD and no components are requested (since components correspond to GLVND libraries).

LEGACY

Prefer to use the legacy libGL library, if available.

Linux-specific

Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND separates context libraries from OpenGL itself; OpenGL lives in "libOpenGL", and contexts are defined in "libGLX" or "libEGL". GLVND is currently the only way to get OpenGL 3+ functionality via EGL in a manner portable across vendors. Projects may use GLVND explicitly with target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.

Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable) to use legacy GL interfaces. These will use the legacy GL library located by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is empty or not found and GLVND is available, the OpenGL::GL target will use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES variable will use the corresponding libraries). Thus, for non-EGL-based Linux targets, the OpenGL::GL target is most portable.

The OpenGL_GL_PREFERENCE variable may be set to specify the preferred way to provide legacy GL interfaces in case multiple choices are available.

For EGL targets the client must rely on GLVND support on the user's system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets. Using GLES* libraries is theoretically possible in place of OpenGL::OpenGL, but this module does not currently support that; contributions welcome.

OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case of GLVND. For non-GLVND Linux and other systems these are left undefined.

macOS-Specific

On macOS this module defaults to using the macOS-native framework version of OpenGL. To use the X11 version of OpenGL on macOS, one can disable searching of frameworks using the CMAKE_FIND_FRAMEWORK variable. For example:

find_package(X11)
if(APPLE AND X11_FOUND)
  set(CMAKE_FIND_FRAMEWORK NEVER)
  find_package(OpenGL)
  unset(CMAKE_FIND_FRAMEWORK)
else()
  find_package(OpenGL)
endif()

An end user building this project may need to point CMake at their X11 installation, e.g., with -DOpenGL_ROOT=/opt/X11.

Deprecated Variables

The following variables are provided for backward compatibility:

OPENGL_FOUND

Deprecated since version 3.3: Superseded by the OpenGL_FOUND, which has the same value.

Examples

Finding the OpenGL library and linking it to a project target:

find_package(OpenGL)
target_link_libraries(project_target PRIVATE OpenGL::OpenGL)

See Also

  • The FindGLEW module to find OpenGL Extension Wrangler Library (GLEW).

  • The FindGLUT module to find OpenGL Utility Toolkit (GLUT) library.

  • The FindVulkan module to find Vulkan graphics API.