Docs: Various documentation fixes

Documentation/Manuals/Native/User/savingScene.md

@@ -21,7 +21,7 @@ HPrefab scenePrefab = Prefab::create(sceneRoot, true);
 
 # Saving & loading prefabs
 
-Once a prefab can be created it can be saved and loaded any other **Resource**.
+Once a prefab has been created it can be saved and loaded as any other **Resource**.
 
 ~~~~~~~~~~~~~{.cpp}
 // Save the prefabs we created previously

Documentation/Manuals/Native/advMaterials.md

@@ -2,12 +2,12 @@ Advanced materials									{#advMaterials}
 ===============
 [TOC]
 
-We have already talked about how to create materials, assign them parameters and bind them to a **Renderable** component. In this section we'll show an advanced way to assign material parameters, how to use materials for rendering directly (without using **Renderable** component) and how to create your own shaders without the use of BSL.
+We have already talked about how to create materials, assign them parameters and bind them to a **Renderable** component. In this section we'll show an advanced way to assign material parameters, how to use materials for rendering directly (without using **Renderable** component) and how to create your own shaders without the use of BSL. 
 
 # Material parameters {#advMaterials_a}
 Previously we have shown to how to set **Material** parameters by calling methods like @ref bs::Material::setTexture "Material::setTexture()", @ref bs::Material::setFloat "Material::setFloat()", @ref bs::Material::setColor "Material::setColor()", @ref bs::Material::setVec4 "Material::setVec4()" and similar.
 
-As an alternative you can also set materials through material handles. Once a material handle is retrieved it allows you to set material parameters much more efficiently than by calling the methods above directly. 
+As an alternative you can also set materials through material parameter handles. Once a material handle is retrieved it allows you to set material parameters much more efficiently than by calling the methods above directly. 
 
 To retrieve the handles call any of the following methods, depending on material parameter type:
  - @ref bs::ct::Material::getParamTexture "ct::Material::getParamTexture()" - Outputs a @ref bs::TMaterialParamTexture<Core> "MaterialParamTexture" handle that can be used for reading & writing the parameter value.
@@ -45,11 +45,11 @@ Material handles are very similar as **GpuParams** handles we talked about earli
  - **GpuProgram** parameters are retrieved directly from program source code, while **Material** parameters need to be explicitly defined in the **Shader** (shown below). **Material** parameters always map to one or multiple **GpuProgram** parameters. 
 
 # Creating a shader manaully {#advMaterials_b}
-So far when we wanted to create a shader we would create a BSL file which would then be imported, creating a @ref bs::Shader "Shader". But you can also create shaders manually by explicitly providing HLSL/GLSL code for **GpuProgram**%s and non-programmable states. 
+So far when we wanted to create a shader we would create a BSL file which would then be imported, creating a @ref bs::Shader "Shader". But you can also create shaders manually by explicitly providing HLSL/GLSL code for **GpuProgram**%s and non-programmable states. Most of the things outlined in this section are performed by BSL compiler internally when a **Shader** is imported.
 
 Each shader definition contains two things:
  - A list of parameters, with a mapping of each parameter to one or multiple variables in a GPU program
- - One or multiple @ref bs::Technique "Technique"%s. Each technique is essentially a fully fledged shader of its own. Techniques are chosen by the renderer depending on the context. For example some techniques only support the DirectX backend, while others only the Vulkan backend.
+ - One or multiple @ref bs::Technique "Technique"%s. Each technique is essentially a fully fledged shader of its own. Techniques are chosen by the renderer depending on the context. For example some techniques only support the DirectX backend, while others only the Vulkan backend. Different techniques will also exist for different shader variations (e.g. a high- and low-end version of the same shader).
   - Each technique contains one or multiple @ref bs::Pass "Pass"%es. A pass is a set of GPU programs and non-programmable states. When rendering using a certain technique each pass will be executed one after another. This allows you to render objects that require more complex rendering that requires multiple separate steps - althrough in practice most techniques have only a single pass.
 
 To summarize, the relationship between materials, shaders, techniques and passes is:
@@ -79,16 +79,15 @@ GPU programs and non-programmable states are created as described in the low-lev
 Now that we know how to create a pass, we can use one or multiple passes to initialize a **Technique**. A technique is just a container for one or multiple passes.
 
 To create a technique call @ref bs::Technique::create "Technique::create()" and provide it with:
- - Shading language name - This should be "HLSL" or "GLSL". The engine will not use this technique unless this language is supported by the current render API.
- - Renderer name - In case you are using a non-default renderer, and the technique only works on it. Otherwise use the built-in variable `RendererAny`
+ - Shading language name - This should be "HLSL" or "GLSL". The engine will not use this technique unless this language is supported by the current render API. 
  - Array containing one or multiple passes
  
 For example:
 ~~~~~~~~~~~~~{.cpp}
 SPtr<Pass> pass = ...;
 
-// Create a technique that uses HLSL and supports any renderer, with a single pass
-SPtr<Technique> technique = Technique::create("HLSL", RendererAny, { pass });
+// Create a technique that uses HLSL and has a single pass
+SPtr<Technique> technique = Technique::create("HLSL", { pass });
 ~~~~~~~~~~~~~
   
 ## Creating a shader {#materials_b_c}

Documentation/Manuals/Native/customImporters.md

@@ -42,7 +42,7 @@ public:
 ~~~~~~~~~~~~~ 
  
 # Registering SpecificImporter {#customImporters_b}
-To register your **SpecificImporter** implementation with the importer system you must call @ref bs::Importer::_registerAssetImporter "_registerAssetImporter()". You can do this after application start-up, or during by implementing your own **Application** class as described in the @ref advancedStartup manual.
+To register your **SpecificImporter** implementation with the importer system you must call @ref bs::Importer::_registerAssetImporter "_registerAssetImporter()". You can do this after application start-up, or during by implementing your own **Application** class as described in the @ref nonComponentApproach manual.
 
 ~~~~~~~~~~~~~{.cpp}
 Application::startUp(...);

Documentation/Manuals/Native/customRenderer.md

@@ -21,6 +21,7 @@ Majority of the renderer interface consists of methods that notify the renderer
  - @ref bs::Light "Light"
  - @ref bs::ReflectionProbe "ReflectionProbe"
  - @ref bs::Skybox "Skybox"
+ - @ref bs::LightProbeVolume "LightProbeVolume"
  
 Whenever such objects are created, destroyed or some property on them is updated, one of the following methods is called:
  - @ref bs::ct::Renderer::notifyCameraAdded "ct::Renderer::notifyCameraAdded()" - Called when a new **Camera** is created (e.g. when a **CCamera** component is added to the scene).
@@ -38,6 +39,9 @@ Whenever such objects are created, destroyed or some property on them is updated
  - @ref bs::ct::Renderer::notifySkyboxAdded "ct::Renderer::notifySkyboxAdded()" - Called when a new **Skybox** is created (e.g. when a **CSkybox** component is added to the scene).
  - @ref bs::ct::Renderer::notifySkyboxTextureChanged "ct::Renderer::notifySkyboxTextureChanged()" - Called when the texture applied to **Skybox** changes.
  - @ref bs::ct::Renderer::notifySkyboxRemoved "ct::Renderer::notifySkyboxRemoved()" - Called when a **Skybox** is destroyed. 
+ - @ref bs::ct::Renderer::notifyLightProbeVolumeAdded "ct::Renderer::notifyLightProbeVolumeAdded()" - Called when a new **LightProbeVolume** is created (e.g. when a **CLightProbeVolume** component is added to the scene).
+ - @ref bs::ct::Renderer::notifyLightProbeVolumeUpdated "ct::Renderer::notifyLightProbeVolumeUpdated()" - Called when probes are added or modified in a **LightProbeVolume**. 
+ - @ref bs::ct::Renderer::notifyLightProbeVolumeRemoved "ct::Renderer::notifyLightProbeVolumeRemoved()" - Called when a **LightProbeVolume** is destroyed.
  
 Your renderer implementation can choose to implement some or all of those methods. By implementing these methods your renderer implementation is expected to keep track of the scene state, and then use that scene state for rendering. For example most renderers will at least need to keep track of all active cameras and renderable objects.
  
@@ -182,16 +186,15 @@ class DownsampleMat : public RendererMaterial<DownsampleMat>
 };
 ~~~~~~~~~~~~~
 
-Once defined the renderer material can be accessed through the static @ref bs::ct::RendererMaterial::get<T>() "ct::RendererMaterial::get<T>()" method. Underlying material can be accessed by calling @ref bs::ct::RendererMaterial::getMaterial() "ct::RendererMaterial::getMaterial()", and the material parameters by calling @ref bs::ct::RendererMaterial::getParamsSet() "ct::RendererMaterial::getParamsSet()". Then you can bind the material for rendering as normal (using **RendererUtility** or directly through **RenderAPI**).
+Once defined the renderer material can be accessed through the static @ref bs::ct::RendererMaterial::get<T>() "ct::RendererMaterial::get<T>()" method.
 
 ~~~~~~~~~~~~~{.cpp}
 DownsampleMat* renderMat = DownsampleMat::get():
-SPtr<Material> material = renderMat->getMaterial();
-
-// Render using the material as normal
 ~~~~~~~~~~~~~
 
-You will normally also want to add a constructor in which you look up any necessary parameters the material might require, so they can be set more easily when rendering.
+Once retrieved the object will contain the instance of the shader in the path you provided. Internally the material will provide you with a reference to either a graphics or compute pipeline state as *mGfxPipeline* and *mComputePipeline*, depending on the type of shader that was loaded. It will also provide you with **GpuParams** in the *mParams* field.
+
+When the material is first created you will likely want to add a constructor in which you look up any necessary parameters the material might require, so they can be set more easily when rendering.
 ~~~~~~~~~~~~~{.cpp}
 class DownsampleMat : public RendererMaterial<DownsampleMat>
 {
@@ -201,12 +204,10 @@ public:
 	DownsampleMat()
 	{
 		// Retrieve material parameters, and optionally perform other set-up
-		mInputTexture = mMaterial->getParamTexture("gInputTex");
-		mInvTexSize = mMaterial->getParamVec2("gInvTexSize");
+		mParams->getTextureParam(GPT_FRAGMENT_PROGRAM, "gInputTex", mInputTexture);
 	}
 
-	MaterialParamVec2 mInvTexSize;
-	MaterialParamTexture mInputTexture;
+	GpuParamTexture mInputTexture;
 };
 ~~~~~~~~~~~~~
 
@@ -223,16 +224,7 @@ class DownsampleMat : public RendererMaterial<DownsampleMat>
 		// Assign parameters before rendering
 		mInputTexture.set(input);
 		
-		const TextureProperties& props = input->getProperties();
-		Vector2 invTextureSize(1.0f / props.getWidth(), 1.0f / props.getHeight());
-
-		mInvTexSize.set(invTextureSize);
-		
-		mMaterial->updateParamsSet(mParamsSet);
-		
-		// Bind material, parameters and draw
-		gRendererUtility().setPass(mMaterial);
-		gRendererUtility().setPassParams(mParamsSet);
+		bind();
 		gRendererUtility().drawScreenQuad();
 	}
 
@@ -240,49 +232,100 @@ class DownsampleMat : public RendererMaterial<DownsampleMat>
 };
 ~~~~~~~~~~~~~
 
-Renderer materials also support variations for cases where you might require slightly different versions of a shader for different use cases. The variations are handled by setting up preprocessor \#defines, which the shader code can then use to conditionally add or remove parts of code (via \#if or similar). To determine which defines are set implement the _initVariations() method in your **RendererMaterial** implementation, and append your defines to the @ref bs::ct::ShaderVariations "ShaderVariations" object. Note that this method must be present, even if not using any variations (simply leave it empty).
+Note that a helper method @ref bs::ct::RendererMaterial::bind() "ct::RendererMaterial::bind()" is provided, which will bind both the GPU pipeline and parameters.
+
+~~~~~~~~~~~~~{.cpp}
+// External code wanting to run the material
+SPtr<Texture> inputTex = ...;
+
+DownsampleMat* renderMat = DownsampleMat::get():
+renderMat->execute(inputTex);
+~~~~~~~~~~~~~
+
+### Variations {#renderer_c_c_a}
+
+If your BSL file contains shader variations, then you can call @ref bs::ct::RendererMaterial::get<T>(const ShaderVariation&) "ct::RendererMaterial::get<T>(const ShaderVariation&)" to retrieve a specific variation. Variations were explained in more detail in the BSL manual.
+
+~~~~~~~~~~~~~{.cpp}
+// External code wanting to run a specific variation of the material
+SPtr<Texture> inputTex = ...;
+
+// Get the variation that has HIGH_QUALITY define enabled
+ShaderVariation variation = ShaderVariation({
+	ShaderVariation::Param("HIGH_QUALITY", true)
+});
+
+DownsampleMat* renderMat = DownsampleMat::get(variation):
+renderMat->execute(inputTex);
+~~~~~~~~~~~~~
+
+Normally you will want to handle creation of various @ref bs::ct::ShaderVariations "ShaderVariations" structures through a templated method, like so:
+
+~~~~~~~~~~~~~{.cpp}
+class DownsampleMat : public RendererMaterial<DownsampleMat>
+{
+	template<bool highQuality>
+	static const ShaderVariation& getVariation()
+	{
+		static ShaderVariation variation = ShaderVariation({
+			ShaderVariation::Param("HIGH_QUALITY", highQuality)
+		});
+
+		return variation;
+	}
+
+	// ... other DownsampleMat code ...
+};
+~~~~~~~~~~~~~
+
+Then you can also add a static **getVariation** method to hide these internals from the caller.
 
 ~~~~~~~~~~~~~{.cpp}
-// Make our downsample shader come in two variations
 class DownsampleMat : public RendererMaterial<DownsampleMat>
 {
-	RMAT_DEF("Downsample.bsl");
-	
 	// ... other DownsampleMat code ...
 	
-private:
-	static ShaderVariation VAR_PointFiltering;
-	static ShaderVariation VAR_BilinearFiltering;
+public:
+	static DownsampleMat* getVariation(bool highQuality)
+	{
+		if(highQuality)
+			return get(getVariation<true>());
+			
+		return get(getVariation<false>());
+	}
 };
+~~~~~~~~~~~~~
 
-// Set up optional defines to control shader compilation
-ShaderVariation DownsampleMat::VAR_PointFiltering = ShaderVariation({
-	ShaderVariation::Param("BILINEAR_FILTERING", false)
-});
+Now the calling code can simply retrieve the variation it requires.
 
-ShaderVariation DownsampleMat::VAR_BilinearFiltering = ShaderVariation({
-	ShaderVariation::Param("BILINEAR_FILTERING", true)
-});
+~~~~~~~~~~~~~{.cpp}
+// External code wanting to run the high quality version of the material
+SPtr<Texture> inputTex = ...;
 
-// Method defined in RMAT_DEF macro
-void DownsampleMat::_initVariations(ShaderVariations& variations)
-{
-	variations.add(VAR_PointFiltering);
-	variations.add(VAR_BilinearFiltering);
-}
+DownsampleMat* renderMat = DownsampleMat::getVariation(true):
+renderMat->execute(inputTex);
 ~~~~~~~~~~~~~
 
-Specific variation of the material can the be retrieved by calling the static @ref bs::ct::RendererMaterial::get<T>(const ShaderVariation&) "ct::RendererMaterial::get<T>(const ShaderVariation&)" method.
+### Defines {#renderer_c_c_b}
+
+Sometimes you wish to be able to dynamically control defines that are used to compile the shader code. This is particularily useful if you want to make sure your C++ code and shader code use the same value. To do this you need to create your material using the @ref RMAT_DEF_CUSTOMIZED macro, instead of **RMAT_DEF**. It has the exact same signature as **RMAT_DEF** but it provides an *_initDefines* method you must implement.
+
+The method receives a @ref bs::ShaderDefines "ShaderDefines" object which you can then populate with relevant values. Those values will then be used when compiling the shader.
 
 ~~~~~~~~~~~~~{.cpp}
-// Get the variation that performs bilinear filtering
-DownsampleMat* renderMat = DownsampleMat::get(VAR_BilinearFiltering):
-SPtr<Material> material = renderMat->getMaterial();
+constxpr static UINT32 TILE_WIDTH = 8;
+constxpr static UINT32 TILE_HEIGHT = 8;
+constxpr static UINT32 PIXELS_PER_THREAD = 4;
 
-// Render using the material as normal
+void IrradianceComputeSHMat::_initDefines(ShaderDefines& defines)
+{
+	defines.set("TILE_WIDTH", TILE_WIDTH);
+	defines.set("TILE_HEIGHT", TILE_HEIGHT);
+	defines.set("PIXELS_PER_THREAD", PIXELS_PER_THREAD);
+}
 ~~~~~~~~~~~~~
 
-> All builtin shaders are cached. The system will automatically pick up any changes to shaders in *Data/Raw/Engine* folder and rebuild the cache when needed. However if you are changing defines as above you must manually force the system to rebuild by deleting the *Timestamp.asset* file in *Data/Engine* folder.
+> All builtin shaders are cached. The system will automatically pick up any changes to shaders in *Data/Raw/Engine* folder and rebuild the cache when needed. However if you are changing defines as above you must manually force the system to rebuild by modifying the BSL file in *Data/Raw/Engine* folder.
 
 ## Parameter blocks {#renderer_c_d}
 In the @ref gpuPrograms manual we talked about parameter block buffers, represented by **GpuParamBlockBuffer** class. These blocks are used for group data parameters (such as float, int or bool) into blocks that can then be efficiently bound to the pipeline. They are better known as uniform buffers in OpenGL/Vulkan, or constant buffers in DX11. 
@@ -326,7 +369,7 @@ PerCameraParamBlockDef def; // Normally you want to make this global so it's ins
 SPtr<GpuParamBlockBuffer> paramBlock = def.createBuffer(); 
 
 // Assign a value to the gViewDir parameter of the parameter block
-def.gViewDir.set(paramBlock, Vector3(0.707.0, 0.707f, 0.0f));
+def.gViewDir.set(paramBlock, Vector3(0.707f, 0.707f, 0.0f));
 ... set other parameters in block ...
 
 // Assign the parameter block to the material (optionally, assign to GpuParams if using them directly)
@@ -341,9 +384,11 @@ Blocks are often used with renderer materials we described in the previous secti
 Note that by using this approach you lose all the error checking normally performed by **Material** or **GpuParams** when you are assigning parameters individually. You must make sure that the layout in C++ matches the layout in the GPU program. In case of GLSL you must also specify `layout(std140)` keyword to ensure its layout is compatible with C++ struct layout. You must also make sure that variable names match the names in the GPU program code.
 
 ## Renderer semantics {#renderer_c_e}
-Renderer semantics allow user created shaders to request that certain parameters in a GPU program are populated by the renderer. They are specified in the shader code as we described in the BSL manual.
+Renderer semantics allow user created shaders to request that certain parameters in a GPU program are populated by the renderer. They can be specified when defining shader parameters.
+
+For example the user might request a "VP" semantic, which could be recognized by the renderer that the shader requests a view-projection matrix. Such a matrix is not something that the user should have to assign to the material himself. The renderer can choose to parse material parameters looking for supported semantics, and assign their values. 
 
-For example the user might request a "VP" semantic, which could be recognized by the renderer that the shader requests a view-projection matrix. Such a matrix is not something that the user should have to assign to the material himself. The renderer can choose to parse material parameters looking for supported semantics, and assign their values. Ultimately whether the renderer chooses to parse the semantics or not is up to the renderer. 
+Ultimately whether the renderer chooses to parse the semantics or not is up to the renderer. Currently the default *RenderBeast* renderer does not make use of any semantics and instead maps parameters directly by using their name.
 
 The semantics for each parameter can be accessed through the **Shader** object, which renderer needs to iterate through manually.
 

Documentation/Manuals/Native/customResources.md

@@ -2,7 +2,7 @@ Creating new resource types					{#customResources}
 ===============
 [TOC]
 
-Throughout the previous manuals we have shown how to import, load and save a variety of resource types. You can also add brand new resource types of your own.
+Throughout the previous manuals we have shown how to import, load and save a variety of resource types. But you can also add brand new resource types of your own.
 
 # Custom resource type {#customResources_a}
 To create a custom resource type you need to implement the @ref bs::Resource "Resource" interface. **Resource** derives from both @ref bs::CoreObject "CoreObject" and @ref bs::IReflectable "IReflectable". These two classes make up majority of its interface, and we have already shown how to implement them in the @ref coreThread and @ref serializingObjects manuals.

Documentation/Manuals/Native/plugins.md

@@ -7,7 +7,6 @@ Many systems in bs::f are implemented through plugins, libraries that are separa
 bs::f supports plugins for the following systems:
  - Audio - Systems for providing audio playback.
  - Importers - Importers that handle conversion of some third party resource format into an engine-ready format.
- - Input - Reports input events (mouse, keyboard, gamepad, etc.)
  - Physics - Runs the physics simulation.
  - Renderer - Determines how is the scene displayed (lighting, shadows, post-processing, etc.). 
  - Rendering API - Wrappers for render APIs like DirectX, OpenGL or Vulkan.