diff --git a/README.md b/README.md index f7b3ca0..f512055 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # OrthoStreamXP +![OrthoStreamXP: free, open-source photo scenery for X-Plane 12, streamed as you fly](docs/images/banner.jpg) + **Fly over real-world aerial imagery in X-Plane 12 — without downloading entire regions in advance.** OrthoStreamXP streams photo scenery as you fly, loading the areas around your aircraft first and keeping downloaded imagery ready for your next flight. @@ -79,12 +81,13 @@ The installer is not currently code-signed, so Windows may display a warning tha ## Choose your scenery quality -OrthoStreamXP provides four presets: +OrthoStreamXP provides five presets: - **Balanced** — prioritises a balance between visual detail and resource use. - **Sharp** — the recommended starting point for most systems. - **Ultra** — for systems with more graphics memory available. - **Extra** — the highest preset, intended for systems with greater resources. +- **Dynamic** — Extra near the ground, Sharp from 5,000 ft and Balanced from 25,000 ft above it. High up, X-Plane still asks for full detail it cannot show, so Dynamic saves about half the downloads in a climb and cruise. On a descent it returns to full detail early, before the ground comes close. You can change presets in Settings. OrthoStreamXP also reports graphics memory usage from your flights and warns when the measured scenery requirements exceed your card's available memory. diff --git a/docs/OrthoStreamXP-UserGuide.pdf b/docs/OrthoStreamXP-UserGuide.pdf index 8bc941a..e83e8a6 100644 Binary files a/docs/OrthoStreamXP-UserGuide.pdf and b/docs/OrthoStreamXP-UserGuide.pdf differ diff --git a/docs/first-setup.md b/docs/first-setup.md index 03cdb4d..99bf2a1 100644 --- a/docs/first-setup.md +++ b/docs/first-setup.md @@ -78,7 +78,7 @@ This is where OrthoStreamXP keeps the pictures it downloads and the textures it ![Setup step 5: Quality](images/setup-quality.png) -Pick how sharp the ground should be: **Balanced**, **Sharp**, **Ultra** or **Extra**. Each card shows the texture size, the imagery zoom level, the metres per pixel, and roughly how long a new area takes to load. See [Settings › Quality](settings.md#quality) for a comparison. +Pick how sharp the ground should be: **Balanced**, **Sharp**, **Ultra**, **Extra** or **Dynamic** (Extra near the ground, less detail high up, where it cannot be seen). Each card shows the texture size, the imagery zoom level, the metres per pixel, and roughly how long a new area takes to load. See [Settings › Quality](settings.md#quality) for a comparison. **Not sure?** Click **Test my connection** (it says **Test again** if you have tested before). OrthoStreamXP downloads real pictures for about 30 seconds, then: diff --git a/docs/flying.md b/docs/flying.md index b25aaf5..c939d59 100644 --- a/docs/flying.md +++ b/docs/flying.md @@ -15,6 +15,8 @@ The Home page has two ways to start: Turn on **Start when OrthoStreamXP opens** if you want the scenery to start every time you open the app. +When **Start and fly** starts X-Plane, OrthoStreamXP waits until X-Plane's window is in front, then moves out of its way to the notification area next to the clock. Click its icon to open the window again, or right-click it for **Open OrthoStreamXP** and **Exit**. When X-Plane quits, the window comes back on the Home page, ready to stop the scenery and show your flight report. If you start X-Plane yourself, the window stays where it is. + If X-Plane was already running when you started OrthoStreamXP, Home shows **Restart X-Plane**. Quit X-Plane and start it again to see the photos. ## The Home page @@ -25,7 +27,8 @@ Before your first start, Home shows **How it works**: start OrthoStreamXP, start From top to bottom: -- **Status card.** Shows whether OrthoStreamXP is stopped, starting, ready (*Photo scenery is ready*) or in use (*Flying with photo scenery*). The **Start** button becomes **Stop** while it runs. The dot at the bottom of the sidebar shows the same state on every page. +- **Check for updates.** Looks for a new version straight away (see [Troubleshooting › Updates](troubleshooting.md#updates)). +- **Status card.** Shows whether OrthoStreamXP is stopped, starting, ready (*Photo scenery is ready*) or in use (*Flying with photo scenery*). The **Start** button becomes **Stop** while it runs. The dot at the bottom of the sidebar shows the same state on every page. Above it, the theme button switches the window between the Windows theme, light and dark. - **Notices.** Tuning suggestions, updates and problems appear here, each with a button for the next step. - **Last flight.** A report on your most recent flight, shown while OrthoStreamXP is stopped (see below). - **Session figures** (*This session* while it runs, *Last session* after it stops): how many textures X-Plane got, how many of its reads got the real picture, how many textures are being built now, and the download speed or the number of picture tiles downloaded. diff --git a/docs/images/about.png b/docs/images/about.png index 1535697..ebc551a 100644 Binary files a/docs/images/about.png and b/docs/images/about.png differ diff --git a/docs/images/banner.jpg b/docs/images/banner.jpg new file mode 100644 index 0000000..eaec3ac Binary files /dev/null and b/docs/images/banner.jpg differ diff --git a/docs/images/cache-quality.png b/docs/images/cache-quality.png index f7c1ac1..e4db934 100644 Binary files a/docs/images/cache-quality.png and b/docs/images/cache-quality.png differ diff --git a/docs/images/cache.png b/docs/images/cache.png index 8319576..2dcd2e8 100644 Binary files a/docs/images/cache.png and b/docs/images/cache.png differ diff --git a/docs/images/home.png b/docs/images/home.png index cb3b39e..2a6d4f8 100644 Binary files a/docs/images/home.png and b/docs/images/home.png differ diff --git a/docs/images/packages.png b/docs/images/packages.png index 3146651..ee4fd9a 100644 Binary files a/docs/images/packages.png and b/docs/images/packages.png differ diff --git a/docs/images/settings-colours.png b/docs/images/settings-colours.png index 1f7d451..574c2f0 100644 Binary files a/docs/images/settings-colours.png and b/docs/images/settings-colours.png differ diff --git a/docs/images/settings-download.png b/docs/images/settings-download.png index 401ce97..c37037e 100644 Binary files a/docs/images/settings-download.png and b/docs/images/settings-download.png differ diff --git a/docs/images/settings-folders.png b/docs/images/settings-folders.png index 9045293..cef76d6 100644 Binary files a/docs/images/settings-folders.png and b/docs/images/settings-folders.png differ diff --git a/docs/images/settings-night.png b/docs/images/settings-night.png index d105004..379fa3f 100644 Binary files a/docs/images/settings-night.png and b/docs/images/settings-night.png differ diff --git a/docs/images/settings-other.png b/docs/images/settings-other.png index 9adb40e..32b7344 100644 Binary files a/docs/images/settings-other.png and b/docs/images/settings-other.png differ diff --git a/docs/images/settings-quality.png b/docs/images/settings-quality.png index 1e863bc..e12aee1 100644 Binary files a/docs/images/settings-quality.png and b/docs/images/settings-quality.png differ diff --git a/docs/images/settings-tuning.png b/docs/images/settings-tuning.png index 6194430..e32311d 100644 Binary files a/docs/images/settings-tuning.png and b/docs/images/settings-tuning.png differ diff --git a/docs/images/setup-cache.png b/docs/images/setup-cache.png index 41356cd..664e955 100644 Binary files a/docs/images/setup-cache.png and b/docs/images/setup-cache.png differ diff --git a/docs/images/setup-quality.png b/docs/images/setup-quality.png index 8e5b724..c4290cc 100644 Binary files a/docs/images/setup-quality.png and b/docs/images/setup-quality.png differ diff --git a/docs/images/setup-ready.png b/docs/images/setup-ready.png index 8f91296..f2a316e 100644 Binary files a/docs/images/setup-ready.png and b/docs/images/setup-ready.png differ diff --git a/docs/images/setup-scenery.png b/docs/images/setup-scenery.png index 5f91814..57157bb 100644 Binary files a/docs/images/setup-scenery.png and b/docs/images/setup-scenery.png differ diff --git a/docs/images/setup-welcome.png b/docs/images/setup-welcome.png index 563dbd4..2a00344 100644 Binary files a/docs/images/setup-welcome.png and b/docs/images/setup-welcome.png differ diff --git a/docs/images/setup-xplane.png b/docs/images/setup-xplane.png index 7420938..5fb8b04 100644 Binary files a/docs/images/setup-xplane.png and b/docs/images/setup-xplane.png differ diff --git a/docs/settings.md b/docs/settings.md index 6674496..750f774 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -23,9 +23,24 @@ Choose how sharp the ground is. Each preset comes with settings tested for it an | **Sharp** | 2048 px | 16, 17 near airports | ~3.4 m per pixel | Everyday flying, approaches included | | **Ultra** | 4096 px | 17, 18 near airports | ~1.7 m per pixel | Low flight and GA, with plenty of graphics memory | | **Extra** | 4096 px | 17, 19 near airports | ~1.7 m per pixel | Low and slow flight and screenshots, on a fast connection | +| **Dynamic** | Extra's near the ground, less higher up | as Extra below 5,000 ft | follows the height | Climbs, cruise and approaches in one flight, on a fast connection | **Extra** is Ultra with the finest imagery (zoom 19) near airports, which often avoids clouds and other artefacts. Elsewhere it is the same as Ultra. Near airports it downloads four times as much as Ultra, and a new area takes a little longer to load: about 4 minutes, then sharp next to the aircraft. +### Dynamic + +**Dynamic** makes the detail follow your height above the ground: + +- **Below 5,000 ft** it is Extra. +- **From 5,000 ft** the photos are downloaded at Sharp's detail. +- **From 25,000 ft** they are downloaded at Balanced's detail. + +High up, X-Plane still asks for the photos in full detail, though from there the detail cannot be seen. Dynamic downloads about half as much in a climb and cruise, which suits airliners and other high flying. + +On a descent, Dynamic looks four minutes ahead and goes back to full detail early, so the ground is sharp again before you come close to it. X-Plane does not load a photo again just because you came lower: one it loaded with less detail high up stays that way while X-Plane keeps it. That is why the switch back comes early. + +Dynamic shares Extra's textures in the cache, so you can switch between the two without downloading anything again, and photos already in the cache are shown as they are at any height. It needs X-Plane to send the aircraft's position, which it does on the same PC by itself. The heights can be changed in the settings file (**Show the file**): `dynamic-sharp-above` and `dynamic-balanced-above`, in feet. + Each card shows the imagery zoom, the metres per pixel, roughly how long a new area takes to load, and how much graphics memory the photo textures take. Until you have flown, that memory figure comes from a test flight; after your first long flight, it is measured on your PC. - The **Recommended** badge marks the preset that suits your connection and graphics card, with the reason below it. @@ -57,6 +72,7 @@ Your scenery packages are not changed: OrthoStreamXP adjusts the terrain files a - **Where the pictures come from:** the imagery source. - *Bing, then Esri where Bing has no picture* (recommended): the sharpest pictures in most places. + - *Esri (ArcGIS), then Bing where Esri has no picture*: in some regions Esri's photos are newer or clearer than Bing's. - *Bing only*. - *Geoportal in Poland (national orthophoto), Bing and Esri elsewhere*. - **Downloads at once:** how many pictures download in parallel, from 16 to 256. Your internet connection sets the real speed; beyond about 160, more downloads only wait longer. Lower this if other programs need the connection while you fly. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6a9785a..10805d8 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -38,7 +38,7 @@ The About page shows your version, whether WinFsp is installed (with a **Get Win ## Updates -OrthoStreamXP checks for updates when it opens and from time to time while it runs, and downloads a new version in the background. When the update is ready, Home shows **OrthoStreamXP x.y.z is ready to install**. If the scenery is streaming, finish your flight and stop it first; then click **Update and restart**. Your settings, cache and flight history stay. +OrthoStreamXP checks for updates when it opens and from time to time while it runs, and downloads a new version in the background. To look straight away, click **Check for updates** at the top of the Home page; if there is nothing new, OrthoStreamXP tells you that you already have the newest version, or why it could not look. When the update is ready, Home shows **OrthoStreamXP x.y.z is ready to install** at the top of the page, above the status card. If the scenery is streaming, finish your flight and stop it first; then click **Update and restart**. Your settings, cache and flight history stay. ## Uninstalling diff --git a/release-notes/v1.4.0.md b/release-notes/v1.4.0.md new file mode 100644 index 0000000..f52b230 --- /dev/null +++ b/release-notes/v1.4.0.md @@ -0,0 +1,18 @@ +## What's new + +- **Dynamic quality.** A new preset in **Settings** (and in the setup): **Dynamic**. Near the ground it is the same as Extra. From 5,000 ft above the ground it downloads the photos at Sharp's detail, and from 25,000 ft at Balanced's. High up, X-Plane still asks for full-detail photos even though you cannot see that detail from there, so Dynamic downloads about half as much in the climb and the cruise. When you descend, it goes back to full detail early, so the ground is sharp again before you get close to it. + +## Why it matters on a jet flight + +Picture a short airliner hop. You take off, and in about twenty minutes you are at 35,000 ft. You stay up there for most of the flight, with the ground almost seven miles below you, and the descent and approach take the last half hour or so. In a jet, most of the flight is spent high above the ground. + +Up there you see whole valleys and coastlines, but not single houses or field edges. X-Plane still asks for the photos at the same full detail it would want at 1,000 ft. Until now OrthoStreamXP did exactly that, so most of what it downloaded in the cruise was detail no one could see. It used your connection and processor and filled the cache, and it could hold up the photos you actually look at. + +With Dynamic, the photos follow your height. In the climb and cruise they come at Sharp's and then Balanced's detail, which still looks good from that high, and the downloads drop by about half. Once you start down, Dynamic looks a few minutes ahead and goes back to full detail early, so the approach, the runway and the area around the airport are as sharp as with Extra. You get the same view from your seat, with much less downloading in the middle of the flight. + +## Good to know + +- Your preset is not changed by the update. To try Dynamic, choose it in **Settings** while OrthoStreamXP is stopped. It applies from the next start. +- Dynamic uses the same cache as Extra, so photos you already downloaded with Extra are still used, and switching between the two downloads nothing again. +- Photos that are already in the cache are shown as they are, at any height. Dynamic only changes what is downloaded new. +- A photo X-Plane loaded at lower detail high up stays that way until X-Plane loads it again. This is why Dynamic goes back to full detail well before the ground comes close on a descent. diff --git a/src/OrthoStreamXP/Configuration/MountSettings.cs b/src/OrthoStreamXP/Configuration/MountSettings.cs index 5e09105..80c63c8 100644 --- a/src/OrthoStreamXP/Configuration/MountSettings.cs +++ b/src/OrthoStreamXP/Configuration/MountSettings.cs @@ -48,6 +48,8 @@ internal sealed record MountSettings public bool SkipPhotosAtNight { get; init; } /// How far below the horizon, in degrees, the sun must be before the photos are skipped (0-18). public double SkipPhotosSunBelow { get; init; } = -Scenery.Daylight.DefaultDarkBelow; + /// Dynamic quality: the photos' detail follows the height above the ground; null when it is off. + public Scenery.DynamicOptions? Dynamic { get; init; } /// A texture-quality value from an older settings file: no longer used, noted in the log. public string? IgnoredTextureQuality { get; init; } /// Photo textures are served level by level as X-Plane reads them (off: built whole first). @@ -153,6 +155,7 @@ public static MountSettings FromValues(SettingValues values, bool console = true bool skipPhotosAtNight = ParseOnOff(skipValue) ?? throw new SettingsException($"skip-photos-at-night must be on or off, not '{skipValue}'"); double skipSunBelow = values.Double("skip-photos-sun-below", -Scenery.Daylight.DefaultDarkBelow); if (skipSunBelow is < 0 or > 18) throw new SettingsException("skip-photos-sun-below must be between 0 and 18 degrees"); + Scenery.DynamicOptions? dynamic = ParseDynamic(values); if (downloadWorkers < 1) throw new SettingsException("download-workers must be at least 1"); if (downloadTimeout is < 1 or > 120) throw new SettingsException("download-timeout must be between 1 and 120 seconds"); @@ -208,6 +211,7 @@ public static MountSettings FromValues(SettingValues values, bool console = true NightLights = nightLights, SkipPhotosAtNight = skipPhotosAtNight, SkipPhotosSunBelow = skipSunBelow, + Dynamic = dynamic, IgnoredTextureQuality = values.String("texture-quality"), MipStreaming = mipStreaming, NearWait = nearWait, @@ -309,6 +313,21 @@ internal static SeasonOptions ParseSeasons(SettingValues values) return new SeasonOptions(on, strength / 100, choice); } + /// Dynamic quality's steps, or null when it is off. + private static Scenery.DynamicOptions? ParseDynamic(SettingValues values) + { + string onValue = values.String("dynamic-quality") ?? "off"; + bool on = ParseOnOff(onValue) ?? throw new SettingsException($"dynamic-quality must be on or off, not '{onValue}'"); + double sharp = values.Double("dynamic-sharp-above", Scenery.DynamicOptions.DefaultSharpAboveFt); + if (sharp is < 1000 or > 40_000) throw new SettingsException("dynamic-sharp-above must be between 1000 and 40000 feet"); + double? balanced = values.String("dynamic-balanced-above") is { } text && ParseOnOff(text) == false + ? null + : values.Double("dynamic-balanced-above", Scenery.DynamicOptions.DefaultBalancedAboveFt); + if (balanced is < 1000 or > 60_000) throw new SettingsException("dynamic-balanced-above must be between 1000 and 60000 feet, or off"); + if (balanced <= sharp) throw new SettingsException("dynamic-balanced-above must be higher than dynamic-sharp-above (or off)"); + return on ? new Scenery.DynamicOptions(sharp, balanced) : null; + } + internal static bool? ParseOnOff(string value) => value.ToLowerInvariant() switch { "on" or "true" or "yes" => true, diff --git a/src/OrthoStreamXP/Configuration/SettingsOptions.cs b/src/OrthoStreamXP/Configuration/SettingsOptions.cs index 5c2973f..ab1c77b 100644 --- a/src/OrthoStreamXP/Configuration/SettingsOptions.cs +++ b/src/OrthoStreamXP/Configuration/SettingsOptions.cs @@ -33,7 +33,10 @@ internal static class SettingsOptions .Add("night-lights", "on or off: light the towns on the photo scenery at night. X-Plane's own scenery glows where it is a town; photo tiles are dark but for X-Plane's roads and buildings. With this on, each photo tile gets a night texture of street lamps, their glow and lit windows along X-Plane's roads (read from the overlay packages), which X-Plane fades in at dusk. Each is painted the first time X-Plane loads it and kept in the cache. The packages' files are not changed. Takes effect at the next start (default: off)") .Add("skip-photos-at-night", "on or off: at night in X-Plane (the sun lower than skip-photos-sun-below) download no detailed photos: the ground under the night lights is drawn from the low-zoom base, blurry, and what is already in the cache is shown as it is. In twilight, and before X-Plane sends where the sun is, the photos stream as usual. Saves downloads and processor time on night flights; needs mip-streaming. Takes effect at the next start (default: off)") .Add("skip-photos-sun-below", "Degrees, 0-18: how far below the horizon the sun in X-Plane must be before skip-photos-at-night skips the photos. 6 is the end of civil twilight, when the sky turns dark; 12 the end of nautical twilight, when the horizon fades; 18 full night. Lower skips more of the twilight; higher keeps the photos while the sky still lights the ground, and brings them back sooner at dawn. Takes effect at the next start (default: 9)") - .Add("lazy-terrain-listing", "Show an empty terrain directory listing; DSF-referenced .ter files remain directly accessible", arity: 0) + .Add("dynamic-quality", "on or off: Dynamic quality, the photos' detail follows the height above the ground. X-Plane wants nearly the same full-detail textures at 10,000 ft as at 1,000 ft, though from up there the detail cannot be seen; with this on, above dynamic-sharp-above the photos are fetched no sharper than Sharp's (2048 px), and above dynamic-balanced-above no sharper than Balanced's (1024 px). What is already in the cache is shown as it is. In a descent the height four minutes ahead counts, so the photos are sharp again before the ground comes close. Saves about half of the downloads in a climb and cruise; needs mip-streaming and track-aircraft. The Dynamic preset sets it with Extra's values. Takes effect at the next start (default: off)") + .Add("dynamic-sharp-above", $"Feet above the ground, 1000-40000: from this height Dynamic quality fetches the photos no sharper than Sharp's; they are sharp again 500 ft below it (default: {Scenery.DynamicOptions.DefaultSharpAboveFt:0})") + .Add("dynamic-balanced-above", $"Feet above the ground, 1000-60000, or off: from this height Dynamic quality fetches the photos no sharper than Balanced's; it must be higher than dynamic-sharp-above (default: {Scenery.DynamicOptions.DefaultBalancedAboveFt:0})") + .Add("lazy-terrain-listing","Show an empty terrain directory listing; DSF-referenced .ter files remain directly accessible", arity: 0) .Add("prefetch-loaded-scenery", "on or off: build the textures of each DSF X-Plane loads as soon as it opens the DSF's terrain definitions, before X-Plane asks for them one by one (default: on)") .Add("track-aircraft", "Follow the aircraft through X-Plane's UDP DATA output (row 20) and build the loaded scenery's textures ahead of it", arity: 0) .Add("xplane-address", "Where X-Plane listens for UDP requests; the aircraft position is requested from it, so nothing has to be set up in X-Plane (default: 127.0.0.1:49000)") @@ -59,5 +62,5 @@ internal static class SettingsOptions .Add("season", "auto (X-Plane's date and the place), or a season for everywhere: early-spring, spring, summer, early-autumn, autumn, late-autumn, winter (default: auto)") .Add("exposure", $"How much light the photo textures let through, {Exposure.Min}-{Exposure.Full} percent: less darkens them evenly, as a camera's exposure, where they look brighter than X-Plane's own scenery. The cache keeps the imagery as downloaded (default: {Exposure.Full})") .Add("season-land-cover", "No longer used: the seasons go by the colours alone (accepted so older settings files still load)") - .Add("read-log", @"on or off: log every open and read X-Plane makes through the mount, and the camera position, as CSV files in the logs folder (reads-*.csv, camera-*.csv), for finding a problem; the flight tuning measures the paging model without them (default: off)"); + .Add("read-log", @"on or off: log every open and read X-Plane makes through the mount, the camera position and every streamed build with what it downloaded, as CSV files in the logs folder (reads-*.csv, camera-*.csv, builds-*.csv), for finding a problem; the flight tuning measures the paging model without them (default: off)"); } diff --git a/src/OrthoStreamXP/Gui/Settings/PresetOption.cs b/src/OrthoStreamXP/Gui/Settings/PresetOption.cs index d737d7b..a03b0e1 100644 --- a/src/OrthoStreamXP/Gui/Settings/PresetOption.cs +++ b/src/OrthoStreamXP/Gui/Settings/PresetOption.cs @@ -20,8 +20,9 @@ internal sealed class PresetOption(QualityPreset preset, Action c /// Why it is recommended, under its badge. public string? RecommendedReason => IsRecommended ? PresetMemory.Recommended.Reason : null; - public string Details => - $"Zoom {Preset.Zl16Zoom} in most areas, {Preset.Zl18Zoom} near airports · about {Preset.MetresPerPixel:0.#} m per pixel · a new area loads in {Preset.FirstVisit}"; + public string Details => Preset == QualityPreset.Dynamic + ? $"Below 5,000 ft as Extra: zoom {Preset.Zl16Zoom} in most areas, {Preset.Zl18Zoom} near airports · higher up as Sharp, then Balanced · sharp again before a descent reaches the ground · a new area loads in {Preset.FirstVisit}" + : $"Zoom {Preset.Zl16Zoom} in most areas, {Preset.Zl18Zoom} near airports · about {Preset.MetresPerPixel:0.#} m per pixel · a new area loads in {Preset.FirstVisit}"; public string BestFor => $"Best for: {Preset.BestFor}"; diff --git a/src/OrthoStreamXP/Gui/Settings/SettingNames.cs b/src/OrthoStreamXP/Gui/Settings/SettingNames.cs index db47421..56e1521 100644 --- a/src/OrthoStreamXP/Gui/Settings/SettingNames.cs +++ b/src/OrthoStreamXP/Gui/Settings/SettingNames.cs @@ -6,6 +6,9 @@ internal static class SettingNames private static readonly Dictionary Names = new(StringComparer.Ordinal) { ["level-change"] = "Quality", + ["dynamic-quality"] = "Quality", + ["dynamic-sharp-above"] = "Quality", + ["dynamic-balanced-above"] = "Quality", ["ground-detail"] = "Ground detail", ["xplane"] = "X-Plane folder", ["base-packages"] = "Scenery packages folder", diff --git a/src/OrthoStreamXP/Gui/ViewModels/HomeViewModel.cs b/src/OrthoStreamXP/Gui/ViewModels/HomeViewModel.cs index 2641cbd..6b0eb2c 100644 --- a/src/OrthoStreamXP/Gui/ViewModels/HomeViewModel.cs +++ b/src/OrthoStreamXP/Gui/ViewModels/HomeViewModel.cs @@ -391,12 +391,12 @@ private void LoadSettingsSummary() { SettingsDocument settings = SettingsDocument.Load(SettingsDocument.DefaultPath); int? level = settings.GetInt("level-change"); - QualityPreset? preset = QualityPreset.ForLevel(level ?? 0); + QualityPreset? preset = QualityPreset.Current(level ?? 0, settings.GetBool(QualityPreset.DynamicQualityKey) == true); QualityTitle = preset?.Name ?? $"Custom (level {level ?? 0})"; var plan = new TexturePlan(level ?? 0); string zooms = $"{plan.SizeFor(16)} px textures from zoom {plan.FetchZoom(16)} in most areas and zoom {plan.FetchZoom(18)} near airports"; - QualityText = preset is null - ? $"{zooms}." + QualityText = preset is null ? $"{zooms}." + : preset == QualityPreset.Dynamic ? $"Near the ground {zooms}; higher up as Sharp, then Balanced. A new area loads in {preset.FirstVisit}." : $"{zooms}, about {preset.MetresPerPixel:0.#} m per pixel. A new area loads in {preset.FirstVisit}."; if (Mount.Running is { } running) diff --git a/src/OrthoStreamXP/Gui/ViewModels/SettingsViewModel.cs b/src/OrthoStreamXP/Gui/ViewModels/SettingsViewModel.cs index 684244f..0e96a37 100644 --- a/src/OrthoStreamXP/Gui/ViewModels/SettingsViewModel.cs +++ b/src/OrthoStreamXP/Gui/ViewModels/SettingsViewModel.cs @@ -24,7 +24,7 @@ internal sealed class SettingsViewModel : ObservableObject, IPage public SettingsViewModel(MainViewModel main) { _main = main; - Presets = [.. QualityPreset.All.Select(p => new PresetOption(p, ChoosePreset))]; + Presets = [.. QualityPreset.Choices.Select(p => new PresetOption(p, ChoosePreset))]; Providers = [ new Choice("Bing, then Esri where Bing has no picture (recommended)", "bing,esri"), @@ -131,7 +131,8 @@ public int Tab private int _tab; /// The preset the settings are at, or null for a level set by hand. - private QualityPreset? CurrentPreset => QualityPreset.ForLevel(_document.GetInt("level-change") ?? 0); + private QualityPreset? CurrentPreset => + QualityPreset.Current(_document.GetInt("level-change") ?? 0, _document.GetBool(QualityPreset.DynamicQualityKey) == true); /// What the flight tuning changed from the preset's own values. public IReadOnlyList TunedRows => CurrentPreset is { } preset @@ -500,7 +501,8 @@ public void Reload() CacheFolder = _document.Get("cache") ?? ""; _loading = false; int level = _document.GetInt("level-change") ?? 0; - foreach (PresetOption option in Presets) option.Show(option.Preset.Level == level); + QualityPreset? current = CurrentPreset; + foreach (PresetOption option in Presets) option.Show(option.Preset == current); CustomLevelNote = QualityPreset.ForLevel(level) is null ? $"Your settings file uses level-change {level}, which is not one of these. Choosing one replaces it." : null; diff --git a/src/OrthoStreamXP/Gui/ViewModels/SetupViewModel.cs b/src/OrthoStreamXP/Gui/ViewModels/SetupViewModel.cs index cabd626..e1f5acb 100644 --- a/src/OrthoStreamXP/Gui/ViewModels/SetupViewModel.cs +++ b/src/OrthoStreamXP/Gui/ViewModels/SetupViewModel.cs @@ -60,7 +60,7 @@ public SetupViewModel(MainViewModel main) XPlaneOptions = [.. SystemCheck.FindXPlaneFolders().Select(f => new FolderOption(f, "X-Plane found here", ChooseXPlane))]; // Which packages to use is the person's own choice: nothing is searched for, only the folder chosen before is offered. PackageOptions = []; - Presets = [.. QualityPreset.All.Select(p => new PresetOption(p, preset => Preset = preset))]; + Presets = [.. QualityPreset.Choices.Select(p => new PresetOption(p, preset => Preset = preset))]; // Re-running the setup starts from the current settings; a first setup suggests the cache beside the packages. _cacheChosen = existing.Get("cache") is not null; _cache = existing.Get("cache") ?? SystemCheck.SuggestedCacheFolder(null); @@ -69,7 +69,8 @@ public SetupViewModel(MainViewModel main) PresetMemory.Load(existing.Get("cache")); foreach (PresetOption option in Presets) option.RefreshMemory(); QualityPreset recommended = PresetMemory.Recommended.Preset; - Preset = QualityPreset.ForLevel(existing.GetInt("level-change") ?? recommended.Level) ?? recommended; + Preset = QualityPreset.Current(existing.GetInt("level-change") ?? recommended.Level, existing.GetBool(QualityPreset.DynamicQualityKey) == true) + ?? recommended; IsRerun = existing.Get("cache") is not null; ConnectionTest = new ConnectionTestViewModel( () => existing.Get("texture-provider") ?? "bing,esri", diff --git a/src/OrthoStreamXP/Mounting/MountSession.cs b/src/OrthoStreamXP/Mounting/MountSession.cs index 4122321..014de8f 100644 --- a/src/OrthoStreamXP/Mounting/MountSession.cs +++ b/src/OrthoStreamXP/Mounting/MountSession.cs @@ -146,6 +146,7 @@ private void StartAll() }); NightPainting? nightPainting = s.NightLights ? StartNightLights(s) : null; Daylight? nightPause = s.SkipPhotosAtNight ? SkipPhotosAtNight(s, streaming) : null; + AltitudeDetail? altitude = s.Dynamic is { } dynamic ? DynamicQuality(s, dynamic, streaming) : null; foreach (PackagePlan package in s.Packages) { @@ -155,7 +156,7 @@ private void StartAll() Log.Info($"Removed {oldNights} night textures an earlier version kept whole; they are painted again, keeping only what X-Plane reads"); roots.RenameToCacheNames(); _mounts.Add(new PackageMount(package, roots, builder, textureOptions, s.TrackAircraft, s.LoadAhead, s.LazyTerrainListing, decals, - streaming ? new TextureStreamer(roots, builder!, _view, model, streamingOptions, nightPause) : null, _view, _readLog, _seasons, _usage, _colours, _loads, exposure, + streaming ? new TextureStreamer(roots, builder!, _view, model, streamingOptions, nightPause, _readLog, package.Name, altitude) : null, _view, _readLog, _seasons, _usage, _colours, _loads, exposure, nightPainting is null ? null : new NightTextures(package.Cache, s.Textures.SizeFor, nightPainting))); Log.Info($"Package {package.Name}: read-only from {package.Source}, cache overlay {package.Cache}, mounted at {package.Mountpoint}"); } @@ -168,11 +169,13 @@ private void StartAll() if (mount.LoadAhead is { } prefetcher) onPosition += prefetcher.OnAircraftPosition; SeasonClock? seasons = _seasons; ReadLog? readLog = _readLog; + TileSource? tiles = _tiles; _listener = new AircraftPositionListener(targets, s.Position, onPosition, camera => { _view.Update(camera); - readLog?.Camera(camera); + altitude?.Offer(camera); + readLog?.Camera(camera, tiles?.TilesDownloaded, tiles?.BytesDownloaded); }, streaming ? model.UseScreen : null, seasons is null ? null : day => seasons.OfferDate(day, _view.Starting), _daylight); @@ -321,9 +324,39 @@ private NightPainting StartNightLights(MountSettings s) return _daylight; } - /// "Extra (level +1)": the quality in the words of the window. + /// + /// Dynamic quality's steps, or null when it cannot work: the photos are built whole without mip streaming, and + /// without the aircraft's position the height is unknown. + /// + private static AltitudeDetail? DynamicQuality(MountSettings s, DynamicOptions dynamic, bool streaming) + { + if (!streaming) + { + Log.Warning("Dynamic quality needs mip streaming; the photos stream at full detail at every height in this run"); + return null; + } + if (!s.TrackAircraft) + { + Log.Warning("Dynamic quality needs the aircraft's position from X-Plane (track-aircraft); the photos stream at full detail at every height in this run"); + return null; + } + IReadOnlyList tiers = dynamic.TiersBelow(s.Textures); + string full = QualityPreset.ForLevel(s.Textures.LevelChange)?.Name ?? "full detail"; + if (tiers.Count == 0) + { + Log.Warning($"Dynamic quality: on, but {full} is no sharper than its steps; the photos stream as they are at every height"); + return null; + } + Log.Step($"Dynamic quality: on; {full} near the ground, " + + string.Join(", ", tiers.Select(t => $"{t.Name} from {t.AboveFt:N0} ft")) + + $" above the ground (in a descent, the height {AltitudeDetail.Lookahead.TotalMinutes:0} minutes ahead counts)"); + return new AltitudeDetail(tiers, full); + } + + /// "Extra quality", "Dynamic quality": the quality in the words of the window. private static string QualityName(MountSettings s) => - QualityPreset.ForLevel(s.Textures.LevelChange) is { } preset ? $"{preset.Name} quality" : $"level {s.Textures.LevelChange:+0;-0;0}"; + s.Dynamic is not null && s.Textures.LevelChange == QualityPreset.Dynamic.Level ? $"{QualityPreset.Dynamic.Name} quality" + : QualityPreset.ForLevel(s.Textures.LevelChange) is { } preset ? $"{preset.Name} quality" : $"level {s.Textures.LevelChange:+0;-0;0}"; /// Keeps the cache within --cache-limit, removing the areas flown longest ago. private void TrimCache() diff --git a/src/OrthoStreamXP/Scenery/Aircraft/AltitudeDetail.cs b/src/OrthoStreamXP/Scenery/Aircraft/AltitudeDetail.cs new file mode 100644 index 0000000..34adb1a --- /dev/null +++ b/src/OrthoStreamXP/Scenery/Aircraft/AltitudeDetail.cs @@ -0,0 +1,98 @@ +using OrthoStreamXP.Textures; + +namespace OrthoStreamXP.Scenery; + +/// A step of Dynamic quality: from above the ground, textures are no sharper than 's. +/// The preset it looks like, for the log ("Sharp"). +internal sealed record DetailTier(string Name, double AboveFt, TexturePlan Plan); + +/// The heights of Dynamic quality's steps, in feet above the ground; Balanced's is null when it is not used. +internal sealed record DynamicOptions(double SharpAboveFt = DynamicOptions.DefaultSharpAboveFt, double? BalancedAboveFt = DynamicOptions.DefaultBalancedAboveFt) +{ + public const double DefaultSharpAboveFt = 5000, DefaultBalancedAboveFt = 25000; + + /// The steps, lowest first, that are coarser than (a step no coarser is no saving). + public IReadOnlyList TiersBelow(TexturePlan mount) + { + var tiers = new List { new("Sharp", SharpAboveFt, new TexturePlan(-1)) }; + if (BalancedAboveFt is { } balanced) tiers.Add(new DetailTier("Balanced", balanced, new TexturePlan(-2))); + return [.. tiers.Where(t => t.Plan.SizeFor(16) < mount.SizeFor(16) || t.Plan.SizeFor(18) < mount.SizeFor(18))]; + } +} + +/// +/// Dynamic quality: the photos' detail follows the camera's height above the ground, as the presets would (Extra +/// near the ground, Sharp higher up, Balanced at airliner heights). X-Plane wants nearly the same full-detail +/// textures at 10,000 ft as at 1,000 ft, so most of a climb and cruise downloads detail too fine to see. +/// +/// X-Plane reads each level of a texture once while it keeps it loaded: a level given with less detail stays that +/// way. So a step down comes early: in a descent the height ahead counts, and a step is left +/// only below its height, so terrain passing underneath does not flip it to and fro. +/// +/// Offered every camera position by the position listener; read by the file-system threads. +/// +internal sealed class AltitudeDetail +{ + /// How far ahead a descent is looked at: textures read at full detail this long before they are passed close by. + public static readonly TimeSpan Lookahead = TimeSpan.FromMinutes(4); + /// A step is left this far below its height. + public const double MarginFt = 500; + /// A sink slower than this (feet per minute) is not a descent: turbulence or a level-off. + public const double DescentFpm = -300; + private const double FeetPerMetre = 1 / 0.3048; + /// The vertical speed is measured over this much of the latest positions. + private static readonly TimeSpan Window = TimeSpan.FromSeconds(20); + private static readonly TimeSpan MinWindow = TimeSpan.FromSeconds(5); + + private readonly IReadOnlyList _tiers; + private readonly string _fullName; + private readonly Queue<(DateTime Utc, double HeightM)> _recent = new(); + private int _index = -1; + private volatile DetailTier? _tier; + + /// The steps, lowest first. + /// The quality below the first step, for the log ("Extra"). + public AltitudeDetail(IReadOnlyList tiers, string fullName) + { + _tiers = [.. tiers.OrderBy(t => t.AboveFt)]; + _fullName = fullName; + } + + /// The step the textures are held to now; null for the full detail of the chosen quality (also before X-Plane sends a position). + public DetailTier? Tier => _tier; + + public IReadOnlyList Tiers => _tiers; + + /// The camera's latest position; returns the new step when it changed (logged), otherwise null. + public DetailTier? Offer(CameraReport camera) + { + if (camera.Jumped) _recent.Clear(); + double aglFt = camera.HeightAglM * FeetPerMetre; + double? fpm = ClimbRate(camera); + // In a descent, the height a few minutes ahead (never below the ground): its textures are read at full detail before they are reached. + double heightFt = fpm is < DescentFpm ? Math.Max(0, Math.Min(aglFt, aglFt + fpm.Value * Lookahead.TotalMinutes)) : aglFt; + + int index = _index; + while (index + 1 < _tiers.Count && heightFt >= _tiers[index + 1].AboveFt) index++; + while (index >= 0 && heightFt < _tiers[index].AboveFt - MarginFt) index--; + if (index == _index) return null; + + _index = index; + DetailTier? tier = index < 0 ? null : _tiers[index]; + _tier = tier; + string why = fpm is < DescentFpm ? $", descending {-fpm.Value:N0} ft/min" : ""; + Log.Step($"Dynamic quality: {tier?.Name ?? _fullName} at {aglFt:N0} ft above the ground{why}"); + return tier; + } + + /// Feet per minute over the latest positions (the height above sea level, which terrain does not move), or null until there are enough. + private double? ClimbRate(CameraReport camera) + { + double heightM = camera.ElevationM ?? camera.HeightAglM; + _recent.Enqueue((camera.ReceivedUtc, heightM)); + while (_recent.Count > 2 && camera.ReceivedUtc - _recent.Peek().Utc > Window) _recent.Dequeue(); + var (firstUtc, firstM) = _recent.Peek(); + TimeSpan span = camera.ReceivedUtc - firstUtc; + return span < MinWindow ? null : (heightM - firstM) * FeetPerMetre / span.TotalMinutes; + } +} diff --git a/src/OrthoStreamXP/Scenery/Streaming/ReadCursor.cs b/src/OrthoStreamXP/Scenery/Streaming/ReadCursor.cs index 700e176..785c2d9 100644 --- a/src/OrthoStreamXP/Scenery/Streaming/ReadCursor.cs +++ b/src/OrthoStreamXP/Scenery/Streaming/ReadCursor.cs @@ -1,5 +1,15 @@ namespace OrthoStreamXP.Scenery; +/// Why a read got less detail than X-Plane asked for, by choice: blurry on purpose, not a missing picture. +internal enum HeldBack +{ + No, + /// Night with the photos skipped: the low-zoom base. + Night, + /// Dynamic quality: no sharper than the step for the camera's height. + Altitude, +} + /// /// The levels one open handle has been given, so a level X-Plane reads in several pieces is all from the same /// version even if better data arrives in between (a BC1 block split between two versions would be garbage). @@ -15,10 +25,15 @@ internal sealed class ReadCursor public long LastEnd { get; set; } = -1; /// - /// The latest level X-Plane wanted on this handle was kept to the low-zoom base at night: the next pieces of the - /// same read are counted with it, as night reads, not as stand-ins. + /// The finest level fetched for the texture when X-Plane last wanted a level on this handle, and why (at night, + /// or by Dynamic quality): a later piece of a level finer than it is a held-back read, not a stand-in. X-Plane + /// interleaves reads on one handle (level 1, then the tail of levels 3 and on, then the rest of level 1), so + /// each piece is judged by its own level, not by the read before it. /// - public bool KeptToBase { get; set; } + public (int Finest, HeldBack Why) Hold { get; set; } + + /// Why a piece reading from on is held back, by . + public HeldBack HeldBackAt(int mip) => mip < Hold.Finest ? Hold.Why : HeldBack.No; public bool TryGet(int mip, out ReadOnlyMemory bytes, out Served kind) { diff --git a/src/OrthoStreamXP/Scenery/Streaming/ReadLog.cs b/src/OrthoStreamXP/Scenery/Streaming/ReadLog.cs index 29fb2d3..4cd8c5b 100644 --- a/src/OrthoStreamXP/Scenery/Streaming/ReadLog.cs +++ b/src/OrthoStreamXP/Scenery/Streaming/ReadLog.cs @@ -12,19 +12,33 @@ internal sealed record ReadRecord(string Package, VirtualPath Path, long Offset, int? FirstMip = null, int? LastMip = null, string? Band = null, string? Served = null, double WaitMs = 0, double? DistanceM = null, double? SizeM = null, int? FullPx = null, int? WantedMip = null); +/// One finished (or failed) build of a streamed texture's levels, as the builds log records it. +/// The finest level built; the chain runs from it to the last level. +/// The zoom its tiles were fetched at. +/// From the camera to the texture's centre when the build was asked for, when the camera is known. +/// Tiles downloaded for it (not in RAM, the low-zoom base, or another build's download). +/// Bytes of those downloads. +/// Tiles it found at hand instead. +internal sealed record BuildRecord(string Package, VirtualPath Path, int FromMip, int SizePx, int Zoom, bool ByRead, + double? DistanceM, double SizeM, int Downloaded, long Bytes, int Reused, double Seconds, bool Ok); + /// /// The logs for calibrating the paging model: every open and read X-Plane makes through the mount -/// (reads-*.csv) and the camera position (camera-*.csv), with the same clock, one pair of files per session -/// in the log folder; the last 10 sessions are kept. Lines are written in the background. +/// (reads-*.csv), the camera position with the session's downloads so far (camera-*.csv) and every streamed build +/// with what it downloaded (builds-*.csv), with the same clock, one set of files per session in the log folder; the +/// last 10 sessions are kept. Lines are written in the background. /// internal sealed class ReadLog : IDisposable { private const int KeepSessions = 10; private const string ReadsHeader = "time_s,package,event,path,offset,length,first_mip,last_mip,band,served,wait_ms,distance_m,size_m,full_px,wanted_mip"; - private const string CameraHeader = "time_s,lat,lon,height_agl_m,elevation_m,ground_speed_kt,track_deg"; + private const string CameraHeader = "time_s,lat,lon,height_agl_m,elevation_m,ground_speed_kt,track_deg,tiles_downloaded,bytes_downloaded"; + private const string BuildsHeader = "time_s,package,path,from_mip,size_px,zoom,reason,distance_m,size_m,tiles_downloaded,bytes_downloaded,tiles_reused,seconds,outcome"; + + private enum Target { Reads, Camera, Builds } - private readonly Channel<(bool Camera, string Line)> _lines = Channel.CreateUnbounded<(bool, string)>(new UnboundedChannelOptions { SingleReader = true }); - private readonly StreamWriter _reads, _camera; + private readonly Channel<(Target Target, string Line)> _lines = Channel.CreateUnbounded<(Target, string)>(new UnboundedChannelOptions { SingleReader = true }); + private readonly StreamWriter _reads, _camera, _builds; private readonly Stopwatch _clock = Stopwatch.StartNew(); private readonly Task _writer; @@ -33,19 +47,22 @@ private ReadLog(string folder) string stamp = DateTime.Now.ToString("yyyyMMdd-HHmmss", CultureInfo.InvariantCulture); ReadsPath = Path.Join(folder, $"reads-{stamp}.csv"); CameraPath = Path.Join(folder, $"camera-{stamp}.csv"); + BuildsPath = Path.Join(folder, $"builds-{stamp}.csv"); _reads = Writer(ReadsPath, ReadsHeader); _camera = Writer(CameraPath, CameraHeader); + _builds = Writer(BuildsPath, BuildsHeader); _writer = Task.Run(WriteAsync); } public string ReadsPath { get; } public string CameraPath { get; } + public string BuildsPath { get; } /// Starts this session's files in , removing all but the last sessions' ones. public static ReadLog Start(string folder) { Directory.CreateDirectory(folder); - foreach (string pattern in new[] { "reads-*.csv", "camera-*.csv" }) + foreach (string pattern in new[] { "reads-*.csv", "camera-*.csv", "builds-*.csv" }) foreach (string old in Directory.EnumerateFiles(folder, pattern).Order(StringComparer.Ordinal).SkipLast(KeepSessions - 1)) try { @@ -70,22 +87,28 @@ private static StreamWriter Writer(string path, string header) private string Time => _clock.Elapsed.TotalSeconds.ToString("F3", CultureInfo.InvariantCulture); public void Open(string package, VirtualPath path, string how) => - Add(false, $"{Time},{Csv(package)},open,{Csv(path.Display)},,,,,,{Csv(how)},,,,,"); + Add(Target.Reads, $"{Time},{Csv(package)},open,{Csv(path.Display)},,,,,,{Csv(how)},,,,,"); public void Read(ReadRecord r) => - Add(false, string.Create(CultureInfo.InvariantCulture, + Add(Target.Reads, string.Create(CultureInfo.InvariantCulture, $"{Time},{Csv(r.Package)},read,{Csv(r.Path.Display)},{r.Offset},{r.Length},{r.FirstMip},{r.LastMip},{r.Band},{r.Served},{r.WaitMs:F0},{Number(r.DistanceM)},{Number(r.SizeM)},{r.FullPx},{r.WantedMip}")); - public void Camera(CameraReport c) => - Add(true, string.Create(CultureInfo.InvariantCulture, - $"{Time},{c.Lat:F6},{c.Lon:F6},{c.HeightAglM:F1},{(c.ElevationM is { } e ? e.ToString("F1", CultureInfo.InvariantCulture) : "")},{(c.Motion is { } m ? (m.SpeedMps * 1.943844).ToString("F0", CultureInfo.InvariantCulture) : "")},{(c.Motion is { } t ? t.TrackDeg.ToString("F0", CultureInfo.InvariantCulture) : "")}")); + /// The session's tiles downloaded so far, when there is a tile source. + /// Their bytes. + public void Camera(CameraReport c, long? tilesDownloaded = null, long? bytesDownloaded = null) => + Add(Target.Camera, string.Create(CultureInfo.InvariantCulture, + $"{Time},{c.Lat:F6},{c.Lon:F6},{c.HeightAglM:F1},{(c.ElevationM is { } e ? e.ToString("F1", CultureInfo.InvariantCulture) : "")},{(c.Motion is { } m ? (m.SpeedMps * 1.943844).ToString("F0", CultureInfo.InvariantCulture) : "")},{(c.Motion is { } t ? t.TrackDeg.ToString("F0", CultureInfo.InvariantCulture) : "")},{tilesDownloaded},{bytesDownloaded}")); + + public void Build(BuildRecord b) => + Add(Target.Builds, string.Create(CultureInfo.InvariantCulture, + $"{Time},{Csv(b.Package)},{Csv(b.Path.Display)},{b.FromMip},{b.SizePx},{b.Zoom},{(b.ByRead ? "read" : "ahead")},{Number(b.DistanceM)},{b.SizeM:F0},{b.Downloaded},{b.Bytes},{b.Reused},{b.Seconds:F2},{(b.Ok ? "ok" : "failed")}")); private static string Number(double? value) => value is { } v ? v.ToString("F0", CultureInfo.InvariantCulture) : ""; private static string Csv(string value) => value.AsSpan().IndexOfAny(",\"\n") < 0 ? value : "\"" + value.Replace("\"", "\"\"", StringComparison.Ordinal) + "\""; - private void Add(bool camera, string line) => _lines.Writer.TryWrite((camera, line)); + private void Add(Target target, string line) => _lines.Writer.TryWrite((target, line)); private async Task WriteAsync() { @@ -93,9 +116,11 @@ private async Task WriteAsync() { while (await _lines.Reader.WaitToReadAsync().ConfigureAwait(false)) { - while (_lines.Reader.TryRead(out var item)) (item.Camera ? _camera : _reads).WriteLine(item.Line); + while (_lines.Reader.TryRead(out var item)) + (item.Target switch { Target.Camera => _camera, Target.Builds => _builds, _ => _reads }).WriteLine(item.Line); _reads.Flush(); _camera.Flush(); + _builds.Flush(); } } catch (IOException ex) @@ -110,5 +135,6 @@ public void Dispose() _writer.Wait(TimeSpan.FromSeconds(2)); _reads.Dispose(); _camera.Dispose(); + _builds.Dispose(); } } diff --git a/src/OrthoStreamXP/Scenery/Streaming/TextureStreamer.cs b/src/OrthoStreamXP/Scenery/Streaming/TextureStreamer.cs index 3b8647f..97215b3 100644 --- a/src/OrthoStreamXP/Scenery/Streaming/TextureStreamer.cs +++ b/src/OrthoStreamXP/Scenery/Streaming/TextureStreamer.cs @@ -22,6 +22,11 @@ namespace OrthoStreamXP.Scenery; /// while the sun in X-Plane is below (skip-photos-sun-below): X-Plane's reads and load-ahead alike get the /// base, stretched, and what is already cached is served as it is. In twilight the photos stream as usual. /// +/// +/// With Dynamic quality () the same holds by height: high up, nothing finer than the +/// step's texture size is fetched (level 1 of a 4096 px texture at Sharp), and finer reads are stretched from it. +/// Night takes precedence (). +/// /// internal sealed class TextureStreamer : IDisposable { @@ -48,15 +53,26 @@ internal sealed class TextureStreamer : IDisposable private readonly ReadWaitStats _waitStats = new(); /// X-Plane's sun when the photos are skipped at night; null streams them whatever the time. private readonly Daylight? _nightPause; + /// Where each build and what it downloaded is recorded; null records nothing. + private readonly ReadLog? _readLog; + private readonly string _package; + /// Dynamic quality: the detail follows the camera's height; null streams the chosen quality at every height. + private readonly AltitudeDetail? _altitude; private long _ramBytes; private int _trimming; - private long _reads, _real, _standIn, _flat, _headerChunks, _readBuilds, _aheadBuilds, _fullBuilds, _failedBuilds, _nightReads; + private long _reads, _real, _standIn, _flat, _headerChunks, _readBuilds, _aheadBuilds, _fullBuilds, _failedBuilds, _nightReads, _altitudeReads; /// X-Plane's sun, to skip the photos at night (only the low-zoom base); null streams them always. + /// Records every build with what it downloaded (builds-*.csv); null records nothing. + /// The package's name in that log. + /// Dynamic quality: holds the detail to the step for the camera's height; null never does. public TextureStreamer(SceneryRoots roots, TextureBuilder builder, ViewTracker view, PagingModel model, StreamingOptions options, - Daylight? nightPause = null) + Daylight? nightPause = null, ReadLog? readLog = null, string package = "", AltitudeDetail? altitude = null) { _nightPause = nightPause; + _readLog = readLog; + _package = package; + _altitude = altitude; _roots = roots; _builder = builder; _view = view; @@ -93,6 +109,20 @@ public static long BuildTiles(TextureName name, int zoom) /// Night in X-Plane with the photos skipped at night: nothing finer than the low-zoom base is fetched now. public bool PhotosPaused => _nightPause?.Dark == true; + /// + /// The finest level fetched for the texture now, and why when that holds X-Plane back: the low-zoom base at night + /// with the photos skipped; with Dynamic quality the first level no larger than the step's texture size (Sharp's + /// 2048 px is level 1 of a 4096 px texture); otherwise level 0. + /// + internal (int Mip, HeldBack Why) Finest(StreamedTexture t) + { + if (PhotosPaused) return (t.BaseMip, HeldBack.Night); + if (_altitude?.Tier is not { } tier) return (0, HeldBack.No); + int size = tier.Plan.SizeFor(t.Name.Zoom), mip = 0; + while (mip < t.BaseMip && t.Layout.SizeOf(mip) > size) mip++; + return (mip, mip == 0 ? HeldBack.No : HeldBack.Altitude); + } + /// Reads of texture data answered (not counting header-only reads). public long Reads => Interlocked.Read(ref _reads); @@ -168,7 +198,7 @@ private ReadAnswer ReadLevels(StreamedTexture t, ReadCursor cursor, long offset, Band? band = null; double? distance = null; double waitedMs = 0; - bool keptToBase = false; + HeldBack heldBack = HeldBack.No; if (wanted is int mip) { // Full detail wanted: the texture is next to the aircraft, which places it before X-Plane sends a position. @@ -185,9 +215,12 @@ private ReadAnswer ReadLevels(StreamedTexture t, ReadCursor cursor, long offset, Probe(t); realFrom = t.RealFrom; } - // At night with the photos skipped, the low-zoom base is the finest level fetched: finer ones are stretched from it. - keptToBase = cursor.KeptToBase = mip < t.BaseMip && PhotosPaused; - int target = keptToBase ? t.BaseMip : mip; + // At night with the photos skipped (the low-zoom base) or with Dynamic quality high up, a finer level than + // X-Plane wants is the finest fetched: the levels it reads above it are stretched from it. + var (finest, why) = Finest(t); + cursor.Hold = (finest, why); + heldBack = cursor.HeldBackAt(mip); + int target = Math.Max(mip, finest); if (target < realFrom) { Task build = StartBuild(t, Math.Min(target, t.BaseMip), band switch @@ -210,14 +243,14 @@ private ReadAnswer ReadLevels(StreamedTexture t, ReadCursor cursor, long offset, bool done = build.Wait(TimeSpan.FromSeconds(wait)); TimeSpan waited = Stopwatch.GetElapsedTime(waitStarted); waitedMs = waited.TotalMilliseconds; - // A wait for the base at night says nothing about how long the photos take: the tuning never sees it. - if (!keptToBase) NoteWait(band!.Value, starting, waitStarted, waited, done, build); + // A wait for a held-back level says nothing about how long the photos take: the tuning never sees it. + if (heldBack == HeldBack.No) NoteWait(band!.Value, starting, waitStarted, waited, done, build); } } } - // The next piece of a read kept to the base at night is counted with it. - else if (!headerChunk) keptToBase = cursor.KeptToBase; + // A later piece is held back when its own level is finer than the hold of the latest level wanted on the handle. + else if (!headerChunk) heldBack = cursor.HeldBackAt(counted); // A level X-Plane is not reading (the header chunk's start of level 0, or the tail before the level it wants) // is filled from the best data at hand; it neither fixes the level's version nor counts in the statistics. @@ -246,9 +279,10 @@ private ReadAnswer ReadLevels(StreamedTexture t, ReadCursor cursor, long offset, Interlocked.Increment(ref _headerChunks); return new ReadAnswer(output.Length, first, last, Served: any); } - // A read kept to the base at night is blurry by choice: counted apart, so the Home page's share of real reads, - // the flight report and the tuning see only the reads that wanted the photo. - if (keptToBase && served != Served.Real) Interlocked.Increment(ref _nightReads); + // A held-back read is blurry by choice: counted apart, so the Home page's share of real reads, the flight report + // and the tuning see only the reads that wanted the photo. + if (heldBack == HeldBack.Night && served != Served.Real) Interlocked.Increment(ref _nightReads); + else if (heldBack == HeldBack.Altitude && served != Served.Real) Interlocked.Increment(ref _altitudeReads); else { Interlocked.Increment(ref _reads); @@ -274,6 +308,9 @@ private void NoteWait(Band band, bool starting, long waitStarted, TimeSpan waite /// X-Plane's reads at night that got the low-zoom base, stretched, because the photos were skipped. public long NightReads => Interlocked.Read(ref _nightReads); + /// X-Plane's reads that got a coarser level, stretched, because Dynamic quality held the detail to the camera's height. + public long AltitudeReads => Interlocked.Read(ref _altitudeReads); + /// /// The band of a read of . The level X-Plane asks for is its own verdict on the distance; /// the camera's distance can only make a read nearer, never farther, so a stale position (X-Plane still sending @@ -532,6 +569,8 @@ private async Task BuildAsync(StreamedTexture t, int k, FetchTicket ticket { long started = Stopwatch.GetTimestamp(); bool detailed = k < t.BaseMip; + var stats = new TileStats(); + double? distance = _readLog is not null && _view.Current is { } camera ? ViewTracker.DistanceM(camera, t.Lat, t.Lon) : null; try { long weight = BuildWeight(t.Layout.SizeOf(k)), tiles = BuildTiles(t.Name, t.ZoomFor(k)); @@ -547,7 +586,6 @@ private async Task BuildAsync(StreamedTexture t, int k, FetchTicket ticket if (ahead) _ahead.Release(tiles); throw; } - var stats = new TileStats(); int zoom = t.ZoomFor(k); byte[] chain; try @@ -560,6 +598,7 @@ private async Task BuildAsync(StreamedTexture t, int k, FetchTicket ticket if (ahead) _ahead.Release(tiles); } Save(t, k, chain); + LogBuild(t, k, byRead, distance, stats, started, ok: true); // before the level is real: whoever sees it real finds the line lock (t.Gate) { t.FailedAt = 0; @@ -583,6 +622,7 @@ private async Task BuildAsync(StreamedTexture t, int k, FetchTicket ticket Interlocked.Increment(ref _failedBuilds); lock (t.Gate) t.FailedAt = Stopwatch.GetTimestamp(); Log.Warning($"Could not stream {t.Path.Display} levels {k}+ from zoom {t.ZoomFor(k)}: {ex.Message}"); + LogBuild(t, k, byRead, distance, stats, started, ok: false); return false; } finally @@ -591,6 +631,11 @@ private async Task BuildAsync(StreamedTexture t, int k, FetchTicket ticket } } + private void LogBuild(StreamedTexture t, int k, bool byRead, double? distance, TileStats stats, long started, bool ok) => + _readLog?.Build(new BuildRecord(_package, t.Path, k, t.Layout.SizeOf(k), t.ZoomFor(k), byRead, distance, t.SizeM, + Volatile.Read(ref stats.Misses), Interlocked.Read(ref stats.Bytes), Volatile.Read(ref stats.Hits), + Stopwatch.GetElapsedTime(started).TotalSeconds, ok)); + /// Level 0 complete becomes a normal cached DDS; a coarser chain goes to .xpstream\mips; base levels are never saved. private void Save(StreamedTexture t, int k, byte[] chain) { @@ -626,11 +671,13 @@ private void Save(StreamedTexture t, int k, byte[] chain) public Task? Warm(VirtualPath path, int k, int priority) { if (Get(path) is not { } t) return null; - // At night a texture with its base has all load-ahead may fetch: nothing to ask for (the warmer rechecks every - // loaded texture at each position, which would count each of them again and again). - if (k < t.BaseMip && PhotosPaused && RealFrom(t) <= t.BaseMip) return Task.FromResult(true); + // Held back (at night, or by Dynamic quality), a texture with its finest allowed level has all load-ahead may + // fetch: nothing to ask for (the warmer rechecks every loaded texture at each position, which would count each + // of them again and again). When the hold lifts, the warmer's next pass asks for the finer levels. + int finest = Finest(t).Mip; + if (k < finest && RealFrom(t) <= finest) return Task.FromResult(true); Interlocked.Increment(ref _warmRequests); - return StartBuild(t, Math.Clamp(k, PhotosPaused ? t.BaseMip : 0, t.BaseMip), priority, byRead: false); + return StartBuild(t, Math.Clamp(k, finest, t.BaseMip), priority, byRead: false); } private long _warmRequests; @@ -755,11 +802,13 @@ public string Summary() $"{Interlocked.Read(ref _flat)} flat{Share(Interlocked.Read(ref _flat))}; waited: {_waitStats.Describe(Band.Near)}, {_waitStats.Describe(Band.Middle)}; " + $"builds: {Interlocked.Read(ref _readBuilds)} for reads, {Interlocked.Read(ref _aheadBuilds)} ahead ({Interlocked.Read(ref _warmRequests)} asked), " + $"{Interlocked.Read(ref _fullBuilds)} at full detail, {Interlocked.Read(ref _failedBuilds)} failed" + - (_nightPause is null ? "" : $", {Interlocked.Read(ref _nightReads)} reads at night kept to the low-zoom base") + $"; RAM {Interlocked.Read(ref _ramBytes) >> 20} MB{k}"; + (_nightPause is null ? "" : $", {Interlocked.Read(ref _nightReads)} reads at night kept to the low-zoom base") + + (_altitude is null ? "" : $", {Interlocked.Read(ref _altitudeReads)} reads held to the detail of the height (now {_altitude.Tier?.Name ?? "full detail"})") + $"; RAM {Interlocked.Read(ref _ramBytes) >> 20} MB{k}"; } /// A number that changes whenever the summary would. - public long SummaryVersion => Reads + Interlocked.Read(ref _readBuilds) + Interlocked.Read(ref _aheadBuilds) + Interlocked.Read(ref _failedBuilds); + public long SummaryVersion => Reads + Interlocked.Read(ref _readBuilds) + Interlocked.Read(ref _aheadBuilds) + Interlocked.Read(ref _failedBuilds) + + Interlocked.Read(ref _altitudeReads); /// Stops new builds and waits for the running ones. public async Task ShutdownAsync() diff --git a/src/OrthoStreamXP/Setup/Settings/QualityPreset.cs b/src/OrthoStreamXP/Setup/Settings/QualityPreset.cs index 8810356..8bb4648 100644 --- a/src/OrthoStreamXP/Setup/Settings/QualityPreset.cs +++ b/src/OrthoStreamXP/Setup/Settings/QualityPreset.cs @@ -35,11 +35,27 @@ internal sealed record QualityPreset(string Name, int Level, string Summary, str "Low and slow flight and screenshots, on a fast connection", "about 4 min, then sharp next to the aircraft", Values(buildWorkers: 8, fileSystemThreads: 96, provisionalLod: 3, provisionalWait: 3, radiusKm: 4, textures: 6, buildMemoryMb: 1024, lookahead: 90)); + // Extra near the ground, Sharp from 5,000 ft and Balanced from 25,000 ft above it: Extra's level and cache, with the + // detail held back high up (dynamic-quality). Measured on a day flight: full-detail textures were 82 % of the + // downloads at every height, and Sharp's detail above 5,000 ft would have saved about half of the climb and cruise. + public static readonly QualityPreset Dynamic = new("Dynamic", Extra.Level, + "Extra near the ground, Sharp from 5,000 ft and Balanced from 25,000 ft above it: full detail where it can be seen, about half the downloads in a climb and cruise.", + "Climbs, cruise and approaches in one flight, on a fast connection", "about 4 min, then sharp next to the aircraft", + new Dictionary(Extra.Settings) { [DynamicQualityKey] = "on" }); + + /// The presets by their level change: Dynamic is Extra's level (its cache, tuning and texture size), so it is not among them. public static IReadOnlyList All { get; } = [Balanced, Sharp, Ultra, Extra]; - /// The preset with this level change, if one has it. + /// The presets offered in the window: every level, and Dynamic. + public static IReadOnlyList Choices { get; } = [.. All, Dynamic]; + + /// The preset with this level change, if one has it (Extra for Dynamic's level). public static QualityPreset? ForLevel(int? level) => All.FirstOrDefault(p => p.Level == level); + /// The preset the settings are at: Dynamic when dynamic-quality is on at its level, otherwise the level's. + public static QualityPreset? Current(int? level, bool dynamicQuality) => + dynamicQuality && level == Dynamic.Level ? Dynamic : ForLevel(level); + public string? Get(string name) => Settings.TryGetValue(name, out string? value) ? value : null; /// Zoom of the common ZL16 textures at this preset (the ones that cover most of the ground). @@ -58,9 +74,14 @@ internal sealed record QualityPreset(string Name, int Level, string Summary, str public void ApplyTo(SettingsDocument settings) { settings.Set("level-change", Level); + // Dynamic quality is Dynamic's alone: any other preset turns it off (an older settings file has no line for it). + if (!Settings.ContainsKey(DynamicQualityKey)) settings.Set(DynamicQualityKey, "off"); foreach (var (name, value) in Settings) settings.Set(name, value); } + /// The setting that makes Extra's level . + public const string DynamicQualityKey = "dynamic-quality"; + private static Dictionary Values(int buildWorkers, int fileSystemThreads, int provisionalLod, double? provisionalWait, double radiusKm, int textures, int buildMemoryMb, double lookahead = MountSettings.DefaultLookaheadSeconds) => new() { diff --git a/src/OrthoStreamXP/Setup/Settings/SettingsDocument.cs b/src/OrthoStreamXP/Setup/Settings/SettingsDocument.cs index 3ffc20c..35343d4 100644 --- a/src/OrthoStreamXP/Setup/Settings/SettingsDocument.cs +++ b/src/OrthoStreamXP/Setup/Settings/SettingsDocument.cs @@ -131,6 +131,8 @@ public static SettingsDocument CreateNew(string path, string xplane, string base .AppendLine("texture-provider = bing,esri") .AppendLine(CultureInfo.InvariantCulture, $"# quality preset: {preset.Name}; the level also sets the texture size ({preset.Size} px)") .AppendLine(CultureInfo.InvariantCulture, $"level-change = {preset.Level.ToString(CultureInfo.InvariantCulture)}") + .AppendLine("# Dynamic quality (the Dynamic preset): less detail high above the ground, where it cannot be seen (on or off)") + .AppendLine(CultureInfo.InvariantCulture, $"{QualityPreset.DynamicQualityKey} = {preset.Get(QualityPreset.DynamicQualityKey) ?? "off"}") .AppendLine() .AppendLine("# --- Speed ------------------------------------------------------------------------") .AppendLine(CultureInfo.InvariantCulture, $"dds-build-workers = {preset.Get("dds-build-workers")}") diff --git a/src/OrthoStreamXP/Textures/Tiles/TileSource.cs b/src/OrthoStreamXP/Textures/Tiles/TileSource.cs index 739b081..6844247 100644 --- a/src/OrthoStreamXP/Textures/Tiles/TileSource.cs +++ b/src/OrthoStreamXP/Textures/Tiles/TileSource.cs @@ -8,6 +8,8 @@ namespace OrthoStreamXP.Textures; internal sealed class TileStats { public int Hits, Misses, Calls, Fallbacks; + /// Bytes of the tiles downloaded for the build (every server answer, as the session's own count). + public long Bytes; private long _downloadTicks; public double DownloadSeconds => TimeSpan.FromTicks(Interlocked.Read(ref _downloadTicks)).TotalSeconds; @@ -343,6 +345,7 @@ private async Task DownloadAsync(int x, int y, int zoom, Pending pending byte[] bytes = await response.Content.ReadAsByteArrayAsync().ConfigureAwait(false); Interlocked.Increment(ref _tilesDownloaded); Interlocked.Add(ref _bytesDownloaded, bytes.Length); + Interlocked.Add(ref stats.Bytes, bytes.Length); Interlocked.Add(ref _tileTicks, Stopwatch.GetElapsedTime(started).Ticks); byte[] decoded = Images.DecodeTile(bytes); // rejects error pages and truncated data stats.AddDownload(Stopwatch.GetElapsedTime(started)); diff --git a/src/OrthoStreamXP/orthostreamxp.example.ini b/src/OrthoStreamXP/orthostreamxp.example.ini index b575f17..aa22bf5 100644 --- a/src/OrthoStreamXP/orthostreamxp.example.ini +++ b/src/OrthoStreamXP/orthostreamxp.example.ini @@ -79,6 +79,13 @@ skip-photos-at-night = off # how far below the horizon the sun must be before the photos are skipped, in degrees (0-18): 6 is the end of civil # twilight, 12 of nautical twilight; higher keeps the photos longer at dusk and brings them back sooner at dawn skip-photos-sun-below = 9 +# Dynamic quality: the photos' detail follows the height above the ground (the Dynamic preset: Extra's values with +# this on). Above dynamic-sharp-above they are fetched no sharper than Sharp's, above dynamic-balanced-above no +# sharper than Balanced's (feet, or off); in a descent the height four minutes ahead counts (on or off; needs +# mip-streaming and track-aircraft) +dynamic-quality = off +dynamic-sharp-above = 5000 +dynamic-balanced-above = 25000 # --- Building ahead of X-Plane ---------------------------------------------------- # build each DSF's textures as soon as X-Plane starts loading it, before it asks for them (on or off) diff --git a/tests/OrthoStreamXP.Tests/DynamicQualityTests.cs b/tests/OrthoStreamXP.Tests/DynamicQualityTests.cs new file mode 100644 index 0000000..ebef27c --- /dev/null +++ b/tests/OrthoStreamXP.Tests/DynamicQualityTests.cs @@ -0,0 +1,169 @@ +using OrthoStreamXP.Scenery; +using OrthoStreamXP.Setup; +using OrthoStreamXP.Textures; +using OrthoStreamXP.Tuning; + +namespace OrthoStreamXP.Tests; + +/// Dynamic quality: the step for the camera's height, its settings and its preset. +public sealed class DynamicQualityTests : IDisposable +{ + private const double Ft = 0.3048; + private static readonly DateTime Start = new(2026, 11, 15, 12, 0, 0, DateTimeKind.Utc); + private readonly TempTree _tree = new(); + + public void Dispose() => _tree.Dispose(); + + /// Extra's steps as the preset sets them: Sharp from 5,000 ft, Balanced from 25,000 ft. + private static AltitudeDetail ExtraSteps() => new(new DynamicOptions().TiersBelow(new TexturePlan(1)), "Extra"); + + private static CameraReport Camera(double seconds, double aglFt, double? mslFt = null, bool jumped = false) => + new(50, 17, aglFt * Ft, (mslFt ?? aglFt) * Ft, null, jumped, Start.AddSeconds(seconds)); + + // ---------------------------------------------------------------- the step for the height + + [Fact] + public void A_climb_goes_from_full_detail_to_Sharp_and_then_Balanced() + { + AltitudeDetail detail = ExtraSteps(); + Assert.Null(detail.Tier); // before X-Plane sends a position + string?[] steps = new string?[45]; + for (int i = 0; i < steps.Length; i++) // 2,000 ft/min from the ground to 29,333 ft + { + detail.Offer(Camera(i * 20, i * 20 * 2000 / 60.0)); + steps[i] = detail.Tier?.Name; + } + Assert.Null(steps[7]); // 4,667 ft + Assert.Equal("Sharp", steps[8]); // 5,333 ft + Assert.Equal("Sharp", steps[37]); // 24,667 ft + Assert.Equal("Balanced", steps[38]); // 25,333 ft + } + + [Fact] + public void Terrain_passing_underneath_does_not_flip_the_step_to_and_fro() + { + AltitudeDetail detail = ExtraSteps(); + // Level at 8,000 ft above the sea; the ground rises and falls beneath. + detail.Offer(Camera(0, 5200, 8000)); + Assert.Equal("Sharp", detail.Tier?.Name); + detail.Offer(Camera(10, 4700, 8000)); // within the 500 ft margin + Assert.Equal("Sharp", detail.Tier?.Name); + detail.Offer(Camera(20, 5100, 8000)); + Assert.Equal("Sharp", detail.Tier?.Name); + detail.Offer(Camera(30, 4400, 8000)); // past it + Assert.Null(detail.Tier); + detail.Offer(Camera(40, 4900, 8000)); // back up, not yet at the step + Assert.Null(detail.Tier); + } + + [Fact] + public void In_a_descent_full_detail_comes_back_four_minutes_before_the_step() + { + AltitudeDetail detail = ExtraSteps(); + detail.Offer(Camera(0, 12_000)); + detail.Offer(Camera(10, 12_000)); + Assert.Equal("Sharp", detail.Tier?.Name); + // 1,500 ft/min down: four minutes ahead is 6,000 ft lower. + double? lifted = null; + for (int i = 1; i <= 120 && lifted is null; i++) + { + double agl = 12_000 - i * 2 * 1500 / 60.0; + detail.Offer(Camera(10 + i * 2, agl)); + if (detail.Tier is null) lifted = agl; + } + Assert.NotNull(lifted); + Assert.InRange(lifted!.Value, 10_000, 10_600); // 4,500 ft + 6,000 ft, not 4,500 ft + } + + [Fact] + public void A_slow_sink_is_not_a_descent() + { + AltitudeDetail detail = ExtraSteps(); + for (int i = 0; i <= 30; i++) detail.Offer(Camera(i * 2, 5800 - i * 2 * 200 / 60.0)); // 200 ft/min down for a minute + Assert.Equal("Sharp", detail.Tier?.Name); + } + + [Fact] + public void A_new_flight_forgets_the_last_ones_descent() + { + AltitudeDetail detail = ExtraSteps(); + for (int i = 0; i <= 10; i++) detail.Offer(Camera(i * 2, 8000 - i * 2 * 3000 / 60.0)); // a steep descent + Assert.Null(detail.Tier); + detail.Offer(Camera(30, 12_000, jumped: true)); // placed at cruise: no descent to look ahead along + Assert.Equal("Sharp", detail.Tier?.Name); + } + + [Fact] + public void Only_steps_coarser_than_the_chosen_quality_are_used() + { + var options = new DynamicOptions(); + Assert.Equal(["Sharp", "Balanced"], options.TiersBelow(new TexturePlan(1)).Select(t => t.Name)); + Assert.Equal(["Balanced"], options.TiersBelow(new TexturePlan(-1)).Select(t => t.Name)); // Sharp is no saving at Sharp + Assert.Empty(options.TiersBelow(new TexturePlan(-2))); + Assert.Equal(["Sharp"], new DynamicOptions(BalancedAboveFt: null).TiersBelow(new TexturePlan(1)).Select(t => t.Name)); + } + + // ---------------------------------------------------------------- the settings + + private MountSettings Parse(params string[] extra) + { + Directory.CreateDirectory(_tree.PathOf("source")); + return MountSettings.FromValues(TestSettings.Of( + [$"source = {_tree.PathOf("source")}", $"cache = {_tree.PathOf("cache")}", $"mountpoint = {_tree.PathOf("mount")}", .. extra])); + } + + [Fact] + public void Dynamic_quality_is_off_unless_turned_on_and_its_heights_are_checked() + { + Assert.Null(Parse().Dynamic); + Assert.Equal(new DynamicOptions(5000, 25000), Parse("dynamic-quality = on").Dynamic); + Assert.Equal(new DynamicOptions(8000, null), Parse("dynamic-quality = on", "dynamic-sharp-above = 8000", "dynamic-balanced-above = off").Dynamic); + Assert.Throws(() => Parse("dynamic-quality = sometimes")); + Assert.Throws(() => Parse("dynamic-quality = on", "dynamic-sharp-above = 500")); + Assert.Throws(() => Parse("dynamic-quality = on", "dynamic-sharp-above = 9000", "dynamic-balanced-above = 8000")); + } + + // ---------------------------------------------------------------- the preset + + [Fact] + public void Dynamic_is_Extra_with_dynamic_quality_on_and_any_other_preset_turns_it_off() + { + var settings = SettingsDocument.FromText("x.ini", "level-change = -1\ndownload-workers = 160\n"); + + QualityPreset.Dynamic.ApplyTo(settings); + Assert.Equal((1, true), (settings.GetInt("level-change"), settings.GetBool("dynamic-quality") == true)); + Assert.Equal(QualityPreset.Extra.Get("dds-build-workers"), settings.Get("dds-build-workers")); + Assert.Equal(QualityPreset.Dynamic, QualityPreset.Current(settings.GetInt("level-change"), true)); + + QualityPreset.Extra.ApplyTo(settings); + Assert.Equal("off", settings.Get("dynamic-quality")); + Assert.Equal(QualityPreset.Extra, QualityPreset.Current(settings.GetInt("level-change"), false)); + + Assert.Equal(QualityPreset.Sharp, QualityPreset.Current(-1, true)); // dynamic-quality set by hand at another level + Assert.Equal(QualityPreset.Extra, QualityPreset.ForLevel(1)); // the cache, tuning and texture size stay Extra's + Assert.Equal(160, settings.GetInt("download-workers")); + } + + [Fact] + public void An_older_settings_file_without_dynamic_quality_is_still_at_its_presets_defaults() + { + var settings = SettingsDocument.FromText("x.ini", ""); + foreach (var (key, value) in TunedSettings.Defaults(QualityPreset.Extra)) settings.Set(key, value); + settings.Set("level-change", 1); + Assert.False(TunedSettings.DiffersFromDefaults(settings, QualityPreset.Extra)); + } + + [Fact] + public void Dynamic_shares_what_was_tuned_for_Extra() + { + string path = _tree.PathOf("orthostreamxp.ini"); + TunedStore store = TunedStore.Load(path); + store.Set(1, "max-wait", "7.5"); + store.Save(); + var settings = SettingsDocument.FromText(path, ""); + + TunedSettings.ChoosePreset(settings, QualityPreset.Dynamic, TunedStore.Load(path)); + + Assert.Equal(("7.5", true), (settings.Get("max-wait"), settings.GetBool("dynamic-quality") == true)); + } +} diff --git a/tests/OrthoStreamXP.Tests/StreamingTests.cs b/tests/OrthoStreamXP.Tests/StreamingTests.cs index c3aaca4..8541e50 100644 --- a/tests/OrthoStreamXP.Tests/StreamingTests.cs +++ b/tests/OrthoStreamXP.Tests/StreamingTests.cs @@ -29,7 +29,8 @@ private sealed record Setup(FakeTileServer Server, TileSource Tiles, SceneryRoot /// -3: ZL16 textures are 1024 px from zoom 14, their base level 2 (zoom 12). -2: 2048 px from zoom 15, base level 3. private Setup Streaming(int level = -3, double maxWait = 0.2, Func? delay = null, Setup? sharing = null, int detailedBuilds = 16, - long buildTiles = TextureStreamer.DefaultBuildTiles, Func? hold = null, Daylight? nightPause = null) + long buildTiles = TextureStreamer.DefaultBuildTiles, Func? hold = null, Daylight? nightPause = null, ReadLog? readLog = null, + AltitudeDetail? altitude = null) { FakeTileServer server = sharing?.Server ?? new FakeTileServer(delay: delay, hold: hold); TileSource tiles = sharing?.Tiles ?? Track(new TileSource("test", FakeTileServer.Template, 32, handler: server) { Store = new TileStore(_tree.PathOf("base")) }); @@ -42,7 +43,8 @@ private Setup Streaming(int level = -3, double maxWait = 0.2, Func s.Streamer.RealFrom(t) == 0); // logged before it is real; disposing the log writes the line + builds = log.BuildsPath; + } + string[] lines = File.ReadAllLines(builds); + Assert.Equal("time_s,package,path,from_mip,size_px,zoom,reason,distance_m,size_m,tiles_downloaded,bytes_downloaded,tiles_reused,seconds,outcome", lines[0]); + string[] full = lines.Skip(1).Select(l => l.Split(',')).Single(f => f[3] == "0"); + Assert.Equal(["Test package", "textures/" + Stem + ".dds", "0", "1024", "14", "read"], full[1..7]); + Assert.Equal("3000", full[7]); // the camera's distance, its height included + Assert.Equal("16", full[9]); // 1024 px: 4 x 4 tiles at zoom 14 (16 + level change -3 + 1) + Assert.True(long.Parse(full[10], System.Globalization.CultureInfo.InvariantCulture) > 0); + Assert.Equal("ok", full[13]); + } + + // ---------------------------------------------------------------- Dynamic quality + + /// A step half the test textures' size (512 of 1024 px): held to it, level 1 is the finest fetched. + private static AltitudeDetail HalfSizeHigh() => new([new DetailTier("Half", 1000, new TexturePlan(-3, 512))], "Full"); + + private static CameraReport Above(StreamedTexture t, double heightM) => new(t.Lat, t.Lon, heightM, null, null, false, DateTime.UtcNow); + + [Fact] + public void High_up_with_Dynamic_quality_a_near_read_downloads_only_the_steps_level_and_is_not_counted_as_blurry() + { + AltitudeDetail altitude = HalfSizeHigh(); + Setup s = Streaming(maxWait: 5, altitude: altitude); + StreamedTexture t = s.Streamer.Get(Texture())!; + altitude.Offer(Above(t, 2000)); // 6,600 ft: above the step + s.View.Update(Above(t, 2000)); + Assert.Equal((1, HeldBack.Altitude), s.Streamer.Finest(t)); + + var (bytes, answer) = ReadLevel(s.Streamer, t, 0); + + Assert.Equal(Served.StandIn, answer.Served); // level 1, stretched + AssertColor(TileColor, bytes, 1024); + Assert.Equal(1, s.Streamer.RealFrom(t)); + Assert.DoesNotContain(14, Zooms(s.Server)); // level 0's zoom never asked for + Assert.Contains(13, Zooms(s.Server)); + Assert.Null(s.Roots.CachedFile(Texture())); + // Blurry by choice: not a read the tuning, the flight report or the Home page counts against the photos. + Assert.Equal((0L, 0L, 1L, 0L), (s.Streamer.Reads, s.Streamer.StandInReads, s.Streamer.AltitudeReads, s.Streamer.NightReads)); + } + + [Fact] + public async Task Load_ahead_stops_at_the_steps_level_high_up_and_fetches_full_detail_once_the_step_is_left() + { + AltitudeDetail altitude = HalfSizeHigh(); + Setup s = Streaming(altitude: altitude); + StreamedTexture t = s.Streamer.Get(Texture())!; + altitude.Offer(Above(t, 2000)); + + Assert.True(await s.Streamer.Warm(Texture(), 0, FetchPriority.Background)!); + Assert.Equal(1, s.Streamer.RealFrom(t)); + Assert.DoesNotContain(14, Zooms(s.Server)); + Assert.True(await s.Streamer.Warm(Texture(), 0, FetchPriority.Background)!); // has all it may fetch: nothing more + Assert.DoesNotContain(14, Zooms(s.Server)); + + altitude.Offer(Above(t, 100)); // 330 ft: below the step and its margin + Assert.Equal((0, HeldBack.No), s.Streamer.Finest(t)); + Assert.True(await s.Streamer.Warm(Texture(), 0, FetchPriority.Background)!); + Assert.Equal(0, s.Streamer.RealFrom(t)); + Assert.Contains(14, Zooms(s.Server)); + } + + [Fact] + public void A_held_back_level_read_around_an_interleaved_tail_read_is_counted_held_back_in_every_piece() + { + // A step a quarter of the size: level 2 (the base) is the finest fetched, so level 1 is held back. + var altitude = new AltitudeDetail([new DetailTier("Quarter", 1000, new TexturePlan(-3, 256))], "Full"); + Setup s = Streaming(maxWait: 5, altitude: altitude); + StreamedTexture t = s.Streamer.Get(Texture())!; + altitude.Offer(Above(t, 2000)); + s.View.Update(Above(t, 2000)); + var cursor = new ReadCursor(); + int half = t.Layout.LengthOf(1) / 2; + + // As X-Plane did on the flight: half of level 1, the tail from level 3, then the rest of level 1. + Assert.Equal(Served.StandIn, s.Streamer.Read(t, cursor, t.Layout.Offset(1), new byte[half]).Served); + Assert.Equal(Served.Real, s.Streamer.Read(t, cursor, t.Layout.Offset(3), new byte[t.Layout.Length - t.Layout.Offset(3)]).Served); + Assert.Equal(Served.StandIn, s.Streamer.Read(t, cursor, t.Layout.Offset(1) + half, new byte[t.Layout.LengthOf(1) - half]).Served); + + Assert.Equal((2L, 0L), (s.Streamer.AltitudeReads, s.Streamer.StandInReads)); + } + + [Fact] + public void Night_takes_precedence_over_Dynamic_quality() + { + var sun = new Daylight(); + sun.Offer(-20); + AltitudeDetail altitude = HalfSizeHigh(); + Setup s = Streaming(nightPause: sun, altitude: altitude); + StreamedTexture t = s.Streamer.Get(Texture())!; + altitude.Offer(Above(t, 2000)); + Assert.Equal((t.BaseMip, HeldBack.Night), s.Streamer.Finest(t)); + } + [Fact] public async Task At_night_every_piece_of_a_level_read_in_pieces_counts_as_a_night_read() { @@ -1017,14 +1124,17 @@ public void The_read_log_writes_reads_and_the_camera_as_csv() { log.Open("My, package", VirtualPath.Of("textures", "a.dds"), "streamed"); log.Read(new ReadRecord("My, package", VirtualPath.Of("textures", "a.dds"), 128, 4096, 0, 0, "near", "real", 12, 2500, 6000, 4096)); - log.Camera(new CameraReport(51.1, 16.9, 300, 420, new Motion(60, 90), false, DateTime.UtcNow)); + log.Camera(new CameraReport(51.1, 16.9, 300, 420, new Motion(60, 90), false, DateTime.UtcNow), 1200, 25_000_000); + log.Camera(new CameraReport(51.1, 16.9, 300, 420, null, false, DateTime.UtcNow)); // no tile source: no download totals (reads, camera) = (log.ReadsPath, log.CameraPath); } string[] lines = File.ReadAllLines(reads); Assert.Equal(3, lines.Length); Assert.EndsWith(",\"My, package\",read,textures/a.dds,128,4096,0,0,near,real,12,2500,6000,4096,", lines[2], StringComparison.Ordinal); Assert.Contains(",\"My, package\",open,textures/a.dds,", lines[1], StringComparison.Ordinal); - Assert.EndsWith(",51.100000,16.900000,300.0,420.0,117,90", File.ReadAllLines(camera)[1], StringComparison.Ordinal); + string[] cameraLines = File.ReadAllLines(camera); + Assert.EndsWith(",51.100000,16.900000,300.0,420.0,117,90,1200,25000000", cameraLines[1], StringComparison.Ordinal); + Assert.EndsWith(",51.100000,16.900000,300.0,420.0,,,,", cameraLines[2], StringComparison.Ordinal); } [Fact]