From 4e3edcbaad520c3312abd95f1513ae72c8a19ca9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1ty=C3=A1s=20Aradi?= Date: Wed, 16 Oct 2024 10:41:54 +0200 Subject: [PATCH] Add OpenGL interop Add words to wordlist WIP --- .wordlist.txt | 4 +- .../how-to/hip_runtime_api/opengl_interop.rst | 157 ++++++++++++++++++ docs/index.md | 1 + docs/sphinx/_toc.yml.in | 1 + 4 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 docs/how-to/hip_runtime_api/opengl_interop.rst diff --git a/.wordlist.txt b/.wordlist.txt index aa0aa7957c..a7a5485a64 100644 --- a/.wordlist.txt +++ b/.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 diff --git a/docs/how-to/hip_runtime_api/opengl_interop.rst b/docs/how-to/hip_runtime_api/opengl_interop.rst new file mode 100644 index 0000000000..6e3b1f276d --- /dev/null +++ b/docs/how-to/hip_runtime_api/opengl_interop.rst @@ -0,0 +1,157 @@ +.. 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 +********************************************************** + +Mapping +======= + +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 +===================== + +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. + +Examples +======== + +Two examples are presented with mapping resources, getting pointers -- directly or with arrays -- and unmapping resources with a OpenGL buffer registration. + +.. tab-set:: + + .. tab-item:: with mapped pointer + + .. code-block:: cpp + :emphasize-lines: 21-24 + + #include + #include + #include + #include + + int main() + { + // Initialize OpenGL and create a buffer + GLuint buffer; + glGenBuffers(1, &buffer); + glBindBuffer(GL_ARRAY_BUFFER, buffer); + glBufferData(GL_ARRAY_BUFFER, size, data, GL_STATIC_DRAW); + + // Register the OpenGL buffer with HIP + hipGraphicsResource* resource; + hipGraphicsGLRegisterBuffer(&resource, buffer, hipGraphicsRegisterFlagsNone); + + // Map the resource for access by HIP + hipGraphicsMapResources(1, &resource, 0); + + // Obtain a pointer to the mapped resource + void* devicePtr; + size_t numBytes; + hipGraphicsResourceGetMappedPointer(&devicePtr, &numBytes, resource); + + // Use devicePtr in HIP kernels... + + // Unmap the resources when done + hipGraphicsUnmapResources(1, &resource, 0); + + // Cleanup OpenGL resources + glDeleteBuffers(1, &buffer); + + return 0; + } + + .. tab-item:: with mapped array + + .. code-block:: cpp + :emphasize-lines: 20-22 + + #include + #include + #include + #include + + int main() + { + // Initialize OpenGL and create a buffer + GLuint buffer; + glGenBuffers(1, &buffer); + glBindBuffer(GL_ARRAY_BUFFER, buffer); + glBufferData(GL_ARRAY_BUFFER, size, data, GL_STATIC_DRAW); + + // Register the OpenGL buffer with HIP + hipGraphicsResource* resource; + hipGraphicsGLRegisterBuffer(&resource, buffer, hipGraphicsRegisterFlagsNone); + + // Map the resource for access by HIP + hipGraphicsMapResources(1, &resource, 0); + + // Obtain a pointer to the mapped array + hipArray* arrayPtr; + hipGraphicsSubResourceGetMappedArray(&arrayPtr, resource, 0, 0); + + // Use arrayPtr in HIP kernels... + + // Unmap the resources when done + hipGraphicsUnmapResources(1, &resource, 0); + + // Cleanup OpenGL resources + glDeleteBuffers(1, &buffer); + + return 0; + } + +An other example is with mapping resources, getting pointers and unmapping resources with a OpenGL image registration. + +.. code-block:: cpp + + #include + #include + #include + #include + + int main() + { + // Initialize OpenGL and create a texture + GLuint texture; + glGenTextures(1, &texture); + glBindTexture(GL_TEXTURE_2D, texture); + glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA, GL_UNSIGNED_BYTE, data); + + // Register the OpenGL texture with HIP + hipGraphicsResource* resource; + hipGraphicsGLRegisterImage(&resource, texture, GL_TEXTURE_2D, hipGraphicsRegisterFlagsNone); + + // Map the resource for access by HIP + hipGraphicsMapResources(1, &resource, 0); + + // Obtain a pointer to the mapped array + hipArray* arrayPtr; + hipGraphicsSubResourceGetMappedArray(&arrayPtr, resource, 0, 0); + + // Use arrayPtr in HIP kernels... + + // Unmap the resources when done + hipGraphicsUnmapResources(1, &resource, 0); + + // Cleanup OpenGL resources + glDeleteTextures(1, &texture); + + return 0; + } diff --git a/docs/index.md b/docs/index.md index 40e910c349..823b1b5c1a 100644 --- a/docs/index.md +++ b/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` diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 1f943a7587..ba55360297 100644 --- a/docs/sphinx/_toc.yml.in +++ b/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