Issue 239: Stencil buffer should be cleared at the start of each frame

This partial fix adds a new "j3d.stencilClear" boolean property that specifies
whether the stencil buffer is cleared every frame by default.

Note that this is the first part of the partial fix. We still need to finish
the D3D code, and we need to verify whether the stencil mask needs to be
saved/forced to all 1s/restored


git-svn-id: https://svn.java.net/svn/j3d-core~svn/trunk@802 ba19aa83-45c5-6ac9-afd3-db810772062c

8 files changed, 78 insertions, 34 deletions

diff --git a/src/classes/jogl/javax/media/j3d/JoglPipeline.java b/src/classes/jogl/javax/media/j3d/JoglPipeline.java
index 6fdbb9b..4ba4868 100644
--- a/src/classes/jogl/javax/media/j3d/JoglPipeline.java
+++ b/src/classes/jogl/javax/media/j3d/JoglPipeline.java
@@ -7631,7 +7631,7 @@ class JoglPipeline extends Pipeline {
         return true;
     }
     
-    void clear(Context ctx, float r, float g, float b) {
+    void clear(Context ctx, float r, float g, float b, boolean clearStencil) {
         if (VERBOSE) System.err.println("JoglPipeline.clear()");
         
         JoglContext jctx = (JoglContext) ctx;
@@ -7645,7 +7645,15 @@ class JoglPipeline extends Pipeline {
         gl.glDepthMask(true);
         gl.glClear(GL.GL_DEPTH_BUFFER_BIT);
         gl.glPopAttrib();
-        
+
+        // Issue 239 - clear stencil if specified
+        // TODO KCR : Issue 239 - should we also set stencil mask? If so, we
+        // may need to save/restore like we do for depth mask
+        if (clearStencil) {
+            gl.glClearStencil(0);
+            gl.glClear(GL.GL_STENCIL_BUFFER_BIT);
+        }
+
     }
     
     void textureFillBackground(Context ctx, float texMinU, float texMaxU, float texMinV, float texMaxV,
diff --git a/src/classes/share/javax/media/j3d/Canvas3D.java b/src/classes/share/javax/media/j3d/Canvas3D.java
index fd3be9b..778b98e 100644
--- a/src/classes/share/javax/media/j3d/Canvas3D.java
+++ b/src/classes/share/javax/media/j3d/Canvas3D.java
@@ -4654,9 +4654,15 @@ public class Canvas3D extends Canvas {
     
     
     void clear(BackgroundRetained bg, int winWidth, int winHeight) {
-        
-        clear( ctx, bg.color.x, bg.color.y, bg.color.z);        
-        
+
+        // Issue 239 - clear stencil if requested and available
+        // Note that this is a partial solution, since we eventually want an API
+        // to control this.
+        boolean clearStencil = VirtualUniverse.mc.stencilClear &&
+                userStencilAvailable;
+
+        clear(ctx, bg.color.x, bg.color.y, bg.color.z, clearStencil);        
+
         // TODO : This is a bug on not mirror bg. Will fix this as a bug after 1.5 beta.
         // For now, as a workaround, we will check bg.image and bg.image.imageData not null.
         if((bg.image != null) && (bg.image.imageData != null)) {
@@ -5075,8 +5081,8 @@ public class Canvas3D extends Canvas {
         return Pipeline.getPipeline().releaseCtx(ctx, dpy);
     }
 
-    void clear(Context ctx, float r, float g, float b) {
-        Pipeline.getPipeline().clear(ctx, r, g, b);
+    void clear(Context ctx, float r, float g, float b, boolean clearStencil) {
+        Pipeline.getPipeline().clear(ctx, r, g, b, clearStencil);
     }
 
     void textureFillBackground(Context ctx, float texMinU, float texMaxU, float texMinV, float texMaxV,
diff --git a/src/classes/share/javax/media/j3d/MasterControl.java b/src/classes/share/javax/media/j3d/MasterControl.java
index 418e325..25d5339 100644
--- a/src/classes/share/javax/media/j3d/MasterControl.java
+++ b/src/classes/share/javax/media/j3d/MasterControl.java
@@ -337,6 +337,12 @@ class MasterControl {
     // legacy applications.
     boolean allowNullGraphicsConfig = false;
 
+    // Issue 239 - Flag indicating whether the stencil buffer is cleared by
+    // default each frame when the color and depth buffers are cleared.
+    // Note that this is a partial solution, since we eventually want an API
+    // to control this.
+    boolean stencilClear = false;
+
     // The global shading language being used. Using a ShaderProgram
     // with a shading language other than the one specified by
     // globalShadingLanguage will cause a ShaderError to be generated,
@@ -567,6 +573,11 @@ class MasterControl {
 						     allowNullGraphicsConfig,
 						     "null graphics configs");
 
+        // Issue 239 - check to see whether per-frame stencil clear is enabled
+        stencilClear = getBooleanProperty("j3d.stencilClear",
+                                          stencilClear,
+                                          "per-frame stencil clear");
+
         // Check to see if stereo mode is sharing the Z-buffer for both eyes.
 	sharedStereoZBuffer = 
 	    getBooleanProperty("j3d.sharedstereozbuffer",
diff --git a/src/classes/share/javax/media/j3d/NativePipeline.java b/src/classes/share/javax/media/j3d/NativePipeline.java
index f8ca815..d8341df 100644
--- a/src/classes/share/javax/media/j3d/NativePipeline.java
+++ b/src/classes/share/javax/media/j3d/NativePipeline.java
@@ -3077,10 +3077,10 @@ class NativePipeline extends Pipeline {
         return useCtx(unbox(ctx), display, unbox(drawable));
     }
     
-    native void clear(long ctx, float r, float g, float b);
+    native void clear(long ctx, float r, float g, float b, boolean clearStencil);
     
-    void clear(Context ctx, float r, float g, float b) {
-        clear(unbox(ctx), r, g, b);
+    void clear(Context ctx, float r, float g, float b, boolean clearStencil) {
+        clear(unbox(ctx), r, g, b, clearStencil);
         
     }
     
diff --git a/src/classes/share/javax/media/j3d/NoopPipeline.java b/src/classes/share/javax/media/j3d/NoopPipeline.java
index 394281e..164a080 100644
--- a/src/classes/share/javax/media/j3d/NoopPipeline.java
+++ b/src/classes/share/javax/media/j3d/NoopPipeline.java
@@ -1368,7 +1368,7 @@ class NoopPipeline extends Pipeline {
         return true;
     }
 
-    void clear(Context ctx, float r, float g, float b) {
+    void clear(Context ctx, float r, float g, float b, boolean clearStencil) {
         
     }
 
diff --git a/src/classes/share/javax/media/j3d/Pipeline.java b/src/classes/share/javax/media/j3d/Pipeline.java
index 380e756..a9f5743 100644
--- a/src/classes/share/javax/media/j3d/Pipeline.java
+++ b/src/classes/share/javax/media/j3d/Pipeline.java
@@ -1376,7 +1376,7 @@ abstract class Pipeline {
         return false;
     }
     
-    abstract void clear(Context ctx, float r, float g, float b);
+    abstract void clear(Context ctx, float r, float g, float b, boolean clearStencil);
     
     abstract void textureFillBackground(Context ctx, float texMinU, float texMaxU, float texMinV, float texMaxV,
             float mapMinX, float mapMaxX, float mapMinY, float mapMaxY, boolean useBiliearFilter);
diff --git a/src/native/d3d/Canvas3D.cpp b/src/native/d3d/Canvas3D.cpp
index 80eeeb7..8463b0d 100644
--- a/src/native/d3d/Canvas3D.cpp
+++ b/src/native/d3d/Canvas3D.cpp
@@ -292,12 +292,13 @@ void JNICALL Java_javax_media_j3d_NativePipeline_texturemapping(
 
 extern "C" JNIEXPORT
 void JNICALL Java_javax_media_j3d_NativePipeline_clear(
-							JNIEnv *env,
-							jobject obj,
-							jlong ctx,
-							jfloat r, 
-							jfloat g, 
-							jfloat b) 
+    JNIEnv *env,
+    jobject obj,
+    jlong ctx,
+    jfloat r, 
+    jfloat g, 
+    jfloat b,
+    jboolean clearStencil)
 {
 
     GetDevice();
@@ -308,8 +309,10 @@ void JNICALL Java_javax_media_j3d_NativePipeline_clear(
     if (!d3dCtx->zWriteEnable) {
 	device->SetRenderState(D3DRS_ZWRITEENABLE, TRUE);
     } 
-    
-    /* clear stencil, if in used */    
+
+    // TODO KCR : Issue 239 - use clearStencil to decide whether to clear stencil
+
+    /* clear stencil, if in used */
     if (d3dCtx->stencilWriteEnable ) {
 	// clear stencil and ZBuffer
 	HRESULT hr = device->Clear(0, NULL, 
diff --git a/src/native/ogl/Canvas3D.c b/src/native/ogl/Canvas3D.c
index 37c8b9f..e70b0c3 100644
--- a/src/native/ogl/Canvas3D.c
+++ b/src/native/ogl/Canvas3D.c
@@ -682,7 +682,6 @@ getPropertiesFromCurrentContext(
 	ctxInfo->multi_draw_arrays_sun = JNI_TRUE;
     }
 
-
     if (isExtensionSupported(tmpExtensionStr, "GL_EXT_compiled_vertex_array") &&
 	getJavaBoolEnv(env, "isCompiledVertexArray")) {
 	ctxInfo->compiled_vertex_array_ext = JNI_TRUE;
@@ -1461,19 +1460,21 @@ void JNICALL Java_javax_media_j3d_NativePipeline_texturemapping(
 }
 
 JNIEXPORT
-void JNICALL Java_javax_media_j3d_NativePipeline_clear(JNIEnv *env,
-						       jobject obj,
-						       jlong ctxInfo,
-						       jfloat r, 
-						       jfloat g, 
-						       jfloat b) 
+void JNICALL Java_javax_media_j3d_NativePipeline_clear(
+    JNIEnv *env,
+    jobject obj,
+    jlong ctxInfo,
+    jfloat r, 
+    jfloat g, 
+    jfloat b,
+    jboolean clearStencil) 
 { 
     GraphicsContextPropertiesInfo *ctxProperties = (GraphicsContextPropertiesInfo *)ctxInfo; 
     jlong ctx = ctxProperties->context;    
-    
 
 #ifdef VERBOSE 
-    fprintf(stderr, "Canvas3D.clear()\n");  
+    fprintf(stderr, "Canvas3D.clear(%g, %g, %g, %s)\n",
+        r, g, b, (stencilClear ? "true" : "false"));
 #endif
     
     glClearColor((float)r, (float)g, (float)b, ctxProperties->alphaClearValue); 
@@ -1484,18 +1485,33 @@ void JNICALL Java_javax_media_j3d_NativePipeline_clear(JNIEnv *env,
     glDepthMask(GL_TRUE);
     glClear(GL_DEPTH_BUFFER_BIT);
     glPopAttrib();
-    
+
+    /* Issue 239 - clear stencil if specified */
+    /*
+     * TODO KCR : Issue 239 - should we also set stencil mask? If so, we
+     * may need to save/restore like we do for depth mask
+     */
+    if (clearStencil) {
+        glClearStencil(0);
+        glClear(GL_STENCIL_BUFFER_BIT);
+    }
+
+/* TODO: we should be able to do the following, which should perform better... */
 #if 0
-    
-    /* Java 3D always clears the Z-buffer */
+    int clearMask = GL_DEPTH_BUFFER_BIT | GL_COLOR_BUFFER_BIT;
+
+    if (clearStencil) {
+        glClearStencil(0);
+        clearMask |= GL_STENCIL_BUFFER_BIT;
+    }
+
     glPushAttrib(GL_DEPTH_BUFFER_BIT);
     glDepthMask(GL_TRUE); 
     glClearColor((float)r, (float)g, (float)b, ctxProperties->alphaClearValue);
-    glClear(GL_DEPTH_BUFFER_BIT | GL_COLOR_BUFFER_BIT);
+    glClear(clearMask);
     glPopAttrib();
 #endif
 
-    
 }
 
 JNIEXPORT