Source: util/ByteBuffer.js

  1. /*
  2.  * Copyright 2003-2006, 2009, 2017, United States Government, as represented by the Administrator of the
  3.  * National Aeronautics and Space Administration. All rights reserved.
  4.  *
  5.  * The NASAWorldWind/WebWorldWind platform is licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. /**
  18.  * @exports ByteBuffer
  19.  */
  20. define(['../error/ArgumentError',
  21.         '../util/Logger'
  22.         ],
  23.     function (ArgumentError,
  24.               Logger) {
  25.         "use strict";
  27.         /**
  28.          * Constructs a wrapper around an array buffer that enables byte-level access to its data.
  29.          * This wrapper strives to minimize secondary allocations when subarrays are accessed.
  30.          * The one exception is when double precision floating point data is access that is not properly aligned.
  31.          * @alias ByteBuffer
  32.          * @classdesc A structured wrapper around an array buffer that provides byte-level access to its data.
  33.          * @param {ArrayBuffer} array An array buffer containing source data.
  34.          * @constructor
  35.          */
  36.         var ByteBuffer = function(array) {
  37.             if (!array) {
  38.                 throw new ArgumentError(
  39.                     Logger.logMessage(Logger.LEVEL_SEVERE, "ByteBuffer", "constructor", "missingArray"));
  40.             }
  42.             /**
  43.              * The raw data of the array buffer.
  44.              * @type {ArrayBuffer}
  45.              */
  46.             this.array = array;
  48.             /**
  49.              * A data view on the array buffer.
  50.              * This data view is used to extract integer and floating point data from that array buffer.
  51.              * @type {DataView}
  52.              */
  53.             this.data = new DataView(array);
  55.             /**
  56.              * The current position in the array buffer.
  57.              * This position is implicitly used to access all data.
  58.              * @type {Number}
  59.              */
  60.             this.position = 0;
  62.             /**
  63.              * The byte order in which the data is encoded.
  64.              * Byte order will either be big endian or little endian.
  65.              * @type {Boolean}
  66.              * @default ByteByffer.LITTLE_ENDIAN
  67.              * @private
  68.              */
  69.             this._order = ByteBuffer.LITTLE_ENDIAN;
  70.         };
  72.         /**
  73.          * Get a byte from the current position and advance the position.
  74.          * @returns {Number}
  75.          */
  76.         ByteBuffer.prototype.getByte = function() {
  77.             var result = this.data.getUint8(this.position);
  78.             this.position += ByteBuffer.BYTE_SIZE;
  79.             return result;
  80.         };
  82.         /**
  83.          * Get a byte array from the current position and advance the position.
  84.          * To avoid secondary allocation, a TypedArray shadows the underlying ArrayBuffer.
  85.          * @param {Number} numBytes The number of bytes in the desired array.
  86.          * @returns {Uint8Array}
  87.          */
  88.         ByteBuffer.prototype.getByteArray = function(numBytes) {
  89.             var result = new Uint8Array(this.array, this.position, numBytes);
  90.             this.position += ByteBuffer.BYTE_SIZE * numBytes;
  91.             return result;
  92.         };
  94.         /**
  95.          * Get a 16-bit integer from the current position and advance the position.
  96.          * @returns {Number}
  97.          */
  98.         ByteBuffer.prototype.getInt16 = function() {
  99.             var result = this.data.getInt16(this.position, this._order);
  100.             this.position += ByteBuffer.INT16_SIZE;
  101.             return result;
  102.         };
  104.         /**
  105.          * Get a 16-bit integer array from the current position and advance the position.
  106.          * To avoid secondary allocation, a TypedArray shadows the underlying ArrayBuffer.
  107.          * @param {Number} numInt16s The number of 16-bit integers in the desired array.
  108.          * @returns {Int16Array}
  109.          */
  110.         ByteBuffer.prototype.getInt16Array = function(numInt16s) {
  111.             var result = new Int16Array(this.array, this.position, numInt16s);
  112.             this.position += ByteBuffer.INT16_SIZE * numInt16s;
  113.             return result;
  114.         };
  116.         /**
  117.          * Get a 32-bit integer from the current position and advance the position.
  118.          * @returns {Number}
  119.          */
  120.         ByteBuffer.prototype.getInt32 = function() {
  121.             var result = this.data.getInt32(this.position, this._order);
  122.             this.position += ByteBuffer.INT32_SIZE;
  123.             return result;
  124.         };
  126.         /**
  127.          * Get a single precision floating point array from the current position and advance the position.
  128.          * To avoid secondary allocation, a TypedArray shadows the underlying ArrayBuffer.
  129.          * @param {Number} numInt32s The number of 32-bit integers in the desired array.
  130.          * @returns {Int32Array}
  131.          */
  132.         ByteBuffer.prototype.getInt32Array = function(numInt32s) {
  133.             var result = new Int32Array(this.array, this.position, numInt32s);
  134.             this.position += ByteBuffer.INT32_SIZE * numInt32s;
  135.             return result;
  136.         };
  138.         /**
  139.          * Get a single precision floating point number from the current position and advance the position.
  140.          * @returns {Number}
  141.          */
  142.         ByteBuffer.prototype.getFloat = function() {
  143.             var result = this.data.getFloat32(this.position, this._order);
  144.             this.position += ByteBuffer.FLOAT_SIZE;
  145.             return result;
  146.         };
  148.         /**
  149.          * Get a single precision floating point array from the current position and advance the position.
  150.          * To avoid secondary allocation, a TypedArray shadows the underlying ArrayBuffer.
  151.          * @param {Number} numFloats The number of single precision floating point numbers in the desired array.
  152.          * @returns {Float32Array}
  153.          */
  154.         ByteBuffer.prototype.getFloatArray = function(numFloats) {
  155.             var result = new Float32Array(this.array, this.position, numFloats);
  156.             this.position += ByteBuffer.FLOAT_SIZE * numFloats;
  157.             return result;
  158.         };
  160.         /**
  161.          * Get a double precision floating point number from the current position and advance the position.
  162.          * @returns {Number}
  163.          */
  164.         ByteBuffer.prototype.getDouble = function() {
  165.             var result = this.data.getFloat64(this.position, this._order);
  166.             this.position += ByteBuffer.DOUBLE_SIZE;
  167.             return result;
  168.         };
  170.         /**
  171.          * Get a single precision floating point array from the current position and advance the position.
  172.          * To avoid secondary allocation, a TypedArray shadows the underlying ArrayBuffer.
  173.          * @param {Number} numDoubles The number of double precision floating point numbers in the desired array.
  174.          * @returns {Float64Array}
  175.          */
  176.         ByteBuffer.prototype.getDoubleArray = function(numDoubles) {
  177.             // Issue: Float64Array c'tor throws an exception if the starting offset is not a multiple of 8.
  178.             // We see this in shapefiles.
  179.             var result;
  180.             // If the data is not DWORD aligned, ...
  181.             if (this.position % 8 != 0) {
  182.                 var bytes = this.array.slice(this.position, this.position + numDoubles * ByteBuffer.DOUBLE_SIZE);
  183.                 result = new Float64Array(bytes);
  184.             }
  185.             else {
  186.                 result = new Float64Array(this.array, this.position, numDoubles);
  187.             }
  188.             this.position += ByteBuffer.DOUBLE_SIZE * numDoubles;
  189.             return result;
  190.         };
  192.         /**
  193.          * Skip over the specified number of bytes.
  194.          * @param {Number} numBytes The number of bytes to skip.
  195.          */
  196.         ByteBuffer.prototype.skipBytes = function(numBytes) {
  197.             this.position += numBytes * ByteBuffer.BYTE_SIZE;
  198.         };
  200.         /**
  201.          * Skip over the specified number of 16-bit integers.
  202.          * @param {Number} numInt16s The number of 16-bit integers to skip.
  203.          */
  204.         ByteBuffer.prototype.skipInt16s = function(numInt16s) {
  205.             this.position += numInt16s * ByteBuffer.INT16_SIZE;
  206.         };
  208.         /**
  209.          * Skip over the specified number of 32-bit integers.
  210.          * @param {Number} numInt32s The number of 32-bit integers to skip.
  211.          */
  212.         ByteBuffer.prototype.skipInt32s = function(numInt32s) {
  213.             this.position += numInt32s * ByteBuffer.INT32_SIZE;
  214.         };
  216.         /**
  217.          * Skip over the specified number of single precision floating point numbers.
  218.          * @param {Number} numFloats The number of single precision floating point numbers to skip.
  219.          */
  220.         ByteBuffer.prototype.skipFloats = function(numFloats) {
  221.             this.position += numFloats * ByteBuffer.FLOAT_SIZE;
  222.         };
  224.         /**
  225.          * Skip over the specified number of double precision floating point numbers.
  226.          * @param {Number} numDoubles The number of double precision floating point numbers to skip.
  227.          */
  228.         ByteBuffer.prototype.skipDoubles = function(numDoubles) {
  229.             this.position += numDoubles * ByteBuffer.DOUBLE_SIZE;
  230.         };
  232.         /**
  233.          * Advance to a specific position.
  234.          * @param {Number} position The specified position.
  235.          */
  236.         ByteBuffer.prototype.seek = function(position) {
  237.             this.position = position;
  238.         };
  240.         /**
  241.          * Set the byte order of the underlying data.
  242.          * @param {Boolean} order The byte order of the underlying data.
  243.          */
  244.         ByteBuffer.prototype.order = function(order) {
  245.             this._order = order;
  246.         };
  248.         /**
  249.          * Return the total size of the underlying data.
  250.          * @returns {Number} The size of the underlying data.
  251.          */
  252.         ByteBuffer.prototype.limit = function() {
  253.             return this.data.byteLength;
  254.         };
  256.         /**
  257.          * Indicates whether there remains any data to be accessed sequentially.
  258.          * @returns {Boolean} True if more data can be accessed sequentially.
  259.          */
  260.         ByteBuffer.prototype.hasRemaining = function() {
  261.             return this.position < this.data.byteLength;
  262.         };
  264.         /**
  265.          * Access the underlying data in big endian order, where the most significant bits of the data are encountered first.
  266.          * @type {Boolean}
  267.          * @constant
  268.          */
  269.         ByteBuffer.BIG_ENDIAN = false;
  271.         /**
  272.          * Access the underlying data in little endian order, where the least significant bits of the data are encountered first.
  273.          * @type {Boolean}
  274.          * @constant
  275.          */
  276.         ByteBuffer.LITTLE_ENDIAN = true;
  278.         /**
  279.          * The size of a byte.
  280.          * @type {Number}
  281.          * @constant
  282.          */
  283.         ByteBuffer.BYTE_SIZE = 1;
  285.         /**
  286.          * The size of a 16-bit integer.
  287.          * @type {Number}
  288.          * @constant
  289.          */
  290.         ByteBuffer.INT16_SIZE = 2;
  292.         /**
  293.          * The size of a 32-bit integer.
  294.          * @type {Number}
  295.          * @constant
  296.          */
  297.         ByteBuffer.INT32_SIZE = 4;
  299.         /**
  300.          * The size of a single precision floating point number.
  301.          * @type {Number}
  302.          * @constant
  303.          */
  304.         ByteBuffer.FLOAT_SIZE = 4;
  306.         /**
  307.          * The size of a double precision floating point number.
  308.          * @type {Number}
  309.          * @constant
  310.          */
  311.         ByteBuffer.DOUBLE_SIZE = 8;
  313.         return ByteBuffer;
  314.     }
  315. );