Adds support for combined Depth+Stencil Texture

[AtiX]

Extends DepthTexture to not only support the depth component, but also depth+stencil component.

Two new constants (THREE.DepthStencilFormat and THREE.UnsignedInt248Type) are introduced.

The WebGLRenderTarget is extended to support setting the depthTexture in the options instead of currently setting it manually afterwards:

target = new THREE.WebGLRenderTarget( width, height, {
   ...
   depthTexture: myDepthTexture
})

Create a depth + stencil texture the following way:

depthTexture = new THREE.DepthTexture(
    texWidth
    texHeight
    THREE.UnsignedInt248Type
    mapping
    wrapS
    wrapT
    magFilter
    minFilter
    anisotropy
    THREE.DepthStencilFormat
  )

(see also: https://www.khronos.org/registry/webgl/extensions/WEBGL_depth_texture/)

[mrdoob]

@mattdesl looks good?

[AtiX]

I resolved all merge conflicts.

Ping @mattdesl ;)

[AtiX]

Merge conflicts resolved again.

(And yeah, ping @mattdesl )

[Bryce-Summers]

When using depth only attachments, the paradigm I have observed in THREE.js is that the user creates a depth texture with an empty constructor as follows:

depthTexture = new THREE.DepthTexture()

then the depth texture is set to default values and later updated with framebuffer size information in the function setupDepthTexture()

// upload an empty depth texture with framebuffer size
if ( !properties.get( renderTarget.depthTexture ).__webglTexture ||
    renderTarget.depthTexture.image.width !== renderTarget.width ||
    renderTarget.depthTexture.image.height !== renderTarget.height ) {
    renderTarget.depthTexture.image.width = renderTarget.width;
    renderTarget.depthTexture.image.height = renderTarget.height;
    renderTarget.depthTexture.needsUpdate = true;
}

Since the texture is set to be a depth only texture by default, it naturally needs to be called using the paradigm of a complete constructor as in your usage comment at the start of this discussion:

depthTexture = new THREE.DepthTexture(
    texWidth
    texHeight
    THREE.UnsignedInt248Type
    mapping
    wrapS
    wrapT
    magFilter
    minFilter
    anisotropy
    THREE.DepthStencilFormat
  )

I think that it would be more consistent if THREE.js constructed a texture with a depth_stencil attachment once it sees that its target buffer has the stencil flag set to true or better yet new in addition to THREE.DepthTexture(), we could also have a THREE.DepthStencilTexture() class to preserve the THREE.js paradigm of allocating textures using default constructors and allowing the rendering targets to fill them in as needed.

[AtiX]

I personally dislike the idea of automatically deciding which texture type to use based on the stencil flag, since this means changing/overriding other values like the pixel format, which could have been set by users.

Using a separate class is probably feasible, but creates duplicate code.

I think a clean approach would be to change the constructor to an options-object styled constructor (since missing parameters are filled in with defaults anyways), this would then result in

new THREE.DepthTexture()

and

new THREE.DepthTexture({
  format: THREE.DepthStencilFormat
  type: THREE.UnsignedInt248Type
})

@mrdoob , @Bryce-Summers what do you think?

[mrdoob]

Looks good!

[mrdoob]

Thanks!

[mrdoob]

Any chance you could also provide an example for this? That way we'll make sure that we don't break it in the future.

[mrdoob]

FYI 9c8d18d 63f412e

[AtiX]

Thanks!

I hope to find time on the weekend, created issue #9417 for that. (Assign to me pls :)?)

[Bryce-Summers]

@AtiX I agree with you. By the way, I integrated your PR into an older version of three.js and it works great for image space CSG!

[makc]

I integrated your PR into an older version of three.js and it works great for image space CSG

@Bryce-Summers do you have a demo up anywhere ?

[Bryce-Summers]

I wish I could point you to my demo code, but at that time I was working with a team with a closed source policy.