Typed Array Specification

Editor's Draft 18 July 2013

This version:

https://www.khronos.org/registry/typedarray/specs/latest/
Web IDL: https://www.khronos.org/registry/typedarray/specs/latest/typedarray.idl

Latest version:

https://www.khronos.org/registry/typedarray/specs/latest/
Web IDL: https://www.khronos.org/registry/typedarray/specs/latest/typedarray.idl

Previous version:

https://www.khronos.org/registry/typedarray/specs/1.0/
Web IDL: https://www.khronos.org/registry/typedarray/specs/1.0/typedarray.idl

Editors:

David Herman (Mozilla Corporation)

Kenneth Russell (Google, Inc.)

Abstract

This specification provides an API for interoperability with native binary data. It defines a generic fixed-length buffer type, as well as accessor types that allow access to the data stored within the buffer.

The functionality described here originated in the WebGL specification [WEBGL].

Status of this document

This document is an editor's draft. Do not cite this document as other than work in progress. Public discussion of this specification is welcome on the (archived) WebGL mailing list public_webgl@khronos.org (see instructions).

The latest version of this document, including all revision history, may be obtained via Subversion:

svn co https://cvs.khronos.org/svn/repos/registry/trunk/public/typedarray
        

Table of contents

Introduction

Overview

      // create an 8-byte ArrayBuffer
      var b = new ArrayBuffer(8);

      // create a view v1 referring to b, of type Int32, starting at
      // the default byte index (0) and extending until the end of the buffer
      var v1 = new Int32Array(b);

      // create a view v2 referring to b, of type Uint8, starting at
      // byte index 2 and extending until the end of the buffer
      var v2 = new Uint8Array(b, 2);

      // create a view v3 referring to b, of type Int16, starting at
      // byte index 2 and having a length of 2
      var v3 = new Int16Array(b, 2, 2);
    

Endianness

The typed array view types operate with the endianness of the host computer.

The DataView type operates upon data with a specified endianness (big-endian or little-endian).

Type Conversion Rules

The specification below implicitly references certain type conversion rules; for example, conversion of floating-point values to integer values of various sizes. The Web IDL specification [WEBIDL] defines these rules, and references the ECMA-262 specification [ECMA-262] for conversion algorithms such as ToInt32.

The Web IDL specification does not currently define all of the numerical types referenced in this specification; for example, byte, which is a signed 8-bit integer type. For these types, the rules for the type of the closest size and signedness shall be extrapolated.

Handling of Not-a-Number (NaN) Values

When the not-a-number (NaN) value is stored into a Float32Array or Float64Array, or into a DataView using the setFloat32 or setFloat64 methods, the bit pattern written into the underlying ArrayBuffer is not specified, but shall be one of the IEEE 754 bit patterns that represent NaN [IEEE-754].

When a bit pattern representing an IEEE 754 NaN is loaded from a Float32Array or Float64Array, or from a DataView using the getFloat32 or getFloat64 methods, the language binding (for example, ECMAScript) may use an alternative bit pattern to represent the NaN value.

The Web IDL [WEBIDL] and ECMA-262 [ECMA-262] specifications govern all other handling of NaN values, in particular the conversion to 0 when converting NaN to an integer value.

The ArrayBuffer Type

The ArrayBuffer type describes a buffer used to store data for the array buffer views. An ArrayBuffer has the following methods and properties:

[ Constructor(unsigned long length) ]
interface ArrayBuffer {
    readonly attribute unsigned long byteLength;
    ArrayBuffer slice(long begin, optional long end);
    static boolean isView(any value);
};
ArrayBuffer implements Transferable;

The ArrayBufferView Type

The ArrayBufferView type holds information shared among all of the types of views of ArrayBuffers. An ArrayBufferView has the following properties:

[NoInterfaceObject]
interface ArrayBufferView {
    readonly attribute ArrayBuffer buffer;
    readonly attribute unsigned long byteOffset;
    readonly attribute unsigned long byteLength;
};

The Typed Array View Types

The typed array view types represent a view of an ArrayBuffer that allows for indexing and manipulation. The length of each of these is fixed. Each of the typed array view types follows the same template.

The following typed array view types are defined by this specification. The size below is given in bytes, and corresponds to the BYTES_PER_ELEMENT constant for the given type.

Each of the typed array types has the following constructors, properties, constants and methods. In the descriptions below, the generic term TypedArray is used to indicate that any valid typed array view type is allowed. Uint8ClampedArray is defined in the next section.

An object array implementing one of the TypedArray interfaces supports indexed properties [WEBIDL] with indices in the range 0 ≤ index < array.length.

Typed array views operating upon multi-byte values use the host computer's endianness when reading or writing values from or to main memory.

[
    Constructor(unsigned long length),
    Constructor(TypedArray array),
    Constructor(type[] array),
    Constructor(ArrayBuffer buffer,
                optional unsigned long byteOffset, optional unsigned long length)
]
interface TypedArray {
    const unsigned long BYTES_PER_ELEMENT = element size in bytes;

    readonly attribute unsigned long length;

    getter type get(unsigned long index);
    setter void set(unsigned long index, type value);
    void set(TypedArray array, optional unsigned long offset);
    void set(type[] array, optional unsigned long offset);
    TypedArray subarray(long begin, optional long end);
};
TypedArray implements ArrayBufferView;

Uint8ClampedArray

Uint8ClampedArray is defined in order to replace CanvasPixelArray. It behaves identically to the other typed array views, except that the setters and constructor use clamping [WEBIDL] rather than modulo arithmetic when converting incoming number values. The IDL for Uint8ClampedArray follows.

// The 'unsigned byte' type does not currently exist in Web IDL, though
// 'octet' is equivalent.
[
    Constructor(unsigned long length),
    Constructor(Uint8ClampedArray array),
    Constructor(octet[] array),
    Constructor(ArrayBuffer buffer,
                optional unsigned long byteOffset, optional unsigned long length)
]
interface Uint8ClampedArray {
    const unsigned long BYTES_PER_ELEMENT = 1;

    readonly attribute unsigned long length;

    getter octet get(unsigned long index);
    setter void set(unsigned long index, [Clamp] octet value);
    void set(Uint8ClampedArray array, optional unsigned long offset);
    void set(octet[] array, optional unsigned long offset);
    Uint8ClampedArray subarray(long begin, optional long end);
};
Uint8ClampedArray implements ArrayBufferView;

The DataView View Type

An ArrayBuffer is a useful object for representing an arbitrary chunk of data. In many cases, such data will be read from disk or from the network, and will not follow the alignment restrictions that are imposed on the typed array views described earlier. In addition, the data will often be heterogeneous in nature and have a defined byte order. The DataView view provides a low-level interface for reading such data from and writing it to an ArrayBuffer.

Regardless of the host computer's endianness, DataView reads or writes values to or from main memory with a specified endianness: big or little.

[
  Constructor(ArrayBuffer buffer,
              optional unsigned long byteOffset,
              optional unsigned long byteLength)
]
interface DataView {
    // Gets the value of the given type at the specified byte offset
    // from the start of the view. There is no alignment constraint;
    // multi-byte values may be fetched from any offset.
    //
    // For multi-byte values, the optional littleEndian argument
    // indicates whether a big-endian or little-endian value should be
    // read. If false or undefined, a big-endian value is read.
    //
    // These methods raise an exception if they would read
    // beyond the end of the view.
    byte getInt8(unsigned long byteOffset);
    octet getUint8(unsigned long byteOffset);
    short getInt16(unsigned long byteOffset,
                   optional boolean littleEndian);
    unsigned short getUint16(unsigned long byteOffset,
                             optional boolean littleEndian);
    long getInt32(unsigned long byteOffset,
                  optional boolean littleEndian);
    unsigned long getUint32(unsigned long byteOffset,
                            optional boolean littleEndian);
    float getFloat32(unsigned long byteOffset,
                     optional boolean littleEndian);
    double getFloat64(unsigned long byteOffset,
                      optional boolean littleEndian);

    // Stores a value of the given type at the specified byte offset
    // from the start of the view. There is no alignment constraint;
    // multi-byte values may be stored at any offset.
    //
    // For multi-byte values, the optional littleEndian argument
    // indicates whether the value should be stored in big-endian or
    // little-endian byte order. If false or undefined, the value is
    // stored in big-endian byte order.
    //
    // These methods raise an exception if they would write
    // beyond the end of the view.
    void setInt8(unsigned long byteOffset,
                 byte value);
    void setUint8(unsigned long byteOffset,
                  octet value);
    void setInt16(unsigned long byteOffset,
                  short value,
                  optional boolean littleEndian);
    void setUint16(unsigned long byteOffset,
                   unsigned short value,
                   optional boolean littleEndian);
    void setInt32(unsigned long byteOffset,
                  long value,
                  optional boolean littleEndian);
    void setUint32(unsigned long byteOffset,
                   unsigned long value,
                   optional boolean littleEndian);
    void setFloat32(unsigned long byteOffset,
                    float value,
                    optional boolean littleEndian);
    void setFloat64(unsigned long byteOffset,
                    double value,
                    optional boolean littleEndian);
};
DataView implements ArrayBufferView;

The following constructors, properties, and methods are available on a DataView:

Cloning and Transferring ArrayBuffers and Views

Cloning an ArrayBuffer

When a user agent is asked to clone an ArrayBuffer object old, it must run the following steps, which return a new ArrayBuffer object. These steps must be run atomically.

1. Create a new ArrayBuffer object new buffer pointing at a copy of the underlying data from old, and with the same byteLength property.
2. Return new buffer. It is the clone.

Transferring an ArrayBuffer

Add the following to the list of Transferable types:

• ArrayBuffer

To transfer [HTML] an ArrayBuffer object old, a user agent must run the following steps.

1. Create a new ArrayBuffer object new buffer pointing at the same underlying data as old, and with the same byteLength property.
2. Neuter [HTML] object old.
3. Return new buffer.

Cloning an ArrayBufferView

When a user agent is asked to clone an ArrayBufferView object old, it must run the following steps, which return a new object. These steps must be run atomically.

1. Let buffer be the result of invoking the internal structured cloning algorithm recursively on the buffer property of old.
2. Let new view be a newly constructed ArrayBufferView subclass of the same type as old, referring to buffer, and with the same byteOffset, byteLength, and any subclass-specific properties as old.
3. Return new view. It is the clone.

Examples

var f32s = new Float32Array(128);

for (var i = 0; i < 128/8; ++i) {
  var sub_f32s = f32s.subarray(i, i+8);
  for (var j = 0; j < 8; ++j) {
    sub_f32s[j] = j;
  }
}
      

var elementSize = 3 * Float32Array.BYTES_PER_ELEMENT + 4 * Uint8Array.BYTES_PER_ELEMENT;
var buffer = new ArrayBuffer(4 * elementSize);
var coords = new Float32Array(buffer, 0);
var colors = new Uint8Array(buffer, 3 * Float32Array.BYTES_PER_ELEMENT);
      

var coordOffset = elementSize / Float32Array.BYTES_PER_ELEMENT;
var colorOffset = elementSize / Uint8Array.BYTES_PER_ELEMENT;

coords[0] = coords[1] = coords[2] = 1.0; // The first point's three coordinate values
colors[0] = colors[1] = colors[2] = colors[3] = 255; // The first point's four colors

coords[0+N*coordOffset] = 5.0; // The Nth point's first coordinate value
colors[0+N*colorOffset] = 128; // The Nth point's first color value

coords[i+N*coordOffset] = 6.0; // The Nth point's i coordinate value;
colors[j+N*colorOffset] = 200; // The Nth point's j color value
      

var buffer = new ArrayBuffer(1024);
      

var floats = new Float32Array(buffer, 0, 128);
      

var shorts = new Uint16Array(buffer, 512, 128);
      

var bytes = new Uint8Array(buffer, shorts.byteOffset + shorts.byteLength);
      

Resolved Issues

References

Acknowledgments

The editors would like to thank Erik Arvidsson (Google), Joshua Bell (Linden Lab), Mark Callow (HI), Brendan Eich (Mozilla), Andreas Gal (Mozilla), Daniel Gessel (Apple), Dave Herman (Mozilla), Oliver Hunt (Apple), Tim Johansson (Opera), Vangelis Kokkevis (Google), Chris Marrin (Apple), Glenn Maynard, Cameron McCormack, Shiki Okasaka (Google), Arun Ranganathan (Mozilla), Alex Russell (Google), Gregg Tavares (Google), Ben Vanik (Google), Cedric Vivier (Mozilla), and the members of the WebGL working group for their contributions to this specification.

The editors would especially like to thank Vladimir Vukicevic for co-editing earlier versions of this specification.