From 3c048075f4b917440f0762721503e8594e721b48 Mon Sep 17 00:00:00 2001
From: Victor Brekenfeld <github@drakulix.de>
Date: Fri, 5 Jun 2020 22:25:36 +0200
Subject: [PATCH] docs: Add more explanations to various graphics code

---
 src/backend/egl/display.rs    | 7 +++++--
 src/backend/egl/surface.rs    | 2 ++
 src/backend/graphics/glium.rs | 2 +-
 3 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/backend/egl/display.rs b/src/backend/egl/display.rs
index 03a9b55..4880c04 100644
--- a/src/backend/egl/display.rs
+++ b/src/backend/egl/display.rs
@@ -90,6 +90,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLDisplay<B, N> {
         };
         debug!(log, "EGL No-Display Extensions: {:?}", dp_extensions);
 
+        // we create an EGLDisplay
         let display = unsafe {
             B::get_display(
                 ptr,
@@ -103,6 +104,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLDisplay<B, N> {
             return Err(Error::DisplayNotSupported);
         }
 
+        // We can then query the egl api version
         let egl_version = {
             let mut major: MaybeUninit<ffi::egl::types::EGLint> = MaybeUninit::uninit();
             let mut minor: MaybeUninit<ffi::egl::types::EGLint> = MaybeUninit::uninit();
@@ -137,6 +139,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLDisplay<B, N> {
         };
         info!(log, "EGL Extensions: {:?}", extensions);
 
+        // egl <= 1.2 does not support OpenGL ES (maybe we want to support OpenGL in the future?)
         if egl_version <= (1, 2) {
             return Err(Error::OpenGlesNotSupported(None));
         }
@@ -222,7 +225,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLDisplay<B, N> {
             out
         };
 
-        // calling `eglChooseConfig`
+        // Try to find configs that match out criteria
         let mut num_configs = 0;
         wrap_egl_call(|| unsafe {
             ffi::egl::ChooseConfig(
@@ -258,7 +261,6 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLDisplay<B, N> {
         }
 
         let desired_swap_interval = if attributes.vsync { 1 } else { 0 };
-
         // try to select a config with the desired_swap_interval
         // (but don't fail, as the margin might be very small on some cards and most configs are fine)
         let config_id = config_ids
@@ -319,6 +321,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLDisplay<B, N> {
             }};
         };
 
+        // return the format that was selected for our config
         let desc = unsafe {
             PixelFormat {
                 hardware_accelerated: attrib!(self.display, config_id, ffi::egl::CONFIG_CAVEAT)
diff --git a/src/backend/egl/surface.rs b/src/backend/egl/surface.rs
index 00d1d42..ea9a198 100644
--- a/src/backend/egl/surface.rs
+++ b/src/backend/egl/surface.rs
@@ -122,6 +122,8 @@ impl<N: native::NativeSurface> EGLSurface<N> {
                     })?
             });
 
+            // if a recreation is pending anyway, ignore page-flip errors.
+            // lets see if we still fail after the next commit.
             result.map_err(|err| {
                 debug!(self.logger, "Hiding page-flip error *before* recreation: {}", err);
                 SwapBuffersError::EGLSwapBuffers(EGLError::BadSurface)
diff --git a/src/backend/graphics/glium.rs b/src/backend/graphics/glium.rs
index 9f619d5..4e04f93 100644
--- a/src/backend/graphics/glium.rs
+++ b/src/backend/graphics/glium.rs
@@ -125,7 +125,7 @@ unsafe impl<T: GLGraphicsBackend> Backend for InternalBackend<T> {
     }
 }
 
-/// Omplementation of `glium::Surface`, targeting the default framebuffer.
+/// Implementation of `glium::Surface`, targeting the default framebuffer.
 ///
 /// The back- and front-buffers are swapped when you call `finish`.
 ///