@maplibre/maplibre-gl-native 5.2.0 → 5.3.0

package/README.md

@@ -1,8 +1,8 @@
 [![MapLibre Logo](https://maplibre.org/img/maplibre-logo-big.svg)](https://maplibre.org/)
 
-# MapLibre GL Native
+# MapLibre Native
 
-MapLibre GL Native is a free and open-source library for publishing maps in your apps and desktop applications on various platforms. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering.
+MapLibre Native is a free and open-source library for publishing maps in your apps and desktop applications on various platforms. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering.
 
 This project originated as a fork of Mapbox GL Native, before their switch to a non-OSS license in December 2020. For more information, see: [`FORK.md`](./FORK.md).
 
@@ -12,11 +12,11 @@ This project originated as a fork of Mapbox GL Native, before their switch to a
 
 ## Getting Started
 
-To get started with MapLibre GL Native, go to your platform below.
+To get started with MapLibre Native, go to your platform below.
 
 ## Documentation
 
-The documentation of MapLibre GL Native is a work in progress. To get an architectural overview and to learn about the current state of the project and its path forward read the [MapLibre GL Native Markdown Book](https://maplibre.org/maplibre-gl-native/docs/book/). See below for platform-specific documentation.
+The documentation of MapLibre Native is a work in progress. To get an architectural overview and to learn about the current state of the project and its path forward read the [MapLibre Native Markdown Book](https://maplibre.org/maplibre-native/docs/book/). See below for platform-specific documentation.
 
 ## Platforms
 
@@ -35,21 +35,24 @@ Platforms with a ⭐️ are **MapLibre Core Projects** and have a substantial am
 
 ![image-metal](https://user-images.githubusercontent.com/53421382/214308933-66cd4efb-b5a5-4de3-b4b4-7ed59045a1c3.png)
 
-MapLibre GL Native is being actively developed. Our big goal for 2023 is to modularize the OpenGL renderer and implement a Metal graphics backend (https://developer.apple.com/metal/). This will improve the performance and yield lower power consumption on iOS devices. At the same time, the Metal preparations will help us in the implementation of a Vulkan graphics backend.
+MapLibre Native is being actively developed. Our big goal for 2023 is to modularize the OpenGL renderer and implement a Metal graphics backend (https://developer.apple.com/metal/). This will improve the performance and yield lower power consumption on iOS devices. At the same time, the Metal preparations will help us in the implementation of a Vulkan graphics backend.
 
 Your help in preparing the codebase for the latest graphics backends is more than welcome. Feel free to reach out if you are interested in joining the effort!
 
 - Check out the [news](https://maplibre.org/news/) on MapLibre's website.
-- See the [Design Proposals](https://github.com/louwers/maplibre-gl-native/tree/main/design-proposals) that have been accepted and are being worked on, the most recent ones being the [Rendering Modularization Design Proposal](design-proposals/2022-10-27-rendering-modularization.md) and the [Metal Port Design Proposal](design-proposals/2022-11-29-metal-port.md).
+- See the [Design Proposals](https://github.com/maplibre/maplibre-native/tree/main/design-proposals) that have been accepted and are being worked on, the most recent ones being the [Rendering Modularization Design Proposal](design-proposals/2022-10-27-rendering-modularization.md) and the [Metal Port Design Proposal](design-proposals/2022-11-29-metal-port.md).
 
 ## Contributing
 
-To contribute to MapLibre GL Native, see [`CONTRIBUTING.md`](CONTRIBUTING.md) and (if applicable) the specific instructions for the platform you want to contribute to.
+To contribute to MapLibre Native, see [`CONTRIBUTING.md`](CONTRIBUTING.md) and (if applicable) the specific instructions for the platform you want to contribute to.
 
 ### Getting Involved
 
 Join the `#maplibre-native` Slack channel at OSMUS. Get an invite at https://slack.openstreetmap.us/ 
 
+### Bounties 💰
+
+Thanks to our sponsors, we are able to award bounties to developers making contributions toward certain [bounty directions](https://github.com/maplibre/maplibre/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty+direction%22). To get started doing bounties, refer to the [step-by-step bounties guide](https://maplibre.org/roadmap/step-by-step-bounties-guide/).
 
 ## Sponsors
 
@@ -59,16 +62,15 @@ Read more about the MapLibre Sponsorship Program at [https://maplibre.org/sponso
 
 Platinum:
 
-<img src="https://maplibre.org/img/aws-logo.svg" alt="Logo AWS" width="25%"/>
-
+<a href="https://aws.com"><img src="https://maplibre.org/img/aws-logo.svg" alt="Logo AWS" width="25%"/></a>
 
 Silver:
 
-<img src="https://maplibre.org/img/meta-logo.svg" alt="Logo Meta" width="50%"/>
+<a href="https://meta.com"><img src="https://maplibre.org/img/meta-logo.svg" alt="Logo Meta" width="25%"/></a>
 
-Stone:
+<a href="https://www.mierune.co.jp/?lang=en"><img src="https://maplibre.org/img/mierune-logo.svg" alt="Logo MIERUNE" width="25%"/></a>
 
-[MIERUNE Inc.](https://www.mierune.co.jp/?lang=en)
+<a href="https://komoot.com/"><img src="https://maplibre.org/img/komoot-logo.svg" alt="Logo komoot" width="25%"/></a>
 
 Backers and Supporters:
 
@@ -76,4 +78,4 @@ Backers and Supporters:
 
 ## License
 
-**MapLibre GL Native** is licensed under the [BSD 2-Clause License](./LICENSE.md).
+**MapLibre Native** is licensed under the [BSD 2-Clause License](./LICENSE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplibre/maplibre-gl-native",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Renders map tiles with Maplibre GL",
   "keywords": [
     "maplibre",
@@ -17,11 +17,11 @@
   "types": "platform/node/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/maplibre/maplibre-gl-native.git"
+    "url": "git+https://github.com/maplibre/maplibre-native.git"
   },
   "license": "BSD-2-Clause",
   "dependencies": {
-    "@acalcutt/node-pre-gyp": "^1.0.11",
+    "@acalcutt/node-pre-gyp": "^1.0.14",
     "@acalcutt/node-pre-gyp-github": "1.4.8",
     "minimatch": "^7.2.0",
     "npm-run-all": "^4.0.2"
@@ -31,6 +31,7 @@
     "@mapbox/mvt-fixtures": "3.10.0",
     "@octokit/plugin-retry": "^4.1.2",
     "@octokit/rest": "^19.0.7",
+    "argparse": "^2.0.1",
     "aws-sdk": "^2.1318.0",
     "csscolorparser": "~1.0.2",
     "d3-queue": "3.0.7",
@@ -57,7 +58,7 @@
     "node": ">=6"
   },
   "scripts": {
-    "install": "node-pre-gyp install --fallback-to-build=true",
+    "install": "node-pre-gyp install --fallback-to-build=false",
     "test": "tape platform/node/test/js/**/*.test.js",
     "test-memory": "node --expose-gc platform/node/test/memory.test.js",
     "test-expressions": "node -r esm platform/node/test/expression.test.js",
@@ -68,7 +69,7 @@
   "binary": {
     "module_name": "mbgl",
     "module_path": "./lib/{node_abi}",
-    "host": "https://github.com/maplibre/maplibre-gl-native/releases/download/",
+    "host": "https://github.com/maplibre/maplibre-native/releases/download/",
     "remote_path": "node-v{version}",
     "package_name": "{node_abi}-{platform}-{arch}-{configuration}.tar.gz"
   }

package/platform/node/README.md

@@ -1,17 +1,17 @@
 # @maplibre/maplibre-gl-native
 
 [![Version](https://img.shields.io/npm/v/@maplibre/maplibre-gl-native?style=flat)](https://www.npmjs.com/package/@maplibre/maplibre-gl-native)
-[![node-ci](https://github.com/maplibre/maplibre-gl-native/actions/workflows/node-ci.yml/badge.svg)](https://github.com/maplibre/maplibre-gl-native/actions/workflows/node-ci.yml)
+[![node-ci](https://github.com/maplibre/maplibre-native/actions/workflows/node-ci.yml/badge.svg)](https://github.com/maplibre/maplibre-native/actions/workflows/node-ci.yml)
 
 ## Installing
 
 Binaries are available and downloaded during install for the following platforms:
 
 - Operating systems:
-  - Ubuntu 20.04 (amd64/arm64)
+  - Ubuntu 22.04 (amd64/arm64)
   - macOS 12 (amd64/arm64)
   - Windows (amd64)
-- Node.js 14, 16, 18
+- Node.js 16, 18, 20
 
 Run:
 
@@ -19,7 +19,7 @@ Run:
 npm install @maplibre/maplibre-gl-native
 ```
 
-Further platforms might work [with additional libraries installed](https://github.com/maplibre/maplibre-gl-native/tree/main/platform/linux#prerequisites).
+Further platforms might work [with additional libraries installed](https://github.com/maplibre/maplibre-native/tree/main/platform/linux#prerequisites).
 
 ## Testing
 
@@ -30,6 +30,38 @@ npm run test-suite
 
 ## Rendering a map tile
 
+The minimal example requires only the instantiation of the `mbgl.Map` object, loading a style and calling the `map.render` method:
+
+```js
+var mbgl = require('@maplibre/maplibre-gl-native');
+var sharp = require('sharp');
+
+var map = new mbgl.Map();
+
+map.load(require('./test/fixtures/style.json'));
+
+map.render(function(err, buffer) {
+    if (err) throw err;
+
+    map.release();
+
+    var image = sharp(buffer, {
+        raw: {
+            width: 512,
+            height: 512,
+            channels: 4
+        }
+    });
+
+    // Convert raw image buffer to PNG
+    image.toFile('image.png', function(err) {
+        if (err) throw err;
+    });
+});
+```
+
+But you can customize the map providing an options object to `mbgl.Map` constructor and to `map.render` method:
+
 ```js
 var fs = require('fs');
 var path = require('path');
@@ -87,7 +119,7 @@ When you are finished using a map object, you can call `map.release()` to perman
 
 ## Implementing a file source
 
-When creating a `Map`, you must pass an options object (with a required `request` method and optional 'ratio' number) as the first parameter.
+When creating a `Map`, you can optionally pass an options object (with an optional `request` method and optional `ratio` number) as the first parameter. The `request()` method handles a request for a resource. The `ratio` sets the scale at which the map will render tiles, such as `2.0` for rendering images for high pixel density displays:
 
 ```js
 var map = new mbgl.Map({
@@ -98,7 +130,7 @@ var map = new mbgl.Map({
 });
 ```
 
-The `request()` method handles a request for a resource. The `ratio` sets the scale at which the map will render tiles, such as `2.0` for rendering images for high pixel density displays. The `req` parameter has two properties:
+If you omit the `request` method, the `map` object will use the default internal request handlers, which is ok for most cases. However, if you have specific needs, you can implement your own `request` handler. When a `request` method is provided, all `map` resources will be requested by calling the `request` method with two parameters, called `req` and `callback` respectively in this example. The `req` parameter has two properties:
 
 ```json
 {
@@ -107,7 +139,7 @@ The `request()` method handles a request for a resource. The `ratio` sets the sc
 }
 ```
 
-The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/maplibre/maplibre-gl-native/blob/main/include/mbgl/storage/resource.hpp):
+The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/maplibre/maplibre-native/blob/main/include/mbgl/storage/resource.hpp):
 
 ```json
 {
@@ -123,7 +155,18 @@ The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/maplib
 
 The `kind` enum has no significance for anything but serves as a hint to your implemention as to what sort of resource to expect. E.g., your implementation could choose caching strategies based on the expected file type.
 
-The `request` implementation should pass uncompressed data to `callback`. If you are downloading assets from a source that applies gzip transport encoding, the implementation must decompress the results before passing them on.
+The `callback` parameter is a function that must be called with two parameters: an error message (if there are no errors, then you must pass `null`), and a response object:
+
+```js
+{
+    data: {data}, // required, must be a byte array, usually a Buffer object
+    modified: {modified}, // Date, optional
+    expires: {expires}, // Date, optional
+    etag: {etag} // string, optional
+}
+```
+
+If there is no data to be sent to the `callback` (empty data, or `no-content` respose), then it must be called without parameters. The `request` implementation should pass uncompressed data to `callback`. If you are downloading assets from a source that applies gzip transport encoding, the implementation must decompress the results before passing them on.
 
 A sample implementation that reads files from disk would look like the following:
 
@@ -187,7 +230,7 @@ Stylesheets are free to use any protocols, but your implementation of `request`
 
 ## Listening for log events
 
-The module imported with `require('maplibre-gl-native')` inherits from [`EventEmitter`](https://nodejs.org/api/events.html), and the `NodeLogObserver` will push log events to this. Log messages can have [`class`](https://github.com/maplibre/maplibre-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L43-L60), [`severity`](https://github.com/maplibre/maplibre-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L17-L23), `code` ([HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)), and `text` parameters.
+The module imported with `require('maplibre-gl-native')` inherits from [`EventEmitter`](https://nodejs.org/api/events.html), and the `NodeLogObserver` will push log events to this. Log messages can have [`class`](https://github.com/maplibre/maplibre-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L43-L60), [`severity`](https://github.com/maplibre/maplibre-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L17-L23), `code` ([HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)), and `text` parameters.
 
 ```js
 var mbgl = require('@maplibre/maplibre-gl-native');

package/platform/node/index.d.ts

@@ -35,7 +35,7 @@ declare module '@maplibre/maplibre-gl-native' {
     /**
      * Will be used during a `Map.render` call to request all necessary map resources (tiles, fonts...)
      */
-    request: (
+    request?: (
       request: { url: string; kind: ResourceKind },
       callback: (error?: Error, response?: RequestResponse) => void,
     ) => void;
@@ -111,7 +111,7 @@ declare module '@maplibre/maplibre-gl-native' {
    * A `Map` instance is used to render images from map views
    */
   class Map {
-    constructor(mapOptions: MapOptions);
+    constructor(mapOptions?: MapOptions);
 
     /**
      * Load a style into a map

package/platform/node/index.js

@@ -6,43 +6,49 @@ var mbgl = require('../../lib/node-v' + process.versions.modules + '/mbgl');
 var constructor = mbgl.Map.prototype.constructor;
 
 var Map = function(options) {
-    if (!(options instanceof Object)) {
+    if (options && !(options instanceof Object)) {
         throw TypeError("Requires an options object as first argument");
     }
 
-    if (!options.hasOwnProperty('request') || !(options.request instanceof Function)) {
-        throw TypeError("Options object must have a 'request' method");
+    if (options && options.hasOwnProperty('request') && !(options.request instanceof Function)) {
+        throw TypeError("Options object 'request' property must be a function");
     }
 
-    var request = options.request;
-
-    return new constructor(Object.assign(options, {
-        request: function(req) {
-            // Protect against `request` implementations that call the callback synchronously,
-            // call it multiple times, or throw exceptions.
-            // http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony
-
-            var responded = false;
-            var callback = function() {
-                var args = arguments;
-                if (!responded) {
-                    responded = true;
-                    process.nextTick(function() {
-                        req.respond.apply(req, args);
-                    });
-                } else {
-                    console.warn('request function responded multiple times; it should call the callback only once');
+    if (options && options.request) {
+        var request = options.request;
+
+        return new constructor(Object.assign(options, {
+            request: function(req) {
+                // Protect against `request` implementations that call the callback synchronously,
+                // call it multiple times, or throw exceptions.
+                // http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony
+
+                var responded = false;
+                var callback = function() {
+                    var args = arguments;
+                    if (!responded) {
+                        responded = true;
+                        process.nextTick(function() {
+                            req.respond.apply(req, args);
+                        });
+                    } else {
+                        console.warn('request function responded multiple times; it should call the callback only once');
+                    }
+                };
+
+                try {
+                    request(req, callback);
+                } catch (e) {
+                    console.warn('request function threw an exception; it should call the callback with an error instead');
+                    callback(e);
                 }
-            };
-
-            try {
-                request(req, callback);
-            } catch (e) {
-                console.warn('request function threw an exception; it should call the callback with an error instead');
-                callback(e);
             }
-        }
-    }));
+        }));
+    } else if (options) {
+        return new constructor(options);
+    } else {
+        return new constructor();
+    }
 };
 
 Map.prototype = mbgl.Map.prototype;