From 73420b75bcb11091f8f31a56787e051ce9c51b37 Mon Sep 17 00:00:00 2001
From: Victor Brekenfeld <github@drakulix.de>
Date: Mon, 24 May 2021 19:28:21 +0200
Subject: [PATCH] renderer: Implementation comments

---
 src/backend/renderer/gles2/mod.rs | 5 +++++
 src/backend/renderer/mod.rs       | 4 ++++
 2 files changed, 9 insertions(+)

diff --git a/src/backend/renderer/gles2/mod.rs b/src/backend/renderer/gles2/mod.rs
index 79f25b3..5b1a240 100644
--- a/src/backend/renderer/gles2/mod.rs
+++ b/src/backend/renderer/gles2/mod.rs
@@ -42,6 +42,10 @@ pub mod ffi {
     include!(concat!(env!("OUT_DIR"), "/gl_bindings.rs"));
 }
 
+// This static is used to assign every created Renderer a unique ID (until is overflows...).
+//
+// This id is used to differenciate between user_data of different renderers, because one
+// cannot assume, that resources between two renderers are (and even can be) shared.
 static RENDERER_COUNTER: AtomicUsize = AtomicUsize::new(0);
 
 #[derive(Debug)]
@@ -361,6 +365,7 @@ impl Gles2Renderer {
     /// `EGLContext` shared with the given one (see `EGLContext::new_shared`) and can be used and destroyed on
     /// any of these renderers.
     /// - This renderer has no default framebuffer, use `Bind::bind` before rendering.
+    /// - Binding a new target, while another one is already bound, will replace the current target.
     /// - Shm buffers can be released after a successful import, without the texture handle becoming invalid.
     pub unsafe fn new<L>(context: EGLContext, logger: L) -> Result<Gles2Renderer, Gles2Error>
     where
diff --git a/src/backend/renderer/mod.rs b/src/backend/renderer/mod.rs
index 8d68c81..e19d344 100644
--- a/src/backend/renderer/mod.rs
+++ b/src/backend/renderer/mod.rs
@@ -108,6 +108,10 @@ impl From<wayland_server::protocol::wl_output::Transform> for Transform {
 /// Abstraction for Renderers, that can render into different targets
 pub trait Bind<Target>: Unbind {
     /// Bind a given rendering target, which will contain the rendering results until `unbind` is called.
+    /// 
+    /// Binding to target, while another one is already bound, is rendering defined.
+    /// Some renderers might happily replace the current target, while other might drop the call
+    /// or throw an error.
     fn bind(&mut self, target: Target) -> Result<(), <Self as Renderer>::Error>;
     /// Supported pixel formats for given targets, if applicable.
     fn supported_formats(&self) -> Option<HashSet<crate::backend::allocator::Format>> {