Add semi-public API for QtQuick3D

Start exposing some of the internal APIs as semi-public with application implementable APIs.

QtQuick3D's public APIs should cover the "90%" of users use-cases, for the rest we should have API that covers the more advanced/custom use-cases. Those APIs must be documented and as semi-public APIs we should strive to keep them stable. I.e., focus on keeping the code source compatible in patch releases.

– Goal –

• Expose the engine the way we use it, without hiding away too much.
  Note: This means avoiding adding abstractions to hide how e.g. a class works internally. The backside of this is that there might be a higher chance for BC changes.

           Note: Compromises were made: It was not feasible to just expose the internal APIs as is, from front-end to back-end.

• • We didn't want to expose the connection between front-end and back-end nodes; how it works now is an implementation detail and changes would have huge impact on users.
  • Many of the back-end nodes are fat objects, this is likely to change, esp. for the node type, so it made little sense to expose it.
  • We therefore have APIs for getting opaque handles from the corresponding public front-end object, QQuick3DObject. This handle is a light weight handle that gives us some freedom to change both how the handle is mapped to an object in the engine and it also follow the pattern that has been chosen for the rest of the render extensions APIs.

• All exposed APIs should be documented.
• The stencil outline test (manual test) - Should be moved into the Helpers library to make it an easily accessible feature.

• Class' or functionality that are deemed not ready, or necessary (yet), they will be kept private. This can be due to lack of documentation or API/data that's not appropriate or in a state that makes it good for public use (high chance for it to change in the near future).

– Stretch goals –

More examples:

• Single view multiple render outputs. Render the same scene multiple times into the same view, e.g., by rendering to 4 different sections of the view showing the same scene rendered differently (e.g., debug views showing normals, specular values etc.).
• "Batching". Simple case, when instancing can't be used, render models that use the same type material (e.g, just color changes) together by using the same base material, effectively avoiding creation of n materials on the front-end.

• Alternative rendering combined with custom materials (non-shaded) to do a completely custom render pipeline.
• Extensions dependency example. Passing result up the hierarchy .

– Initial work –

Work has been ongoing, and currently we have:

• Internal sub-passes for individual steps of the rendering, which can be moved or replaced.

• Application side API (public) for render extension.
  Render extensions (QML/C+) are nodes in the scene that can be injected, or eventually replace, sub-rendering passes in our renderer using the QRhi API (C+). See stencil outline manual test.

– Remaining or In-progress –

• Add infrastructure to expose QtQuick3D headers as semi-public (as done for qpa and rhi) (done).

• Sanitize all internal classes that are candidates for being made semi-public.

First round of candidates (and supporting headers) are:

• QSSGRenderContextInterface (in-progress)
  • header and source file is named qssgrendercontextcore.h that's not really consistent with the class name, consider renaming.
  • All sub-components exposed, but some require private headers to be used still (decide if these should be "hidden", left as-is, or documented as 'internal'.
• QSSGRhiContext (in-progress)
  • Documentation severely missing.
  • Declared class' needs to be clean-up.
  • QSSGRhiRenderableTexture private but exposed in QSSGFrameData. We'll need to find a better abstraction for "render results".
• QSSGRenderer (done: Not exposed, relevant API moved)
  • Exposes QSSGRhiQuadRenderer, QSSGRhiCubeRenderer, but these are still private.
• QSSGRenderGraphObject (in-progress)
  • no-documentation
• QSSGRenderLayer (done: Not exposed. This is our internal data depo. User facing code exposed through QSSGFrameData etc.)
  • Probably not going to be exposes as-is, so we'll need to check if all the relevant settings are usable through some other means.
• QSSGRenderNode (done: Not exposed)
  • Needs a big clean-up. Ideally we'd also decouple the data from the node (some work in progress, but it's a big effort). We can probably also live with the node-id approach.
• QSSGModelHelpers (in-progress)
  • Very rudimentary, no documentation.
• QSSGRenderHelpers (in-progress)
  • Basic. Prep and Render functions doesn't provide much.
• QSSGFrameData (in-progress)
• QSSGRenderExtension (in-progress)
  • "RenderMode" the two current modes are a bit limiting.
• QQuick3DRenderExtension (in-progress)
• QSSGRhiCubeRenderer (done: Not exposed)
  • Still private, exposed in QSSGRenderer.
• QSSGRhiQuadRenderer (done: Not exposed)
  • Still private, exposed in QSSGRenderer.

Extra:

• Allocators... (Allocators not exposed for now)

- Documentation -

• QSSGRenderContextInterface ()
• QSSGRhiContext ()
• QSSGRenderGraphObject ()
• QSSGModelHelpers ()
• QSSGRenderHelpers ()
• QSSGFrameData (internal doc)
• QSSGRenderExtension (internal doc)
• QQuick3DRenderExtension ()
• Overview ()
• Example(s) ()

Classes with no comment () has no documentation or in-line comments only.

Some TODO and investigation items in no particular order:

• Add alternative to the createRenderables() to make it recursive (Take the subtree from the input model).

• Add functionality to change the render target, i.e., render nodes to a texture.
• Shadow and reflection map managers. Should those be exposed some way? 
• Fix backend node destruction to happen on the correct thread and at the correct time. (together with the QQ scenegraph)
  • Hopefully no need for a dedicated releaseGraphicsResources() virtual.

• Rename release() to something else. Like resetForFrame() or similar. (donde)

• Are underlay and overlay modes enough? Do we need an after-opaque-before-alpha mode?

• Combined extensions need clear docs and examples when it comes to the order of backend nodes (creation, destruction, callback order). First manual test is being added.

• Standalone extension creating a QRhiTexture or buffer by directly using QRhi, where the resources are then used not by an extension, but by a material e.g. as a base color map, or as a texture in a postprocessing effect or custom material? This needs enablers that are out of the scope of the extension API, e.g. to allow creating a Texture that wraps an "external" QRhiTexture, and then somehow set that on a material or effect, etc.

• And the opposite: what if an extension wants to use a texture from Q3D? Or a mesh, etc.

• Detecting changes for camera, and probably other objects. Example: how to detect that we do not need to call calculateViewProjectionMatrix() again? Right now the only way is to call it in every prepareData() to get the view-projection matrix for later use.
• Sorting, we can now have multiple entries per-camera, extension etc., and with different requirements, so:

• • parallelize when there are multiple entries.
  • Add option to define the sorting?

Long term stretch goals:

• JavaScript API?