Implementation of the final API for clustered lighting, shadowType support

[mvaligursky]

Clustered lighting API has been updated to its final form.

New API (still private)

        app.scene.clusteredLightingEnabled = true;

        app.scene.lighting.cells = new pc.Vec3(30, 2, 30);
        app.scene.lighting.maxLightsPerCell = 20;

        app.scene.lighting.shadowsEnabled = true;
        app.scene.lighting.shadowType = pc.SHADOW_PCF1;
        app.scene.lighting.shadowAtlasResolution = 2048;

        app.scene.lighting.cookiesEnabled = true;
        app.scene.lighting.cookieAtlasResolution = 1500;

        app.scene.lighting.areaLightsEnabled = true;

Old API (removed)

        pc.LayerComposition.clusteredLightingEnabled = true;
        app.scene.layers.clusteredLightingCells = new pc.Vec3(16, 12, 16);
        app.scene.layers.clusteredLightingMaxLights = 80;
        app.scene.layers.clusteredLightingShadowsEnabled = true;
        app.scene.layers.clusteredLightingCookiesEnabled = true;
        app.scene.layers.clusteredLightingAreaLightsEnabled = true;

Other changes

• The Scene object now accepts GraphicsDevice as a parameter. This constructor has been made private as well, as the engine does not support multiple Scenes at all.
• Added controls to Clustered spot and omni shadow examples

Clustered shadow filtering: support for PCF1, 3 and 5 filtering for clustered shadows (PCF5 is WebGl2 only, falls backs to PCF3 on WebGl1). Details about added PCF1:

• on webgl1 this is a single sample with point filtering (linear filtering would need 4 samples)
• on webgl2 this is a single sample with linear depth filtering (hardware depth filter)

[Maksims]

If there is one scene per app, so one clustered lighting per app, would it be better to have such API (less depth): app.clusteredLighting.enabled and similar.
Also easier on documentation, can be separately found in own section instead of scene.

[mvaligursky]

The longer team goal is to make multi Scene supported. Scene would represent its set up - global lighting, fog, clustered lighting and similar. But due to many shortcuts taken in how this was put together, this is not possible at the moment, and so there is no reason to expose Scene constructor. But I don't want to close this door.

[willeastcott]

My knee-jerk reaction is that the property names are quite verbose. So presumably we're heading for a world where it's not really 'clustered lighting' any more but just 'lighting' (because we plan to dump the current lighting system).

So, I'm thinking more along the lines of:

        app.scene.lightingCells = new pc.Vec3(30, 2, 30);
        app.scene.maxLights = 20;
        app.scene.shadowsEnabled = true;
        app.scene.cookiesEnabled = true;
        app.scene.areaLightsEnabled = true;
        app.scene.shadowAtlasResolution = 2048;
        app.scene.cookieAtlasResolution = 1500;

I've not included app.scene.clusteredLightingEnabled above because presumably, that will go away when clustered lighting is the only option?

Also, keep in mind that the Editor codebase does call the Scene constructor in at least a couple of places.

[mvaligursky]

great suggestions @willeastcott - I've done just that, but additionally renamed lightingCells to lightCells.

[willeastcott]

This PR introduces Scene#shadowType but we already have LightComponent#shadowType. How do we manage this API change?

[mvaligursky]

This PR introduces Scene#shadowType but we already have LightComponent#shadowType. How do we manage this API change?

Clustered lighting ignores shadowType on the LightComponent, and all cluster lights use the same shadow filtering. If at some point we switch to clustered lighting as a main lighting system, only directional lights will have shadowType exposed on the component. Similarly to shadow resolution - this is automatically assigned from the atlas.

We could possibly do the same with light attenuation - this is per light, as it's reasonably cheap .. but personally I would make it global for cluster lights to save all dynamic branches we can.

[willeastcott]

Do we prefer enableXXX or xxxEnabled?

I can find a few precedents for enableXXX. For example:

• StandardMaterial#enableGGXSpecular
• ElementComponent#enableMarkup
• Application#enableBundles (currently private)

[mvaligursky]

Good question.

I like enabled vs enable as that matches the Component.enabled which is commonly used. In a way, its used in a similar way to for example entity.camera.enabled or scripts.bloom.enabled

We also have lightmapFilterEnabled.

But I don't mind either way.

[mvaligursky]

the naming agreed to in a discussion:

scene.lighting
	.cells
	.maxLightsPerCell
	.shadowsEnabled
	.shadowType = pc.SHADOW_PCF1;
	.shadowAtlasResolution = 2048;

	.cookiesEnabled = true;
	.cookieAtlasResolution = 1500;

	.areaLightsEnabled = true;

[slimbuck]

Do we prefer enableXXX or xxxEnabled?

I can find a few precedents for enableXXX. For example:

• StandardMaterial#enableGGXSpecular
• ElementComponent#enableMarkup
• Application#enableBundles (currently private)

To me xxxEnabled sounds informative, not something I can set. Since this is lighting API for setting config, I'd probably prefer enableXxx form. From a quick look around the engine I see use of both forms, but probably more enableXxx at this point.

[mvaligursky]

to me, xxxEnabled matches with the style of entity.enabled and component.enabled.
enableXXX sounds like a name of a function to me, not a getter & setter.
@willeastcott any thoughts on this?

[willeastcott]

OK, @mvaligursky, while I'm still a little torn on this, I'll go with xxxEnabled.