From c3edea26e58feabab3df04b6d77ea15cfeecba4d Mon Sep 17 00:00:00 2001 From: Drabble Date: Thu, 12 May 2022 15:38:10 +0200 Subject: [PATCH] Improve the Cargo documentation (#87) * Improve the Cargo documentation * Fix mistakes with merge on main branch * Fix the guide book url within the API documentation * Update the documentation on `QuadKey` --- maplibre-winit/src/input/mod.rs | 2 + maplibre-winit/src/input/pan_handler.rs | 4 -- maplibre/build.rs | 7 +++- maplibre/src/benchmarking.rs | 4 ++ maplibre/src/coords.rs | 10 ++++- maplibre/src/error.rs | 1 + maplibre/src/io/geometry_index.rs | 28 ++++++++++---- maplibre/src/io/mod.rs | 9 ++++- maplibre/src/io/scheduler.rs | 4 ++ maplibre/src/io/shared_thread_state.rs | 3 ++ maplibre/src/io/source_client.rs | 19 +++++++--- maplibre/src/io/static_tile_fetcher.rs | 7 ++++ maplibre/src/io/tile_cache.rs | 14 +++++++ maplibre/src/io/tile_request_state.rs | 3 ++ maplibre/src/lib.rs | 37 +++++++++++++++++++ maplibre/src/map_state.rs | 10 ++++- maplibre/src/platform/mod.rs | 14 ++++--- .../src/platform/noweb/schedule_method.rs | 1 + maplibre/src/render/texture.rs | 2 +- maplibre/src/style/layer.rs | 4 ++ maplibre/src/style/mod.rs | 2 + maplibre/src/style/source.rs | 16 +++++--- maplibre/src/style/style.rs | 3 ++ maplibre/src/tessellation/mod.rs | 3 ++ maplibre/src/tessellation/zero_tessellator.rs | 3 ++ maplibre/src/window.rs | 4 ++ web/src/platform/pool.rs | 2 +- 27 files changed, 181 insertions(+), 35 deletions(-) diff --git a/maplibre-winit/src/input/mod.rs b/maplibre-winit/src/input/mod.rs index 9cf694e7..c3e0b979 100644 --- a/maplibre-winit/src/input/mod.rs +++ b/maplibre-winit/src/input/mod.rs @@ -56,6 +56,8 @@ impl InputController { false } + /// Process the given winit `[winit::event::WindowEvent]`. + /// Returns true if the event has been processed and false otherwise. pub fn window_input(&mut self, event: &WindowEvent) -> bool { match event { WindowEvent::CursorMoved { position, .. } => { diff --git a/maplibre-winit/src/input/pan_handler.rs b/maplibre-winit/src/input/pan_handler.rs index d630c00b..bc9188bd 100644 --- a/maplibre-winit/src/input/pan_handler.rs +++ b/maplibre-winit/src/input/pan_handler.rs @@ -97,10 +97,6 @@ impl PanHandler { return false; } - if !self.is_panning { - // starting to pan - } - if *state == ElementState::Pressed { // currently panning or starting to pan self.is_panning = true; diff --git a/maplibre/build.rs b/maplibre/build.rs index cbda4dbf..b949e1a4 100644 --- a/maplibre/build.rs +++ b/maplibre/build.rs @@ -1,3 +1,8 @@ +//! # Build +//! +//! This script is built and executed just before building the package. +//! It will validate the WGSL (WebGPU Shading Language) shaders and embed static files. + use std::path::{Path, PathBuf}; use std::{env, fs}; @@ -8,7 +13,7 @@ const MUNICH_X: u32 = 17425; const MUNICH_Y: u32 = 11365; const MUNICH_Z: u8 = 15; -/// Tiles which can be used by StaticTileFetcher +/// Tiles which can be used by StaticTileFetcher. fn clean_static_tiles() -> PathBuf { let out_dir = env::var("OUT_DIR").unwrap(); diff --git a/maplibre/src/benchmarking.rs b/maplibre/src/benchmarking.rs index 692670ae..a1bb6cec 100644 --- a/maplibre/src/benchmarking.rs +++ b/maplibre/src/benchmarking.rs @@ -1,7 +1,11 @@ +//! Collection of utilities used to perform certain calculations more conveniently. + +/// Re-export of the io module. pub mod io { pub use crate::io::*; } +/// Re-export of the tessellation module. pub mod tessellation { pub use crate::tessellation::*; } diff --git a/maplibre/src/coords.rs b/maplibre/src/coords.rs index f03c50a7..acd76c42 100644 --- a/maplibre/src/coords.rs +++ b/maplibre/src/coords.rs @@ -1,4 +1,4 @@ -//! File which exposes all kinds of coordinates used throughout maplibre-rs +//! Provides utilities related to coordinates. use std::fmt; use std::fmt::Formatter; @@ -31,6 +31,11 @@ const fn create_zoom_bounds() -> [u32; DIM] { result } +/// Represents the position of a node within a quad tree. The first u8 defines the `ZoomLevel` of the node. +/// The remaining bytes define which part (north west, south west, south east, north east) of each +/// subdivision of the quadtree is concerned. +/// +/// TODO: We can optimize the quadkey and store the keys on 2 bits instead of 8 #[derive(Ord, PartialOrd, Eq, PartialEq, Clone, Copy)] pub struct Quadkey([u8; MAX_ZOOM]); @@ -55,6 +60,8 @@ impl fmt::Debug for Quadkey { } } +/// `Zoom` is an exponential scale that defines the zoom of the camera on the map. +/// We can derive the `ZoomLevel` from `Zoom` by using the `[crate::coords::ZOOM_BOUNDS]`. #[derive(Copy, Clone, Debug)] pub struct Zoom(f64); @@ -439,6 +446,7 @@ impl From> for WorldCoords { } } +/// Defines a bounding box on a tiled map with a [`ZoomLevel`] and a padding. #[derive(Debug)] pub struct ViewRegion { min_tile: WorldTileCoords, diff --git a/maplibre/src/error.rs b/maplibre/src/error.rs index 23086c60..9827ea3f 100644 --- a/maplibre/src/error.rs +++ b/maplibre/src/error.rs @@ -30,6 +30,7 @@ impl RenderError { } } +/// Enumeration of errors which can happen during the operation of the library. #[derive(Debug)] pub enum Error { Schedule, diff --git a/maplibre/src/io/geometry_index.rs b/maplibre/src/io/geometry_index.rs index 4ab45bd4..6febc93a 100644 --- a/maplibre/src/io/geometry_index.rs +++ b/maplibre/src/io/geometry_index.rs @@ -1,3 +1,5 @@ +//! Geometry index. + use std::collections::{BTreeMap, HashMap}; use cgmath::num_traits::Signed; @@ -12,6 +14,7 @@ use rstar::{Envelope, PointDistance, RTree, RTreeObject, AABB}; use crate::coords::{InnerCoords, Quadkey, WorldCoords, WorldTileCoords, Zoom, EXTENT, TILE_SIZE}; use crate::util::math::bounds_from_points; +/// A quad tree storing the currently loaded tiles. pub struct GeometryIndex { index: BTreeMap, } @@ -55,6 +58,11 @@ impl GeometryIndex { } } +/// Index of tiles which can be of two types: spatial or linear. +/// Spatial tiles are stored in a multi-dimentional tree which represents their position in the tile. +/// Linear tiles are simply stored in a vector. +/// +/// A spatial tile index can theoretically improve query performance on tiles. Practically it could be slower though. The `Spatial` index is experimental and currently unused. pub enum TileIndex { Spatial { tree: RTree> }, Linear { list: Vec> }, @@ -85,6 +93,8 @@ impl TileIndex { } } +/// An indexed geometry contains an exact vector geometry, computed bounds which +/// can be helpful when interacting with the geometry and a hashmap of properties. #[derive(Debug, Clone)] pub struct IndexedGeometry where @@ -95,6 +105,7 @@ where pub properties: HashMap, } +/// Contains either a polygon or line vector. #[derive(Debug, Clone)] pub enum ExactGeometry where @@ -158,6 +169,7 @@ where } } +/// A processor able to create geometries using `[geozero::geo_types::GeoWriter]`. pub struct IndexProcessor { geo_writer: GeoWriter, geometries: Vec>, @@ -236,36 +248,36 @@ impl PropertyProcessor for IndexProcessor { } impl FeatureProcessor for IndexProcessor { - /// Begin of dataset processing + /// Begin of dataset processing. fn dataset_begin(&mut self, _name: Option<&str>) -> Result<(), GeozeroError> { Ok(()) } - /// End of dataset processing + /// End of dataset processing. fn dataset_end(&mut self) -> Result<(), GeozeroError> { Ok(()) } - /// Begin of feature processing + /// Begin of feature processing. fn feature_begin(&mut self, _idx: u64) -> Result<(), GeozeroError> { Ok(()) } - /// End of feature processing + /// End of feature processing. fn feature_end(&mut self, _idx: u64) -> Result<(), GeozeroError> { Ok(()) } - /// Begin of feature property processing + /// Begin of feature property processing. fn properties_begin(&mut self) -> Result<(), GeozeroError> { self.properties = Some(HashMap::new()); Ok(()) } - /// End of feature property processing + /// End of feature property processing. fn properties_end(&mut self) -> Result<(), GeozeroError> { Ok(()) } - /// Begin of feature geometry processing + /// Begin of feature geometry processing. fn geometry_begin(&mut self) -> Result<(), GeozeroError> { Ok(()) } - /// End of feature geometry processing + /// End of feature geometry processing. fn geometry_end(&mut self) -> Result<(), GeozeroError> { let geometry = self.geo_writer.geometry().cloned().unwrap(); diff --git a/maplibre/src/io/mod.rs b/maplibre/src/io/mod.rs index fd215494..f132d59c 100644 --- a/maplibre/src/io/mod.rs +++ b/maplibre/src/io/mod.rs @@ -18,6 +18,7 @@ pub mod shared_thread_state; pub mod tile_cache; pub mod tile_request_state; +/// Contains a `Tile` if the fetch was successful otherwise `Unavailable`. pub enum TileFetchResult { Unavailable { coords: WorldTileCoords, @@ -41,16 +42,20 @@ impl fmt::Debug for TileFetchResult { } } +/// [crate::io::TileTessellateMessage] or [crate::io::LayerTessellateMessage] tessellation message. pub enum TessellateMessage { Tile(TileTessellateMessage), Layer(LayerTessellateMessage), } +/// The result of the tessellation of a tile. pub struct TileTessellateMessage { pub request_id: TileRequestID, pub coords: WorldTileCoords, } +/// `TessellatedLayer` contains the result of the tessellation for a specific layer, otherwise +/// `UnavailableLayer` if the layer doesn't exist. pub enum LayerTessellateMessage { UnavailableLayer { coords: WorldTileCoords, @@ -59,7 +64,7 @@ pub enum LayerTessellateMessage { TessellatedLayer { coords: WorldTileCoords, buffer: OverAlignedVertexBuffer, - /// Holds for each feature the count of indices + /// Holds for each feature the count of indices. feature_indices: Vec, layer_data: tile::Layer, }, @@ -87,6 +92,7 @@ impl LayerTessellateMessage { } } +/// A request for a tile at the given coordinates and in the given layers. #[derive(Clone)] pub struct TileRequest { pub coords: WorldTileCoords, @@ -99,4 +105,5 @@ impl fmt::Debug for TileRequest { } } +/// The ID format for a tile request. pub type TileRequestID = u32; diff --git a/maplibre/src/io/scheduler.rs b/maplibre/src/io/scheduler.rs index 972d62a3..31c18081 100644 --- a/maplibre/src/io/scheduler.rs +++ b/maplibre/src/io/scheduler.rs @@ -1,9 +1,12 @@ +//! Scheduling. + use std::future::Future; use crate::error::Error; use crate::io::shared_thread_state::SharedThreadState; +/// Async/await scheduler. pub struct Scheduler where SM: ScheduleMethod, @@ -24,6 +27,7 @@ where } } +/// Can schedule a task from a future factory and a shared state. pub trait ScheduleMethod: 'static { #[cfg(not(feature = "no-thread-safe-futures"))] fn schedule( diff --git a/maplibre/src/io/shared_thread_state.rs b/maplibre/src/io/shared_thread_state.rs index 64896940..97e9fdeb 100644 --- a/maplibre/src/io/shared_thread_state.rs +++ b/maplibre/src/io/shared_thread_state.rs @@ -1,3 +1,5 @@ +//! Shared thread state. + use crate::coords::{WorldCoords, WorldTileCoords, Zoom}; use crate::error::Error; use crate::io::geometry_index::{GeometryIndex, IndexProcessor, IndexedGeometry, TileIndex}; @@ -14,6 +16,7 @@ use geozero::GeozeroDatasource; use prost::Message; use std::sync::{mpsc, Arc, Mutex}; +/// Stores and provides access to the thread safe data shared between the schedulers. #[derive(Clone)] pub struct SharedThreadState { pub tile_request_state: Arc>, diff --git a/maplibre/src/io/source_client.rs b/maplibre/src/io/source_client.rs index ceaaf62a..44662bf9 100644 --- a/maplibre/src/io/source_client.rs +++ b/maplibre/src/io/source_client.rs @@ -1,22 +1,27 @@ +//! HTTP client. + use crate::coords::WorldTileCoords; use crate::error::Error; use crate::style::source::TileAddressingScheme; use async_trait::async_trait; +/// A closure that returns a HTTP client. pub type HTTPClientFactory = dyn Fn() -> HC; -// On the web platform futures are not thread-safe (i.e. not Send). This means we need to tell -// async_trait that these bounds should not be placed on the async trait: -// https://github.com/dtolnay/async-trait/blob/b70720c4c1cc0d810b7446efda44f81310ee7bf2/README.md#non-threadsafe-futures -// -// Users of this library can decide whether futures from the HTTPClient are thread-safe or not via -// the future "no-thread-safe-futures". Tokio futures are thread-safe. +/// On the web platform futures are not thread-safe (i.e. not Send). This means we need to tell +/// async_trait that these bounds should not be placed on the async trait: +/// [https://github.com/dtolnay/async-trait/blob/b70720c4c1cc0d810b7446efda44f81310ee7bf2/README.md#non-threadsafe-futures](https://github.com/dtolnay/async-trait/blob/b70720c4c1cc0d810b7446efda44f81310ee7bf2/README.md#non-threadsafe-futures) +/// +/// Users of this library can decide whether futures from the HTTPClient are thread-safe or not via +/// the future "no-thread-safe-futures". Tokio futures are thread-safe. #[cfg_attr(feature = "no-thread-safe-futures", async_trait(?Send))] #[cfg_attr(not(feature = "no-thread-safe-futures"), async_trait)] pub trait HTTPClient: Clone + Sync + Send + 'static { async fn fetch(&self, url: &str) -> Result, Error>; } +/// Gives access to the HTTP client which can be of multiple types, +/// see [crates::io::source_client::SourceClient] #[derive(Clone)] pub struct HttpSourceClient where @@ -25,6 +30,8 @@ where inner_client: HC, } +/// Defines the different types of HTTP clients such as basic HTTP and Mbtiles. +/// More types might be coming such as S3 and other cloud http clients. #[derive(Clone)] pub enum SourceClient where diff --git a/maplibre/src/io/static_tile_fetcher.rs b/maplibre/src/io/static_tile_fetcher.rs index f49a8169..b95c09d9 100644 --- a/maplibre/src/io/static_tile_fetcher.rs +++ b/maplibre/src/io/static_tile_fetcher.rs @@ -1,3 +1,5 @@ +//! Static tile fetcher + use std::concat; use std::env; @@ -13,6 +15,7 @@ static TILES: Dir = include_dir!("$OUT_DIR/extracted-tiles"); #[cfg(not(static_tiles))] static TILES: Dir = Dir::new("/path", &[]); +/// Load PBF files which were statically embedded in the `build.rs` #[derive(Default)] pub struct StaticTileFetcher; @@ -25,10 +28,14 @@ impl StaticTileFetcher { Self {} } + /// Fetch the tile static file asynchrounously and returns a vector of bytes or a network error if the file + /// could not be fetched. pub async fn fetch_tile(&self, coords: &TileCoords) -> Result, Error> { self.sync_fetch_tile(coords) } + /// Fetch the tile static file and returns a vector of bytes or a network error if the file + /// could not be fetched. pub fn sync_fetch_tile(&self, coords: &TileCoords) -> Result, Error> { if TILES.entries().is_empty() { log::error!( diff --git a/maplibre/src/io/tile_cache.rs b/maplibre/src/io/tile_cache.rs index 966c0e5b..2166b391 100644 --- a/maplibre/src/io/tile_cache.rs +++ b/maplibre/src/io/tile_cache.rs @@ -1,9 +1,12 @@ +//! Tile cache. + use crate::coords::{Quadkey, WorldTileCoords}; use crate::io::LayerTessellateMessage; use std::collections::{btree_map, BTreeMap, HashSet}; +/// Stores the multiple [crate::io::LayerTessellateMessage] of a cached tile. pub struct CachedTile { layers: Vec, } @@ -16,6 +19,7 @@ impl CachedTile { } } +/// Stores and provides access to a quad tree of cached tiles with world tile coords. #[derive(Default)] pub struct TileCache { cache: BTreeMap, @@ -28,6 +32,11 @@ impl TileCache { } } + /// Inserts a tessellated layer into the quad tree at its world tile coords. + /// If the space is vacant, the tessellated layer is inserted into a new + /// [crate::io::tile_cache::CachedTile]. + /// If the space is occupied, the tessellated layer is added to the current + /// [crate::io::tile_cache::CachedTile]. pub fn put_tessellated_layer(&mut self, message: LayerTessellateMessage) { if let Some(entry) = message .get_coords() @@ -45,6 +54,8 @@ impl TileCache { } } + /// Returns the list of tessellated layers at the given world tile coords. None if tile is + /// missing from the cache. pub fn iter_tessellated_layers_at( &self, coords: &WorldTileCoords, @@ -55,6 +66,8 @@ impl TileCache { .map(|results| results.layers.iter()) } + /// Removes all the cached tessellate layers that are not contained within the given + /// layers hashset. pub fn retain_missing_layer_names( &self, coords: &WorldTileCoords, @@ -71,6 +84,7 @@ impl TileCache { } } + /// Checks if a layer is missing from the given layers set at the given coords. pub fn is_layers_missing(&self, coords: &WorldTileCoords, layers: &HashSet) -> bool { if let Some(cached_tile) = coords.build_quad_key().and_then(|key| self.cache.get(&key)) { let tessellated_set: HashSet<&str> = cached_tile diff --git a/maplibre/src/io/tile_request_state.rs b/maplibre/src/io/tile_request_state.rs index 8433d185..382aa208 100644 --- a/maplibre/src/io/tile_request_state.rs +++ b/maplibre/src/io/tile_request_state.rs @@ -1,7 +1,10 @@ +//! Tile request state. + use crate::coords::WorldTileCoords; use crate::io::{TileRequest, TileRequestID}; use std::collections::{HashMap, HashSet}; +/// Stores a map of pending requests, coords and the current tile being requested. #[derive(Default)] pub struct TileRequestState { current_id: TileRequestID, diff --git a/maplibre/src/lib.rs b/maplibre/src/lib.rs index 0014e2ff..ecc03686 100644 --- a/maplibre/src/lib.rs +++ b/maplibre/src/lib.rs @@ -1,3 +1,21 @@ +//! # Maplibre-rs +//! +//! A multi-platform library for rendering vector tile maps with WebGPU. +//! +//! Maplibre-rs is a map renderer that can run natively on MacOS, Linux, Windows, Android, iOS and the web. +//! It takes advantage of Lyon to tessellate vector tiles and WebGPU to display them efficiently. +//! Maplibre-rs also has an headless mode (*work in progress*) that can generate rasters. +//! +//! The official guide book can be found [here](https://maxammann.org/maplibre-rs/docs/). +//! +//! ### Example +//! +//! To import maplibre-rs in your `Cargo.toml`: +//! +//! ```toml +//! maplibre = "0.0.2" +//! ``` + use crate::io::scheduler::{ScheduleMethod, Scheduler}; use crate::io::source_client::HTTPClient; use crate::map_state::MapState; @@ -23,6 +41,7 @@ pub(crate) mod tessellation; pub(crate) mod tilejson; pub(crate) mod util; +/// Map's configuration and execution. pub struct Map where W: MapWindow, @@ -39,19 +58,34 @@ where SM: ScheduleMethod, HC: HTTPClient, { + /// Starts the [`crate::map_state::MapState`] Runnable with the configured event loop. pub fn run(self) { self.run_with_optionally_max_frames(None); } + /// Starts the [`crate::map_state::MapState`] Runnable with the configured event loop. + /// + /// # Arguments + /// + /// * `max_frames` - Maximum number of frames per second. pub fn run_with_max_frames(self, max_frames: u64) { self.run_with_optionally_max_frames(Some(max_frames)); } + /// Starts the MapState Runnable with the configured event loop. + /// + /// # Arguments + /// + /// * `max_frames` - Optional maximum number of frames per second. pub fn run_with_optionally_max_frames(self, max_frames: Option) { self.window.run(self.map_state, max_frames); } } +/// Stores the map configuration before the map's state has been fully initialized. +/// +/// FIXME: We could maybe remove this class, and store the render_state in an Optional in [`crate::map_state::MapState`]. +/// FIXME: I think we can find a workaround so that this class doesn't exist. pub struct UninitializedMap where MWC: MapWindowConfig, @@ -71,6 +105,8 @@ where SM: ScheduleMethod, HC: HTTPClient, { + /// Initializes the whole rendering pipeline for the given configuration. + /// Returns the initialized map, ready to be run. pub async fn initialize(self) -> Map { let instance = wgpu::Instance::new(wgpu::Backends::all()); //let instance = wgpu::Instance::new(wgpu::Backends::GL); @@ -157,6 +193,7 @@ where self } + /// Builds the UninitializedMap with the given configuration. pub fn build(self) -> UninitializedMap { let scheduler = self .scheduler diff --git a/maplibre/src/map_state.rs b/maplibre/src/map_state.rs index 38c39d9b..74d2fe05 100644 --- a/maplibre/src/map_state.rs +++ b/maplibre/src/map_state.rs @@ -1,3 +1,5 @@ +//! Stores the state of the map such as `[crate::coords::Zoom]`, `[crate::camera::Camera]`, `[crate::style::Style]`, `[crate::io::tile_cache::TileCache]` and more. + use crate::coords::{ViewRegion, WorldTileCoords, Zoom, TILE_SIZE}; use crate::error::Error; use crate::io::geometry_index::GeometryIndex; @@ -14,9 +16,9 @@ use crate::style::Style; use crate::util::ChangeObserver; use crate::{MapWindow, MapWindowConfig, ScheduleMethod, WindowSize}; use std::collections::HashSet; - use std::sync::{mpsc, Arc, Mutex}; +/// Stores the camera configuration. pub struct ViewState { zoom: ChangeObserver, pub camera: ChangeObserver, @@ -42,6 +44,10 @@ impl ViewState { } } +/// Stores the state of the map, dispatches tile fetching and caching, tessellation and drawing. +/// +/// FIXME: MapState may not follow the Single-responsibility principle, as it not only stores +/// the state of the map but also the rendering, caching, etc. pub struct MapState where MWC: MapWindowConfig, @@ -164,7 +170,7 @@ where } } - /// Request tiles which are currently in view + /// Request tiles which are currently in view. #[tracing::instrument(skip_all)] fn request_tiles_in_view(&mut self, view_region: &ViewRegion) -> bool { let mut try_failed = false; diff --git a/maplibre/src/platform/mod.rs b/maplibre/src/platform/mod.rs index 1da94654..c71fed8c 100644 --- a/maplibre/src/platform/mod.rs +++ b/maplibre/src/platform/mod.rs @@ -1,5 +1,5 @@ -//! This module handles platform specific code. Depending on the compilation target different -//! parts of this module are used +//! Handles platform specific code. Depending on the compilation target, different +//! parts of this module are used. // WebGPU #[cfg(all(target_arch = "wasm32", not(feature = "web-webgl")))] @@ -13,7 +13,7 @@ pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8 #[cfg(target_os = "android")] pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm; -// macOS and iOS (Metal) +/// MacOS and iOS (Metal). #[cfg(any(target_os = "macos", target_os = "ios"))] pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Bgra8UnormSrgb; @@ -29,11 +29,13 @@ pub const COLOR_TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Bgra8 #[cfg(not(target_arch = "wasm32"))] mod noweb; +/// Http client for non-web targets. pub mod http_client { #[cfg(not(target_arch = "wasm32"))] pub use super::noweb::http_client::*; } +/// Scheduler for non-web targets. pub mod schedule_method { #[cfg(not(target_arch = "wasm32"))] pub use super::noweb::schedule_method::*; @@ -42,6 +44,8 @@ pub mod schedule_method { #[cfg(not(target_arch = "wasm32"))] pub use noweb::run_multithreaded; -// FIXME: This limit is enforced by WebGL. Actually this makes sense! -// FIXME: This can also be achieved by _pad attributes in shader_ffi.rs +/// Minimum WebGPU buffer size +/// +/// FIXME: This limit is enforced by WebGL. Actually this makes sense! +/// FIXME: This can also be achieved by _pad attributes in shader_ffi.rs pub const MIN_BUFFER_SIZE: u64 = 32; diff --git a/maplibre/src/platform/noweb/schedule_method.rs b/maplibre/src/platform/noweb/schedule_method.rs index fd55cfa8..09d3fba1 100644 --- a/maplibre/src/platform/noweb/schedule_method.rs +++ b/maplibre/src/platform/noweb/schedule_method.rs @@ -3,6 +3,7 @@ use crate::io::shared_thread_state::SharedThreadState; use crate::ScheduleMethod; use std::future::Future; +/// Multi-threading with Tokio. pub struct TokioScheduleMethod; impl TokioScheduleMethod { diff --git a/maplibre/src/render/texture.rs b/maplibre/src/render/texture.rs index 06a0a5d9..3e3e44bc 100644 --- a/maplibre/src/render/texture.rs +++ b/maplibre/src/render/texture.rs @@ -32,7 +32,7 @@ impl Texture { } } - /// Creates a texture that uses MSAA and fits a given swap chain + /// Creates a texture that uses MSAA and fits a given swap chain. pub fn create_multisampling_texture( device: &wgpu::Device, desc: &wgpu::SurfaceConfiguration, diff --git a/maplibre/src/style/layer.rs b/maplibre/src/style/layer.rs index 1c1a35a4..39454bbf 100644 --- a/maplibre/src/style/layer.rs +++ b/maplibre/src/style/layer.rs @@ -1,3 +1,5 @@ +//! Vector tile layer drawing utilities. + use cint::{Alpha, EncodedSrgb}; use csscolorparser::Color; use serde::{Deserialize, Serialize}; @@ -27,6 +29,7 @@ pub struct LinePaint { // TODO a lot } +/// The different types of paints. #[derive(Serialize, Deserialize, Debug, Clone)] #[serde(tag = "type", content = "paint")] pub enum LayerPaint { @@ -51,6 +54,7 @@ impl LayerPaint { } } +/// Stores all the styles for a specific layer. #[derive(Serialize, Deserialize, Debug, Clone)] pub struct StyleLayer { #[serde(skip)] diff --git a/maplibre/src/style/mod.rs b/maplibre/src/style/mod.rs index be030362..6adcdcb6 100644 --- a/maplibre/src/style/mod.rs +++ b/maplibre/src/style/mod.rs @@ -1,3 +1,5 @@ +//! Vector tile format styling. + pub mod layer; pub mod source; mod style; diff --git a/maplibre/src/style/source.rs b/maplibre/src/style/source.rs index 1addc341..b612b1b4 100644 --- a/maplibre/src/style/source.rs +++ b/maplibre/src/style/source.rs @@ -1,9 +1,14 @@ +//! Vector tile data utilities. + use serde::{Deserialize, Serialize}; +/// String url to a tile. pub type TileUrl = String; +/// String url to a JSON tile. pub type TileJSONUrl = String; +/// Tiles can be positioned using either the xyz coordinates or the TMS (Tile Map Service) protocol. #[derive(Serialize, Deserialize, Debug, Clone)] pub enum TileAddressingScheme { #[serde(rename = "xyz")] @@ -18,18 +23,19 @@ impl Default for TileAddressingScheme { } } +/// Source properties for tiles or rasters. #[derive(Serialize, Deserialize, Debug, Clone)] pub struct VectorSource { - /// String which contains attribution information for the used tiles + /// String which contains attribution information for the used tiles. #[serde(skip_serializing_if = "Option::is_none")] pub attribution: Option, - /// The bounds in which tiles are available + /// The bounds in which tiles are available. #[serde(skip_serializing_if = "Option::is_none")] pub bounds: Option<(f64, f64, f64, f64)>, - /// Max zoom level at which tiles are available + /// Max zoom level at which tiles are available. #[serde(skip_serializing_if = "Option::is_none")] pub maxzoom: Option, - /// Min zoom level at which tiles are available + /// Min zoom level at which tiles are available. #[serde(skip_serializing_if = "Option::is_none")] pub minzoom: Option, // TODO: promoteId @@ -49,5 +55,5 @@ pub enum Source { #[serde(rename = "vector")] Vector(VectorSource), #[serde(rename = "raster")] - Raster(VectorSource), + Raster(VectorSource), // FIXME: Does it make sense that a raster have a VectorSource? } diff --git a/maplibre/src/style/style.rs b/maplibre/src/style/style.rs index 3b15e65d..0de67453 100644 --- a/maplibre/src/style/style.rs +++ b/maplibre/src/style/style.rs @@ -1,3 +1,5 @@ +//! Default vector tile styles configuration. + use crate::style::layer::{LayerPaint, LinePaint, StyleLayer}; use crate::style::source::Source; use csscolorparser::Color; @@ -5,6 +7,7 @@ use serde::{Deserialize, Serialize}; use std::collections::HashMap; use std::str::FromStr; +/// Stores the style for a multi-layered map. #[derive(Serialize, Deserialize, Debug, Clone)] pub struct Style { pub version: u16, diff --git a/maplibre/src/tessellation/mod.rs b/maplibre/src/tessellation/mod.rs index a1ba1f2b..62c84502 100644 --- a/maplibre/src/tessellation/mod.rs +++ b/maplibre/src/tessellation/mod.rs @@ -15,8 +15,10 @@ pub mod zero_tessellator; const DEFAULT_TOLERANCE: f32 = 0.02; +/// Vertex buffers index data type. pub type IndexDataType = u32; // Must match INDEX_FORMAT +/// An element that can be tessellated into vertex buffers. pub trait Tessellated { /// Returns a vertex buffer which represents some object like a layer. Each object can contain /// multiple features. For each feature also the amount of indices is returned. @@ -24,6 +26,7 @@ pub trait Tessellated { fn tessellate(&self) -> Result<(VertexBuffers, Vec), Error>; } +/// Constructor for Fill and Stroke vertices. pub struct VertexConstructor {} impl FillVertexConstructor for VertexConstructor { diff --git a/maplibre/src/tessellation/zero_tessellator.rs b/maplibre/src/tessellation/zero_tessellator.rs index b6af5f13..e9476b68 100644 --- a/maplibre/src/tessellation/zero_tessellator.rs +++ b/maplibre/src/tessellation/zero_tessellator.rs @@ -1,3 +1,5 @@ +//! Tessellator implementation. + use geozero::{FeatureProcessor, GeomProcessor, PropertyProcessor}; use lyon::geom; @@ -15,6 +17,7 @@ use crate::tessellation::{VertexConstructor, DEFAULT_TOLERANCE}; type GeoResult = geozero::error::Result; +/// Build tessellations with vectors. pub struct ZeroTessellator + MaxIndex> { path_builder: RefCell, path_open: bool, diff --git a/maplibre/src/window.rs b/maplibre/src/window.rs index 6c5bd667..b40a05f3 100644 --- a/maplibre/src/window.rs +++ b/maplibre/src/window.rs @@ -1,5 +1,8 @@ +//! Utilities for the window system. + use crate::{HTTPClient, MapState, ScheduleMethod}; +/// Window with an optional [carte::window::WindowSize]. pub trait MapWindow { type EventLoop; type Window: raw_window_handle::HasRawWindowHandle; @@ -25,6 +28,7 @@ where fn run(self, map_state: MapState, max_frames: Option); } +/// Window size with a width and an height in pixels. #[derive(Clone, Copy)] pub struct WindowSize { width: u32, diff --git a/web/src/platform/pool.rs b/web/src/platform/pool.rs index 2fc63201..9c6f43ec 100644 --- a/web/src/platform/pool.rs +++ b/web/src/platform/pool.rs @@ -62,7 +62,7 @@ impl WorkerPool { Ok(pool) } - /// Unconditionally spawns a new worker + /// Unconditionally spawns a new worker. /// /// The worker isn't registered with this `WorkerPool` but is capable of /// executing work for this wasm module.