diff options
Diffstat (limited to 'src/jogl/classes/javax/media/opengl')
9 files changed, 65 insertions, 54 deletions
diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java index bdbbd96a5..989a61aaf 100644 --- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java +++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java @@ -48,12 +48,14 @@ import jogamp.opengl.Debug; an event based mechanism ({@link GLEventListener}) for performing OpenGL rendering. A GLAutoDrawable automatically creates a primary rendering context which is associated with the GLAutoDrawable for - the lifetime of the object. This context has the {@link - GLContext#setSynchronized synchronized} property enabled so that - calls to {@link GLContext#makeCurrent makeCurrent} will block if - the context is current on another thread. This allows the internal - GLContext for the GLAutoDrawable to be used both by the event - based rendering mechanism as well by end users directly. + the lifetime of the object. + <p> + Since the {@link GLContext} {@link GLContext#makeCurrent makeCurrent} + implementation is synchronized, i.e. blocks if the context + is current on another thread, the internal + {@link GLContext} for the GLAutoDrawable can be used for the event + based rendering mechanism and by end users directly. + </p> <p> The implementation shall initialize itself as soon as possible, ie if the attached {@link javax.media.nativewindow.NativeSurface NativeSurface} becomes visible/realized. @@ -310,9 +312,9 @@ public interface GLAutoDrawable extends GLDrawable { * <p> * Impacts {@link #display()} and {@link #invoke(boolean, GLRunnable)} semantics.</p><br> * - * @param animator <code>null</code> reference indicates no animator is using - * this <code>GLAutoDrawable</code>,<br> - * a valid reference indicates an animator is using this <code>GLAutoDrawable</code>. + * @param animatorControl <code>null</code> reference indicates no animator is using + * this <code>GLAutoDrawable</code>,<br> + * a valid reference indicates an animator is using this <code>GLAutoDrawable</code>. * * @throws GLException if an animator is already registered. * @see #display() @@ -406,7 +408,7 @@ public interface GLAutoDrawable extends GLDrawable { * @see #setAnimator(GLAnimatorControl) * @see #display() * @see GLRunnable - * @see #enqueue(GLRunnable) + * @see #invoke(boolean, List) */ public boolean invoke(boolean wait, GLRunnable glRunnable); @@ -416,6 +418,7 @@ public interface GLAutoDrawable extends GLDrawable { * @param wait if <code>true</code> block until execution of the last <code>glRunnable</code> is finished, otherwise return immediately w/o waiting * @param glRunnables the {@link GLRunnable}s to execute within {@link #display()} * @return <code>true</code> if the {@link GLRunnable}s has been processed or queued, otherwise <code>false</code>. + * @see #invoke(boolean, GLRunnable) */ public boolean invoke(boolean wait, List<GLRunnable> glRunnables); @@ -540,7 +543,6 @@ public interface GLAutoDrawable extends GLDrawable { * This method may also return <code>null</code> if no UI toolkit is being used, * as common for offscreen rendering. * </p> - * @return */ public Object getUpstreamWidget(); diff --git a/src/jogl/classes/javax/media/opengl/GLBase.java b/src/jogl/classes/javax/media/opengl/GLBase.java index 07dfc7e72..1f75a7b4a 100644 --- a/src/jogl/classes/javax/media/opengl/GLBase.java +++ b/src/jogl/classes/javax/media/opengl/GLBase.java @@ -436,7 +436,6 @@ public interface GLBase { * NPOT textures are supported in OpenGL >= 3, GLES2 or if the * 'GL_ARB_texture_non_power_of_two' extension is available. * </p> - * @return */ public boolean isNPOTTextureAvailable(); @@ -518,12 +517,12 @@ public interface GLBase { public long glGetBufferSize(int buffer); /** - * @return true if a VBO is bound to {@link GL.GL_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false + * @return true if a VBO is bound to {@link GL#GL_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false */ public boolean glIsVBOArrayBound(); /** - * @return true if a VBO is bound to {@link GL.GL_ELEMENT_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false + * @return true if a VBO is bound to {@link GL#GL_ELEMENT_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false */ public boolean glIsVBOElementArrayBound(); @@ -537,7 +536,7 @@ public interface GLBase { * Return the default draw framebuffer name. * <p> * May differ from it's default <code>zero</code> - * in case an framebuffer object ({@link FBObject}) based drawable + * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable * is being used. * </p> */ @@ -547,7 +546,7 @@ public interface GLBase { * Return the default read framebuffer name. * <p> * May differ from it's default <code>zero</code> - * in case an framebuffer object ({@link FBObject}) based drawable + * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable * is being used. * </p> */ diff --git a/src/jogl/classes/javax/media/opengl/GLCapabilities.java b/src/jogl/classes/javax/media/opengl/GLCapabilities.java index 5b3eb9119..872069fb8 100644 --- a/src/jogl/classes/javax/media/opengl/GLCapabilities.java +++ b/src/jogl/classes/javax/media/opengl/GLCapabilities.java @@ -50,7 +50,8 @@ import javax.media.nativewindow.CapabilitiesImmutable; must support, such as the OpenGL profile, color depth and whether stereo is enabled.<br> The actual capabilites of created {@link GLDrawable}s are then reflected by their own - GLCapabilites instance, which can be queried with {@link GLDrawable#getGLCapabilities()}.<br> + GLCapabilites instance, which can be queried with {@link GLDrawable#getChosenGLCapabilities()}. + <br> It currently contains the minimal number of routines which allow configuration on all supported window systems. */ @@ -246,7 +247,7 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil /** * Requesting offscreen pbuffer mode. * <p> - * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}. + * If enabled this method also invokes {@link #setOnscreen(boolean) setOnscreen(false)}. * </p> * <p> * Defaults to false. @@ -270,7 +271,7 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil /** * Requesting offscreen FBO mode. * <p> - * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}. + * If enabled this method also invokes {@link #setOnscreen(boolean) setOnscreen(false)}. * </p> * <p> * Defaults to false. diff --git a/src/jogl/classes/javax/media/opengl/GLContext.java b/src/jogl/classes/javax/media/opengl/GLContext.java index 618ee2584..854d96807 100644 --- a/src/jogl/classes/javax/media/opengl/GLContext.java +++ b/src/jogl/classes/javax/media/opengl/GLContext.java @@ -283,8 +283,9 @@ public abstract class GLContext { * this context is made current on another thread. * * @see #isGLReadDrawableAvailable() + * @see #setGLReadDrawable(GLDrawable) * @see #getGLReadDrawable() - * @see #setGLReadDrawable() + * @see #setGLDrawable(GLDrawable, boolean) * @see #getGLDrawable() */ public abstract GLDrawable setGLDrawable(GLDrawable readWrite, boolean setWriteOnly); @@ -334,8 +335,8 @@ public abstract class GLContext { * it equals to the write-drawable (default). * </p> * @see #isGLReadDrawableAvailable() - * @see #setGLReadDrawable(javax.media.opengl.GLDrawable) - * @see #getGLDrawable() + * @see #setGLReadDrawable(GLDrawable) + * @see #getGLReadDrawable() */ public abstract GLDrawable getGLReadDrawable(); @@ -407,7 +408,7 @@ public abstract class GLContext { * parameter indicates which groups of state variables are to be * copied. <code>mask</code> contains the bitwise OR of the same * symbolic names that are passed to the GL command {@link - * GL#glPushAttrib glPushAttrib}. The single symbolic constant + * GL2#glPushAttrib glPushAttrib}. The single symbolic constant * {@link GL2#GL_ALL_ATTRIB_BITS GL_ALL_ATTRIB_BITS} can be used to * copy the maximum possible portion of rendering state. <P> * @@ -1115,7 +1116,9 @@ public abstract class GLContext { /** * Indicates whether this GLContext is capable of GL2ES3. <p>Includes [ GL4bc, GL4, GL3bc, GL3, GLES3, GL3ES3, GL2, GL2GL3 ].</p> - * @see GLProfile#isGL2ES3() + * @see GLProfile#isGL2ES3() + * @see #isGL3ES3() + * @see #isGL2GL3() */ public final boolean isGL2ES3() { return isGL3ES3() || isGL2GL3(); @@ -1216,7 +1219,7 @@ public abstract class GLContext { * Return the default draw framebuffer name. * <p> * May differ from it's default <code>zero</code> - * in case an framebuffer object ({@link FBObject}) based drawable + * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable * is being used. * </p> */ @@ -1226,7 +1229,7 @@ public abstract class GLContext { * Return the default read framebuffer name. * <p> * May differ from it's default <code>zero</code> - * in case an framebuffer object ({@link FBObject}) based drawable + * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable * is being used. * </p> */ @@ -1253,23 +1256,23 @@ public abstract class GLContext { /** * @return The extension implementing the GLDebugOutput feature, - * either <i>GL_ARB_debug_output</i> or <i>GL_AMD_debug_output</i>. + * either {@link GLExtensions#ARB_debug_output} or {@link GLExtensions#AMD_debug_output}. * If unavailable or called before initialized via {@link #makeCurrent()}, <i>null</i> is returned. */ public abstract String getGLDebugMessageExtension(); /** - * @return the current synchronous debug behavior via - * @see #setSynchronous(boolean) + * @return the current synchronous debug behavior, set via {@link #setGLDebugSynchronous(boolean)}. */ public abstract boolean isGLDebugSynchronous(); /** * Enables or disables the synchronous debug behavior via - * {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB glEnable/glDisable(GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB)}, - * if extension is {@link #GL_ARB_debug_output}. - * There is no equivalent for {@link #GL_AMD_debug_output}. - * <p> The default is <code>true</code>, ie {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB}.</p> + * {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS glEnable/glDisable(GL_DEBUG_OUTPUT_SYNCHRONOUS)}, + * if extension is {@link GLExtensions#ARB_debug_output}. + * There is no equivalent for {@link GLExtensions#AMD_debug_output}. + * <p> The default is <code>true</code>, ie {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS}.</p> + * @link {@link #isGLDebugSynchronous()} */ public abstract void setGLDebugSynchronous(boolean synchronous); @@ -1279,8 +1282,8 @@ public abstract class GLContext { public abstract boolean isGLDebugMessageEnabled(); /** - * Enables or disables the GLDebugOutput feature of extension <i>GL_ARB_debug_output</i> - * or <i>GL_AMD_debug_output</i>, if available. + * Enables or disables the GLDebugOutput feature of extension {@link GLExtensions#ARB_debug_output} + * or {@link GLExtensions#AMD_debug_output}, if available. * * <p>To enable the GLDebugOutput feature {@link #enableGLDebugMessage(boolean) enableGLDebugMessage(true)} * or {@link #setContextCreationFlags(int) setContextCreationFlags}({@link GLContext#CTX_OPTION_DEBUG}) @@ -1305,7 +1308,7 @@ public abstract class GLContext { /** * Add {@link GLDebugListener}.<br> * - * @param listener {@link GLDebugListener} handling {@GLDebugMessage}s + * @param listener {@link GLDebugListener} handling {@link GLDebugMessage}s * @see #enableGLDebugMessage(boolean) * @see #removeGLDebugListener(GLDebugListener) */ @@ -1314,28 +1317,28 @@ public abstract class GLContext { /** * Remove {@link GLDebugListener}.<br> * - * @param listener {@link GLDebugListener} handling {@GLDebugMessage}s + * @param listener {@link GLDebugListener} handling {@link GLDebugMessage}s * @see #enableGLDebugMessage(boolean) * @see #addGLDebugListener(GLDebugListener) */ public abstract void removeGLDebugListener(GLDebugListener listener); /** - * Generic entry for {@link GL2GL3#glDebugMessageControlARB(int, int, int, int, IntBuffer, boolean)} + * Generic entry for {@link GL2GL3#glDebugMessageControl(int, int, int, int, IntBuffer, boolean)} * and {@link GL2GL3#glDebugMessageEnableAMD(int, int, int, IntBuffer, boolean)} of the GLDebugOutput feature. * @see #enableGLDebugMessage(boolean) */ public abstract void glDebugMessageControl(int source, int type, int severity, int count, IntBuffer ids, boolean enabled); /** - * Generic entry for {@link GL2GL3#glDebugMessageControlARB(int, int, int, int, int[], int, boolean)} + * Generic entry for {@link GL2GL3#glDebugMessageControl(int, int, int, int, int[], int, boolean)} * and {@link GL2GL3#glDebugMessageEnableAMD(int, int, int, int[], int, boolean)} of the GLDebugOutput feature. * @see #enableGLDebugMessage(boolean) */ public abstract void glDebugMessageControl(int source, int type, int severity, int count, int[] ids, int ids_offset, boolean enabled); /** - * Generic entry for {@link GL2GL3#glDebugMessageInsertARB(int, int, int, int, int, String)} + * Generic entry for {@link GL2GL3#glDebugMessageInsert(int, int, int, int, int, String)} * and {@link GL2GL3#glDebugMessageInsertAMD(int, int, int, int, String)} of the GLDebugOutput feature. * @see #enableGLDebugMessage(boolean) */ @@ -1485,8 +1488,8 @@ public abstract class GLContext { } /** - * Called by {@link jogamp.opengl.GLContextImpl#createContextARBMapVersionsAvailable} not intended to be used by - * implementations. However, if {@link #createContextARB} is not being used within + * Called by {@link jogamp.opengl.GLContextImpl#createContextARBMapVersionsAvailable(int,int)} not intended to be used by + * implementations. However, if {@link jogamp.opengl.GLContextImpl#createContextARB(long, boolean)} is not being used within * {@link javax.media.opengl.GLDrawableFactory#getOrCreateSharedContext(javax.media.nativewindow.AbstractGraphicsDevice)}, * GLProfile has to map the available versions. * diff --git a/src/jogl/classes/javax/media/opengl/GLDebugMessage.java b/src/jogl/classes/javax/media/opengl/GLDebugMessage.java index f8959e653..4b8d62898 100644 --- a/src/jogl/classes/javax/media/opengl/GLDebugMessage.java +++ b/src/jogl/classes/javax/media/opengl/GLDebugMessage.java @@ -29,6 +29,10 @@ package javax.media.opengl; import com.jogamp.common.os.Platform; +/** + * OpenGL debug message generated by the driver + * and delivered via {@link GLDebugListener}. + */ public class GLDebugMessage { final GLContext source; final long when; diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java index 369ea6d2b..46fa923ad 100644 --- a/src/jogl/classes/javax/media/opengl/GLDrawable.java +++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java @@ -202,7 +202,7 @@ public interface GLDrawable { * <p> * On EGL it is represented by the EGLSurface.<br> * On X11/GLX it is represented by either the Window XID, GLXPixmap, or GLXPbuffer.<br> - * On Windows it is represented by the HDC, which may change with each {@link #lockSurface()}.<br> + * On Windows it is represented by the HDC, which may change with each {@link NativeSurface#lockSurface()}.<br> * </p> * @see #setRealized(boolean) * @see NativeSurface#lockSurface() diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java index c2e7e0829..7c3c42e45 100644 --- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java +++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java @@ -336,7 +336,7 @@ public abstract class GLDrawableFactory { * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> for the platform's default device. * @param quirk the quirk to be tested, e.g. {@link GLRendererQuirks#NoDoubleBufferedPBuffer}. * @throws IllegalArgumentException if the quirk is out of range - * @see #getRendererQuirks() + * @see #getRendererQuirks(AbstractGraphicsDevice) * @see GLRendererQuirks */ public final boolean hasRendererQuirk(AbstractGraphicsDevice device, int quirk) { @@ -459,7 +459,7 @@ public abstract class GLDrawableFactory { * @see javax.media.opengl.GLCapabilities#isOnscreen() * @see javax.media.opengl.GLCapabilities#isFBO() * @see javax.media.opengl.GLCapabilities#isPBuffer() - * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen) + * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, javax.media.nativewindow.CapabilitiesChooser, AbstractGraphicsScreen, int) */ public abstract GLDrawable createGLDrawable(NativeSurface target) throws IllegalArgumentException, GLException; @@ -560,7 +560,8 @@ public abstract class GLDrawableFactory { public abstract GLDrawable createDummyDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLProfile glp); /** - * Creates a proxy {@link NativeSurface} w/ defined surface handle, i.e. a {@link WrappedSurface} or {@link GDISurface} instance. + * Creates a proxy {@link NativeSurface} w/ defined surface handle, + * i.e. a {@link jogamp.nativewindow.WrappedSurface} or {@link jogamp.nativewindow.windows.GDISurface} instance. * <p> * It's {@link AbstractGraphicsConfiguration} is properly set according to the given * <code>windowHandle</code>'s native visualID if set or the given {@link GLCapabilitiesImmutable}. @@ -571,7 +572,8 @@ public abstract class GLDrawableFactory { * </p> * <p> * Such surface can be used to instantiate a GLDrawable. With the help of {@link GLAutoDrawableDelegate} - * you will be able to implement a new native windowing system binding almost on-the-fly, see {@link com.jogamp.opengl.swt.GLCanvas}. + * you will be able to implement a new native windowing system binding almost on-the-fly, + * see {@link com.jogamp.opengl.swt.GLCanvas}. * </p> * * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> for the platform's default device. @@ -580,7 +582,7 @@ public abstract class GLDrawableFactory { * @param windowHandle the native window handle * @param caps the requested GLCapabilties * @param chooser the custom chooser, may be null for default - * @param upstream optional {@link ProxySurface.UpstreamSurfaceHook} allowing control of the {@link ProxySurface}'s lifecycle and data it presents. + * @param upstream optional {@link UpstreamSurfaceHook} allowing control of the {@link ProxySurface}'s lifecycle and data it presents. * @return the created {@link ProxySurface} instance w/ defined surface handle. */ public abstract ProxySurface createProxySurface(AbstractGraphicsDevice device, diff --git a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java index 4d6c7c20e..df38745d5 100644 --- a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java +++ b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java @@ -62,14 +62,14 @@ import com.jogamp.opengl.FBObject.TextureAttachment; * </p> * <p> * It would be possible to implement double buffering simply using - * {@link FBObject.TextureAttachment texture attachment}s with one {@link FBObject framebuffer}. + * {@link TextureAttachment}s with one {@link FBObject framebuffer}. * This would require mode selection and hence complicate the API. Besides, it would * not support differentiation of read and write framebuffer and hence not be spec compliant. * </p> * <p> - * Actual swapping of the {@link FBObject.TextureAttachment texture}s or {@link FBObject framebuffer} - * is performed either in the {@link #contextMadeCurrent(boolean) context current hook} - * or when {@link #swapBuffersImpl(boolean) swapping buffers}, whatever comes first.<br/> + * Actual swapping of the {@link TextureAttachment texture}s and/or {@link FBObject framebuffer} + * is performed either in the {@link jogamp.opengl.GLContextImpl#contextMadeCurrent(boolean) context current hook} + * or when {@link jogamp.opengl.GLDrawableImpl#swapBuffersImpl(boolean) swapping buffers}, whatever comes first. * </p> */ public interface GLFBODrawable extends GLDrawable { diff --git a/src/jogl/classes/javax/media/opengl/GLProfile.java b/src/jogl/classes/javax/media/opengl/GLProfile.java index b5e89a23b..1dde2cbb6 100644 --- a/src/jogl/classes/javax/media/opengl/GLProfile.java +++ b/src/jogl/classes/javax/media/opengl/GLProfile.java @@ -1130,8 +1130,8 @@ public class GLProfile { /** * Indicates whether this profile is capable of GL2ES3. <p>Includes [ GL4bc, GL4, GL3bc, GL3, GLES3, GL3ES3, GL2, GL2GL3 ].</p> - * @see isGL3ES3() - * @see isGL2GL3() + * @see #isGL3ES3() + * @see #isGL2GL3() */ public final boolean isGL2ES3() { return isGL3ES3() || isGL2GL3(); |