half precision floating point for JavaScript
See ES Discuss Float16Array topic
Install
yarn add @petamoriken/float16
npm install @petamoriken/float16 --save
Require
Node.js or Bundler (webpack, rollup.js, esbuild, etc)
import { Float16Array, getFloat16, setFloat16, hfround } from "@petamoriken/float16";
const { Float16Array, getFloat16, setFloat16, hfround } = require("@petamoriken/float16");
Browser
Serve browser/float16.mjs
/ browser/float16.js
files from your Web server as JavaScript Content-Type.
<script type="module">
import { Float16Array, getFloat16, setFloat16, hfround } from "DEST/TO/float16.mjs";
</script>
<script src="DEST/TO/float16.js"></script>
<script>
const { Float16Array, getFloat16, setFloat16, hfround } = float16;
</script>
Or use jsDelivr CDN.
<script type="module">
import { Float16Array, getFloat16, setFloat16, hfround } from "https://cdn.jsdelivr.net/npm/@petamoriken/float16/browser/float16.mjs/+esm";
</script>
<script src="https://cdn.jsdelivr.net/npm/@petamoriken/float16/browser/float16.min.js"></script>
<script>
const { Float16Array, getFloat16, setFloat16, hfround } = float16;
</script>
You can use ES Modules with Skypack CDN.
<script type="module">
import { Float16Array, getFloat16, setFloat16, hfround } from "https://cdn.skypack.dev/@petamoriken/float16?min";
</script>
Deno (Skypack CDN)
import { Float16Array, getFloat16, setFloat16, hfround } from "https://cdn.skypack.dev/@petamoriken/float16?dts";
Supports (at least)
This library's Float16Array
uses Proxy
object, so IE11 is never supported.
lib/
and browser/
directories in the npm package have JavaScript files already built, whose target are
- Firefox: last 2 versions and ESR
- Chrome: last 2 versions
- Edge: last 2 versions
- Safari: last 2 versions
- Node.js: latest version
When you build by yourself using webpack or rollup.js for old browsers support, please transpile JavaScript files in src/
directory.
API
Float16Array
This API is similar to TypedArray
such as Float32Array
.
const array = new Float16Array([1.0, 1.1, 1.2]);
for (const val of array) {
console.log(val);
}
array.reduce((prev, current) => prev + current);
DataView
declare function getFloat16(view: DataView, byteOffset: number, littleEndian?: boolean): number;
declare function setFloat16(view: DataView, byteOffset: number, value: number, littleEndian?: boolean): void;
These APIs are similar to DataView
methods such as DataView#getFloat32
and DataView#setFloat32
.
const buffer = new ArrayBuffer(10);
const view = new DataView(buffer);
view.setUint16(0, 0x1234);
getFloat16(view, 0);
view.getFloat16 = (...args) => getFloat16(view, ...args);
view.setFloat16 = (...args) => setFloat16(view, ...args);
view.getFloat16(0);
view.setFloat16(0, Math.PI, true);
view.getFloat16(0, true);
hfround
declare function hfround(x: number): number;
This API is similar to Math.fround
(MDN).
This function returns nearest half precision float representation of a number.
Math.fround(1.337);
hfround(1.337);
Limitations
Built-in functions
Built-in TypedArray
objects use "internal slots" for built-in methods. Some limitations exist because the Proxy
object can't trap internal slots (explanation).
This library isn't polyfill, in other words, it doesn't change native global functions and static/prototype methods.
E.g. ArrayBuffer.isView
is the butlt-in method that checks if it has the [[ViewedArrayBuffer]]
internal slot. It returns false
for Proxy
object such as Float16Array
.
ArrayBuffer.isView(new Float32Array(10));
ArrayBuffer.isView(new Float16Array(10));
Float16Array
prototype methods
Due to implementation reasons, some details of Float16Array
prototype methods may differ from the ECMAScript specification. See JSDoc comments in src/Float16Array.mjs
.
WebGL
WebGL requires Uint16Array
for buffer or texture data whose types are gl.HALF_FLOAT
(WebGL 2) or ext.HALF_FLOAT_OES
(WebGL 1 extension). Do not apply the Float16Array
object directly to gl.bufferData
or gl.texImage2D
etc.
const vertices = new Float16Array([
-0.5, -0.5, 0,
0.5, -0.5, 0,
0.5, 0.5, 0,
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, new Uint16Array( vertices.buffer ), gl.STATIC_DRAW);
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 3, gl.HALF_FLOAT, false, 0, 0);
gl.bindBuffer(gl.ARRAY_BUFFER, null);
Build
First, download devDependencies.
yarn
Build lib/
, browser/
files.
yarn run build
Build docs/
files (for browser test).
yarn run docs
Test
First, download devDependencies.
yarn
Node.js Test
yarn build:lib
yarn test
Browser Test
yarn build:browser
yarn docs
Access docs/test/index.html
with browsers.
You can access current test page (power-assert version) in master
branch.