Add OpenGL interop

Author: neon60

.wordlist.txt

@@ -73,7 +73,7 @@ iGPU
 inlined
 inplace
 interop
-Interoperation
+interoperation
 interoperate
 interoperation
 Interprocess
@@ -162,6 +162,8 @@ unintuitive
 UMM
 unmap
 unmapped
+unmapping
+unregister
 upscaled
 variadic
 vulkan

docs/how-to/hip_runtime_api.rst

@@ -44,4 +44,5 @@ Here are the various HIP Runtime API high level functions:
 * :doc:`./hip_runtime_api/hipgraph`
 * :doc:`./hip_runtime_api/call_stack`
 * :doc:`./hip_runtime_api/multi_device`
+* :doc:`./hip_runtime_api/opengl_interop`
 * :doc:`./hip_runtime_api/external_interop`

docs/how-to/hip_runtime_api/opengl_interop.rst

@@ -0,0 +1,94 @@
+.. 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 to interact with OpenGL. 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 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
+ 
+   .. <!-- spellcheck-disable -->
+
+   .. literalinclude:: ../../tools/example_codes/opengl_interop.hip
+      :start-after: // [Sphinx opengl functions load start]
+      :end-before: // [Sphinx opengl functions load end]
+      :language: cpp
+
+   .. <!-- spellcheck-enable -->
+
+The OpenGL buffer is imported to HIP in the following way:
+
+.. <!-- spellcheck-disable -->
+
+.. 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
+
+.. <!-- spellcheck-enable -->
+
+The imported pointer is manipulated in the sinewave kernel as shown in the
+following example:
+
+.. <!-- spellcheck-disable -->
+
+.. 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
+
+.. <!-- spellcheck-enable -->
+
+The HIP graphics resource that is imported from the OpenGL buffer and is not
+needed anymore should be unmapped and unregistered as shown in the following way:
+
+.. <!-- spellcheck-disable -->
+
+.. literalinclude:: ../../tools/example_codes/opengl_interop.hip
+   :start-after: // [Sphinx unregister start]
+   :end-before: // [Sphinx unregister end]
+   :language: cpp
+
+.. <!-- spellcheck-enable -->

docs/sphinx/_toc.yml.in

@@ -53,6 +53,7 @@ subtrees:
       - file: how-to/hip_runtime_api/hipgraph
       - file: how-to/hip_runtime_api/call_stack
       - file: how-to/hip_runtime_api/multi_device
+      - file: how-to/hip_runtime_api/opengl_interop
       - file: how-to/hip_runtime_api/external_interop
   - file: how-to/hip_porting_guide
   - file: how-to/hip_porting_driver_api