text: #pragma once
  /*
      kbd.h -- keyboard matrix helpers
  
      Do this:
          #define CHIPS_IMPL
      before you include this file in *one* C or C++ file to create the 
      implementation.
  
      Optionally provide the following macros with your own implementation
      
          CHIPS_ASSERT(c)     -- your own assert macro (default: assert(c))
  
      OVERVIEW
  
      A kbd_t instance maps key codes to the cross-sections of
      an up to 12x12 keyboard matrix with up to 4 modifier keys (shift, ctrl, ...)
  
          C0  C1  C1  C2  C3 ... C12
           /   /   /   /   /       |
      L0---+---+---+---+---+-....--+
           |   /   /   /   /       /
      L1---+---+---+---+---+-....--+
           .   .   .   .   .       .
      L12--+---+---+---+---+-....--+
  
      First register host-system key codes with the keyboard matrix (where are keys
      positioned in the matrix) by calling kbd_register_modifier() and
      kbd_register_key().
  
      Feed 'host system key presses' into the keyboard_matrix instance
      by calling kbd_key_down() and kbd_key_up(). Some emulated systems
      took quite long to scan a key press, so the keyboard matrix has
      a 'sticky count', which may prolong the key press visible to the
      emulated system if the host-system key press was too short.
  
      Call the function kbd_update() once per frame, this will keep track
      of the 'sticky count' and auto-release sticky key presses which
      have expired.
  
      There's two ways to chech the state of the keyboard matrix:
  
      (1) Call the functions kbd_test_lines() or kbd_test_columns(), these
      take a bit mask of active columns or lines as input, and return a bit mask
      of the associated lines or columns which have become active in turn.
  
      (2) Sometimes the input bit mask is not available in the place where the
      keyboard scanout needs to happen. In this case you can store
      an active input mask by calling either kbd_set_active_columns() or
      kbd_set_active_lines() first, and then somewhere else, call
      kbd_scan_lines() or kbd_scan_columns() to get the resulting scanned
      bit mask.
  
      All functions for testing/scanning the keyboard matrix state are 'fast'
      because of internal state caching, most processing happens in the
      less frequently called functions kbd_update(), kbd_key_down() and
      kbd_key_up().
  
      ## zlib/libpng license
  
      Copyright (c) 2018 Andre Weissflog
      This software is provided 'as-is', without any express or implied warranty.
      In no event will the authors be held liable for any damages arising from the
      use of this software.
      Permission is granted to anyone to use this software for any purpose,
      including commercial applications, and to alter it and redistribute it
      freely, subject to the following restrictions:
          1. The origin of this software must not be misrepresented; you must not
          claim that you wrote the original software. If you use this software in a
          product, an acknowledgment in the product documentation would be
          appreciated but is not required.
          2. Altered source versions must be plainly marked as such, and must not
          be misrepresented as being the original software.
          3. This notice may not be removed or altered from any source
          distribution. 
  */
  #include <stdint.h>
  #include <stdbool.h>
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  #define KBD_MAX_COLUMNS (12)
  #define KBD_MAX_LINES (12)
  #define KBD_MAX_MOD_KEYS (4)
  #define KBD_MAX_KEYS (256)
  #define KBD_MAX_PRESSED_KEYS (4)
  
  /* a pressed-key state */
  typedef struct {
      /* key code of the pressed key */
      int key;
      /* mask bit layout is 8-bits modifier, and 12-bits each columns and lines */
      /* |SSSSSSSS|CCCCCCCCCCCC|LLLLLLLLLLLL| */
      uint32_t mask;
      /* timestamp when the key was pressed down */
      uint64_t pressed_time;
      /* true if the key has been released */
      bool released;
  } key_state_t;
  
  /* keyboard matrix state */
  typedef struct {
      /* current time stamp, bumped by kbd_update() */
      uint64_t cur_time;
      /* number of frames a key will at least remain pressed */
      uint32_t sticky_time;
      /* currently active columns */
      uint16_t active_columns;
      /* currently active lines */
      uint16_t active_lines;
      /* map key ASCII code to modifier/column/line bits */
      uint32_t key_masks[KBD_MAX_KEYS];
      /* column/line bits for modifier keys */
      uint32_t mod_masks[KBD_MAX_MOD_KEYS];
      /* currently pressed keys (bitmask==0 is empty slot) */
      key_state_t key_buffer[KBD_MAX_PRESSED_KEYS];
      /* active column/line masks, updated when key pressed state changes */
      uint16_t scanout_column_masks[KBD_MAX_LINES];
      uint16_t scanout_line_masks[KBD_MAX_COLUMNS];
      /* last cached column / scanout combinations */
      uint16_t cur_column_mask;
      uint16_t cur_scanout_line_mask;
      uint16_t cur_line_mask;
      uint16_t cur_scanout_column_mask;
  } kbd_t;
  
  /* initialize a keyboard matrix instance, provide key-sticky duration in number of 60Hz frames */
  void kbd_init(kbd_t* kbd, int sticky_frames);
  /* update keyboard matrix state (releases sticky keys), call once per frame with frame time in micro-seconds */
  void kbd_update(kbd_t* kbd, uint32_t frame_time_us);
  /* register a modifier key, layers are between from 0 to KBD_MAX_MOD_KEYS-1 */
  void kbd_register_modifier(kbd_t* kbd, int layer, int column, int line);
  /* register a modifier key where the modifier is mapped to an entire keyboard line */
  void kbd_register_modifier_line(kbd_t* kbd, int layer, int line);
  /* register a modifier key where the modifier is mapped to an entire keyboard column */
  void kbd_register_modifier_column(kbd_t* kbd, int layer, int column);
  /* register a key */
  void kbd_register_key(kbd_t* kbd, int key, int column, int line, int mod_mask);
  /* add a key to the pressed-key buffer */
  void kbd_key_down(kbd_t* kbd, int key);
  /* remove a key from the pressed-key buffer */
  void kbd_key_up(kbd_t* kbd, int key);
  /* test keyboard matrix against a column bitmask and return lit lines */
  uint16_t kbd_test_lines(kbd_t* kbd, uint16_t column_mask);
  /* test keyboard matrix against a line bitmask and return lit columns */
  uint16_t kbd_test_columns(kbd_t* kbd, uint16_t line_mask);
  /* set active column mask (use together with kbd_scan_lines */
  void kbd_set_active_columns(kbd_t* kbd, uint16_t column_mask);
  /* scan active lines (used together with kbd_set_active_columns */
  uint16_t kbd_scan_lines(kbd_t* kbd);
  /* set active lines mask (use together with kbd_scan_columns */
  void kbd_set_active_lines(kbd_t* kbd, uint16_t line_mask);
  /* scan active columns (used together with kbd_set_active_lines */
  uint16_t kbd_scan_columns(kbd_t* kbd);
  
  #ifdef __cplusplus
  } /* extern "C" */
  #endif
  
  /*-- IMPLEMENTATION ----------------------------------------------------------*/
  #ifdef CHIPS_IMPL
  #include <string.h>
  #ifndef CHIPS_ASSERT
      #include <assert.h>
      #define CHIPS_ASSERT(c) assert(c)
  #endif
  
  /*
      kbd_init(kbd_t* kbd, int sticky_count)
  
      Initialize a kbd instance:
  
      kbd             -- pointer to kbd_t instance
      sticky_frames   -- number of 60Hz frames a key will at least remain
                         pressed even when calling kbd_key_up()
                         to give emulated system enough time to sample the
                         keyboard matrix
  */
  void kbd_init(kbd_t* kbd, int sticky_frames) {
      CHIPS_ASSERT(kbd);
      memset(kbd, 0, sizeof(*kbd));
      kbd->sticky_time = sticky_frames * 16667;
  }
  
  void kbd_register_modifier(kbd_t* kbd, int layer, int column, int line) {
      CHIPS_ASSERT(kbd);
      CHIPS_ASSERT((column >= 0) && (column < KBD_MAX_COLUMNS));
      CHIPS_ASSERT((line >= 0) && (line < KBD_MAX_LINES));
      CHIPS_ASSERT((layer >= 0) && (layer < KBD_MAX_MOD_KEYS));
      kbd->mod_masks[layer] = (1<<(layer+KBD_MAX_COLUMNS+KBD_MAX_LINES)) | (1<<(column+KBD_MAX_LINES)) | (1<<line);
  }
  
  void kbd_register_modifier_line(kbd_t* kbd, int layer, int line) {
      CHIPS_ASSERT(kbd);
      CHIPS_ASSERT((line >= 0) && (line < KBD_MAX_LINES));
      CHIPS_ASSERT((layer >= 0) && (layer < KBD_MAX_MOD_KEYS));
      kbd->mod_masks[layer] = (1<<(layer+KBD_MAX_COLUMNS+KBD_MAX_LINES)) | (1<<line);
  }
  
  void kbd_register_modifier_column(kbd_t* kbd, int layer, int column) {
      CHIPS_ASSERT(kbd);
      CHIPS_ASSERT((column >= 0) && (column < KBD_MAX_COLUMNS));
      CHIPS_ASSERT((layer >= 0) && (layer < KBD_MAX_MOD_KEYS));
      kbd->mod_masks[layer] = (1<<(layer+KBD_MAX_COLUMNS+KBD_MAX_LINES)) | (1<<(column+KBD_MAX_LINES));
  }
  
  void kbd_register_key(kbd_t* kbd, int key, int column, int line, int mod_mask) {
      CHIPS_ASSERT(kbd);
      CHIPS_ASSERT((key >= 0) && (key < KBD_MAX_KEYS));
      CHIPS_ASSERT((column >= 0) && (column < KBD_MAX_COLUMNS));
      CHIPS_ASSERT((line >= 0) && (line < KBD_MAX_LINES));
      kbd->key_masks[key] = (mod_mask << (KBD_MAX_COLUMNS+KBD_MAX_LINES)) | (1<<(column+KBD_MAX_LINES)) | (1<<line);
  }
  
  /* extract column bits from a 32-bit key mask */
  static uint16_t _kbd_columns(uint32_t key_mask) {
      return (key_mask>>KBD_MAX_LINES) & ((1<<KBD_MAX_COLUMNS)-1);
  }
  
  /* extract line bits from a 32-bit key mask */
  static uint16_t _kbd_lines(uint32_t key_mask) {
      return key_mask & ((1<<KBD_MAX_LINES)-1);
  }
  
  /* extract modifier mask bits from a 32-bit key mask */
  static uint32_t _kbd_mod(uint32_t key_mask) {
      return key_mask & ((1<<KBD_MAX_MOD_KEYS)-1)<<(KBD_MAX_COLUMNS+KBD_MAX_LINES);
  }
  
  /* internal function to scan keyboard lines by column mask, SLOW! */
  static uint16_t _kbd_test_lines(kbd_t* kbd, uint16_t column_mask) {
      CHIPS_ASSERT(kbd);
      uint16_t line_bits = 0;
      for (int key_index = 0; key_index < KBD_MAX_PRESSED_KEYS; key_index++) {
          const uint32_t key_mask = kbd->key_buffer[key_index].mask;
          if (key_mask) {
              const uint16_t key_col_mask = _kbd_columns(key_mask);
              if ((key_col_mask & column_mask) == key_col_mask) {
                  line_bits |= _kbd_lines(key_mask);
              }
              const uint32_t key_mod_mask = _kbd_mod(key_mask);
              if (key_mod_mask) {
                  for (int mod_index = 0; mod_index < KBD_MAX_MOD_KEYS; mod_index++) {
                      const uint32_t mod_mask = kbd->mod_masks[mod_index];
                      if (mod_mask & key_mod_mask) {
                          const uint16_t mod_col_mask = _kbd_columns(mod_mask);
                          if (mod_col_mask) {
                              if ((mod_col_mask & column_mask) == mod_col_mask) {
                                  line_bits |= _kbd_lines(mod_mask);
                              }
                          }
                          else {
                              line_bits |= _kbd_lines(mod_mask);
                          }
                      }
                  }
              }
          }
      }
      return line_bits;
  }
  
  /* internal function to scan keyboard rows by column mask, SLOW! */
  static uint16_t _kbd_test_columns(kbd_t* kbd, uint16_t line_mask) {
      CHIPS_ASSERT(kbd);
      uint16_t column_bits = 0;
      for (int key_index = 0; key_index < KBD_MAX_PRESSED_KEYS; key_index++) {
          const uint32_t key_mask = kbd->key_buffer[key_index].mask;
          if (key_mask) {
              const uint16_t key_line_mask = _kbd_lines(key_mask);
              if ((key_line_mask & line_mask) == key_line_mask) {
                  column_bits |= _kbd_columns(key_mask);
              }
              const uint32_t key_mod_mask = _kbd_mod(key_mask);
              if (key_mod_mask) {
                  for (int mod_index = 0; mod_index < KBD_MAX_MOD_KEYS; mod_index++) {
                      const uint32_t mod_mask = kbd->mod_masks[mod_index];
                      if (mod_mask & key_mod_mask) {
                          const uint16_t mod_line_mask = _kbd_lines(mod_mask);
                          if (mod_line_mask) {
                              if ((mod_line_mask & line_mask) == mod_line_mask) {
                                  column_bits |= _kbd_columns(mod_mask);
                              }
                          }
                          else {
                              column_bits |= _kbd_columns(mod_mask);
                          }
                      }
                  }
              }
          }
      }
      return column_bits;
  }
  
  /* update the scanout column- and line-masks, SLOW! */
  static void _kbd_update_scanout_masks(kbd_t* kbd) {
      for (int line = 0; line < KBD_MAX_LINES; line++) {
          kbd->scanout_column_masks[line] = _kbd_test_columns(kbd, (1<<line));
      }
      for (int col = 0; col < KBD_MAX_COLUMNS; col++) {
          kbd->scanout_line_masks[col] = _kbd_test_lines(kbd, (1<<col));
      }
      kbd->cur_column_mask = 0;
      kbd->cur_scanout_line_mask = 0;
      kbd->cur_line_mask = 0;
      kbd->cur_scanout_column_mask = 0;
  }
  
  void kbd_update(kbd_t* kbd, uint32_t frame_time_us) {
      CHIPS_ASSERT(kbd);
      /* check for sticky keys that should be released */
      for (int i = 0; i < KBD_MAX_PRESSED_KEYS; i++) {
          key_state_t* k = &kbd->key_buffer[i];
          if (k->released) {
              /* properly handle cur_time wraparound */
              if ((kbd->cur_time < k->pressed_time) ||
                  (kbd->cur_time > (k->pressed_time + kbd->sticky_time))) {
                  k->mask = 0;
                  k->key = 0;
                  k->pressed_time = 0;
                  k->released = false;
              }
          }
      }
      kbd->cur_time += frame_time_us;
      _kbd_update_scanout_masks(kbd);
  }
  
  void kbd_key_down(kbd_t* kbd, int key) {
      CHIPS_ASSERT(kbd && (key >= 0) && (key < KBD_MAX_KEYS));
      /* first check if the key is already in the key buffer,
         if yes, just update its pressed-frame and return,
         otherwise find a new, free keybuffer slot
      */
      for (int i = 0; i < KBD_MAX_PRESSED_KEYS; i++) {
          key_state_t* k = &kbd->key_buffer[i];
          if (k->key == key) {
              k->pressed_time = kbd->cur_time;
              _kbd_update_scanout_masks(kbd);
              return;
          }
      }
      for (int i = 0; i < KBD_MAX_PRESSED_KEYS; i++) {
          key_state_t* k = &kbd->key_buffer[i];
          if (0 == k->mask) {
              k->key = key;
              k->mask = kbd->key_masks[key];
              k->pressed_time = kbd->cur_time;
              k->released = false;
              _kbd_update_scanout_masks(kbd);
              return;
          }
      }
  }
  
  void kbd_key_up(kbd_t* kbd, int key) {
      CHIPS_ASSERT(kbd && (key >= 0) && (key < KBD_MAX_KEYS));
      /* find the key in the keybuffer, just set released_frame */
      for (int i = 0; i < KBD_MAX_PRESSED_KEYS; i++) {
          key_state_t* k = &kbd->key_buffer[i];
          if (key == k->key) {
              k->released = true;
          }
      }
      _kbd_update_scanout_masks(kbd);
  }
  
  /* scan keyboard matrix lines by column mask */
  uint16_t kbd_test_lines(kbd_t* kbd, uint16_t column_mask) {
      if (column_mask != kbd->cur_column_mask) {
          kbd->cur_column_mask = column_mask;
          kbd->cur_scanout_line_mask = 0;
          for (int col = 0; col < KBD_MAX_COLUMNS; col++) {
              if (column_mask & (1<<col)) {
                  kbd->cur_scanout_line_mask |= kbd->scanout_line_masks[col];
              }
          }
      }
      return kbd->cur_scanout_line_mask;
  }
  
  /* scan keyboard matrix lines by column mask */
  uint16_t kbd_test_columns(kbd_t* kbd, uint16_t line_mask) {
      if (line_mask != kbd->cur_line_mask) {
          kbd->cur_line_mask = line_mask;
          kbd->cur_scanout_column_mask = 0;
          for (int line = 0; line < KBD_MAX_COLUMNS; line++) {
              if (line_mask & (1<<line)) {
                  kbd->cur_scanout_column_mask |= kbd->scanout_column_masks[line];
              }
          }
      }
      return kbd->cur_scanout_column_mask;
  }
  
  /* set currently active columns */
  void kbd_set_active_columns(kbd_t* kbd, uint16_t column_mask) {
      kbd->active_columns = column_mask;
  }
  
  /* scan the keyboard matrix using currently active columns */
  uint16_t kbd_scan_lines(kbd_t* kbd) {
      return kbd_test_lines(kbd, kbd->active_columns);
  }
  
  /* set currently active lines */
  void kbd_set_active_lines(kbd_t* kbd, uint16_t line_mask) {
      kbd->active_lines = line_mask;
  }
  
  /* scan the keyboard matrix using currently active lines */
  uint16_t kbd_scan_columns(kbd_t* kbd) {
      return kbd_test_columns(kbd, kbd->active_lines);
  }
  
  #endif /* CHIPS_IMPL */
  