# FindOpenGL

FindModule for OpenGL and OpenGL Utility Library (GLU).

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

Added in version 3.10: GLVND support on Linux. See the Linux-specific section below.

## Optional COMPONENTS

Added in version 3.10.

This module respects several optional COMPONENTS:

`EGL`

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

`GLX`

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

`OpenGL`

  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

Added in version 3.8.

This module defines the `IMPORTED` targets:

`OpenGL::GL`

  Defined to the platform-specific OpenGL libraries if the system has OpenGL.

`OpenGL::GLU`

  Defined if the system has OpenGL Utility Library (GLU).

Added in version 3.10: Additionally, the following GLVND-specific library targets are defined:

`OpenGL::OpenGL`

  Defined to libOpenGL if the system is GLVND-based.

`OpenGL::GLX`

  Defined if the system has OpenGL Extension to the X Window System (GLX).

`OpenGL::EGL`

  Defined if the system has EGL.

`OpenGL::GLES2`

  Added in version 3.27.

  Defined if the system has GLES2.

`OpenGL::GLES3`

  Added in version 3.27.

  Defined if the system has GLES3.

## Result Variables

This module sets the following variables:

`OPENGL_FOUND`

  True, if the system has OpenGL and all components are found.

`OPENGL_XMESA_FOUND`

  True, if the system has XMESA.

`OPENGL_GLU_FOUND`

  True, if the system has GLU.

`OpenGL_OpenGL_FOUND`

  True, if the system has an OpenGL library.

`OpenGL_GLX_FOUND`

  True, if the system has GLX.

`OpenGL_EGL_FOUND`

  True, if the system has EGL.

`OpenGL::GLES2`

  Defined if the system has GLES2.

`OpenGL::GLES3`

  Defined if the system has GLES3.

`OPENGL_INCLUDE_DIR`

  Path to the OpenGL include directory. The `OPENGL_INCLUDE_DIRS` variable is preferred.

`OPENGL_EGL_INCLUDE_DIRS`

  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::*` import targets instead.

`OPENGL_INCLUDE_DIRS`

  Added in version 3.29.

  Paths to the OpenGL include directories.

Added in version 3.10: Variables for GLVND-specific libraries `OpenGL`, `EGL` and `GLX`.

## Cache variables

The following cache variables may also be set:

`OPENGL_egl_LIBRARY`

  Path to the EGL library.

`OPENGL_glu_LIBRARY`

  Path to the GLU library.

`OPENGL_glx_LIBRARY`

  Path to the GLVND 'GLX' library.

`OPENGL_opengl_LIBRARY`

  Path to the GLVND 'OpenGL' library

`OPENGL_gl_LIBRARY`

  Path to the OpenGL library. New code should prefer the `OpenGL::*` import targets.

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

`OPENGL_GLU_INCLUDE_DIR`

  Added in version 3.29.

  Path to the OpenGL GLU include directory.

Added in version 3.10: Variables for GLVND-specific libraries `OpenGL`, `EGL` and `GLX`.

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

A `OpenGL_GL_PREFERENCE` variable may be set 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.

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