From 8d278705b102b4174ee19ba691366d9c5213c61d Mon Sep 17 00:00:00 2001
From: nadro <nadro@dfc29bdd-3216-0410-991c-e03cc46cb475>
Date: Tue, 5 Nov 2013 20:56:26 +0000
Subject: [PATCH] Added comments to EGL manager.

git-svn-id: svn://svn.code.sf.net/p/irrlicht/code/branches/ogl-es@4603 dfc29bdd-3216-0410-991c-e03cc46cb475
---
 source/Irrlicht/CEGLManager.cpp | 16 +++++++++++++++-
 source/Irrlicht/CEGLManager.h   | 12 ++++++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/source/Irrlicht/CEGLManager.cpp b/source/Irrlicht/CEGLManager.cpp
index 19829074..6b341dea 100755
--- a/source/Irrlicht/CEGLManager.cpp
+++ b/source/Irrlicht/CEGLManager.cpp
@@ -32,6 +32,7 @@ bool CEGLManager::initialize()
     if (EglWindow != 0 && EglDisplay != EGL_NO_DISPLAY)
         return true;
 
+	// Window is depend on platform.
 #if defined(_IRR_COMPILE_WITH_WINDOWS_DEVICE_)
 	EglWindow = (NativeWindowType)Data->OpenGLWin32.HWnd;
 	HDc = GetDC((HWND)EglWindow);
@@ -44,6 +45,7 @@ bool CEGLManager::initialize()
     EglDisplay = eglGetDisplay((NativeDisplayType) EGL_DEFAULT_DISPLAY);
 #endif
 
+	// We must check if EGL display is valid.
 	if (EglDisplay == EGL_NO_DISPLAY)
     {
 		os::Printer::log("Could not get EGL display.");
@@ -59,6 +61,7 @@ bool CEGLManager::initialize()
         return false;
     }
 
+	// Initialize EGL here.
 	if (!eglInitialize(EglDisplay, &MajorVersion, &MinorVersion))
     {
 		os::Printer::log("Could not initialize EGL display.");
@@ -86,6 +89,7 @@ void CEGLManager::terminate()
     if (EglWindow == 0 && EglDisplay == EGL_NO_DISPLAY)
         return;
 
+	// We should unbind current EGL context before terminate EGL.
     eglMakeCurrent(EglDisplay, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
 
 	eglTerminate(EglDisplay);
@@ -111,12 +115,15 @@ bool CEGLManager::createSurface()
     if (EglSurface != EGL_NO_SURFACE)
         return true;
 
+	// We should assign new WindowID on platforms, where WindowID may change at runtime,
+	// at this time only Android support this feature.
 #if defined(_IRR_COMPILE_WITH_ANDROID_DEVICE_)
 	EglWindow = (ANativeWindow*)Data->OGLESAndroid.window;
 #endif
 
 	EGLint EglOpenGLBIT = 0;
 
+	// We need properly OpenGL BIT.
 	switch (Params.DriverType)
 	{
 	case EDT_OGLES1:
@@ -151,6 +158,7 @@ bool CEGLManager::createSurface()
 	EGLint NumConfigs = 0;
 	u32 Steps = 5;
 
+	// Choose the best EGL config.
 	while (!eglChooseConfig(EglDisplay, Attribs, &EglConfig, 1, &NumConfigs) || !NumConfigs)
 	{
 		switch (Steps)
@@ -238,7 +246,8 @@ bool CEGLManager::createSurface()
 
     ANativeWindow_setBuffersGeometry(EglWindow, 0, 0, Format);
 #endif
-   
+	
+	// Now we are able to create EGL surface.
 	EglSurface = eglCreateWindowSurface(EglDisplay, EglConfig, EglWindow, 0);
 	
 	if (EGL_NO_SURFACE == EglSurface)
@@ -252,9 +261,11 @@ bool CEGLManager::createSurface()
 		eglBindAPI(EGL_OPENGL_ES_API);
 #endif
 
+	// FIX-ME
     if (Params.Vsync)
 		eglSwapInterval(EglDisplay, 1);
 
+	// If EGL context already exist we should activate it.
     if (EglContext != EGL_NO_CONTEXT)
         eglMakeCurrent(EglDisplay, EglSurface, EglSurface, EglContext);
 
@@ -266,6 +277,7 @@ void CEGLManager::destroySurface()
     if (EglSurface == EGL_NO_SURFACE)
         return;
 
+	// We should unbind current EGL context before destroy EGL surface.
     eglMakeCurrent(EglDisplay, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
 
     eglDestroySurface(EglDisplay, EglSurface);
@@ -320,7 +332,9 @@ void CEGLManager::destroyContext()
     if (EglContext == EGL_NO_CONTEXT)
         return;
 
+	// We must unbind current EGL context before destroy it.
     eglMakeCurrent(EglDisplay, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
+
 	eglDestroyContext(EglDisplay, EglContext);
 
     EglContext = EGL_NO_CONTEXT;
diff --git a/source/Irrlicht/CEGLManager.h b/source/Irrlicht/CEGLManager.h
index ad4a9a76..fc89f6ce 100755
--- a/source/Irrlicht/CEGLManager.h
+++ b/source/Irrlicht/CEGLManager.h
@@ -32,21 +32,33 @@ namespace video
         virtual ~CEGLManager();
 
         // Initialize EGL.
+		/* This method initialize EGLand create EGL display, anyway surface and context
+		aren't create. */
         bool initialize();
 
         // Terminate EGL.
+		/* Terminate EGL context. This method break both existed surface and context. */
         void terminate();
 
         // Create EGL surface.
+		/* This method create EGL surface. On some platforms eg. Android, we must
+		recreate surface on each resume, because WindowID may change, so existed
+		surface may not be valid. If EGL context already exist, this method
+		automatically activates it. */
         bool createSurface();
 
         // Destroy EGL surface.
+		/* This method destroy EGL. On some platforms eg. Android, we should call
+		this method on each pause, because after resume this surface may not be valid.
+		Hovewer this method doesn'r break EGL context. */
         void destroySurface();
 
         // Create EGL context.
+		/* This method create and activate EGL context. */
         bool createContext();
 
         // Destroy EGL context.
+		/* This method destroy EGL context. */
         void destroyContext();
 
         // Swap buffers.