Apertura del repositorio

doc/testplans/RenderMaxTextureResolution.md

@@ -0,0 +1,16 @@
+The Setting RenderMaxTextureResolution controls the maximum resolution of non-boosted textures as displayed by the viewer.
+
+Valid values are 512-2048 (clamped in C++).
+
+![image](https://github.com/secondlife/viewer/assets/23218274/d0f889fc-8135-41d2-9d83-871ad4eebed5)
+
+![image](https://github.com/secondlife/viewer/assets/23218274/19950828-7eb1-4bb2-85d7-f35c63b34294)
+
+![image](https://github.com/secondlife/viewer/assets/23218274/249afc83-4de6-488d-a05e-4877d08573b1)
+
+Test Asset available on beta grid:
+Object: 'Damaged Helmet', AssetID 0623e759-11b5-746c-a75e-7ba1caa6eb0e
+
+
+
+

doc/testplans/hdri_local_preview.md

@@ -0,0 +1,21 @@
+A resident may swap out their sky for an EXR format HDRI for the purposes of previewing how their object would render in Second Life in an environment that matches the supplied HDRI.  This should aid in matching inworld lighting with external tools so artists can know if their content has imported properly.
+
+To load an HDRI, click Develop->Render Tests->HDRI Preview:
+
+![image](https://github.com/secondlife/viewer/assets/23218274/fbdeab5f-dc1f-4406-be19-0c9ee7437b3f)
+
+Choose an EXR image.  A library of publicly available HDRIs can be found here: https://polyhaven.com/hdris
+
+The Personal Lighting floater will open, and the sky will be replaced with the HDRI you chose.  Reflection Probes will reset, and the scene will be illuminated by the HDRI.
+
+Three debug settings affect how the HDRI is displayed:
+
+RenderHDRIExposure - Exposure adjustment of HDRI when previewing an HDRI.  Units are EV.  Sane values would be -10 to 10.
+RenderHDRIRotation - Rotation (in degrees) of environment when previewing an HDRI.
+RenderHDRISplitScreen - What percentage of screen to render using HDRI vs EEP sky.
+
+Exposure and Rotation should behave similarly to the rotation and exposure controls in Substance Painter.
+
+Split Screen can be used to display an EEP sky side-by-side with an HDRI sky to aid in authoring an EEP sky that matches an HDRI sky.  It is currently expected that EEP sun disc, moon, clouds, and stars do not render when previewing an HDRI, but that may change in the future.
+
+

doc/testplans/material_preview.md

@@ -0,0 +1,83 @@
+# Material Preview
+
+## Overview
+
+Material preview is a UI feature which displays a lit spherical preview of a PBR material. It can be found in the following UIs:
+
+- The material picker swatch
+    - In the build floater, in the Texture tab, when applying a PBR material
+    - (If the feature is enabled) In the Region/Estate floater, in the Terrain tab, when applying PBR materials to terrain
+- In the floater to select a material from inventory, which can be opened by clicking the material picker swatch
+
+## Known Issues
+
+These are known issues that the current implementation of this feature does not address:
+
+- The material preview in the build floater is a preview of the base material ID only, and ignores other properties on the prim face like material overrides (https://github.com/secondlife/viewer/issues/865)
+- Alpha mask previews as alpha blend (https://github.com/secondlife/viewer/issues/866)
+- Double-sided previews as single-sided (https://github.com/secondlife/viewer/issues/867)
+- Material preview inherits some of its lighting from the current environment, and reflections from the default reflection probe (https://github.com/secondlife/viewer/issues/868)
+
+## General Regression Testing
+
+- Check that the material preview swatch looks OK with different materials selected
+- Check that the material preview swatch runs reasonably well on different systems, especially when the select material from inventory floater is also open
+    - In particular: AMD, MacOS, minimum spec machines
+- Watch out for regressions in rendering caused by opening a floater with a material preview swatch
+
+## Bug Fixes
+
+### Disappearing Objects Fix Test
+
+This test is recommended for verifying that https://github.com/secondlife/viewer-issues/issues/72 is fixed.
+
+#### Symptoms
+
+When the bug occurs, one or more of following types of objects could randomly disappear in the world, permanently until relog:
+
+- Objects
+- Water level in current region
+- Adjacent region/void water
+
+Note: Disappearing objects in reflections have a different root cause and are not covered by the fix.
+
+#### Bug Reproduction Steps
+
+Verify the disappearing objects bug does not reproduce, given the following steps:
+
+- Runtime prerequisites: Material preview swatch may not be available in your viewer or region if this feature is still behind a feature flag. It is safe to enable this feature manually by setting, "UIPreviewMaterial" to True in the advanced settings. The setting will persist for the current session.
+- Region prerequisites: Unknown, but a region with lots of objects in it seems to increase repro rate. The following locations have been known to easily reproduce the bug, as of 2024-02-16:
+    - http://maps.secondlife.com/secondlife/LindenWorld%20B/161/75/47
+    - [secondlife://Aditi/secondlife/Rumpus%20Room%202048/128/128/24](secondlife://Aditi/secondlife/Rumpus%20Room%202048/128/128/24)
+- Right click an object and select, "Edit item"
+- Go to texture tab, select PBR Metallic Roughness from dropdown, and click the button to select material from inventory
+- Ensure "Apply now" is checked in the inventory selection floater
+- Alternate between different materials from the inventory selection floater
+- Look around the world and check for permanently disappeared objects.
+
+### Dynamic Exposure Influence Fix Test
+
+This test is recommended for verifying that https://github.com/secondlife/viewer-issues/issues/72 is fixed.
+
+#### Symptoms
+
+Dynamic exposure in the world could be influenced by the material preview being displayed. If a material preview was being generated in a given frame, then, depending on the current environment, the user would observe an unpleasant flashing effect in the environment:
+
+- The world view could suddenly get darker and then fade back to normal exposure levels
+- The world view could suddenly get brighter and then fade back to normal exposure levels
+
+#### Bug Reproduction Steps
+
+Verify the dynamic exposure influence bug does not reproduce. Test using a few environment presets such as Default Midday, Sunset, and Midnight.
+
+- Right click an object and select, "Edit item"
+- Go to texture tab, select PBR Metallic Roughness from dropdown, and click the button to select material from inventory
+- Alternate between different materials from the inventory selection floater
+
+#### Regression Testing
+
+Dynamic exposure in the world should continue to work correctly. In particular:
+
+- Exposure should fade gradually from high exposure to low exposure and back as needed
+- Exposure should decrease in brighter environments
+- Exposure should increase in darker environments

doc/testplans/optimize_away_alpha.md

@@ -0,0 +1,5 @@
+Textures imported via Build->Upload->Material that have an all opaque (255) alpha channel should have their alpha channel removed before upload.
+
+1. Make 4 images that have different colors but all 255 alpha channels
+2. Upload them all using Build->Upload->Material, with one in each of the material texture slots
+3. Verify that using the textures as a blinn-phong diffuse map does not make the corresponding face render in the alpha pass (face should stay visible after disabling alpha pass by unchecking Advanced->Render Types->Alpha).

doc/testplans/pbr_materials.md

@@ -0,0 +1,12 @@
+# PBR Materials
+
+## KHR Texture Transforms
+
+Texture repeats for PBR materials on prims are based on the [KHR\_texture\_transform](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_transform) spec, and thus should be expected to behave according to the spec. We currently suport offset, rotation, and scale from the spec. texCoord is not currently supported.
+
+PBR materials should have approximately correct lighting based on the normal texture:
+
+- With default texture transforms, assuming the prim or model has correct normals and tangents
+- With a texture transform applied, especially rotation or negative scale
+- With a texture animation applied via `llSetTextureAnim`, especially a rotation animation
+    - Note: Texture animations are not guaranteed to loop when a PBR texture transform is applied

doc/testplans/pbr_terrain_appearance.md

@@ -0,0 +1,63 @@
+# PBR Terrain Appearance
+
+## Tiling Without Texture Transforms
+
+This section assumes the PBR terrain of the current region and adjacent regions have the default texture transforms.
+
+The southwest corner of a region with PBR materials should exactly match up with the bottom left corner of the material texture(s).
+
+If two adjacent regions have the same PBR terrain settings, then there should not be seams between the two regions at their shared border.
+
+The ground should not suddenly slide beneath the avatar when moving between two PBR terrain regions (except due to movement of the avatar, which is not covered by this test plan)
+
+## Feature Gating
+
+PBR terrain should have lower detail on lower graphics settings. PBR terrain will also not show emissive textures on some machines (like Macs) which do not support more than 16 textures.
+
+### Triplanar Mapping
+
+Triplanar mapping improves the texture repeats on the sides of terrain slopes.
+
+Availability of Triplanar mapping:
+
+- Medium-High and below: No triplanar mapping
+- High and above: Triplanar mapping
+
+### PBR Textures
+
+At the highest graphics support level, PBR terrain supports all PBR textures.
+
+Availability of PBR textures varies by machine and graphics setting:
+
+- Low: Base color only (looks similar to texture terrain)
+- Medium-Low, and machines that do not support greater than 16 textures such as Macs: All PBR textures enabled except emissive textures.
+- Medium: All PBR textures enabled
+
+### PBR Alpha
+
+PBR terrain does not support materials with alpha blend or double-sided. In addition, the viewer does not make any guarantees about what will render behind the terrain if alpha is used.
+
+## PBR Terrain Texture Transforms
+
+Like PBR materials on prims, PBR terrain repeats are based on the [KHR\_texture\_transform](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_transform) spec, and thus should be expected to behave the same way. We currently suport offset, rotation, and scale from the spec. texCoord is not currently supported.
+
+The southwest corner of a region, at z=0, is the UV origin for all texture coordinates of the whole region. Unless an offset is also applied, scale and rotation of the terrain texture transforms are relative to that point.
+
+When an avatar faces north and looks down at flat ground, the textures of the materials should appear to face upright, unless a rotation is applied.
+
+If triplanar mapping is enabled, and an avatar faces an axially-aligned wall, the textures of the materials should appear to face upright, unless a rotation is applied.
+
+Textures of materials should not appear mirrored.
+
+When triplanar mapping is enabled, rotations on the axially aligned walls should apply in the same direction as they would on flat ground.
+
+## PBR Terrain Normal Textures
+
+This section assumes terrain normal maps are enabled at the current graphics setting.
+
+PBR terrain should have approximately correct lighting based on the normal texture:
+
+- When on flat ground
+- On cliffs, when triplanar mapping is enabled. Lighting will be somewhat less accurate when the cliff face is not axially aligned.
+- If no Terrain Texture Transform is applied.
+- If a Terrain Texture Transform is applied, especially for rotation or negative scale.

doc/testplans/pbr_terrain_composition.md

@@ -0,0 +1,106 @@
+# PBR Terrain Composition
+
+## Feature Availability
+
+PBR Terrain is visible for all viewers with the PBR Terrain feature, regardless of if the feature flag is enabled.
+
+There is only one set of four asset IDs applied to the terrain. In other words, unlike PBR materials on prims, there is no fallback texture set for viewers that do not support PBR terrain. Viewers without support will view terrain as blank (solid grey or white).
+
+## Editing Terrain Composition
+
+All tests in this section assume the PBR terrain feature flag is enabled, and that the user has appropriate permissions to modify the terrain textures.
+
+### Feature Availability
+
+These features are related to UI, where the Region/Estate floater is opened to the terrain Tab.
+
+#### Feature: PBR Terrain
+
+On the client, the advanced setting `RenderTerrainPBREnabled` is the PBR terrain feature flag.
+
+The PBR terrain feature flag should be set automatically when logging in/teleporting to a new region.
+
+- The flag should be enabled on regions where the PBR terrain feature is enabled
+- Otherwise the flag should be disabled
+
+When the PBR terrain feature flag is disabled:
+
+- The "PBR Metallic Roughness" checkbox should not be visible
+- The user should not be able to apply PBR terrain to the region, only textures.
+
+When the PBR terrain feature flag is enabled:
+
+- The "PBR Metallic Roughness" checkbox should be visible
+- The user should be able to apply PBR terrain or textures to the region, depending on if the "PBR Metallic Roughness" checkbox is checked.
+
+#### Feature: PBR Terrain Texture Transforms
+
+On the client, the advanced setting, `RenderTerrainPBRTransformsEnabled` is the PBR terrain texture transform flag. Generally, this feature should not be expected to work correctly unless the PBR terrain feature is also enabled.
+
+The PBR terrain texture transform flag should be set automatically when logging in/teleporting to a new region.
+
+- The flag should be enabled on regions where the PBR terrain texture transform feature is enabled
+- Otherwise the flag should be disabled
+
+When the PBR terrain texture transform feature is enabled, the UI of the Terrain tab should be overhauled. Availability of features depends on the type of terrain.
+
+**Known issue:** The Region/Estate floater may have to be closed/reopened a second time in order for the UI overhaul to take effect, after teleporting between regions that do and do not have the feature flag set.
+
+When "PBR Metallic Roughness" is checked:
+
+- There should be a way for the user to change the texture transforms for the terrain in the current region
+- For each of the four swatches, the user can change the scale, offset, and rotation of that swatch. Nonuniform scale is allowed
+
+When "PBR Metallic Roughness" is unchecked, the controls for texture transforms should be hidden.
+
+### Current Composition Type
+
+When the Region/Estate floater is opened to the terrain Tab, the current terrain should be shown in the four swatches, and the "PBR Metallic Roughness" checkbox should be checked or unchecked accordingly.
+
+- If it is texture terrain, the "PBR Metallic Roughness" checkbox should be unchecked, and the floater should display the four textures applied to the terrain.
+- If it is material terrain, the "PBR Metallic Roughness" checkbox should be checked, and the floater should display the four materials applied to the terrain.
+
+In addition, where possible, textual labels and descriptions in the tab should make sense given the current value of the "PBR Metallic Roughness" checkbox. If the checkbox is unchecked, the labels should refer to textures. If the checkbox is checked, the labels should refer to materials.
+
+### Toggling Composition Type
+
+When toggling the "PBR Metallic Roughness" checkbox to the opposite value, which does not correspond to the current terrain type, one of the following sets of four terrain swatches will be displayed:
+
+- The default textures/materials
+    - For textures, this is the default terrain texture set
+    - For materials, this is all blank materials, but this is subject to change
+- The previously applied texture/material set
+    - History is available on a best-effort basis only. In particular, the history does not persist on viewer restart.
+
+When toggling back the "PBR Metallic Roughness" checkbox to the original value, assuming nothing else has changed, then the current terrain should be shown in the four swatches again.
+
+### Saving Composition
+
+A user with appropriate permissions can change and save the textures or materials to the terrain. If the "PBR Metallic Roughness" checkbox is checked, the user applies materials, otherwise the user applies textures.
+
+The user should not be allowed to set the texture or material swatches to null.
+
+Saving may fail for the following reasons:
+
+- A terrain or material texture is invalid
+- A terrain texture is greater than the max texture upload resolution
+
+If saving the terrain fails for any reason, the terrain should not be updated.
+
+Unlike a viewer without PBR terrain support, the new viewer will no longer treat textures with alpha channels as invalid.
+
+### Saving PBR Terrain Texture Transforms
+
+If "PBR Metallic Roughness" checkbox is checked, a user with saving composition permissions should also be allowed to edit and save PBR texture transforms.
+
+One texture transform may be set for each material swatch. Setting texture transforms for each individual texture on the material is not currently supported.
+
+## Graphics Features
+
+Texture terrain with transparency is not permitted to be applied in the viewer.
+
+See [PBR Terrain Appearance](./pbr_terrain_appearance.md) for supported PBR terrain features.
+
+## Minimap
+
+The minimap should display the terrain with appropriate textures and colors.

doc/testplans/pbr_terrain_paintmap.md

@@ -0,0 +1,48 @@
+# PBR Terrain Paintmap
+
+## Introduction/Disclaimer
+
+As of 2024-08-06, PBR terrain painting is **WIP**. Currently, there is only a client-side terrain paintmap, with no way to directly edit it. This document will explain how to informally explore this feature and compare it to the existing heightmap with noise. In the future, a testing document will be added for PBR terrain painting.
+
+## Background
+
+Historically, PBR terrain in a region has several parameters for controlling its composition. These are:
+
+- The four materials
+- The elevation of the terrain, which roughly controls the material, with some noise added on top ("heightmap with noise")
+- Material Elevation Ranges, which control where the materials start and end
+
+This allows for some coarse control over terrain composition. For example, you can have one corner of the terrain be a sandy beach and the rest of the coastline be rocky. Or you can have the peaks of your mountains be covered with snow. However, artistic control is limited due to the gradient imposed by the material elevation ranges, and the unpredictability of the noise.
+
+A terrain painting option would allow for more control over the terrain composition. The first step to getting that working is the paintmap.
+
+## How to activate the local paintmap
+
+The local paintmap is a good way to assess the quality of the PBR terrain paintmap. By default, the newly created local paintmap inherits its composition (i.e. where the grass and dirt goes) from the existing terrain. This allows for a direct comparison with the terrain heightmap-with-noise shader.
+
+Activating the local paintmap is similar to [applying local PBR terrain via the debug settings](https://wiki.secondlife.com/wiki/PBR_Terrain#How_to_apply_PBR_Terrain), but with a couple extra steps.
+
+You will need:
+
+- Four fullperm PBR material items to copy UUIDs from
+- A region with a good variation of elevations which showcase the four composition layers (no special permissions needed)
+
+Open the Debug Settings menu (Advanced > Show Debug Settings) and search for "terrain". The following relevant options are available:
+
+- LocalTerrainAsset1
+- LocalTerrainAsset1
+- LocalTerrainAsset3
+- LocalTerrainAsset4
+- LocalTerrainPaintEnabled
+- TerrainPaintBitDepth
+- TerrainPaintResolution
+
+By setting LocalTerrainAsset1, etc to valid material IDs, you will override the terrain to use those materials.
+
+The next step is to "bake" the terrain into a paintmap (Develop > Terrain > Create Local Paintmap). This will *automatically* set LocalTerrainPaintEnabled to true. **WARNING:** LocalTerrainPaintEnabled will *not* do anything until one of LocalTerrainAsset1, etc is set.
+
+You are now looking at the same terrain, but rendered as a paintmap.
+
+To compare the quality of the paintmap version and the heightmap-with-noise version, toggle LocalTerrainPaintEnabled in Debug Settings.
+
+To change the bit depth and/or resolution of the paintmap, change TerrainPaintBitDepth and TerrainPaintResolution as desired, then "re-bake" the paintmap (Develop > Terrain > Create Local Paintmap).

doc/testplans/terrain_loading.md

@@ -0,0 +1,29 @@
+# Terrain Loading
+
+## Behavior overview
+
+- Texture terrain should load if textures are applied to the region, and no PBR Metallic Roughness materials are applied.
+- PBR terrain should load if PBR materials are applied to the region, even if the RenderTerrainPBREnabled feature flag is disabled in debug settings. This setting only disables the display of PBR materials in the Region / Estate > Terrain UI.
+- Related subsystem: A change to the PBR terrain loading system may affect the texture terrain loading system and vice-versa
+- Related subsystem: Minimap should load if terrain loads
+    - They may not finish loading at the same time
+
+## Implementation details
+
+This section is provided mainly for clarification of how the terrain loading system works.
+
+The simulator sends 4 terrain composition UUIDs to the viewer for the region. The viewer does not know ahead-of-time if the terrain composition uses textures or materials. Therefore, to expedite terrain loading, the viewer makes up to 8 "top-level" asset requests simultaneously:
+
+- Up to 4 texture asset requests, one for each UUID
+- Up to 4 material asset requests, one for each UUID
+
+It is therefore expected that half of these asset lookups will fail.
+
+The viewer inspects the load success of these top-level assets to make the binary decision of whether to render all 4 texture assets or all 4 material assets. This determines the choice of composition for terrain both in-world and on the minimap.
+
+The minimap also attempts to wait for textures to partially load before it can render a tile for a given region:
+
+- When rendering texture terrain, the minimap attempts to wait for top-level texture assets to partially load
+- When rendering PBR material terrain, the minimap attempts to wait for any base color/emissive textures in the materials to partially load, if they are present
+
+We don't make guarantees that the minimap tile will render for the region if any aforementioned required textures/materials fail to sufficiently load. However, the minimap may make a best-effort attempt to render the region by ignoring or replacing data.