title: Using stencil test to clip items being drawn in OpenGL-ES
body: <p>I'm currently working on an OpenGL project in Android. Right now, I'm trying to create a "clip" for items to be confined to when drawing, using the stencil buffer. My problem is that I would like to be able to create a clip shape, and then "remove" portions of that clipped shape later on (much like in an Android Canvas calling clipPath() with Region.Op.UNION and then another clipPath() call with Region.Op.DIFFERENCE)</p>
  
  <p>Basically, my intention is to only draw to portions of the screen with a stencil buffer bit of value 1. Therefore, as I understand it, I should be able to draw to the stencil buffer with different glStencilOp functions that will allow me to draw with 1's in some areas, and then perhaps replace them later on with the default 0 in portions of those areas.</p>
  
  <p>As an example test, I tried to clip a "doughnut" on the screen, using something like this (Note: I am using the ShapeRenderer from the LibGDX open source project to draw shapes): </p>
  
  <pre><code>// Beginning LibGDX shapeRenderer.
  shapeRenderer.begin(ShapeType.FILLED);
  
  gl20.glClear(GL20.GL_STENCIL_BUFFER_BIT); // Clear stencil buffer.
  gl20.glEnable(GL20.GL_STENCIL_TEST); // Enable stencil test.
  gl20.glColorMask(false, false, false, false); // Disable color drawing.
  gl20.glStencilMask(0xFF); // Set 0xFF as stencil mask.
  
  // Have stencil test always fail, replace drawn stencil bits with 1.
  gl20.glStencilFunc(GL20.GL_NEVER, 1, 0xFF); 
  gl20.glStencilOp(GL20.GL_REPLACE, GL20.GL_KEEP,GL20.GL_KEEP);
  
  /* Draw outer circle, libGDX call. 600px radius. */
  shapeRenderer.circle(screenRect.width() / 2, screenRect.height() / 2, 600);
  
  // Now, replace newly drawn stencil bits with 0.
  gl20.glStencilOp(GL20.GL_ZERO, GL20.GL_KEEP, GL20.GL_KEEP);
  
  /* Draw inner circle, libGDX call. 200px radius. */
  shapeRenderer.circle(screenRect.width() / 2, screenRect.height() / 2, 200);
  
  // Re-enable color drawing. 
  gl20.glColorMask(true, true, true, true);
  // Now, items drawn will be confined to areas with '1' stencil bit.
  gl20.glStencilFunc(GL20.GL_EQUAL, 1, 0xFF);
  gl20.glStencilOp(GL20.GL_KEEP, GL20.GL_KEEP, GL20.GL_KEEP);
  gl20.glStencilMask(0x00);
  
  /* Draw a filled, colored rectangle to the entire screen. */
  shapeRenderer.setColor(Color.RED);
  shapeRenderer.drawRect(screenRect);
  
  shapeRenderer.end();
  </code></pre>
  
  <p>Now, as I understand it, this should result in a colored 'doughnut' drawn to the screen; However, as the code is written above, nothing is drawn to the screen.</p>
  
  <p>However, if I only clip the outer circle (and not try to get rid of the inner circle with the "gl20.glStencilOp(GL20.GL_ZERO, GL20.GL_KEEP, GL20.GL_KEEP)" call and subsequent inner circle drawing, a circle the size of the intended outer circle draws on the screen. </p>
  
  <p>I've looked through the documentation that I could find, and everything that I've read so far indicates that this should work. Is there something that I'm missing here? Any help is greatly appreciated.</p>