Confusing behavior: Stencil Test is disabled unless Stencil Write is true

This is a minor issue, but it forced me to read the three.js source to figure it out so it may be something to fix…

Anyway, enabling/disabling the stencil test for an object is currently the same as disabling or enabling stencilWrite.

The problem with this is that when using stencil it’s very common to have objects that don’t write stencil, they only test against what’s already in the buffer… so I ended up wasting some time trying to figure out why my object with stencilWrite = false was not affected by the stencil func at all.

I think it may make more sense to have a separate stencilTest bool, so that testing can be enabled without writing, or just assume that the test must be on if stencilFunc is not Always.

Again, this is not a big deal - stencilWrite = true doesn’t actually change anything because all Ops default to Keep, so it’s not too bad to use that one.

[mrdoob]

@Tomcc Would you like to do a PR with your proposed behaviour?

[gkjohnson]

I see it can be confusing. I think exposing the stencilMask field made it a bit less clear how to handle this. At the least I think the docs could be updated.

I suppose it could make sense to follow the same pattern as the dpeth buffer, though.

stencilTest -> enables reading / writing stencil buffer (defaults to false) stencilWrite -> sets the stencil write mask to 0 if false, uses stencilMask if true (defaults to true) stencilMask -> the write mask used when stencilWrite is true.

The difference is that right now depth mask is not exposed. I think generally a write mask for stencil has more utility.

Thoughts?