Instantly share code, notes, and snippets.

# jensnockert/dsp-api.md Created Jul 29, 2012

Initial Thoughts on the DSP API Specification (http://people.opera.com/mage/dspapi/)

# Basic Operations

## clamp

What happens if a NaN is provided as input? Copying to output seems like the best option.

## modulo

Is almost, but not exactly the same as the IEEE 754 remainder operation, which specifies some special cases. Should just define this in terms of the IEEE 754 spec, since that is what ES does for all other arithmetic operations. (Note that I don't think this is the same as the ES `%` operator, which does rounding differently iirc)

## sign

I don't like how sign(NaN) is implementation defined, should be NaN.

## Trigonometry and Other Elementary Functions

These are not actually specified in ES, only their names, so we may need to define them here; since everything else seems to aim for quite rigid specification.

Since we're using single-precision, while Math uses double-precision, you would otherwise need to use double intermediates and therefore round twice if you follow the current wording of the spec.

# DSP Interface

Not really required, would not be faster than madd.

## mul/div (for Complex numbers)

Is more complex than it seems, do you allow FMA for example? Is Gauß 3-multiplication form allowed, how does it overflow, etc? C99 provides a more complete specification, handling overflow etc.

Should probably define if it allows fused multiply-add, and probably add another variant that requires fused behaviour which is useful for a few interesting algorithms.

Should probably also have a msub version also, which is similarly useful.

## abs (for Complex numbers)

Should be defined in terms of something like abs(x)*sqrt(1 + (y/x)^2), abs(x) > abs(y), so intermediates do not overflow. ES.next is likely going to introduce a Math.hypot function with this definition.

## fract

Should be defined in terms of the modulo primitive. Is there any point in exposing this instead of modulo (except that it doesn't match up with the ES `%` operator?)

## pack / unpack

Should probably have n arguments, rather than max 4. Multi-channel audio for example could require 5+1 (or more) channels for example.

## ramp

I don't think it performance-wise makes for much of an improvement, but should things like `dst[k] = first + k * ((last - first) / (dst.length - 1))` be allowed? This also removes an overflow opportunity in the current implementation.

## random

What are the requirements, is it required to return the same result as ES Math.random() ran in a scalar loop? Is it allowed to use another parallel algorithm for generation? Is it allowed to use a different seed?

## Interpolation Operations

Do we allow, or disallow FMA etc. Are optimizations allowed, are methods that reduce the risk of overflow allowed? Are they required?

## sum

The implementation is not trivial, you should specify a method that sets the minimum precision at least. Just looping over the array with,

``````var sum = 0.0;

for (var i = 0; i < a.length; i++) {
sum += a[i]
}

return sum
``````

does not yield acceptable precision.

## Missing

A dot-product seems like an obiously missing part, the same thing with 1-norm (sum of absolute values), 2-norm (sum of squares) and inf-norm (max) functions for real and complex numbers.