Merge pull request #277555 from FlorianBorn71/OutlinesWithTextureMask

Outlines with texture mask, and some other new features

Author: ttorble

articles/remote-rendering/overview/features/color-materials.md

@@ -31,9 +31,9 @@ The following material properties are exposed in the runtime API, for instance o
 * `AlbedoMap`: A [2D texture](../../concepts/textures.md) for per-pixel albedo values.
 
 * `AlphaClipThreshold`: If the `AlphaClipped` flag is set on the `ColorFlags` property, all pixels where the albedo alpha value is lower than the value of `AlphaClipThreshold` won't be drawn. Alpha clipping can be used even without enabling transparency and is much faster to render. Alpha clipped materials are still slower to render than fully opaque materials, though. By default alpha clipping is disabled.
-
-* `TexCoordScale` and `TexCoordOffset`: The scale is multiplied into the UV texture coordinates, the offset is added to it. Can be used to stretch and shift the textures. The default scale is (1, 1) and offset is (0, 0).
-
+* `TexCoordMode`: Defines the mode that is used to produce texture coordinates for the albedo texture. This mode is ignored if this material doesn't use a texture. By default, the texture coordinates are fetched from the mesh's input vertex streams (mode `TextureCoordinateGenerationMode.SourceUv0` or `TextureCoordinateGenerationMode.SourceUv1`) and then transformed through `TexCoordScale` and `TexCoordOffset`. When setting up a material through code, this mode can also be set to `TextureCoordinateGenerationMode.PlanarObjectSpace` or `TextureCoordinateGenerationMode.PlanarWorldSpace` to generate the coordinates as the vertex distance to two configurable 3D planes `TexCoordPlaneU` and `TexCoordPlaneV`. This is referred to as 'planar texture mapping'.
+* `TexCoordScale` and `TexCoordOffset`: For texture coordinates from source mesh, an extra linear transform can be applied. The scale is multiplied into the UV texture coordinates, the offset is added to it. Can be used to stretch and shift the textures. The default scale is (1, 1) and offset is (0, 0).
+* `TexCoordPlaneU` and `TexCoordPlaneV`: For planar mapping modes, these define the texture planes for the u-coordinate and v-coordinate respectively. Planes are defined in standard normal form (A,B,C,D), so a coordinate is calculated as t = A*x + B*y + C*z + D, where (x,y,z) is the vertex position in either world or object space.
 * `FresnelEffectColor`: The fresnel color used for this material. Only important when the fresnel effect flag has been set on this material (see above). This property controls the base color of the fresnel shine (see [fresnel effect](../../overview/features/fresnel-effect.md) for a full explanation). Currently only the RGB-channel values are important and the alpha value will be ignored.
 
 * `FresnelEffectExponent`: The fresnel exponent used for this material. Only important when the fresnel effect flag has been set on this material (see above). This property controls the spread of the fresnel shine. The minimum value 0.01 causes a spread across the whole object. The maximum value 10.0 constricts the shine to only the most grazing edges visible.

articles/remote-rendering/overview/features/media/outlines-with-texture-mask.png

@@ -12,7 +12,7 @@ ms.custom: devx-track-csharp
 
 Selected objects can be highlighted visually by adding outline rendering via the [Hierarchical state override component](../../overview/features/override-hierarchical-state.md). This chapter explains how global parameters for outline rendering are changed through the client API.
 
-Outline properties are a global setting. All objects that use outline rendering will use the same setting - it isn't possible to use a per-object outline color.
+Outline properties are a global setting. All objects that use outline rendering use the same setting - it isn't possible to use a per-object outline color.
 
 > [!NOTE]
 > The outline rendering effect can't be applied to point clouds.
@@ -26,9 +26,12 @@ Class `OutlineSettings` holds the settings related to global outline properties.
 | `Color`          | Color4Ub | The color that is used for drawing the outline. The alpha portion is ignored.         |
 | `PulseRateHz`    | float   | The rate at which the outline oscillates per second|
 | `PulseIntensity` | float   | The intensity of the outline pulse effect. Must be between 0.0 for no pulsing and 1.0 for full pulsing. Intensity implicitly sets the minimum opacity of the outline as `MinOpacity = 1.0 - PulseIntensity`. |
+| `MaskTexture` | 2D texture | If specified, the color of the outline will be tinted by this texture. The texture is sampled in screen-space coordinates and various parameters (`MaskScale`, `MaskScaleToFit`, `MaskOffset`, `MaskScrollSpeed`, `MaskRotationCenter`, `MaskRotationAngle`, `MaskRotationSpeed`) affect the stretching, rotation, and scrolling of that mapping. This feature can be used to achieve effects like a color gradient or dashed outlines. See second example image below. |
 
 ![An object rendered three times with different outline parameters](./media/outlines.png) The effect of changing the `color` parameter from yellow (left) to magenta (center) and `pulseIntensity` from 0 to 0.8 (right).
 
+![An object rendered two times showing distinct use cases for outline texture masks](./media/outlines-with-texture-mask.png) The effect of applying a mask texture to the outlines: Screen aligned color gradients (left) or dashed outlines simulated by using a tiling texture with stripes (right).
+
 ## Example
 
 The following code shows an example for setting outline parameters via the API:
@@ -57,7 +60,7 @@ void SetOutlineParameters(ApiHandle<RenderingSession> session)
 
 ## Performance
 
-Outline rendering may have a significant impact on rendering performance. This impact varies based on screen-space spatial relation between selected and non-selected objects for a given frame.
+Outline rendering may have a significant impact on rendering performance. This impact varies based on screen-space spatial relation between selected and nonselected objects for a given frame.
 
 ## API documentation
 

articles/remote-rendering/overview/features/outlines.md

@@ -41,7 +41,7 @@ The fixed set of states that can be overridden are:
   > [!NOTE]
   > The see-through effect is ignored for point clouds.
 
-* **`Shell`**: The geometry is rendered as a transparent, de-saturated shell. This mode allows fading out non-important parts of a scene while still retaining a sense of shape and relative positioning. To change the shell rendering's appearance, use the [ShellRenderingSettings](shell-effect.md) state. See the following image for the car model being entirely shell-rendered, except for the blue springs:
+* **`Shell`**: The geometry is rendered as a transparent, desaturated shell. This mode allows fading out unimportant parts of a scene while still retaining a sense of shape and relative positioning. To change the shell rendering's appearance, use the [ShellRenderingSettings](shell-effect.md) state. See the following image for the car model being entirely shell-rendered, except for the blue springs:
 
   ![Shell mode used to fade out specific objects](./media/shell.png)
 
@@ -60,11 +60,16 @@ The fixed set of states that can be overridden are:
 
 * **`DisableCollision`**: The geometry is exempt from [spatial queries](spatial-queries.md). The **`Hidden`** flag doesn't affect the collision state flag, so these two flags are often set together.
 
-* **`TransparencyWritesDepth`**: Activates depth writing for **`See-through`** and material transparencies in the component's entity's scene-tree. Using this flag, **`See-through`** transparencies can have depth writing either enabled or disabled in a subtree, even if `TransparencyWritesDepth` is globally forced. For material transparency, the flag behaves inclusively, meaning if `TransparencyWritesDepth` is enabled with either override, globally forced or via the material's flags, depth writing will be enabled for objects rendered with this material.
+* **`TransparencyWritesDepth`**: Activates depth writing for **`See-through`** and material transparencies in the component's entity's scene-tree. Using this flag, **`See-through`** transparencies can have depth writing either enabled or disabled in a subtree, even if `TransparencyWritesDepth` is globally forced. For material transparency, the flag behaves inclusively, meaning if `TransparencyWritesDepth` is enabled with either override, globally forced or via the material's flags, depth writing is enabled for objects rendered with this material.
 
 * **`UseCutPlaneFilterMask`**: Use an individual filter bit mask to control the cut plane selection. This flag determines whether the individual filter mask should be used or inherited from its parent. The filter bit mask itself is set via the `CutPlaneFilterMask` property. For detailed information about how the filtering works, refer to the [Selective cut planes paragraph](cut-planes.md#selective-cut-planes). See the following example where only the tire and rim is cut while the rest of the scene remains unaffected.
 ![Selective cut planes](./media/selective-cut-planes-hierarchical-override.png)
 
+* **`UseOverrideMaterial`**: If enabled, the material stored in `OverrideMaterial` is used to render the geometry with that material. It's an efficient way to switch rendering of larger model parts to a dedicated material without actually switching individual part materials. [Color materials](color-materials.md) may override [PBR materials](pbr-materials.md) and vice versa. However, it must be guaranteed that the model provides mandatory vertex streams, for instance, the vertex normal in case the overridden material is a [PBR material](pbr-materials.md). Furthermore, overrides that toggle on transparency, only work reliably in the *TileBasedComposition* [rendering mode](../../concepts/rendering-modes.md).
+
+  > [!NOTE]
+  > The override material is ignored for point clouds.
+
 
 > [!TIP]
 > As an alternative to turning off the visibility and spatial queries for a full sub graph, the `enabled` state of a game object can be toggled. If a hierarchy is disabled, this has preference over any `HierarchicalStateOverrideComponent`.
@@ -111,7 +116,7 @@ component->SetState(
 
 ### Tint color
 
-The `tint color` override is slightly special in that there's both an on/off/inherit state and a tint color property. The alpha portion of the tint color defines the weight of the tinting effect: If set to 0.0, no tint color is visible and if set to 1.0 the object will be rendered with pure tint color. For in-between values, the final color will be mixed with the tint color. The tint color can be changed on a per-frame basis to achieve a color animation.
+The `tint color` override is slightly special in that there's both an on/off/inherit state and a tint color property. The alpha portion of the tint color defines the weight of the tinting effect: If set to 0.0, no tint color is visible and if set to 1.0 the object is rendered with pure tint color. For in-between values, the final color is mixed with the tint color. The tint color can be changed on a per-frame basis to achieve a color animation.
 
 ## Performance considerations