# 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 OpenGL and all requested components were found.

`OPENGL_XMESA_FOUND`

  Boolean indicating whether OpenGL XMESA was found.

`OPENGL_GLU_FOUND`

  Boolean indicating whether GLU was found.

`OpenGL_OpenGL_FOUND`

  Added in version 3.10.

  Boolean indicating whether the GLVND OpenGL library was found.

`OpenGL_GLX_FOUND`

  Added in version 3.10.

  Boolean indicating whether GLVND GLX was found.

`OpenGL_EGL_FOUND`

  Added in version 3.10.

  Boolean indicating whether GLVND EGL was found.

`OpenGL_GLES2_FOUND`

  Added in version 3.27.

  Boolean indicating whether GLES2 was found.

`OpenGL_GLES3_FOUND`

  Added in version 3.27.

  Boolean indicating whether GLES3 was 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 4.2: Use `OpenGL_FOUND`, which has the same value.

  Boolean indicating whether OpenGL and all requested components were found.

## 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.