Add OpenGL interop

.wordlist.txt

@@ -72,7 +72,7 @@ iGPU
 inlined
 inplace
 interop
-Interoperation
+interoperation
 interoperate
 Interprocess
 interprocess
@@ -154,6 +154,8 @@ typedefs
 unintuitive
 UMM
 unmap
+unmapped
+unmapping
 upscaled
 variadic
 WinGDB

docs/how-to/hip_runtime_api/opengl_interop.rst

@@ -0,0 +1,76 @@
+.. meta::
+   :description: HIP provides an OpenGL interoperability API that allows
+                 efficient data sharing between HIP's computing power and
+                 OpenGL's graphics rendering.
+   :keywords: AMD, ROCm, HIP, OpenGL, interop, interoperability
+
+********************************************************************************
+OpenGL interoperability
+********************************************************************************
+
+The HIP--OpenGL interoperation involves mapping OpenGL resources, such as
+buffers and textures, for HIP access. This mapping process enables HIP to
+utilize these resources directly, bypassing the need for costly data transfers between
+the CPU and GPU. This capability is useful in applications that require both
+intensive GPU computation and real-time visualization.
+
+The graphics resources must be registered using functions like
+:cpp:func:`hipGraphicsGLRegisterBuffer` or :cpp:func:`hipGraphicsGLRegisterImage`
+then they can be mapped to HIP with :cpp:func:`hipGraphicsMapResources`
+function.
+
+After mapping, the :cpp:func:`hipGraphicsResourceGetMappedPointer` or
+:cpp:func:`hipGraphicsSubResourceGetMappedArray` functions used to retrieve a
+device pointer to the mapped resource, which can then be used in HIP kernels.
+
+Unmapping resources with :cpp:func:`hipGraphicsUnmapResources` after
+computations ensure proper resource management.
+
+Example
+================================================================================
+
+ROCm examples have a `HIP--OpenGL interoperation example <https://github.com/ROCm/rocm-examples/tree/develop/HIP-Basic/opengl_interop>`_,
+where a simple HIP kernel is used to simulate a sine wave and rendered to a
+window as a grid of triangles using OpenGL. For a working example, there are
+multiple initialization steps needed like creating and opening a window, 
+initializing OpenGL or selecting the OpenGL-capable device. After the initialization
+in the example, the kernel simulates the sinewave and updates the window's
+framebuffer in a cycle until the window is not closed.
+
+.. note::
+
+   The more recent OpenGL functions are loaded with `OpenGL loader <https://github.com/ROCm/rocm-examples/tree/develop/External/glad>`_,
+   as these are not loaded by default on all platforms. The use of a custom
+   loader is shown in the following example
+
+   .. literalinclude:: ../../tools/example_codes/opengl_interop.hip
+      :start-after: // [Sphinx opengl functions load start]
+      :end-before: // [Sphinx opengl functions load end]
+      :language: cpp
+
+The OpenGL buffer is imported to HIP in the following way:
+
+.. literalinclude:: ../../tools/example_codes/opengl_interop.hip
+   :start-after: // [Sphinx buffer register and get start]
+   :end-before: // [Sphinx buffer register and get end]
+   :language: cpp
+
+The imported pointer is manipulated in the sinewave kernel as shown in the following example:
+
+.. literalinclude:: ../../tools/example_codes/opengl_interop.hip
+   :start-after: /// [Sphinx sinewave kernel start]
+   :end-before: /// [Sphinx sinewave kernel end]
+   :language: cpp
+
+.. literalinclude:: ../../tools/example_codes/opengl_interop.hip
+   :start-after: // [Sphinx buffer use in kernel start]
+   :end-before: // [Sphinx buffer use in kernel end]
+   :language: cpp
+
+The HIP graphics resource that is imported from the OpenGL buffer has to be
+unmap and unregister in the following way:
+
+.. literalinclude:: ../../tools/example_codes/opengl_interop.hip
+   :start-after: // [Sphinx unregister start]
+   :end-before: // [Sphinx unregister end]
+   :language: cpp

docs/index.md

@@ -33,6 +33,7 @@ The HIP documentation is organized into the following categories:
   * {doc}`./how-to/hip_runtime_api/memory_management`
   * {doc}`./how-to/hip_runtime_api/cooperative_groups`
   * {doc}`./how-to/hip_runtime_api/hipgraph`
+  * {doc}`./how-to/hip_runtime_api/opengl_interop`
 * [HIP porting guide](./how-to/hip_porting_guide)
 * [HIP porting: driver API guide](./how-to/hip_porting_driver_api)
 * {doc}`./how-to/hip_rtc`

docs/sphinx/_toc.yml.in

@@ -48,6 +48,7 @@ subtrees:
           - file: how-to/hip_runtime_api/memory_management/stream_ordered_allocator
       - file: how-to/hip_runtime_api/cooperative_groups
       - file: how-to/hip_runtime_api/hipgraph
+      - file: how-to/hip_runtime_api/opengl_interop
   - file: how-to/hip_porting_guide
   - file: how-to/hip_porting_driver_api
   - file: how-to/hip_rtc