From 24be068742dc2881f63a023f85687c6636381111 Mon Sep 17 00:00:00 2001
From: thefiddler <stapostol@gmail.com>
Date: Sun, 26 Jan 2014 10:36:52 +0100
Subject: [PATCH] [GLControl] Clarified docs regarding multiple contexts

---
 Source/GLControl/GLControl.cs | 44 ++++++++++++++++++++++++++++-------
 1 file changed, 35 insertions(+), 9 deletions(-)

diff --git a/Source/GLControl/GLControl.cs b/Source/GLControl/GLControl.cs
index bafed945..a4efd029 100644
--- a/Source/GLControl/GLControl.cs
+++ b/Source/GLControl/GLControl.cs
@@ -287,6 +287,7 @@ namespace OpenTK
 
         /// <summary>
         /// Swaps the front and back buffers, presenting the rendered scene to the screen.
+        /// This method will have no effect on a single-buffered <c>GraphicsMode</c>.
         /// </summary>
         public void SwapBuffers()
         {
@@ -299,8 +300,19 @@ namespace OpenTK
         #region public void MakeCurrent()
 
         /// <summary>
-        /// Makes the underlying this GLControl current in the calling thread.
-        /// All OpenGL commands issued are hereafter interpreted by this GLControl.
+        /// <para>
+        /// Makes <see cref="GLControl.Context"/> current in the calling thread.
+        /// All OpenGL commands issued are hereafter interpreted by this context.
+        /// </para>
+        /// <para>
+        /// When using multiple <c>GLControl</c>s, calling <c>MakeCurrent</c> on
+        /// one control will make all other controls non-current in the calling thread.
+        /// </para>
+        /// <seealso cref="Context"/>
+        /// <para>
+        /// A <c>GLControl</c> can only be current in one thread at a time.
+        /// To make a control non-current, call <c>GLControl.Context.MakeCurrent(null)</c>.
+        /// </para>
         /// </summary>
         public void MakeCurrent()
         {
@@ -330,7 +342,12 @@ namespace OpenTK
         #region public IGraphicsContext Context
 
         /// <summary>
-        /// Gets an interface to the underlying GraphicsContext used by this GLControl.
+        /// Gets the <c>IGraphicsContext</c> instance that is associated with the <c>GLControl</c>.
+        /// The associated <c>IGraphicsContext</c> is updated whenever the <c>GLControl</c>
+        /// handle is created or recreated.
+        /// When using multiple <c>GLControl</c>s, ensure that <c>Context</c>
+        /// is current before performing any OpenGL operations.
+        /// <seealso cref="MakeCurrent"/>
         /// </summary>
         [Browsable(false)]
         public IGraphicsContext Context
@@ -365,7 +382,11 @@ namespace OpenTK
         #region public bool VSync
 
         /// <summary>
-        /// Gets or sets a value indicating whether vsync is active for this GLControl.
+        /// Gets or sets a value indicating whether vsync is active for this <c>GLControl</c>.
+        /// When using multiple <c>GLControl</c>s, ensure that <see cref="Context"/>
+        /// is current before accessing this property.
+        /// <seealso cref="Context"/>
+        /// <seealso cref="MakeCurrent"/>
         /// </summary>
         [Description("Indicates whether GLControl updates are synced to the monitor's refresh rate.")]
         public bool VSync
@@ -400,11 +421,10 @@ namespace OpenTK
         #region public GraphicsMode GraphicsMode
 
         /// <summary>
-        /// Gets the GraphicsMode of the GraphicsContext attached to this GLControl.
+        /// Gets the <c>GraphicsMode</c> of the <c>IGraphicsContext</c> associated with
+        /// this <c>GLControl</c>. If you wish to change <c>GraphicsMode</c>, you must
+        /// destroy and recreate the <c>GLControl</c>.
         /// </summary>
-        /// <remarks>
-        /// To change the GraphicsMode, you must destroy and recreate the GLControl.
-        /// </remarks>
         public GraphicsMode GraphicsMode
         {
             get
@@ -430,7 +450,13 @@ namespace OpenTK
 
         #region public Bitmap GrabScreenshot()
 
-        /// <summary>Grabs a screenshot of the frontbuffer contents.</summary>
+        /// <summary>
+        /// Grabs a screenshot of the frontbuffer contents.
+        /// When using multiple <c>GLControl</c>s, ensure that  <see cref="Context"/>
+        /// is current before accessing this property.
+        /// <seealso cref="Context"/>
+        /// <seealso cref="MakeCurrent"/>
+        /// </summary>
         /// <returns>A System.Drawing.Bitmap, containing the contents of the frontbuffer.</returns>
         /// <exception cref="OpenTK.Graphics.GraphicsContextException">
         /// Occurs when no OpenTK.Graphics.GraphicsContext is current in the calling thread.