Package edu.cornell.gdiac.graphics

Enum Class Stencil.Effect

java.lang.Object
java.lang.Enum<Stencil.Effect>
edu.cornell.gdiac.graphics.Stencil.Effect
All Implemented Interfaces:
Serializable, Comparable<Stencil.Effect>, Constable
Enclosing class:
Stencil
public static enum Stencil.Effect extends Enum<Stencil.Effect>
An enum enumerating all of the supported stencil effects. These values should be passed to Stencil.applyEffect(edu.cornell.gdiac.graphics.Stencil.Effect) to be applied.

  • Enum Constant Details

    • NATIVE

      public static final Stencil.Effect NATIVE
      Defers to the existing OpenGL stencil settings. (DEFAULT)

      This effect neither enables nor disables the stencil buffer. Instead it uses the existing OpenGL settings. This is the effect that you should use when you need to manipulate the stencil buffer directly.

    • NONE

      public static final Stencil.Effect NONE
      Disables any stencil effects.

      This effect directs a SpriteBatch to ignore the stencil buffer (both halves) when drawing. However, it does not clear the contents of the stencil buffer. To clear the stencil buffer, you will need to call Stencil.clearBuffer(int).

    • CLIP

      public static final Stencil.Effect CLIP
      Restrict all drawing to the unified stencil region.

      In order for this effect to do anything, you must have created a stencil region with STAMP or one of its variants. This effect will process the drawing commands normally, but restrict all drawing to the stencil region. This can be used to quickly draw non-convex shapes by making a stencil and drawing a rectangle over the stencil.

      This effect is the same as CLIP_JOIN in that it respects the union of the two halves of the stencil buffer.

    • MASK

      public static final Stencil.Effect MASK
      Prohibits all drawing to the unified stencil region.

      In order for this effect to do anything, you must have created a stencil region with STAMP or one of its variants. This effect will process the drawing commands normally, but reject any attempts to draw to the stencil region. This can be used to quickly draw shape borders on top of a solid shape.

      This effect is the same as MASK_JOIN in that it respects the union of the two halves of the stencil buffer.

    • FILL

      public static final Stencil.Effect FILL
      Restrict all drawing to the unified stencil region.

      In order for this effect to do anything, you must have created a stencil region with STAMP or one of its variants. This effect will process the drawing commands normally, but restrict all drawing to the stencil region. This can be used to quickly draw non-convex shapes by making a stencil and drawing a rectangle over the stencil.

      This effect is different from CLIP in that it will zero out the pixels it draws in the stencil buffer, effectively removing them from the stencil region. In many applications, this is a fast way to clear the stencil buffer once it is no longer needed.

      This effect is the same as FILL_JOIN in that it respects the union of the two halves of the stencil buffer.

    • WIPE

      public static final Stencil.Effect WIPE
      Erases from the unified stencil region.

      This effect will not draw anything to the screen. Instead, it will only draw to the stencil buffer directly. Any pixel drawn will be zeroed in the buffer, removing it from the stencil region. The effect FILL is a combination of this and CLIP. Again, this is a potential optimization for clearing the stencil buffer. However, on most tiled-based GPUs, it is probably faster to simply clear the whole buffer.

    • STAMP

      public static final Stencil.Effect STAMP
      Adds a stencil region the unified buffer

      This effect will not have any immediate visible effects. Instead it creates a stencil region for the effects such as CLIP, MASK, and the like.

      The shapes are drawn to the stencil buffer using a nonzero fill rule. This has the advantage that (unlike an even-odd fill rule) stamps are additive and can be drawn on top of each other. However, it has the disadvantage that it requires both halves of the stencil buffer to store the stamp (which part of the stamp is in which half is undefined).

      While this effect implements a nonzero fill rule faithfully, there are technical limitations. The size of the stencil buffer means that more than 256 overlapping polygons of the same orientation will cause unpredictable effects. If this is a problem, use an even odd fill rule instead like STAMP_NONE (which has no such limitations).

    • CARVE

      public static final Stencil.Effect CARVE
      Adds a stencil region the lower buffer

      This effect will not have any immediate visible effects. Instead it creates a stencil region for the effects such as CLIP, MASK, and the like.

      Like STAMP, shapes are drawn to the stencil buffer instead of the screen. But unlike stamp, this effect is always additive. It ignores path orientation, and does not support holes. This allows the effect to implement a nonzero fill rule while using only half of the buffer. This effect is equivalent to CARVE_NONE in that it uses only the lower half.

      The primary application of this effect is to create stencils from extruded paths so that overlapping sections are not drawn twice (which has negative effects on alpha blending).

    • CLAMP

      public static final Stencil.Effect CLAMP
      Limits drawing so that each pixel is updated once.

      This effect is a variation of CARVE that also draws as it writes to the stencil buffer. This guarantees that each pixel is updated exactly once. This is used by extruded paths so that overlapping sections are not drawn twice (which has negative effects on alpha blending).

      This effect is equivalent to CLAMP_NONE in that it uses only the lower half.

    • NONE_CLIP

      public static final Stencil.Effect NONE_CLIP
      Applies CLIP using the upper stencil buffer only.

      As with CLIP, this effect restricts drawing to the stencil region. However, this effect only uses the stencil region present in the upper stencil buffer.

      This effect is designed to be used with stencil regions created by NONE_STAMP. While it can be used by a stencil region created by STAMP, the lower stencil buffer is ignored, and hence the results are unpredictable.

    • NONE_MASK

      public static final Stencil.Effect NONE_MASK
      Applies MASK using the upper stencil buffer only.

      As with MASK, this effect prohibits drawing to the stencil region. However, this effect only uses the stencil region present in the upper stencil buffer.

      This effect is designed to be used with stencil regions created by NONE_STAMP. While it can be used by a stencil region created by STAMP, the lower stencil buffer is ignored, and hence the results are unpredictable.

    • NONE_FILL

      public static final Stencil.Effect NONE_FILL
      Applies FILL using the upper stencil buffer only.

      As with FILL, this effect limits drawing to the stencil region. However, this effect only uses the stencil region present in the upper stencil buffer. It also only zeroes out the upper stencil buffer.

      This effect is designed to be used with stencil regions created by NONE_STAMP. While it can be used by a stencil region created by STAMP, the lower stencil buffer is ignored, and hence the results are unpredictable.

    • NONE_WIPE

      public static final Stencil.Effect NONE_WIPE
      Applies WIPE using the upper stencil buffer only.

      As with WIPE, this effect zeroes out the stencil region, erasing parts of it. However, its effects are limited to the upper stencil region.

      This effect is designed to be used with stencil regions created by NONE_STAMP. While it can be used by a stencil region created by STAMP, the lower stencil buffer is ignored, and hence the results are unpredictable.

    • NONE_STAMP

      public static final Stencil.Effect NONE_STAMP
      Adds a stencil region to the upper buffer

      This effect will not have any immediate visible effect on the screen screen. Instead, it creates a stencil region for the effects such as CLIP, MASK, and the like.

      Unlike STAMP, the region created is limited to the upper half of the stencil buffer. That is because the shapes are drawn to the buffer with an even-odd fill rule (which does not require the full stencil buffer to implement). This has the disadvantage that stamps drawn on top of each other have an "erasing" effect. However, it has the advantage that the this stamp supports a wider array of effects than the simple stamp effect.

      Use NONE_CLAMP if you have an simple stencil with no holes that you wish to write to the upper half of the buffer.

    • NONE_CARVE

      public static final Stencil.Effect NONE_CARVE
      Adds a stencil region to the upper buffer

      This value will not have any immediate visible effect on the screen. Instead, it creates a stencil region for the effects such as CLIP, MASK, and the like. Like STAMP, shapes are drawn to the stencil buffer instead of the screen. But unlike stamp, this effect is always additive. It ignores path orientation, and does not support holes. This allows the effect to implement a nonzero fill rule while using only the upper half of the buffer.

      The primary application of this effect is to create stencils from extruded paths so that overlapping sections are not drawn twice (which has negative effects on alpha blending).

    • NONE_CLAMP

      public static final Stencil.Effect NONE_CLAMP
      Uses the upper buffer to limit each pixel to single update.

      This effect is a variation of NONE_CARVE that also draws as it writes to the upper stencil buffer. This guarantees that each pixel is updated exactly once. This is used by extruded paths so that overlapping sections are not drawn twice (which has negative effects on alpha blending).

    • CLIP_JOIN

      public static final Stencil.Effect CLIP_JOIN
      Restrict all drawing to the unified stencil region.

      This effect is the same as CLIP in that it respects the union of the two halves of the stencil buffer.

    • CLIP_MEET

      public static final Stencil.Effect CLIP_MEET
      Restrict all drawing to the intersecting stencil region.

      This effect is the same as CLIP, except that it limits drawing to the intersection of the stencil regions in the two halves of the stencil buffer. If a unified stencil region was created by STAMP, then the results of this effect are unpredictable.

    • CLIP_NONE

      public static final Stencil.Effect CLIP_NONE
      Applies CLIP using the lower stencil buffer only.

      As with CLIP, this effect restricts drawing to the stencil region. However, this effect only uses the stencil region present in the lower stencil buffer.

      This effect is designed to be used with stencil regions created by NONE_STAMP. While it can be used by a stencil region created by STAMP, the lower stencil buffer is ignored, and hence the results are unpredictable.

    • CLIP_MASK

      public static final Stencil.Effect CLIP_MASK
      Applies a lower buffer CLIP with an upper MASK.

      This command restricts drawing to the stencil region in the lower buffer while prohibiting any drawing to the stencil region in the upper buffer. If this effect is applied to a unified stencil region created by STAMP, then the results are unpredictable.

    • CLIP_FILL

      public static final Stencil.Effect CLIP_FILL
      Applies a lower buffer CLIP with an upper FILL.

      This command restricts drawing to the stencil region in the unified stencil region of the two buffers. However, it only zeroes pixels in the stencil region of the upper buffer; the lower buffer is untouched. If this effect is applied to a unified stencil region created by STAMP, then the results are unpredictable.

    • CLIP_WIPE

      public static final Stencil.Effect CLIP_WIPE
      Applies a lower buffer CLIP with an upper WIPE.

      As with WIPE, this command does not do any drawing on screen. Instead, it zeroes out the upper stencil buffer. However, it is clipped by the stencil region in the lower buffer, so that it does not zero out any pixel outside this region. Hence this is a way to erase the lower buffer stencil region from the upper buffer stencil region.

    • CLIP_STAMP

      public static final Stencil.Effect CLIP_STAMP
      Applies a lower buffer CLIP with an upper STAMP.

      As with NONE_CLAMP, this writes a shape to the upper stencil buffer using an even-odd fill rule. This means that adding a shape on top of existing shape has an erasing effect. However, it also restricts its operation to the stencil region in the lower stencil buffer. Note that if a pixel is clipped while drawing, it will not be added the stencil region in the upper buffer.

    • CLIP_CARVE

      public static final Stencil.Effect CLIP_CARVE
      Applies a lower buffer CLIP with an upper CARVE.

      As with NONE_CARVE, this writes an additive shape to the upper stencil buffer. However, it also restricts its operation to the stencil region in the lower stencil buffer. Note that if a pixel is clipped while drawing, it will not be added the stencil region in the upper buffer. Hence this is a way to copy the lower buffer stencil region into the upper buffer.

    • CLIP_CLAMP

      public static final Stencil.Effect CLIP_CLAMP
      Applies a lower buffer CLIP with an upper CLAMP.

      As with NONE_CLAMP, this draws a nonoverlapping shape using the upper stencil buffer. However, it also restricts its operation to the stencil region in the lower stencil buffer. Note that if a pixel is clipped while drawing, it will not be added the stencil region in the upper buffer.

    • MASK_JOIN

      public static final Stencil.Effect MASK_JOIN
      Prohibits all drawing to the unified stencil region.

      This effect is the same as MASK in that it respects the union of the two halves of the stencil buffer.

    • MASK_MEET

      public static final Stencil.Effect MASK_MEET
      Prohibits all drawing to the intersecting stencil region.

      This effect is the same as MASK, except that it limits drawing to the intersection of the stencil regions in the two halves of the stencil buffer. If a unified stencil region was created by STAMP, then the results of this effect are unpredictable.

    • MASK_NONE

      public static final Stencil.Effect MASK_NONE
      Applies MASK using the lower stencil buffer only.

      As with MASK, this effect prohibits drawing to the stencil region. However, this effect only uses the stencil region present in the lower stencil buffer.

      This effect is designed to be used with stencil regions created by STAMP_NONE. While it can be used by a stencil region created by STAMP, the upper stencil buffer is ignored, and hence the results are unpredictable.

    • MASK_CLIP

      public static final Stencil.Effect MASK_CLIP
      Applies a lower buffer MASK with an upper CLIP.

      This command restricts drawing to the stencil region in the upper buffer while prohibiting any drawing to the stencil region in the lower buffer. If this effect is applied to a unified stencil region created by STAMP, then the results are unpredictable.

    • MASK_FILL

      public static final Stencil.Effect MASK_FILL
      Applies a lower buffer MASK with an upper FILL.

      This command restricts drawing to the stencil region in the upper buffer while prohibiting any drawing to the stencil region in the lower buffer. However, it only zeroes the stencil region in the upper buffer; the lower buffer is untouched. In addition, it will only zero those pixels that were drawn.

      If this effect is applied to a unified stencil region created by STAMP, then the results are unpredictable.

    • MASK_WIPE

      public static final Stencil.Effect MASK_WIPE
      Applies a lower buffer MASK with an upper WIPE.

      As with WIPE, this command does not do any drawing on screen. Instead, it zeroes out the upper stencil buffer. However, it is masked by the stencil region in the lower buffer, so that it does not zero out any pixel inside this region.

    • MASK_STAMP

      public static final Stencil.Effect MASK_STAMP
      Applies a lower buffer MASK with an upper STAMP.

      As with NONE_STAMP, this writes a shape to the upper stencil buffer using an even-odd fill rule. This means that adding a shape on top of existing shape has an erasing effect. However, it also masks its operation by the stencil region in the lower stencil buffer. Note that if a pixel is masked while drawing, it will not be added the stencil region in the upper buffer.

    • MASK_CARVE

      public static final Stencil.Effect MASK_CARVE
      Applies a lower buffer MASK with an upper CARVE.

      As with NONE_CARVE, this writes an additive shape to the upper stencil buffer. However, it also prohibits any drawing to the stencil region in the lower stencil buffer. Note that if a pixel is masked while drawing, it will not be added the stencil region in the upper buffer.

    • MASK_CLAMP

      public static final Stencil.Effect MASK_CLAMP
      Applies a lower buffer MASK with an upper CLAMP.

      As with NONE_CLAMP, this draws a nonoverlapping shape using the upper stencil buffer. However, it also prohibits any drawing to the stencil region in the lower stencil buffer. Note that if a pixel is masked while drawing, it will not be added the stencil region in the upper buffer.

    • FILL_JOIN

      public static final Stencil.Effect FILL_JOIN
      Restricts all drawing to the unified stencil region.

      This effect is the same as FILL in that it respects the union of the two halves of the stencil buffer.

    • FILL_MEET

      public static final Stencil.Effect FILL_MEET
      Restricts all drawing to the intersecting stencil region.

      This effect is the same as FILL, except that it limits drawing to the intersection of the stencil regions in the two halves of the stencil buffer.

      When zeroing out pixels, this operation zeroes out both halves of the stencil buffer. If a unified stencil region was created by STAMP, the results of this effect are unpredictable.

    • FILL_NONE

      public static final Stencil.Effect FILL_NONE
      Applies FILL using the lower stencil buffer only.

      As with FILL, this effect restricts drawing to the stencil region. However, this effect only uses the stencil region present in the lower stencil buffer. It also only zeroes the stencil region in this lower buffer.

      This effect is designed to be used with stencil regions created by NONE_STAMP. While it can be used by a stencil region created by STAMP, the lower stencil buffer is ignored, and hence the results are unpredictable.

    • FILL_MASK

      public static final Stencil.Effect FILL_MASK
      Applies a lower buffer FILL with an upper MASK.

      This command restricts drawing to the stencil region in the lower buffer while prohibiting any drawing to the stencil region in the upper buffer.

      When zeroing out the stencil region, this part of the effect is only applied to the lower buffer. If this effect is applied to a unified stencil region created by STAMP, then the results are unpredictable.

    • FILL_CLIP

      public static final Stencil.Effect FILL_CLIP
      Applies a lower buffer FILL with an upper CLIP.

      This command restricts drawing to the stencil region in the unified stencil region of the two buffers. However, it only zeroes pixels in the stencil region of the lower buffer; the lower buffer is untouched. If this effect is applied to a unified stencil region created by STAMP, then the results are unpredictable.

    • WIPE_NONE

      public static final Stencil.Effect WIPE_NONE
      Applies WIPE using the lower stencil buffer only.

      As with WIPE, this effect zeroes out the stencil region, erasing parts of it. However, its effects are limited to the lower stencil region.

      This effect is designed to be used with stencil regions created by NONE_STAMP. While it can be used by a stencil region created by STAMP, the lower stencil buffer is ignored, and hence the results are unpredictable.

    • WIPE_MASK

      public static final Stencil.Effect WIPE_MASK
      Applies a lower buffer WIPE with an upper MASK.

      This command erases from the stencil region in the lower buffer. However, it limits its erasing to locations that are not masked by the stencil region in the upper buffer. If this effect is applied to a unified stencil region created by STAMP, the results are unpredictable.

    • WIPE_CLIP

      public static final Stencil.Effect WIPE_CLIP
      Applies a lower buffer WIPE with an upper CLIP.

      This command erases from the stencil region in the lower buffer. However, it limits its erasing to locations that are contained in the stencil region in the upper buffer. If this effect is applied to a unified stencil region created by STAMP, the results are unpredictable.

    • STAMP_NONE

      public static final Stencil.Effect STAMP_NONE
      Adds a stencil region to the lower buffer

      This effect will not have any immediate visible effect on the screen screen. Instead, it creates a stencil region for the effects such as CLIP, MASK, and the like.

      Unlike STAMP, the region created is limited to the lower half of the stencil buffer. That is because the shapes are drawn to the buffer with an even-odd fill rule (which does not require the full stencil buffer to implement). This has the disadvantage that stamps drawn on top of each other have an "erasing" effect. However, it has the advantage that the this stamp supports a wider array of effects than the simple stamp effect.

    • STAMP_CLIP

      public static final Stencil.Effect STAMP_CLIP
      Applies a lower buffer STAMP with an upper CLIP.

      As with STAMP_NONE, this writes a shape to the lower stencil buffer using an even-odd fill rule. This means that adding a shape on top of existing shape has an erasing effect. However, it also restricts its operation to the stencil region in the upper stencil buffer. Note that if a pixel is clipped while drawing, it will not be added the stencil region in the lower buffer.

    • STAMP_MASK

      public static final Stencil.Effect STAMP_MASK
      Applies a lower buffer STAMP with an upper MASK.

      As with STAMP_NONE, this writes a shape to the lower stencil buffer using an even-odd fill rule. This means that adding a shape on top of existing shape has an erasing effect. However, it also masks its operation by the stencil region in the upper stencil buffer. Note that if a pixel is masked while drawing, it will not be added the stencil region in the lower buffer.

    • STAMP_BOTH

      public static final Stencil.Effect STAMP_BOTH
      Adds a stencil region to both the lower and the upper buffer

      This effect will not have any immediate visible effect on the screen screen. Instead, it creates a stencil region for the effects such as CLIP, MASK, and the like.

      Unlike STAMP, the region is create twice and put in both the upper and the lower stencil buffer. That is because the shapes are drawn to the buffer with an even-odd fill rule (which does not require the full stencil buffer to implement). This has the disadvantage that stamps drawn on top of each other have an "erasing" effect. However, it has the advantage that the this stamp supports a wider array of effects than the simple stamp effect.

      The use of both buffers to provide a greater degree of flexibility.

    • CARVE_NONE

      public static final Stencil.Effect CARVE_NONE
      Adds a stencil region to the lower buffer

      This effect is equivalent to CARVE, since it only uses half of the stencil buffer.

    • CARVE_CLIP

      public static final Stencil.Effect CARVE_CLIP
      Applies a lower buffer CARVE with an upper CLIP.

      As with CARVE_NONE, this writes an additive shape to the lower stencil buffer. However, it also restricts its operation to the stencil region in the upper stencil buffer. Note that if a pixel is clipped while drawing, it will not be added the stencil region in the lower buffer. Hence this is a way to copy the upper buffer stencil region into the lower buffer.

    • CARVE_MASK

      public static final Stencil.Effect CARVE_MASK
      Applies a lower buffer CARVE with an upper MASK.

      As with CARVE_NONE, this writes an additive shape to the lower stencil buffer. However, it also prohibits any drawing to the stencil region in the upper stencil buffer. Note that if a pixel is masked while drawing, it will not be added the stencil region in the lower buffer.

    • CARVE_BOTH

      public static final Stencil.Effect CARVE_BOTH
      Adds a stencil region to both the lower and upper buffer

      This effect is similar to CARVE, except that it uses both buffers. This is to give a wider degree of flexibility.

    • CLAMP_NONE

      public static final Stencil.Effect CLAMP_NONE
      Uses the lower buffer to limit each pixel to single update.

      This effect is equivalent to CLAMP, since it only uses half of the stencil buffer.

    • CLAMP_CLIP

      public static final Stencil.Effect CLAMP_CLIP
      Applies a lower buffer CLAMP with an upper CLIP.

      As with CLAMP_NONE, this draws a nonoverlapping shape using the lower stencil buffer. However, it also restricts its operation to the stencil region in the upper stencil buffer. Note that if a pixel is clipped while drawing, it will not be added the stencil region in the lower buffer.

    • CLAMP_MASK

      public static final Stencil.Effect CLAMP_MASK
      Applies a lower buffer CLAMP with an upper MASK.

      As with CLAMP_NONE, this draws a nonoverlapping shape using the lower stencil buffer. However, it also prohibits any drawing to the stencil region in the upper stencil buffer. Note that if a pixel is masked while drawing, it will not be added the stencil region in the lower buffer.

  • Method Details

    • values

      public static Stencil.Effect[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static Stencil.Effect valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null