WIP

docs/how-to/hip_runtime_api/opengl_interop.rst

@@ -8,58 +8,25 @@
 OpenGL interoperability
 ********************************************************************************
 
-Mapping
-================================================================================
+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 data transfers between
+the CPU and GPU. This capability is useful in applications that require both
+intensive GPU computation and real-time visualization.
 
-Mapping resources
---------------------------------------------------------------------------------
-
-The initial step in 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 data transfers
-between the CPU and GPU. Specific HIP runtime API functions are employed to map
-the resources, making them available for HIP kernels' computations. This step is
-crucial for applications requiring large dataset processing using GPU
-computational power. By creating a bridge between OpenGL and HIP, mapping
-significantly enhances data handling efficiency. Intermediate data copies are
-eliminated, resulting in expedited data processing and rendering. Consequently,
-mapping resources is essential for smooth interoperation.
-
-Getting mapped pointers
---------------------------------------------------------------------------------
-
-Following the mapping of resources, the next task is obtaining the
-device-accessible address of the OpenGL resource. HIP API functions are utilized
-to retrieve pointers to these mapped resources. These pointers allow HIP kernels
-to directly access and manipulate the data within OpenGL resources. The process
-entails querying the mapped resource for its device address, which can then be
-used in HIP kernels for reading and writing operations. Direct access through
-the device-addressable pointer reduces overhead associated with data movement
-and enhances overall performance. The integration of the device address
-facilitates seamless data handling and sharing between HIP and OpenGL.
-
-Unmapping resources
---------------------------------------------------------------------------------
-
-Upon completion of the necessary computations and data manipulations, resources
-must be unmapped to release HIP access. HIP API functions are employed to unmap
-the resources, ensuring proper management and availability for future use.
-Unmapping resources signals the end of their usage by HIP, maintaining the
-integrity and availability of these resources. This step prevents unnecessary
-retention of resources, thereby freeing up GPU memory. Effective resource
-lifecycle management is achieved through the unmapping process, contributing to
-system stability and efficiency. Properly concluding the interoperation process
-necessitates unmapping resources.
-
-Registering resources
-================================================================================
+The OpenGL resource can be mapped to HIP with :cpp:func:`hipGraphicsMapResources`
+function and the device pointers are accessed with
+:cpp:func:`hipGraphicsResourceGetMappedPointer` or
+:cpp:func:`hipGraphicsSubResourceGetMappedArray` functions.
 
-To enable HIP--OpenGL interoperation, registering OpenGL resources with HIP is required. This process creates corresponding HIP graphics resources, utilized in HIP kernels. Registration is accomplished using HIP runtime API functions, which take OpenGL resources and generate their HIP representations. These HIP graphics resources can then be mapped, accessed, and manipulated within HIP. This preparatory step ensures resources are properly identified and managed within the HIP environment. Dual accessibility of resources in both OpenGL and HIP contexts is achieved through registration. The registration of resources establishes the foundation for efficient and integrated data handling in HIP--OpenGL interoperation.
+Unmapping resources with :cpp:func:`hipGraphicsUnmapResources` after
+computations ensures proper resource management.
 
 Examples
-========
+================================================================================
 
-Two examples are presented with mapping resources, getting pointers -- directly or with arrays -- and unmapping resources with a OpenGL buffer registration.
+Two examples are presented with mapping resources, getting pointers -- directly
+or with arrays -- and unmapping resources with a OpenGL buffer registration.
 
 .. tab-set::