mapbox-gl 1.13.2

package/src/util/struct_array.js

@@ -0,0 +1,243 @@
+// @flow
+
+// Note: all "sizes" are measured in bytes
+
+import assert from 'assert';
+
+import type {Transferable} from '../types/transferable';
+
+const viewTypes = {
+    'Int8': Int8Array,
+    'Uint8': Uint8Array,
+    'Int16': Int16Array,
+    'Uint16': Uint16Array,
+    'Int32': Int32Array,
+    'Uint32': Uint32Array,
+    'Float32': Float32Array
+};
+
+export type ViewType = $Keys<typeof viewTypes>;
+
+/**
+ * @private
+ */
+class Struct {
+    _pos1: number;
+    _pos2: number;
+    _pos4: number;
+    _pos8: number;
+    +_structArray: StructArray;
+
+    // The following properties are defined on the prototype of sub classes.
+    size: number;
+
+    /**
+     * @param {StructArray} structArray The StructArray the struct is stored in
+     * @param {number} index The index of the struct in the StructArray.
+     * @private
+     */
+    constructor(structArray: StructArray, index: number) {
+        (this: any)._structArray = structArray;
+        this._pos1 = index * this.size;
+        this._pos2 = this._pos1 / 2;
+        this._pos4 = this._pos1 / 4;
+        this._pos8 = this._pos1 / 8;
+    }
+}
+
+const DEFAULT_CAPACITY = 128;
+const RESIZE_MULTIPLIER = 5;
+
+export type StructArrayMember = {
+    name: string,
+    type: ViewType,
+    components: number,
+    offset: number
+};
+
+export type StructArrayLayout = {
+    members: Array<StructArrayMember>,
+    size: number,
+    alignment: ?number
+}
+
+export type SerializedStructArray = {
+    length: number,
+    arrayBuffer: ArrayBuffer
+};
+
+/**
+ * `StructArray` provides an abstraction over `ArrayBuffer` and `TypedArray`
+ * making it behave like an array of typed structs.
+ *
+ * Conceptually, a StructArray is comprised of elements, i.e., instances of its
+ * associated struct type. Each particular struct type, together with an
+ * alignment size, determines the memory layout of a StructArray whose elements
+ * are of that type.  Thus, for each such layout that we need, we have
+ * a corrseponding StructArrayLayout class, inheriting from StructArray and
+ * implementing `emplaceBack()` and `_refreshViews()`.
+ *
+ * In some cases, where we need to access particular elements of a StructArray,
+ * we implement a more specific subclass that inherits from one of the
+ * StructArrayLayouts and adds a `get(i): T` accessor that returns a structured
+ * object whose properties are proxies into the underlying memory space for the
+ * i-th element.  This affords the convience of working with (seemingly) plain
+ * Javascript objects without the overhead of serializing/deserializing them
+ * into ArrayBuffers for efficient web worker transfer.
+ *
+ * @private
+ */
+class StructArray {
+    capacity: number;
+    length: number;
+    isTransferred: boolean;
+    arrayBuffer: ArrayBuffer;
+    uint8: Uint8Array;
+
+    // The following properties are defined on the prototype.
+    members: Array<StructArrayMember>;
+    bytesPerElement: number;
+    +emplaceBack: Function;
+    +emplace: Function;
+
+    constructor() {
+        this.isTransferred = false;
+        this.capacity = -1;
+        this.resize(0);
+    }
+
+    /**
+     * Serialize a StructArray instance.  Serializes both the raw data and the
+     * metadata needed to reconstruct the StructArray base class during
+     * deserialization.
+     * @private
+     */
+    static serialize(array: StructArray, transferables?: Array<Transferable>): SerializedStructArray {
+        assert(!array.isTransferred);
+
+        array._trim();
+
+        if (transferables) {
+            array.isTransferred = true;
+            transferables.push(array.arrayBuffer);
+        }
+
+        return {
+            length: array.length,
+            arrayBuffer: array.arrayBuffer,
+        };
+    }
+
+    static deserialize(input: SerializedStructArray) {
+        const structArray = Object.create(this.prototype);
+        structArray.arrayBuffer = input.arrayBuffer;
+        structArray.length = input.length;
+        structArray.capacity = input.arrayBuffer.byteLength / structArray.bytesPerElement;
+        structArray._refreshViews();
+        return structArray;
+    }
+
+    /**
+     * Resize the array to discard unused capacity.
+     */
+    _trim() {
+        if (this.length !== this.capacity) {
+            this.capacity = this.length;
+            this.arrayBuffer = this.arrayBuffer.slice(0, this.length * this.bytesPerElement);
+            this._refreshViews();
+        }
+    }
+
+    /**
+     * Resets the the length of the array to 0 without de-allocating capcacity.
+     */
+    clear() {
+        this.length = 0;
+    }
+
+    /**
+     * Resize the array.
+     * If `n` is greater than the current length then additional elements with undefined values are added.
+     * If `n` is less than the current length then the array will be reduced to the first `n` elements.
+     * @param {number} n The new size of the array.
+     */
+    resize(n: number) {
+        assert(!this.isTransferred);
+        this.reserve(n);
+        this.length = n;
+    }
+
+    /**
+     * Indicate a planned increase in size, so that any necessary allocation may
+     * be done once, ahead of time.
+     * @param {number} n The expected size of the array.
+     */
+    reserve(n: number) {
+        if (n > this.capacity) {
+            this.capacity = Math.max(n, Math.floor(this.capacity * RESIZE_MULTIPLIER), DEFAULT_CAPACITY);
+            this.arrayBuffer = new ArrayBuffer(this.capacity * this.bytesPerElement);
+
+            const oldUint8Array = this.uint8;
+            this._refreshViews();
+            if (oldUint8Array) this.uint8.set(oldUint8Array);
+        }
+    }
+
+    /**
+     * Create TypedArray views for the current ArrayBuffer.
+     */
+    _refreshViews() {
+        throw new Error('_refreshViews() must be implemented by each concrete StructArray layout');
+    }
+}
+
+/**
+ * Given a list of member fields, create a full StructArrayLayout, in
+ * particular calculating the correct byte offset for each field.  This data
+ * is used at build time to generate StructArrayLayout_*#emplaceBack() and
+ * other accessors, and at runtime for binding vertex buffer attributes.
+ *
+ * @private
+ */
+function createLayout(
+    members: Array<{ name: string, type: ViewType, +components?: number, }>,
+    alignment: number = 1
+): StructArrayLayout {
+
+    let offset = 0;
+    let maxSize = 0;
+    const layoutMembers = members.map((member) => {
+        assert(member.name.length);
+        const typeSize = sizeOf(member.type);
+        const memberOffset = offset = align(offset, Math.max(alignment, typeSize));
+        const components = member.components || 1;
+
+        maxSize = Math.max(maxSize, typeSize);
+        offset += typeSize * components;
+
+        return {
+            name: member.name,
+            type: member.type,
+            components,
+            offset: memberOffset,
+        };
+    });
+
+    const size = align(offset, Math.max(maxSize, alignment));
+
+    return {
+        members: layoutMembers,
+        size,
+        alignment
+    };
+}
+
+function sizeOf(type: ViewType): number {
+    return viewTypes[type].BYTES_PER_ELEMENT;
+}
+
+function align(offset: number, size: number): number {
+    return Math.ceil(offset / size) * size;
+}
+
+export {StructArray, Struct, viewTypes, createLayout};

package/src/util/struct_array.js.ejs

@@ -0,0 +1,112 @@
+<%
+const {
+    arrayClass,
+    members,
+    size,
+    usedTypes,
+    hasAnchorPoint,
+    layoutClass,
+    includeStructAccessors
+} = locals
+
+const StructTypeClass = arrayClass.replace('Array', 'Struct');
+const StructArrayClass = arrayClass;
+const StructArrayLayoutClass = layoutClass;
+-%>
+<%
+// collect components
+const components = [];
+for (const member of members) {
+    for (let c = 0; c < member.components; c++) {
+        let name = member.name;
+        if (member.components > 1) {
+            name += c;
+        }
+        components.push({name, member, component: c});
+    }
+}
+
+// exceptions for which we generate accessors on the array rather than a separate struct for performance
+const useComponentGetters = StructArrayClass === 'GlyphOffsetArray' || StructArrayClass === 'SymbolLineVertexArray';
+
+if (includeStructAccessors && !useComponentGetters) {
+-%>
+class <%=StructTypeClass%> extends Struct {
+    _structArray: <%=StructArrayClass%>;
+<%
+    // property declarations
+    for (const {name} of components) {-%>
+    <%=name%>: number;
+<%  }
+    if (hasAnchorPoint) { -%>
+    anchorPoint: Point;
+<%  } -%>
+<%
+for (const {name, member, component} of components) {
+    const elementOffset = `this._pos${member.size.toFixed(0)}`;
+    const componentOffset = (member.offset / member.size + component).toFixed(0);
+    const index = `${elementOffset} + ${componentOffset}`;
+    const componentAccess = `this._structArray.${member.view}[${index}]`;
+-%>
+    get <%=name%>() { return <%=componentAccess%>; }
+<%
+// generate setters for properties that are updated during runtime symbol placement; others are read-only
+if (name === 'crossTileID' || name === 'placedOrientation' || name === 'hidden') {
+-%>
+    set <%=name%>(x: number) { <%=componentAccess%> = x; }
+<%
+}
+}
+// Special case used for the CollisionBoxArray type
+if (hasAnchorPoint) {
+-%>
+    get anchorPoint() { return new Point(this.anchorPointX, this.anchorPointY); }
+<%
+}
+-%>
+}
+
+<%=StructTypeClass%>.prototype.size = <%=size%>;
+
+export type <%=StructTypeClass.replace('Struct', '')%> = <%=StructTypeClass%>;
+
+<%
+} // end 'if (includeStructAccessors)'
+-%>
+/**
+ * @private
+ */
+export class <%=StructArrayClass%> extends <%=StructArrayLayoutClass%> {
+<%
+if (useComponentGetters) {
+    for (const member of members) {
+        for (let c = 0; c < member.components; c++) {
+            if (!includeStructAccessors) continue;
+            let name = `get${member.name}`;
+            if (member.components > 1) {
+                name += c;
+            }
+            const componentOffset = (member.offset / member.size + c).toFixed(0);
+            const componentStride = size / member.size;
+-%>
+    <%=name%>(index: number) { return this.<%=member.view%>[index * <%=componentStride%> + <%=componentOffset%>]; }
+<%
+        }
+    }
+} else if (includeStructAccessors) { // get(i)
+-%>
+    /**
+     * Return the <%=StructTypeClass%> at the given location in the array.
+     * @param {number} index The index of the element.
+     * @private
+     */
+    get(index: number): <%=StructTypeClass%> {
+        assert(!this.isTransferred);
+        return new <%=StructTypeClass%>(this, index);
+    }
+<%
+}
+-%>
+}
+
+register('<%=StructArrayClass%>', <%=StructArrayClass%>);

package/src/util/struct_array_layout.js.ejs

@@ -0,0 +1,98 @@
+<%
+const {
+    className,
+    members,
+    size,
+    usedTypes
+} = locals
+
+const StructArrayLayoutClass = className;
+-%>
+/**
+ * Implementation of the StructArray layout:
+<%
+for (const member of members) {
+-%>
+ * [<%=member.offset%>]: <%=member.type%>[<%=member.components%>]
+<%
+}
+-%>
+ *
+ * @private
+ */
+class <%=StructArrayLayoutClass%> extends StructArray {
+<%
+for (const type of usedTypes) {
+-%>
+    <%=type.toLowerCase()%>: <%=type%>Array;
+<%
+}
+-%>
+
+    _refreshViews() {
+<%
+for (const type of usedTypes) {
+-%>
+        this.<%=type.toLowerCase()%> = new <%=type%>Array(this.arrayBuffer);
+<%
+}
+-%>
+    }
+
+<%
+// prep for emplaceBack: collect type sizes and count the number of arguments
+// we'll need
+const bytesPerElement = size;
+const usedTypeSizes = [];
+const argNames = [];
+const argNamesTyped = [];
+for (const member of members) {
+    if (usedTypeSizes.indexOf(member.size) < 0) {
+        usedTypeSizes.push(member.size);
+    }
+    for (let c = 0; c < member.components; c++) {
+        // arguments v0, v1, v2, ... are, in order, the components of
+        // member 0, then the components of member 1, etc.
+        const name = `v${argNames.length}`;
+        argNames.push(name);
+        argNamesTyped.push(`${name}: number`);
+    }
+}
+-%>
+    emplaceBack(<%=argNamesTyped.join(', ')%>) {
+        const i = this.length;
+        this.resize(i + 1);
+        return this.emplace(i, <%=argNames.join(', ')%>);
+    }
+
+    emplace(i: number, <%=argNamesTyped.join(', ')%>) {
+<%
+{
+for (const size of usedTypeSizes) {
+-%>
+        const o<%=size.toFixed(0)%> = i * <%=(bytesPerElement / size).toFixed(0)%>;
+<%
+}
+
+let argIndex = 0;
+for (const member of members) {
+    for (let c = 0; c < member.components; c++) {
+        // The index for `member` component `c` into the appropriate type array is:
+        // this.{TYPE}[o{SIZE} + MEMBER_OFFSET + {c}] = v{X}
+        // where MEMBER_OFFSET = ROUND(member.offset / size) is the per-element
+        // offset of this member into the array
+        const index = `o${member.size.toFixed(0)} + ${(member.offset / member.size + c).toFixed(0)}`;
+-%>
+        this.<%=member.view%>[<%=index%>] = v<%=argIndex++%>;
+<%
+    }
+}
+}
+-%>
+        return i;
+    }
+-%>
+}
+
+<%=StructArrayLayoutClass%>.prototype.bytesPerElement = <%= size %>;
+register('<%=StructArrayLayoutClass%>', <%=StructArrayLayoutClass%>);

package/src/util/task_queue.js

@@ -0,0 +1,68 @@
+// @flow strict
+import assert from 'assert';
+
+export type TaskID = number; // can't mark opaque due to https://github.com/flowtype/flow-remove-types/pull/61
+type Task = {
+    callback: (timeStamp: number) => void;
+    id: TaskID;
+    cancelled: boolean;
+};
+
+class TaskQueue {
+    _queue: Array<Task>;
+    _id: TaskID;
+    _cleared: boolean;
+    _currentlyRunning: Array<Task> | false;
+
+    constructor()  {
+        this._queue = [];
+        this._id = 0;
+        this._cleared = false;
+        this._currentlyRunning = false;
+    }
+
+    add(callback: (timeStamp: number) => void): TaskID {
+        const id = ++this._id;
+        const queue = this._queue;
+        queue.push({callback, id, cancelled: false});
+        return id;
+    }
+
+    remove(id: TaskID) {
+        const running = this._currentlyRunning;
+        const queue = running ? this._queue.concat(running) : this._queue;
+        for (const task of queue) {
+            if (task.id === id) {
+                task.cancelled = true;
+                return;
+            }
+        }
+    }
+
+    run(timeStamp: number = 0) {
+        assert(!this._currentlyRunning);
+        const queue = this._currentlyRunning = this._queue;
+
+        // Tasks queued by callbacks in the current queue should be executed
+        // on the next run, not the current run.
+        this._queue = [];
+
+        for (const task of queue) {
+            if (task.cancelled) continue;
+            task.callback(timeStamp);
+            if (this._cleared) break;
+        }
+
+        this._cleared = false;
+        this._currentlyRunning = false;
+    }
+
+    clear() {
+        if (this._currentlyRunning) {
+            this._cleared = true;
+        }
+        this._queue = [];
+    }
+}
+
+export default TaskQueue;

package/src/util/throttle.js

@@ -0,0 +1,27 @@
+// @flow strict
+
+/**
+ * Throttle the given function to run at most every `period` milliseconds.
+ * @private
+ */
+export default function throttle(fn: () => void, time: number): () => ?TimeoutID {
+    let pending = false;
+    let timerId: ?TimeoutID = null;
+
+    const later = () => {
+        timerId = null;
+        if (pending) {
+            fn();
+            timerId = setTimeout(later, time);
+            pending = false;
+        }
+    };
+
+    return () => {
+        pending = true;
+        if (!timerId) {
+            later();
+        }
+        return timerId;
+    };
+}

package/src/util/throttled_invoker.js

@@ -0,0 +1,46 @@
+// @flow
+
+/**
+ * Invokes the wrapped function in a non-blocking way when trigger() is called. Invocation requests
+ * are ignored until the function was actually invoked.
+ *
+ * @private
+ */
+class ThrottledInvoker {
+    _channel: MessageChannel;
+    _triggered: boolean;
+    _callback: Function
+
+    constructor(callback: Function) {
+        this._callback = callback;
+        this._triggered = false;
+        if (typeof MessageChannel !== 'undefined') {
+            this._channel = new MessageChannel();
+            this._channel.port2.onmessage = () => {
+                this._triggered = false;
+                this._callback();
+            };
+        }
+    }
+
+    trigger() {
+        if (!this._triggered) {
+            this._triggered = true;
+            if (this._channel) {
+                this._channel.port1.postMessage(true);
+            } else {
+                setTimeout(() => {
+                    this._triggered = false;
+                    this._callback();
+                }, 0);
+            }
+        }
+    }
+
+    remove() {
+        delete this._channel;
+        this._callback = () => {};
+    }
+}
+
+export default ThrottledInvoker;