diff options
Diffstat (limited to 'platform/node/README.md')
-rw-r--r-- | platform/node/README.md | 102 |
1 files changed, 10 insertions, 92 deletions
diff --git a/platform/node/README.md b/platform/node/README.md index 5a8e51571b..1a18c61d01 100644 --- a/platform/node/README.md +++ b/platform/node/README.md @@ -23,6 +23,7 @@ Other platforms will fall back to a source compile with `make node`. To compile ``` npm test +npm run test-suite ``` ## Rendering a map tile @@ -63,11 +64,12 @@ The first argument passed to `map.render` is an options object, all keys are opt height: {height}, // number (px), defaults to 512 center: [{longitude}, {latitude}], // array of numbers (coordinates), defaults to [0,0] bearing: {bearing}, // number (in degrees, counter-clockwise from north), defaults to 0 + pitch: {pitch}, // number (in degrees, arcing towards the horizon), defaults to 0 classes: {classes} // array of strings } ``` -When you are finished using a map object, you can call `map.release()` to permanently dispose the internal map resources. This is not necessary, but can be helpful to optimize resource usage (memory, file sockets) on a more granualar level than v8's garbage collector. Calling `map.release()` will prevent a map object from being used for any further render calls, but can be safely called as soon as the `map.render()` callback returns, as the returned pixel buffer will always be retained for the scope of the callback. +When you are finished using a map object, you can call `map.release()` to permanently dispose the internal map resources. This is not necessary, but can be helpful to optimize resource usage (memory, file sockets) on a more granualar level than V8's garbage collector. Calling `map.release()` will prevent a map object from being used for any further render calls, but can be safely called as soon as the `map.render()` callback returns, as the returned pixel buffer will always be retained for the scope of the callback. ## Implementing a file source @@ -82,7 +84,7 @@ var map = new mbgl.Map({ }); ``` -The `request()` method starts a new request to a file. 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: +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: ```json { @@ -91,7 +93,7 @@ The `request()` method starts a new request to a file. The `ratio` sets the scal } ``` -The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/mapbox/mapbox-gl-native/blob/node/include/mbgl/storage/resource.hpp): +The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/mapbox/mapbox-gl-native/blob/master/include/mbgl/storage/resource.hpp): ```json { @@ -105,7 +107,7 @@ The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/mapbox } ``` -It 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 `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. @@ -121,7 +123,7 @@ var map = new mbgl.Map({ }); ``` -This is a very barebones implementation and you'll probably want a better implementation. E.g. it passes the url verbatim to the file system, but you'd want add some logic that normalizes `http` URLs. You'll notice that once your implementation has obtained the requested file, you have to deliver it to the requestee by calling `callback()`, which takes either an error object or `null` and an object with several settings: +This is a very barebones implementation and you'll probably want a better implementation. E.g. it passes the url verbatim to the file system, but you'd want add some logic that normalizes `http` URLs. You'll notice that once your implementation has obtained the requested file, you have to deliver it to the requestee by calling `callback()`, which takes either an error object or `null` and an object with several keys: ```js { @@ -129,10 +131,10 @@ This is a very barebones implementation and you'll probably want a better implem expires: new Date(), etag: "string", data: new Buffer() -}; +} ``` -A sample implementation that uses [`request`](https://github.com/request/request) to query data from HTTP: +A sample implementation that uses [`request`](https://github.com/request/request) to fetch data from a remote source: ```js var mbgl = require('mapbox-gl-native'); @@ -165,43 +167,12 @@ var map = new mbgl.Map({ }); ``` -Mapbox GL uses two types of protocols: `asset://` for files that should be loaded from some local static system, and `http://` (and `https://`), which should be loaded from the internet. However, stylesheets are free to use other protocols too, if your implementation of `request` supports these; e.g. you could use `s3://` to indicate that files are supposed to be loaded from S3. +Stylesheets are free to use any protocols, but your implementation of `request` must support these; e.g. you could use `s3://` to indicate that files are supposed to be loaded from S3. ## Listening for log events The module imported with `require('mapbox-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/mapbox/mapbox-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L43-L60), [`severity`](https://github.com/mapbox/mapbox-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. -``` -MBGL_DEFINE_ENUM_CLASS(EventClass, Event, { - { Event::General, "General" }, - { Event::Setup, "Setup" }, - { Event::Shader, "Shader" }, - { Event::ParseStyle, "ParseStyle" }, - { Event::ParseTile, "ParseTile" }, - { Event::Render, "Render" }, - { Event::Style, "Style" }, - { Event::Database, "Database" }, - { Event::HttpRequest, "HttpRequest" }, - { Event::Sprite, "Sprite" }, - { Event::Image, "Image" }, - { Event::OpenGL, "OpenGL" }, - { Event::JNI, "JNI" }, - { Event::Android, "Android" }, - { Event::Crash, "Crash" }, - { Event(-1), "Unknown" }, -}); -``` - -``` -MBGL_DEFINE_ENUM_CLASS(EventSeverityClass, EventSeverity, { - { EventSeverity::Debug, "DEBUG" }, - { EventSeverity::Info, "INFO" }, - { EventSeverity::Warning, "WARNING" }, - { EventSeverity::Error, "ERROR" }, - { EventSeverity(-1), "UNKNOWN" }, -}); -``` - ```js var mbgl = require('mapbox-gl-native'); mbgl.on('message', function(msg) { @@ -212,59 +183,6 @@ mbgl.on('message', function(msg) { }); ``` -## Mapbox API Access tokens - -To use styles that rely on Mapbox vector tiles, you must pass an [API access token](https://www.mapbox.com/developers/api/#access-tokens) in your `request` implementation with requests to `mapbox://` protocols. - -```js -var mbgl = require('mapbox-gl-native'); -var request = require('request'); -var url = require('url'); - -var map = new mbgl.Map({ - request: function(req, callback) { - var opts = { - url: req.url, - encoding: null, - gzip: true - }; - - if (url.parse(req.url).protocol === 'mapbox:') { - opts.qs = { access_token: process.env.MAPBOX_ACCESS_TOKEN}; - } - - request(opts, function (err, res, body) { - if (err) { - callback(err); - } else if (res.statusCode == 200) { - var response = {}; - - if (res.headers.modified) { response.modified = new Date(res.headers.modified); } - if (res.headers.expires) { response.expires = new Date(res.headers.expires); } - if (res.headers.etag) { response.etag = res.headers.etag; } - - response.data = body; - - callback(null, response); - } else { - callback(new Error(JSON.parse(body).message)); - } - }); - } -}); - -// includes a datasource with a reference to something like `mapbox://mapbox.mapbox-streets-v6` -var style = mapboxStyle; - -map.load(style); -map.render({}, function(err, buffer) { - if (err) throw err; - - // Do something with raw pixel buffer -}); - -``` - ## Contributing See [DEVELOPING.md](DEVELOPING.md) for instructions on building this module for development. |