Adjust readme

Author: raub

README.md

@@ -13,28 +13,37 @@ npm i -s webgl-raub
 
 ![Example](examples/screenshot.jpg)
 
-**WebGL**/**OpenGL** bindings. The addon **does not provide** a window control system, and it
-**can not set up an OpenGL context** on its own. This API simply maps the
-native OpenGL function calls to their JS counterparts.
-
 **TL;DR**: For a quick start, use [3d-core-raub](https://github.com/node-3d/3d-core-raub)
-or try the [Examples](/examples) (and note [package.json](/examples/package.json)).
-
-> Note: this **addon uses N-API**, and therefore is ABI-compatible across different
-Node.js versions. Addon binaries are precompiled and **there is no compilation**
-step during the `npm i` command.
-
-
-## Details
+or look at [Examples](/examples).
 
 ```js
-const webgl = require('webgl-raub');
+import webgl from 'webgl-raub';
 ```
 
-Here `webgl` contains the **WebGL** API, like a `WebGLRenderingContext` instance would. See
-[WebGLRenderingContext docs](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)
-for reference, and [TypeScript definitions](/index.d.ts) for the full list of exports.
-There are also numerous non-WebGL methods exported in case you want to use advanced OpenGL functions.
+Here `webgl` contains the **WebGL/OpenGL** API, like a `WebGLRenderingContext` instance would.
+* See [WebGLRenderingContext docs](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)
+    for reference.
+* See [TS declarations](/index.d.ts) for the full list of exports.
+* There are also non-WebGL methods exported in case you want to use advanced OpenGL functions.
+* The addon **does not provide** a window control system, you can use
+    [glfw-raub](https://github.com/node-3d/glfw-raub) (or anything else!) to create a window.
+
+> This addon is ABI-compatible across Node.js versions. **There is no compilation** during the `npm install`.
+
+The JS API mostly maps the native OpenGL function calls to their JS counterparts. E.g.:
+
+```cpp
+// gl.clear(target)
+DBG_EXPORT JS_METHOD(clear) { NAPI_ENV;
+	REQ_INT32_ARG(0, target);
+	glClear(target);
+	RET_WEBGL_VOID;
+}
+```
+
+You can optionally call `webgl.init()` after the GL context becomes available - this translates
+into a `glewInit()` call. See [GLEW docs](https://glew.sourceforge.net/basic.html) for what
+it does and if you need it (probably "yes"?).
 
 To use browser **WebGL** libs, like [three.js](https://threejs.org/),
 several additional interfaces must also be provided to mimic the browser.
@@ -44,39 +53,26 @@ and additional browser-like interfaces.
 * Package [image-raub](https://github.com/node-3d/glfw-raub) loads and serves the image data as web
 [Image](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement#example) would.
 
-Those two are bundled into
-the [3d-core-raub](https://github.com/node-3d/3d-core-raub) in a following manner:
+See [this example](/examples/textured.mjs) using both **GLFW** and **Image**.
+The main idea being as follows:
 
-```js
+```
 import Image from 'image-raub';
 import webgl from 'webgl-raub';
 import glfw from 'glfw-raub';
 const { Document } = glfw;
 
-Document.setImage(image); // plug this Image impl into the Document
-Document.setWebgl(webgl); // plug this WebGL impl into the Document
-
-const doc = new Document();
-global.document = global.window = doc;
+Document.setImage(image); // plug Image impl into the Document
+Document.setWebgl(webgl); // plug WebGL impl into the Document
 
-const canvas = document.createElement('canvas'); // === doc
-const gl = canvas.getContext('webgl'); // === webgl
+const doc = new Document({ width: 1600, height: 900, vsync: true });
+...
 ```
 
-You can optionally call `webgl.init()` after the GL context becomes available - this translates
-into a `glewInit()` call. See [GLEW docs](https://glew.sourceforge.net/basic.html) for what
-it does and if you need it (probably "yes"?).
-
-> OSX Note: some features may depend on OpenGL profile being used. Core profile
-is necessary for VAO and other OpenGL 3.2+ features. Depending on your windowing
-backend, set the OpenGL profile of your preference.
-In case [glfw-raub](https://github.com/node-3d/glfw-raub) is used,
-the profile can be set through the `Window`/`Document`
-[constructor](https://github.com/node-3d/glfw-raub#class-window) or with
-`glfw.windowHint` calls.
-
+Similarly, these modules are utilized in [3d-core-raub](https://github.com/node-3d/3d-core-raub).
+Using [3d-core-raub](https://github.com/node-3d/3d-core-raub), you can skip setting up
+most environment features for those libs.
 
----
 
 ## WebGL Libs
 
@@ -85,5 +81,13 @@ implementation of **WebGL**.
 * [PixiJS](https://pixijs.com/) - seems to work with some minor hacks, as proven by this
 [example](https://github.com/node-3d/3d-core-raub/blob/master/examples/pixi/index.js).
 
-Using [node-3d-core](https://github.com/node-3d/3d-core-raub), you can skip setting up
-most environment features for those libs.
+
+## MacOS Note
+
+Some features may depend on OpenGL profile being used. Core profile
+is necessary for VAO and other OpenGL 3.2+ features. Depending on your windowing
+backend, set the OpenGL profile of your preference.
+In case [glfw-raub](https://github.com/node-3d/glfw-raub) is used,
+the profile can be set through the `Window`/`Document`
+[constructor](https://github.com/node-3d/glfw-raub#class-window) or with
+`glfw.windowHint` calls.