From 98c4f0fb5cd69afc3322d2e64c878d3f15231593 Mon Sep 17 00:00:00 2001 From: Maximilian Ammann Date: Thu, 7 Apr 2022 15:01:54 +0200 Subject: [PATCH] Refactor book and add more about font rendering --- docs/src/SUMMARY.md | 35 +++++++------ docs/src/{appendix.md => appendix/index.md} | 49 ++++++++++++++----- .../link-collection.md} | 3 +- docs/src/developer-resources.md | 29 ----------- .../architecture.md | 3 +- .../{ => development-documents}/caching.md | 2 +- docs/src/development-documents/design.md | 3 ++ .../figures/domain-model.drawio.svg | 4 ++ .../figures/gpu-stack.drawio.svg | 0 .../figures/os-stack.drawio.svg | 0 .../figures/stencil_buffer.drawio.svg | 0 .../development-documents/font-rendering.md | 49 +++++++++++++++++++ docs/src/development-documents/index.md | 1 + .../stencil-masking.md | 0 docs/src/{ => development-guide}/building.md | 0 docs/src/development-guide/debugging.md | 13 +++++ docs/src/development-guide/index.md | 1 + docs/src/introduction.md | 1 + 18 files changed, 133 insertions(+), 60 deletions(-) rename docs/src/{appendix.md => appendix/index.md} (54%) rename docs/src/{further_technical_reading.md => appendix/link-collection.md} (99%) delete mode 100644 docs/src/developer-resources.md rename docs/src/{ => development-documents}/architecture.md (96%) rename docs/src/{ => development-documents}/caching.md (90%) create mode 100644 docs/src/development-documents/design.md create mode 100644 docs/src/development-documents/figures/domain-model.drawio.svg rename docs/src/{ => development-documents}/figures/gpu-stack.drawio.svg (100%) rename docs/src/{ => development-documents}/figures/os-stack.drawio.svg (100%) rename docs/src/{ => development-documents}/figures/stencil_buffer.drawio.svg (100%) create mode 100644 docs/src/development-documents/font-rendering.md create mode 100644 docs/src/development-documents/index.md rename docs/src/{ => development-documents}/stencil-masking.md (100%) rename docs/src/{ => development-guide}/building.md (100%) create mode 100644 docs/src/development-guide/debugging.md create mode 100644 docs/src/development-guide/index.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index b04b5cdb..cb19088d 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -2,19 +2,26 @@ [Introduction](./introduction.md) [Supported Platforms](./supported-platforms.md) -[Building](./building.md) - -## Developer Resources - -- [Developer Resources](./developer-resources.md) - - [Architecture](./architecture.md) - - [Caching](./caching.md) - - [Stencil Masking](./stencil-masking.md) - - [Developer Log](./developer-log.md) - -## Appendix - -- [Appendix](./appendix.md) - - [Further Technical Reading](./further_technical_reading.md) +[Developer Log](./developer-log.md) + + +- [User Guide](./user-guide/index.md) + + +- [Development Guide](./development-guide/index.md) + - [Building](./development-guide/building.md) + - [Debugging](./development-guide/debugging.md) + + +- [Development Documents](./development-documents/index.md) + - [Architecture](./development-documents/architecture.md) + - [Design](./development-documents/design.md) + - [Caching](./development-documents/caching.md) + - [Stencil Masking](./development-documents/stencil-masking.md) + - [Font Rendering](./development-documents/font-rendering.md) + + +- [Appendix](./appendix/index.md) + - [Link Collection](./appendix/link-collection.md) diff --git a/docs/src/appendix.md b/docs/src/appendix/index.md similarity index 54% rename from docs/src/appendix.md rename to docs/src/appendix/index.md index d7690038..2595f3bb 100644 --- a/docs/src/appendix.md +++ b/docs/src/appendix/index.md @@ -1,5 +1,42 @@ # Appendix + +## Goals + +### Next Major Goals + +* ~~Improve buffer_pool eviction rules~~ +* ~~Use MPI: https://doc.rust-lang.org/book/ch16-02-message-passing.html~~ +* Input-handling via events and functional pipelines +* ~~Show old tiles until new tile is ready / Show mixed tiles, based on availability~~ +* Use a simple style definition + * type: background/fill/line + * minzoom/maxzoom + * source + * source-layer + * paint (fill-color) +* Map feeling: + * Wrap world around in x direction + * Limit panning in y direction + * Nicer default map style + +### Intermediate Goals +* Support multiple projections? PoC such that we are sure the renderer is acceptable + +### Future Goals +* Very simple text rendering +* Cache tessellation results + * We have three "caches": downloaded tiles, tessellated tiles, gpu tiles +* Handle missing tiles +* Support different tile raster addressing + +## Future Ideas + +* Use [rust-gpu](https://github.com/EmbarkStudios/rust-gpu) as shading language +* Focus on accessibility of maps: https://www.w3.org/WAI/RD/wiki/Accessible_Maps +* Display in AR: https://developer.apple.com/documentation/arkit/displaying_an_ar_experience_with_metal +* Use tracing framework: [tracing](https://docs.rs/tracing/0.1.31/tracing) + ## Challenges: * Accuracy of floating point numbers is very bad for big world view @@ -12,15 +49,3 @@ Streets can have unusual shaped like shown [here](https://www.google.de/maps/@48 does not offer such data and therefore just renders an ordinary street contour like shown [here](https://www.openstreetmap.org/query?lat=48.13533&lon=11.57143). Because the data is probably not available this is a very hard challenge. - -## Future Ideas - -* Use [rust-gpu](https://github.com/EmbarkStudios/rust-gpu) as shading language -* Focus on accessibility of maps: https://www.w3.org/WAI/RD/wiki/Accessible_Maps -* Display in AR: https://developer.apple.com/documentation/arkit/displaying_an_ar_experience_with_metal -* Use tracing framework: [tracing](https://docs.rs/tracing/0.1.31/tracing) - -## Debugging Rendering - -For WebGL there is SpectorJS is enabled by default right now. For debugging on a desktop environment you can use -[RenderDoc](https://renderdoc.org/). \ No newline at end of file diff --git a/docs/src/further_technical_reading.md b/docs/src/appendix/link-collection.md similarity index 99% rename from docs/src/further_technical_reading.md rename to docs/src/appendix/link-collection.md index eb09efc5..5a28d38f 100644 --- a/docs/src/further_technical_reading.md +++ b/docs/src/appendix/link-collection.md @@ -109,12 +109,11 @@ Projects: ## Specifications * [TileJSON](https://github.com/mapbox/tilejson-spec) -* + ## Render Graphs * https://github.com/metal-by-example/simple-instancing/blob/master/MetalSimpleInstancing/Renderer.swift - * https://github.com/troughton/Substrate * https://de.slideshare.net/DICEStudio/framegraph-extensible-rendering-architecture-in-frostbite * http://themaister.net/blog/2017/08/15/render-graphs-and-vulkan-a-deep-dive/ diff --git a/docs/src/developer-resources.md b/docs/src/developer-resources.md deleted file mode 100644 index 124aa9bd..00000000 --- a/docs/src/developer-resources.md +++ /dev/null @@ -1,29 +0,0 @@ -# Developer Resources - -## Next Major Goals - -* Improve buffer_pool eviction rules -* Use MPI: https://doc.rust-lang.org/book/ch16-02-message-passing.html -* Input-handling via events and functional pipelines -* Show old tiles until new tile is ready / Show mixed tiles, based on availability -* Use a simple style definition - * type: background/fill/line - * minzoom/maxzoom - * source - * source-layer - * paint (fill-color) -* Map feeling: - * Wrap world around in x direction - * Limit panning in y direction - * Nicer default map style - -## Intermediate Goals -* Support multiple projections? PoC such that we are sure the renderer is acceptable - -## Future Goals -* Very simple text rendering -* Cache tessellation results - * We have three "caches": downloaded tiles, tessellated tiles, gpu tiles -* Handle missing tiles -* Support different tile raster addressing - diff --git a/docs/src/architecture.md b/docs/src/development-documents/architecture.md similarity index 96% rename from docs/src/architecture.md rename to docs/src/development-documents/architecture.md index a6129495..74749710 100644 --- a/docs/src/architecture.md +++ b/docs/src/development-documents/architecture.md @@ -1,7 +1,6 @@ # Architecture - -## GPU Architecture +## Rendering Architecture The big picture of wgpu is as follows: diff --git a/docs/src/caching.md b/docs/src/development-documents/caching.md similarity index 90% rename from docs/src/caching.md rename to docs/src/development-documents/caching.md index aec51411..4d9d9ade 100644 --- a/docs/src/caching.md +++ b/docs/src/development-documents/caching.md @@ -6,7 +6,7 @@ the format of the network requests. The mapr library is not introducing a separa Instead, caching functionality of HTTP client libraries of the web platform are used. This has the advantage that we can honor HTTP headers which configure caching. This is very important for fetched tiles, as they can have an expiry date. -* On the web we are using service workers to cache network requests. +* On the web the browser is automatically caching raw tiles. * On Linux, MacOs, iOS and Android we are utilizing [reqwest-middleware-cache](https://crates.io/crates/reqwest-middleware-cache/), which writes raw network requests to disk. \ No newline at end of file diff --git a/docs/src/development-documents/design.md b/docs/src/development-documents/design.md new file mode 100644 index 00000000..ac073bad --- /dev/null +++ b/docs/src/development-documents/design.md @@ -0,0 +1,3 @@ +# Design + +![](./figures/domain-model.drawio.svg) \ No newline at end of file diff --git a/docs/src/development-documents/figures/domain-model.drawio.svg b/docs/src/development-documents/figures/domain-model.drawio.svg new file mode 100644 index 00000000..fd2a2e35 --- /dev/null +++ b/docs/src/development-documents/figures/domain-model.drawio.svg @@ -0,0 +1,4 @@ + + + +MapRenderStateSchedulerScheduleMethodStyleStyleLayerSourceSourceClientReqwestHttpClientWHATWGFetchHttpClientBufferPoolTileCacheGeometryIndexIndexedGeometrygeometries: Vec<Polygon/Line>CachedTileTileRequestState(Sender<TessellateMessage>, Receiver<TessellateMessage>)wgpu::Devicewgpu::Queuewgpu::InstanceFPSMeterTileViewPatternCameraPerspectivezoom: ZoomTileInViewRingIndexVecDeque<IndexEntry>
...
...1TesselatedMessageTilerequest_idLayerAvailablebufferfeature_indicescoordsUnavailablecoordslayer_nameLayerViewRegionText is not SVG - cannot display \ No newline at end of file diff --git a/docs/src/figures/gpu-stack.drawio.svg b/docs/src/development-documents/figures/gpu-stack.drawio.svg similarity index 100% rename from docs/src/figures/gpu-stack.drawio.svg rename to docs/src/development-documents/figures/gpu-stack.drawio.svg diff --git a/docs/src/figures/os-stack.drawio.svg b/docs/src/development-documents/figures/os-stack.drawio.svg similarity index 100% rename from docs/src/figures/os-stack.drawio.svg rename to docs/src/development-documents/figures/os-stack.drawio.svg diff --git a/docs/src/figures/stencil_buffer.drawio.svg b/docs/src/development-documents/figures/stencil_buffer.drawio.svg similarity index 100% rename from docs/src/figures/stencil_buffer.drawio.svg rename to docs/src/development-documents/figures/stencil_buffer.drawio.svg diff --git a/docs/src/development-documents/font-rendering.md b/docs/src/development-documents/font-rendering.md new file mode 100644 index 00000000..2176957e --- /dev/null +++ b/docs/src/development-documents/font-rendering.md @@ -0,0 +1,49 @@ +# Font Rendering + +There exists no universally perfect solution to font rendering. Depending on the runtime environment a method needs to +be chosen. [This StackOverflow post](https://stackoverflow.com/a/5278471) outlines some state-of-the-art methods. Some +more approaches are described [here](https://aras-p.info/blog/2017/02/15/Font-Rendering-is-Getting-Interesting/). + +From my perspective the following approaches could work potentially: + +1. Tessellate Fonts +2. SDF Font Rendering +3. GPU Text Rendering directly from Bezier Curves +4. Draw text using a Web Canvas and load them to GPU + +There is a thesis which summarizes some methods [here](https://lup.lub.lu.se/luur/download?func=downloadFile&recordOId=9024910&fileOId=9024911). +A link collection about font related projects can be viewed [here](../appendix/link-collection.md#font-rendering). + +## Approaches + +### Tessellate Fonts +There is [ttf2mesh](https://github.com/fetisov/ttf2mesh) which generates meshes. I was already able to generate about 1k +glyphs with ~40FPS. + +### SDF Font Rendering + +There is a blogpost by Mapbox [here](https://blog.mapbox.com/drawing-text-with-signed-distance-fields-in-mapbox-gl-b0933af6f817). +Some more implementation documents are available [here](https://github.com/mapbox/mapbox-gl-native/wiki/Text-Rendering). +A good foundation for SDF fonts was created by Chlumsky with [msdfgen](https://github.com/Chlumsky/msdfgen). + + +### GPU Text Rendering from Bezier Curves + +The solutions exist: + +* [By Will Dobbie](https://wdobbie.com/post/gpu-text-rendering-with-vector-textures/) with an + implementation [here](https://github.com/azsn/gllabel) +* [Slug Library](http://sluglibrary.com/) which is patented and probably therefore not usable + +[Here](https://jcgt.org/published/0006/02/02/paper.pdf) is the whitepaper of the Slug library. There is also +a [poster](http://sluglibrary.com/slug_algorithm.pdf) about it. There also exists +an [open implementation](https://github.com/mightycow/Sluggish). + +### Draw text using a Web Canvas + +This approach has the downside that we can not dynamically scale rendered fonts according to the current zoom level. + + +## Other Approaches + +* [16x AA font rendering using coverage masks](https://superluminal.eu/16x-aa-font-rendering-using-coverage-masks-part-iii/) \ No newline at end of file diff --git a/docs/src/development-documents/index.md b/docs/src/development-documents/index.md new file mode 100644 index 00000000..68a29aa1 --- /dev/null +++ b/docs/src/development-documents/index.md @@ -0,0 +1 @@ +# Development Documents \ No newline at end of file diff --git a/docs/src/stencil-masking.md b/docs/src/development-documents/stencil-masking.md similarity index 100% rename from docs/src/stencil-masking.md rename to docs/src/development-documents/stencil-masking.md diff --git a/docs/src/building.md b/docs/src/development-guide/building.md similarity index 100% rename from docs/src/building.md rename to docs/src/development-guide/building.md diff --git a/docs/src/development-guide/debugging.md b/docs/src/development-guide/debugging.md new file mode 100644 index 00000000..adb11d0d --- /dev/null +++ b/docs/src/development-guide/debugging.md @@ -0,0 +1,13 @@ +# Debugging + + + +## Frame Profiling + + +## CPU Profiling + +## GPU Profiling + +* For WebGL there is SpectorJS is enabled by default right now. For debugging on a desktop environment you can use +[RenderDoc](https://renderdoc.org/). \ No newline at end of file diff --git a/docs/src/development-guide/index.md b/docs/src/development-guide/index.md new file mode 100644 index 00000000..79a9975b --- /dev/null +++ b/docs/src/development-guide/index.md @@ -0,0 +1 @@ +# Development Guide diff --git a/docs/src/introduction.md b/docs/src/introduction.md index e10b99d0..3d07efe5 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1 +1,2 @@ # Introduction +