Javadoc.

3 files changed, 195 insertions, 3 deletions

diff --git a/bundles/org.eclipse.swt.opengl/common/org/eclipse/swt/opengl/GLData.java b/bundles/org.eclipse.swt.opengl/common/org/eclipse/swt/opengl/GLData.java
index b57872ac34..fc393dac5c 100644
--- a/bundles/org.eclipse.swt.opengl/common/org/eclipse/swt/opengl/GLData.java
+++ b/bundles/org.eclipse.swt.opengl/common/org/eclipse/swt/opengl/GLData.java
@@ -10,20 +10,111 @@
  *******************************************************************************/
 package org.eclipse.swt.opengl;
 
+/**
+ * The GLData class is a device-independent description
+ * of the pixel format attributes of a GL drawable.
+ *
+ * @see GLCanvas
+ */
+
 public class GLData {
-	public int bufferSize;
+	/**
+	 * Specifies a double-buffered surface.  During context
+	 * creation, only double-buffered formats are considered
+	 * when set to true. 
+	 */
 	public boolean doubleBuffer;
+
+	/**
+	 * Specifies a stereo surface.  During context creation,
+	 * only stereo formats are considered when set to true. 
+	 */
 	public boolean stereo;
+
+	/**
+	 * The size in bits of the color buffer's red channel.
+	 * During context creation, this specifies the minimum
+	 * required red bits.
+	 */
 	public int redSize;
+
+	/**
+	 * The size in bits of the color buffer's green channel.
+	 * During context creation, this specifies the minimum
+	 * required green bits.
+	 */
 	public int greenSize;
+
+	/**
+	 * The size in bits of the color buffer's blue channel.
+	 * During context creation, this specifies the minimum
+	 * required blue bits.
+	 */
 	public int blueSize;
+
+	/**
+	 * The size in bits of the color buffer's alpha channel.
+	 * During context creation, this specifies the minimum
+	 * required alpha bits.
+	 */
 	public int alphaSize;
+
+	/**
+	 * The size in bits of the depth buffer.  During context
+	 * creation, the smallest depth buffer of at least the
+	 * specified value is preferred, or zero for no depth
+	 * buffer.
+	 */
 	public int depthSize;
+
+	/**
+	 * The desired number of stencil bitplanes.  During
+	 * context creation, the smallest stencil buffer of at
+	 * least the specified value is preferred, or zero for
+	 * no stencil buffer.
+	 */
 	public int stencilSize;
+
+	/**
+	 * The size in bits of the accumulation buffer's red
+	 * channel. During context creation, this specifies the
+	 * minimum required red bits.
+	 */
 	public int accumRedSize;
+
+	/**
+	 * The size in bits of the accumulation buffer's green
+	 * channel. During context creation, this specifies the
+	 * minimum required green bits.
+	 */
 	public int accumGreenSize;
+
+	/**
+	 * The size in bits of the accumulation buffer's blue
+	 * channel. During context creation, this specifies the
+	 * minimum required blue bits.
+	 */
 	public int accumBlueSize;
+
+	/**
+	 * The size in bits of the accumulation buffer's alpha
+	 * channel. During context creation, this specifies the
+	 * minimum required alpha bits.
+	 */
 	public int accumAlphaSize;
+
+	/**
+	 * The number of multisample buffers used by this context.
+	 * During context creation, this specifies the minimum
+	 * number of multisample buffers requested.
+	 */
 	public int sampleBuffers;
+
+	/**
+	 * The number of samples accepted in the multisample buffer.
+	 * During creation, pixel formats with the smallest number of
+	 * samples that meets or exceeds the specified minimum number
+	 * are preferred.
+	 */
 	public int samples;
 }
diff --git a/bundles/org.eclipse.swt.opengl/gtk/org/eclipse/swt/opengl/GLCanvas.java b/bundles/org.eclipse.swt.opengl/gtk/org/eclipse/swt/opengl/GLCanvas.java
index ee93d30e5b..a3c049780f 100644
--- a/bundles/org.eclipse.swt.opengl/gtk/org/eclipse/swt/opengl/GLCanvas.java
+++ b/bundles/org.eclipse.swt.opengl/gtk/org/eclipse/swt/opengl/GLCanvas.java
@@ -2,10 +2,14 @@ package org.eclipse.swt.opengl;
 
 import org.eclipse.swt.*;
 import org.eclipse.swt.widgets.*;
-import org.eclipse.swt.graphics.Rectangle;
+import org.eclipse.swt.graphics.*;
 import org.eclipse.swt.internal.gtk.*;
 import org.eclipse.swt.internal.opengl.gtk.*;
 
+/**
+ * GLCanvas is a widget capable of displaying OpenGL content.
+ */
+
 public class GLCanvas extends Canvas {
 	private int /*long*/ xdisplay;
 	private int /*long*/ xid;
@@ -14,6 +18,25 @@ public class GLCanvas extends Canvas {
 
 	private static final int MAX_ATTRIBUTES = 32;
 
+/**
+ * Create a GLCanvas widget using the attributes described in the GLData
+ * object provided.
+ *
+ * @param parent a composite widget
+ * @param style the bitwise OR'ing of widget styles
+ * @param data the requested attributes of the GLCanvas
+ *
+ * @exception IllegalArgumentException
+ * <ul><li>ERROR_NULL_ARGUMENT when the data is null
+ *     <li>ERROR_UNSUPPORTED_DEPTH when the requested attributes cannot be provided</ul> 
+ * @exception SWTException
+ * <ul><li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread
+ *     <li>ERROR_CANNOT_CREATE_OBJECT when failed to create OLE Object
+ *     <li>ERROR_CANNOT_OPEN_FILE when failed to open file
+ *     <li>ERROR_INTERFACE_NOT_FOUND when unable to create callbacks for OLE Interfaces
+ *     <li>ERROR_INVALID_CLASSID
+ * </ul>
+ */
 public GLCanvas (Composite parent, int style, GLData data) {
 	super (parent, style);	
 	if (data == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
@@ -139,17 +162,45 @@ public GLCanvas (Composite parent, int style, GLData data) {
 	addListener (SWT.Dispose, listener);
 }
 
+/**
+ * Returns a boolean indicating whether the receiver's OpenGL context
+ * is the current context.
+ *  
+ * @return true if the receiver holds the current OpenGL context,
+ * false otherwise
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public boolean isCurrent () {
 	checkWidget ();
 	return GLX.glXGetCurrentContext () == context;
 }
 
+/**
+ * Sets the OpenGL context associated with this GLCanvas to be the
+ * current GL context.
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public void setCurrent () {
 	checkWidget ();
 	if (GLX.glXGetCurrentContext () == context) return;
 	GLX.glXMakeCurrent (xdisplay, xid, context);
 }
 
+/**
+ * Swaps the front and back color buffers.
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public void swapBuffers () {
 	checkWidget ();
 	GLX.glXSwapBuffers (xdisplay, xid);
diff --git a/bundles/org.eclipse.swt.opengl/win32/org/eclipse/swt/opengl/GLCanvas.java b/bundles/org.eclipse.swt.opengl/win32/org/eclipse/swt/opengl/GLCanvas.java
index 29e2109fc7..2502c56aa5 100644
--- a/bundles/org.eclipse.swt.opengl/win32/org/eclipse/swt/opengl/GLCanvas.java
+++ b/bundles/org.eclipse.swt.opengl/win32/org/eclipse/swt/opengl/GLCanvas.java
@@ -15,9 +15,32 @@ import org.eclipse.swt.opengl.internal.win32.*;
 import org.eclipse.swt.internal.win32.*;
 import org.eclipse.swt.widgets.*;
 
+/**
+ * GLCanvas is a widget capable of displaying OpenGL content.
+ */
+
 public class GLCanvas extends Canvas {
 	int context;
 
+/**
+ * Create a GLCanvas widget using the attributes described in the GLData
+ * object provided.
+ *
+ * @param parent a composite widget
+ * @param style the bitwise OR'ing of widget styles
+ * @param data the requested attributes of the GLCanvas
+ *
+ * @exception IllegalArgumentException
+ * <ul><li>ERROR_NULL_ARGUMENT when the data is null
+ *     <li>ERROR_UNSUPPORTED_DEPTH when the requested attributes cannot be provided</ul> 
+ * @exception SWTException
+ * <ul><li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread
+ *     <li>ERROR_CANNOT_CREATE_OBJECT when failed to create OLE Object
+ *     <li>ERROR_CANNOT_OPEN_FILE when failed to open file
+ *     <li>ERROR_INTERFACE_NOT_FOUND when unable to create callbacks for OLE Interfaces
+ *     <li>ERROR_INVALID_CLASSID
+ * </ul>
+ */
 public GLCanvas (Composite parent, int style, GLData data) {
 	super (parent, style);
 	if (data == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
@@ -28,7 +51,6 @@ public GLCanvas (Composite parent, int style, GLData data) {
 	pfd.dwFlags = WGL.PFD_DRAW_TO_WINDOW | WGL.PFD_SUPPORT_OPENGL;
 	pfd.dwLayerMask = WGL.PFD_MAIN_PLANE;
 	pfd.iPixelType = (byte) WGL.PFD_TYPE_RGBA;
-	pfd.cColorBits = (byte) data.bufferSize;
 	if (data.doubleBuffer) pfd.dwFlags |= WGL.PFD_DOUBLEBUFFER;
 	if (data.stereo) pfd.dwFlags |= WGL.PFD_STEREO;
 	pfd.cRedBits = (byte) data.redSize;
@@ -84,11 +106,31 @@ public GLCanvas (Composite parent, int style, GLData data) {
 	addListener (SWT.Dispose, listener);
 }
 
+/**
+ * Returns a boolean indicating whether the receiver's OpenGL context
+ * is the current context.
+ *  
+ * @return true if the receiver holds the current OpenGL context,
+ * false otherwise
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public boolean isCurrent () {
 	checkWidget ();
 	return WGL.wglGetCurrentContext () == handle;
 }
 
+/**
+ * Sets the OpenGL context associated with this GLCanvas to be the
+ * current GL context.
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public void setCurrent () {
 	checkWidget ();
 	if (WGL.wglGetCurrentContext () == handle) return;
@@ -97,6 +139,14 @@ public void setCurrent () {
 	OS.ReleaseDC (handle, hDC);
 }
 
+/**
+ * Swaps the front and back color buffers.
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public void swapBuffers () {
 	checkWidget ();
 	int hDC = OS.GetDC (handle);