@petamoriken/float16

What is @petamoriken/float16?

@petamoriken/float16 is an npm package that provides utilities for handling 16-bit floating-point numbers (half-precision). It allows for conversion between 16-bit floats and other numeric types, as well as arithmetic operations on 16-bit floats.

What are @petamoriken/float16's main functionalities?

Conversion from 32-bit float to 16-bit float

This feature allows you to convert a 32-bit floating-point number to a 16-bit floating-point number. The code sample demonstrates converting the 32-bit float value 1.5 to its 16-bit float representation.

const { float32ToFloat16 } = require('@petamoriken/float16');
const float32 = 1.5;
const float16 = float32ToFloat16(float32);
console.log(float16); // Output: 15360

Conversion from 16-bit float to 32-bit float

This feature allows you to convert a 16-bit floating-point number back to a 32-bit floating-point number. The code sample demonstrates converting the 16-bit float value 15360 back to its 32-bit float representation.

const { float16ToFloat32 } = require('@petamoriken/float16');
const float16 = 15360;
const float32 = float16ToFloat32(float16);
console.log(float32); // Output: 1.5

Arithmetic operations on 16-bit floats

This feature provides basic arithmetic operations (addition, subtraction, multiplication, and division) on 16-bit floating-point numbers. The code sample demonstrates these operations using two 16-bit float values representing 1.5.

const { addFloat16, subFloat16, mulFloat16, divFloat16 } = require('@petamoriken/float16');
const a = 15360; // 1.5 in 16-bit float
const b = 15360; // 1.5 in 16-bit float
console.log(addFloat16(a, b)); // Output: 16384 (3.0 in 16-bit float)
console.log(subFloat16(a, b)); // Output: 0 (0.0 in 16-bit float)
console.log(mulFloat16(a, b)); // Output: 15872 (2.25 in 16-bit float)
console.log(divFloat16(a, b)); // Output: 15360 (1.0 in 16-bit float)

Other packages similar to @petamoriken/float16

float16

The 'float16' package provides similar functionality for handling 16-bit floating-point numbers. It includes methods for converting between 16-bit and 32-bit floats, as well as arithmetic operations. However, it may have a different API and performance characteristics compared to @petamoriken/float16.

README

@petamoriken/float16

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)

// ES Modules
import { Float16Array, getFloat16, setFloat16, hfround } from "@petamoriken/float16";

// CommonJS
const { Float16Array, getFloat16, setFloat16, hfround } = require("@petamoriken/float16");

Browser

Copy browser/float16.js file to your project directory.

<script src="DEST/TO/float16.js"></script>
<script>
    const { Float16Array, getFloat16, setFloat16, hfround } = float16;
</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); // => 1, 1.099609375, 1.19921875
}

array.reduce((prev, current) => prev + current); // 3.298828125

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); // 0.0007572174072265625

// You can append methods to DataView instance
view.getFloat16 = (...args) => getFloat16(view, ...args);
view.setFloat16 = (...args) => setFloat16(view, ...args);

view.getFloat16(0); // 0.0007572174072265625

view.setFloat16(0, Math.PI, true);
view.getFloat16(0, true); // 3.140625

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); // 1.3370000123977661
hfround(1.337); // 1.3369140625

Limitations

Built-in TypedArray objects uses "internal slots" for built-in methods. Some limitations exist because the Proxy object can't trap internal slots (explanation).

Built-in Functions

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)); // true
ArrayBuffer.isView(new Float16Array(10)); // false

WebGL

WebGL requires Uint16Array for buffer or texture data whose type 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.

// WebGL 2 example

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); // wrap in Uint16Array
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.