binary_dither.h

Go to the documentation of this file.

#pragma once

 
#include "fl/stl/int.h"
#include "fl/stl/compiler_control.h"
#include "fl/stl/noexcept.h"
#include "fl/math/math8.h"
#include "fl/math/scale8.h"

#ifndef MAX_LIKELY_UPDATE_RATE_HZ
#define MAX_LIKELY_UPDATE_RATE_HZ     400
#endif

#ifndef MIN_ACCEPTABLE_DITHER_RATE_HZ
#define MIN_ACCEPTABLE_DITHER_RATE_HZ  50
#endif

#ifndef UPDATES_PER_FULL_DITHER_CYCLE
#define UPDATES_PER_FULL_DITHER_CYCLE (MAX_LIKELY_UPDATE_RATE_HZ / MIN_ACCEPTABLE_DITHER_RATE_HZ)
#endif

#ifndef RECOMMENDED_VIRTUAL_BITS
#define RECOMMENDED_VIRTUAL_BITS ((UPDATES_PER_FULL_DITHER_CYCLE>1) + \
                                  (UPDATES_PER_FULL_DITHER_CYCLE>2) + \
                                  (UPDATES_PER_FULL_DITHER_CYCLE>4) + \
                                  (UPDATES_PER_FULL_DITHER_CYCLE>8) + \
                                  (UPDATES_PER_FULL_DITHER_CYCLE>16) + \
                                  (UPDATES_PER_FULL_DITHER_CYCLE>32) + \
                                  (UPDATES_PER_FULL_DITHER_CYCLE>64) + \
                                  (UPDATES_PER_FULL_DITHER_CYCLE>128) )
#endif

#ifndef VIRTUAL_BITS
#define VIRTUAL_BITS RECOMMENDED_VIRTUAL_BITS
#endif
 
namespace fl {

struct BinaryDither {
    enum { kEnabled = 1 };

    static FASTLED_FORCE_INLINE u8 phase(u8 frame) FL_NO_EXCEPT {
        frame &= (0x01 << VIRTUAL_BITS) - 1;
        u8 q = 0;
        if (frame & 0x01) { q |= 0x80; }
        if (frame & 0x02) { q |= 0x40; }
        if (frame & 0x04) { q |= 0x20; }
        if (frame & 0x08) { q |= 0x10; }
        if (frame & 0x10) { q |= 0x08; }
        if (frame & 0x20) { q |= 0x04; }
        if (frame & 0x40) { q |= 0x02; }
        if (frame & 0x80) { q |= 0x01; }
        if (VIRTUAL_BITS < 8) {
            q += 0x01 << (7 - VIRTUAL_BITS);
        }
        return q;
    }

    static FASTLED_FORCE_INLINE u8 offset(u8 q, u8 range) FL_NO_EXCEPT {
        u8 d = fl::scale8(q, range);
#if (FASTLED_SCALE8_FIXED == 1)
        // Adjust for the fixed scale8's rounding up.
        if (d) { --d; }
#endif
        return d;
    }

    static FASTLED_FORCE_INLINE void init(u8 (&d)[3], u8 (&e)[3], const u8 (&scale)[3],
                                          u8 frame) FL_NO_EXCEPT {
        const u8 q = phase(frame);
        for (int i = 0; i < 3; ++i) {
            // Computed in a local and stored once; re-reading `e[i]` after
            // the `d[i]` store cost 36 B on AVR (#4672).
            const u8 s = scale[i];
            u8 range = s ? (256 / s) + 1 : 0;
            d[i] = offset(q, range);
            if (range) { --range; }
            e[i] = range;
        }
    }

    static FASTLED_FORCE_INLINE void reseed(u8 (&d)[3], const u8 (&e)[3], u8 frame) FL_NO_EXCEPT {
        const u8 q = phase(frame);
        for (int i = 0; i < 3; ++i) {
            // `e[i]` is init's range less one; zero only for an unlit
            // channel, which carries no offset.
            d[i] = e[i] ? offset(q, static_cast<u8>(e[i] + 1)) : 0;
        }
    }
 
    static FASTLED_FORCE_INLINE void clear(u8 (&d)[3], u8 (&e)[3]) FL_NO_EXCEPT {
        d[0] = d[1] = d[2] = e[0] = e[1] = e[2] = 0;
    }
 
    static FASTLED_FORCE_INLINE bool active(const u8 (&e)[3]) FL_NO_EXCEPT {
        return (e[0] | e[1] | e[2]) != 0;
    }

    static FASTLED_FORCE_INLINE void step(u8 (&d)[3], const u8 (&e)[3]) FL_NO_EXCEPT {
        d[0] = e[0] - d[0];
        d[1] = e[1] - d[1];
        d[2] = e[2] - d[2];
    }

    static FASTLED_FORCE_INLINE void stepChannel(u8 (&d)[3], const u8 (&e)[3], int c) FL_NO_EXCEPT {
        d[c] = e[c] - d[c];
    }

    static FASTLED_FORCE_INLINE u8 apply(u8 b, u8 d) FL_NO_EXCEPT {
        return b ? fl::qadd8(b, d) : 0;
    }
};

struct NoDither {
    enum { kEnabled = 0 };
 
    static FASTLED_FORCE_INLINE u8 phase(u8) FL_NO_EXCEPT { return 0; }
    static FASTLED_FORCE_INLINE u8 offset(u8, u8) FL_NO_EXCEPT { return 0; }
    static FASTLED_FORCE_INLINE void init(u8 (&d)[3], u8 (&e)[3], const u8 (&)[3], u8) FL_NO_EXCEPT {
        clear(d, e);
    }
    static FASTLED_FORCE_INLINE void reseed(u8 (&)[3], const u8 (&)[3], u8) FL_NO_EXCEPT {}
    static FASTLED_FORCE_INLINE void clear(u8 (&d)[3], u8 (&e)[3]) FL_NO_EXCEPT {
        d[0] = d[1] = d[2] = e[0] = e[1] = e[2] = 0;
    }
    static FASTLED_FORCE_INLINE bool active(const u8 (&)[3]) FL_NO_EXCEPT { return false; }
    static FASTLED_FORCE_INLINE void step(u8 (&)[3], const u8 (&)[3]) FL_NO_EXCEPT {}
    static FASTLED_FORCE_INLINE void stepChannel(u8 (&)[3], const u8 (&)[3], int) FL_NO_EXCEPT {}
    static FASTLED_FORCE_INLINE u8 apply(u8 b, u8) FL_NO_EXCEPT { return b; }
};

#if defined(NO_DITHERING) && (NO_DITHERING == 1)
typedef NoDither Dither;
#else
typedef BinaryDither Dither;
#endif
 
}  // namespace fl