API functions for OpenGL's 'alpha testing' capability

Issue #534 resolved
Alex Szpakowski
created an issue

OpenGL's alpha testing functionality, when enabled, compares incoming alpha values of images and primitives to a user-specified "reference alpha" value, and based on the outcome of the comparison and a user-defined 'function'/mode, either discards or draws the pixel.

This functionality can easily be reproduced via a PixelEffect, but there are still plenty of systems which run LÖVE and don't support PixelEffects. Alpha testing is supported in all versions and implementations of OpenGL.

I have attached a diff which adds this functionality to LÖVE. There are 2 new functions in the love.graphics table:

  • love.graphics.setAlphaTest(mode, referencealpha)
  • mode, referencealpha = love.graphics.getAlphaTest()

mode is either "<", "<=", "==", "~=", ">=", or ">", and specifies how the reference alpha value gets compared. referencealpha is an integer between 0 and 255, and specifies the alpha value the incoming fragment is compared to.

For example, love.graphics.setAlphaTest(">", 127) will, for every image and primitive drawn afterward, only display pixels from those images and primitives if the alpha value of the pixel is greater than 127.

Alpha testing is disabled by default. love.graphics.setAlphaTest() (no arguments) will disable alpha testing if it is enabled. love.graphics.getAlphaTest() will return nil if alpha testing is disabled, otherwise it returns the current values previously set by the user.

I have also included an example .love showing the new alpha testing API being used to create metaballs without the use of PixelEffects. Left/right arrow control which mode is being used, up/down arrow control the reference alpha, and "T" toggles alpha testing entirely.

Comments (14)

  1. Anders Ruud repo owner


    I wonder if the string constants should be actual words instead of operators. When looking at string constants like that ... it almost implies to me that it supports evaluation of whatever statement you choose.

    How about "less", "greater", "lequal", "gequal", "equal", "nequal"?

  2. Boolsheet

    I had it happen that my brain made the G in GL_GEQUAL disappear. Now that I'm aware of it, I'll be more careful when approaching those enumerations, but other lovers might have more trouble.

    Are there other words for "greater or equal to" and such? My vocabulary is lacking in that regard.

  3. Alex Szpakowski reporter

    Personally I'd still prefer the operator-style syntax because it feels very natural to me - I don't have to remember any LÖVE-specific names for what I want to do, I just have to know Lua. I can see how some people might be confused by them though.

  4. Anders Ruud repo owner

    We should always strive for at least some level of consistency (not that everything is completely consistent in its current form). That's why I try to oppose "unfamiliar" ways of doing things. Just to test (out loud) if we actually want to introduce a new pattern.

    It's probably OK to use "<" etc., now, and in similar cases in the future (if any). I guess it doesn't matter much that it theoretically conflicts (visually) with functions that pass source code (i.e. shaders), if we display BSOL for invalid constants.

  5. Alex Szpakowski reporter

    I should mention that OpenGL ES 2.0+ doesn't support fixed-function alpha testing (however it does support shaders so no functionality is lost), so if alpha testing does get included in LÖVE, it would probably be a good idea to add an isSupported string to go along with it.

  6. Alex Szpakowski reporter

    Setting this as "on hold" because of the aforementioned issues, although as GLSL-incapable systems become less and less common, fixed-function alpha testing APIs will be less and less useful.

  7. Alex Szpakowski reporter
    • changed status to open

    Alpha testing can be combined with stenciling to do per pixel alpha-based stenciling based on the alpha component of images.

    This is a pretty handy feature I think, and while shaders can do everything that alpha testing does (and more), the simple API and compatibility with older systems is nice. The only stopper is the lack of support on mobile systems.

    Anyone else have opinions about having this feature vs. potential future compatibility issues with mobile/ES2?

  8. Bart van Strien

    This looks good, also, I am definitely in favor of the operators, and for rude, who says this has no antecedent, did he forget the wonderful " ", or other such key constants?

  9. Log in to comment