Skip to content

Commit 28e6a19

Browse files
louwerslouwers
committed
Add some documentation
1 parent 1f17ad9 commit 28e6a19

File tree

4 files changed

+236
-9
lines changed

4 files changed

+236
-9
lines changed

‎platform/ios/MapLibre.docc/MapLibre.md

+1
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Powerful, free and open-source mapping toolkit with full control over data sourc
5151

5252
### Advanced
5353

54+
- <doc:ObserverExample>
5455
- <doc:CustomStyleLayerExample>
5556

5657
### Other Articles

‎platform/ios/MapLibre.docc/ObserverExample.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Observe Low-Level Events
2+
3+
Learn about the ``MLNMapViewDelegate`` methods for observing map events.
4+
5+
> Warning: These methods are not thread-safe.
6+
7+
You can observe certain low-level events as they happen. Use these methods to collect metrics or investigate issues during map rendering. This feature is intended primarily for power users. We are always interested in improving observability, so if you have a special use case, feel free to [open an issue or pull request](https://github.com/maplibre/maplibre-native) to extend the types of observability methods.
8+
9+
## Shader Events
10+
11+
Observe shader compilation with ``MLNMapViewDelegate/mapView:shaderWillCompile:backend:defines:`` and ``MLNMapViewDelegate/mapView:shaderDidCompile:backend:defines:``.
12+
13+
<!-- include-example(ObserverExampleShaders) -->
14+
15+
```swift
16+
func mapView(_: MLNMapView, shaderWillCompile id: Int, backend: Int, defines: String) {
17+
print("A new shader is being compiled - shaderID:\(id), backend type:\(backend), program configuration:\(defines)")
18+
}
19+
20+
func mapView(_: MLNMapView, shaderDidCompile id: Int, backend: Int, defines: String) {
21+
print("A shader has been compiled - shaderID:\(id), backend type:\(backend), program configuration:\(defines)")
22+
}
23+
```
24+
25+
See also: ``MLNMapViewDelegate/mapView:shaderDidFailCompile:backend:defines:``.
26+
27+
## Glyph Loading
28+
29+
Observe glyph loading events with ``MLNMapViewDelegate/mapView:glyphsWillLoad:range:`` and ``MLNMapViewDelegate/mapView:glyphsDidLoad:range:``.
30+
31+
<!-- include-example(ObserverExampleGlyphs) -->
32+
33+
```swift
34+
func mapView(_: MLNMapView, glyphsWillLoad fontStack: [String], range: NSRange) {
35+
print("Glyphs are being requested for the font stack \(fontStack), ranging from \(range.location) to \(range.location + range.length)")
36+
}
37+
38+
func mapView(_: MLNMapView, glyphsDidLoad fontStack: [String], range: NSRange) {
39+
print("Glyphs have been loaded for the font stack \(fontStack), ranging from \(range.location) to \(range.location + range.length)")
40+
}
41+
```
42+
43+
See also: ``MLNMapViewDelegate/mapView:glyphsDidError:range:``.
44+
45+
## Tile Events
46+
47+
Monitor tile-related actions using the delegate method ``MLNMapViewDelegate/mapView:tileDidTriggerAction:x:y:z:wrap:overscaledZ:sourceID:`` with the ``MLNTileOperation`` type.
48+
49+
<!-- include-example(ObserverExampleTiles) -->
50+
51+
```swift
52+
func mapView(_: MLNMapView, tileDidTriggerAction operation: MLNTileOperation,
53+
x: Int,
54+
y: Int,
55+
z: Int,
56+
wrap: Int,
57+
overscaledZ: Int,
58+
sourceID: String)
59+
{
60+
let tileStr = String(format: "(x: %ld, y: %ld, z: %ld, wrap: %ld, overscaledZ: %ld, sourceID: %@)",
61+
x, y, z, wrap, overscaledZ, sourceID)
62+
63+
switch operation {
64+
case MLNTileOperation.requestedFromCache:
65+
print("Requesting tile \(tileStr) from cache")
66+
67+
case MLNTileOperation.requestedFromNetwork:
68+
print("Requesting tile \(tileStr) from network")
69+
70+
case MLNTileOperation.loadFromCache:
71+
print("Loading tile \(tileStr), requested from the cache")
72+
73+
case MLNTileOperation.loadFromNetwork:
74+
print("Loading tile \(tileStr), requested from the network")
75+
76+
case MLNTileOperation.startParse:
77+
print("Parsing tile \(tileStr)")
78+
79+
case MLNTileOperation.endParse:
80+
print("Completed parsing tile \(tileStr)")
81+
82+
case MLNTileOperation.error:
83+
print("An error occured during proccessing for tile \(tileStr)")
84+
85+
case MLNTileOperation.cancelled:
86+
print("Pending work on tile \(tileStr)")
87+
88+
case MLNTileOperation.nullOp:
89+
print("An unknown tile operation was emitted for tile \(tileStr)")
90+
91+
@unknown default:
92+
assertionFailure()
93+
}
94+
}
95+
```
96+
97+
## Sprite Loading
98+
99+
Observe sprite loading events with ``MLNMapViewDelegate/mapView:spriteWillLoad:url:`` and ``MLNMapViewDelegate/mapView:spriteDidLoad:url:``.
100+
101+
<!-- include-example(ObserverExampleSprites) -->
102+
103+
```swift
104+
func mapView(_: MLNMapView, spriteWillLoad id: String, url: String) {
105+
print("The sprite \(id) has been requested from \(url)")
106+
}
107+
108+
func mapView(_: MLNMapView, spriteDidLoad id: String, url: String) {
109+
print("The sprite \(id) has been loaded from \(url)")
110+
}
111+
```
112+
113+
See also: ``MLNMapViewDelegate/mapView:spriteDidError:url:``.

‎platform/ios/app-swift/Sources/ObserverExample.swift

+11-5
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@ import MapLibre
22
import SwiftUI
33
import UIKit
44

5-
// #-example-code(ObserverExample)
65
class ObserverExampleView: UIViewController, MLNMapViewDelegate {
76
var mapView: MLNMapView!
87

@@ -22,8 +21,7 @@ class ObserverExampleView: UIViewController, MLNMapViewDelegate {
2221
mapView.delegate = self
2322
}
2423

25-
// MARK: - MLNMapViewDelegate methods
26-
24+
// #-example-code(ObserverExampleShaders)
2725
func mapView(_: MLNMapView, shaderWillCompile id: Int, backend: Int, defines: String) {
2826
print("A new shader is being compiled - shaderID:\(id), backend type:\(backend), program configuration:\(defines)")
2927
}
@@ -32,6 +30,9 @@ class ObserverExampleView: UIViewController, MLNMapViewDelegate {
3230
print("A shader has been compiled - shaderID:\(id), backend type:\(backend), program configuration:\(defines)")
3331
}
3432

33+
// #-end-example-code
34+
35+
// #-example-code(ObserverExampleGlyphs)
3536
func mapView(_: MLNMapView, glyphsWillLoad fontStack: [String], range: NSRange) {
3637
print("Glyphs are being requested for the font stack \(fontStack), ranging from \(range.location) to \(range.location + range.length)")
3738
}
@@ -40,6 +41,9 @@ class ObserverExampleView: UIViewController, MLNMapViewDelegate {
4041
print("Glyphs have been loaded for the font stack \(fontStack), ranging from \(range.location) to \(range.location + range.length)")
4142
}
4243

44+
// #-end-example-code
45+
46+
// #-example-code(ObserverExampleTiles)
4347
func mapView(_: MLNMapView, tileDidTriggerAction operation: MLNTileOperation,
4448
x: Int,
4549
y: Int,
@@ -84,17 +88,19 @@ class ObserverExampleView: UIViewController, MLNMapViewDelegate {
8488
}
8589
}
8690

91+
// #-end-example-code
92+
93+
// #-example-code(ObserverExampleSprites)
8794
func mapView(_: MLNMapView, spriteWillLoad id: String, url: String) {
8895
print("The sprite \(id) has been requested from \(url)")
8996
}
9097

9198
func mapView(_: MLNMapView, spriteDidLoad id: String, url: String) {
9299
print("The sprite \(id) has been loaded from \(url)")
93100
}
101+
// #-end-example-code
94102
}
95103

96-
// #-end-example-code
97-
98104
struct ObserverExampleViewExampleUIViewControllerRepresentable: UIViewControllerRepresentable {
99105
typealias UIViewControllerType = ObserverExampleView
100106

‎platform/ios/src/MLNMapViewDelegate.h

+111-4
Original file line numberDiff line numberDiff line change
@@ -326,35 +326,113 @@ NS_ASSUME_NONNULL_BEGIN
326326
*/
327327
- (BOOL)mapView:(MLNMapView *)mapView shouldRemoveStyleImage:(NSString *)imageName;
328328

329-
// MARK: Shader Compilation
329+
// MARK: - Shader Compilation
330330

331+
/**
332+
Called when a shader is about to be compiled.
333+
334+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
335+
@param id The unique identifier for the shader being compiled.
336+
@param backend An integer representing the backend type used for shader compilation.
337+
@param defines A string containing the shader program configuration definitions.
338+
339+
> Warning: This method is not thread-safe.
340+
*/
331341
- (void)mapView:(MLNMapView *)mapView
332342
shaderWillCompile:(NSInteger)id
333343
backend:(NSInteger)backend
334344
defines:(NSString *)defines;
345+
346+
/**
347+
Called when a shader was successfully compiled.
348+
349+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
350+
@param id The unique identifier for the shader that was compiled.
351+
@param backend An integer representing the backend type used for shader compilation.
352+
@param defines A string containing the shader program configuration definitions.
353+
354+
> Warning: This method is not thread-safe.
355+
*/
335356
- (void)mapView:(MLNMapView *)mapView
336357
shaderDidCompile:(NSInteger)id
337358
backend:(NSInteger)backend
338359
defines:(NSString *)defines;
360+
361+
/**
362+
Called when a shader failed to compile.
363+
364+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
365+
@param id The unique identifier for the shader that failed to compile.
366+
@param backend An integer representing the backend type used for shader compilation.
367+
@param defines A string containing the shader program configuration definitions.
368+
369+
> Warning: This method is not thread-safe.
370+
*/
339371
- (void)mapView:(MLNMapView *)mapView
340372
shaderDidFailCompile:(NSInteger)id
341373
backend:(NSInteger)backend
342374
defines:(NSString *)defines;
343375

344-
// MARK: Glyph Requests
376+
// MARK: - Glyph Requests
377+
378+
/**
379+
Called when glyphs for the specified font stack are about to be loaded.
380+
381+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
382+
@param fontStack An array of strings identifying the requested font stack.
383+
@param range The range of glyphs that are being requested.
345384
385+
> Warning: This method is not thread-safe.
386+
*/
346387
- (void)mapView:(MLNMapView *)mapView
347388
glyphsWillLoad:(NSArray<NSString *> *)fontStack
348389
range:(NSRange)range;
390+
391+
/**
392+
Called when glyphs for the specified font stack have been successfully loaded.
393+
394+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
395+
@param fontStack An array of strings identifying the requested font stack.
396+
@param range The range of glyphs that were successfully loaded.
397+
398+
> Warning: This method is not thread-safe.
399+
*/
349400
- (void)mapView:(MLNMapView *)mapView
350401
glyphsDidLoad:(NSArray<NSString *> *)fontStack
351402
range:(NSRange)range;
403+
404+
/**
405+
Called when an error occurred while loading glyphs for the specified font stack.
406+
407+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
408+
@param fontStack An array of strings identifying the requested font stack.
409+
@param range The range of glyphs for which loading failed.
410+
411+
> Warning: This method is not thread-safe.
412+
*/
352413
- (void)mapView:(MLNMapView *)mapView
353414
glyphsDidError:(NSArray<NSString *> *)fontStack
354415
range:(NSRange)range;
355416

356-
// MARK: Tile Requests
417+
// MARK: - Tile Requests
418+
419+
/**
420+
Called when a tile-related action is triggered.
421+
422+
This method notifies the delegate of various stages of tile processing, such as requesting from
423+
cache or network, parsing, or encountering errors.
424+
425+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
426+
@param operation The type of tile operation triggered. See ``MLNTileOperation``.
427+
@param x The x-coordinate of the tile.
428+
@param y The y-coordinate of the tile.
429+
@param z The z (zoom) level of the tile.
430+
@param wrap The wrap value for the tile.
431+
@param overscaledZ The overscaled zoom level of the tile.
432+
@param sourceID A string identifier for the tile source.
357433
434+
> Warning: This method is not thread-safe.
435+
*/
358436
- (void)mapView:(MLNMapView *)mapView
359437
tileDidTriggerAction:(MLNTileOperation)operation
360438
x:(NSInteger)x
@@ -364,10 +442,39 @@ NS_ASSUME_NONNULL_BEGIN
364442
overscaledZ:(NSInteger)overscaledZ
365443
sourceID:(NSString *)sourceID;
366444

367-
// MARK: Sprite Requests
445+
// MARK: - Sprite Requests
446+
447+
/**
448+
Called when a sprite is about to be loaded.
368449
450+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
451+
@param id The unique identifier for the sprite being loaded.
452+
@param url The URL from which the sprite is being requested.
453+
454+
> Warning: This method is not thread-safe.
455+
*/
369456
- (void)mapView:(MLNMapView *)mapView spriteWillLoad:(NSString *)id url:(NSString *)url;
457+
458+
/**
459+
Called when a sprite has been successfully loaded.
460+
461+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
462+
@param id The unique identifier for the sprite that was loaded.
463+
@param url The URL from which the sprite was loaded.
464+
465+
> Warning: This method is not thread-safe.
466+
*/
370467
- (void)mapView:(MLNMapView *)mapView spriteDidLoad:(NSString *)id url:(NSString *)url;
468+
469+
/**
470+
Called when an error occurs while loading a sprite.
471+
472+
@param mapView The ``MLNMapView`` instance invoking this delegate method.
473+
@param id The unique identifier for the sprite for which loading failed.
474+
@param url The URL from which the sprite was being requested.
475+
476+
> Warning: This method is not thread-safe.
477+
*/
371478
- (void)mapView:(MLNMapView *)mapView spriteDidError:(NSString *)id url:(NSString *)url;
372479

373480
// MARK: Tracking User Location

0 commit comments

Comments
 (0)