From b40b3973fb432cc3f7ee563436b9d4b59c3c2354 Mon Sep 17 00:00:00 2001
From: MediaPipe Team <mediapipe-team@google.com>
Date: Wed, 6 Sep 2023 11:37:47 -0700
Subject: [PATCH] Add notes/warnings for calculators which use dedicated GL
 contexts.

PiperOrigin-RevId: 563167765
---
 mediapipe/gpu/gl_surface_sink_calculator.cc      |  4 ++++
 .../gpu/gpu_buffer_to_image_frame_calculator.cc  | 16 ++++++++++++++++
 .../gpu/image_frame_to_gpu_buffer_calculator.cc  |  5 +++++
 3 files changed, 25 insertions(+)

diff --git a/mediapipe/gpu/gl_surface_sink_calculator.cc b/mediapipe/gpu/gl_surface_sink_calculator.cc
index dbbf25268..f56dbc849 100644
--- a/mediapipe/gpu/gl_surface_sink_calculator.cc
+++ b/mediapipe/gpu/gl_surface_sink_calculator.cc
@@ -40,6 +40,10 @@ enum { kAttribVertex, kAttribTexturePosition, kNumberOfAttributes };
 //   SURFACE: unique_ptr to an EglSurfaceHolder to draw to.
 //
 // See GlSurfaceSinkCalculatorOptions for options.
+//
+// NOTE: all GlSurfaceSinkCalculators use a common dedicated shared GL context
+// thread by default, which is different from the main GL context thread used by
+// the graph. (If MediaPipe uses multithreading and multiple OpenGL contexts.)
 class GlSurfaceSinkCalculator : public Node {
  public:
   static constexpr Input<
diff --git a/mediapipe/gpu/gpu_buffer_to_image_frame_calculator.cc b/mediapipe/gpu/gpu_buffer_to_image_frame_calculator.cc
index c9527880a..7222273e6 100644
--- a/mediapipe/gpu/gpu_buffer_to_image_frame_calculator.cc
+++ b/mediapipe/gpu/gpu_buffer_to_image_frame_calculator.cc
@@ -27,6 +27,22 @@
 namespace mediapipe {
 
 // Convert an input image (GpuBuffer or ImageFrame) to ImageFrame.
+//
+// NOTE: all GpuBufferToImageFrameCalculators use a common dedicated shared GL
+// context thread by default, which is different from the main GL context thread
+// used by the graph. (If MediaPipe uses multithreading and multiple OpenGL
+// contexts.)
+//
+// IMPORTANT: graph writer must make sure input GpuBuffer backed OpenGL texture
+// is not in use before the calculator starts processing and not used by any
+// other code until the calculator returns:
+// - pixel transfer involves attaching GpuBuffer backing texture as a logical
+//   buffer to a particular bound framebuffer.
+// - and if texture is already bound and enabled for texturing, this may lead
+//   to a "feedback loop" and undefined results.
+// See, OpenGL ES 3.0 Spec 4.4.3 "Feedback Loops between Textures and the
+// Framebuffer"
+//
 class GpuBufferToImageFrameCalculator : public CalculatorBase {
  public:
   GpuBufferToImageFrameCalculator() {}
diff --git a/mediapipe/gpu/image_frame_to_gpu_buffer_calculator.cc b/mediapipe/gpu/image_frame_to_gpu_buffer_calculator.cc
index a741e42a7..8b56ee1c5 100644
--- a/mediapipe/gpu/image_frame_to_gpu_buffer_calculator.cc
+++ b/mediapipe/gpu/image_frame_to_gpu_buffer_calculator.cc
@@ -24,6 +24,11 @@
 namespace mediapipe {
 
 // Convert ImageFrame to GpuBuffer.
+//
+// NOTE: all ImageFrameToGpuBufferCalculators use a common dedicated shared GL
+// context thread by default, which is different from the main GL context thread
+// used by the graph. (If MediaPipe uses multithreading and multiple OpenGL
+// contexts.)
 class ImageFrameToGpuBufferCalculator : public CalculatorBase {
  public:
   ImageFrameToGpuBufferCalculator() {}