Basis's RDO DXTc compression API

This is a work in progress, but here's the API to the new rate distortion optimizing DXTc codec I've been working on for Basis. There's only one function (excluding basis_get_version()): basis_rdo_dxt_encode(). You call it with some encoding parameters and an array of input images (or "slices"), and it gives you back a blob of DXTc blocks which you then feed to any LZ codec like zlib, zstd, LZHAM, Oodle, etc.

The output DXTc blocks are organized in simple raster order, with slice 0's blocks first, then slice 1's, etc. The slices could be mipmap levels, or cubemap faces, etc. For highest compression, it's very important to feed the output blocks to the LZ codec in the order that this function gives them back to you.

On my near-term TODO list is to allow the user to specify custom per-channel weightings, and to add more color distance functions. Right now it supports either uniform weights, or a custom model for sRGB colorspace photos/textures. Also, I may expose optional per-slice weightings (for mipmaps).

I'm shipping the first version (as a Windows DLL) tomorrow.

// File: basis_rdo_dxt_public.h
#pragma once

#include <stdlib.h>
#include <memory.h>

#ifdef BASIS_DLL_EXPORTS
#define BASIS_DLL_EXPORT __declspec(dllexport)  
#else  
#define BASIS_DLL_EXPORT
#endif  

#if defined(_MSC_VER)
#define BASIS_CDECL __cdecl
#else
#define BASIS_CDECL
#endif

namespace basis
{
   const int BASIS_VERSION = 0x0100;

   typedef unsigned int basis_uint;
   typedef basis_uint rdo_dxt_bool;

   enum rdo_dxt_format
   {
      cRDO_DXT1 = 0,
      cRDO_DXT5,
      cRDO_DXN,
      cRDO_DXT5A,

      cRDO_DXT_FORCE_DWORD = 0xFFFFFFFF
   };

   const basis_uint RDO_DXT_STRUCT_VERSION = 0xABCD0001;

   const basis_uint RDO_QUALITY_MIN = 1;
   const basis_uint RDO_QUALITY_MAX = 255;

   struct rdo_dxt_params
   {
      basis_uint m_struct_size;
      basis_uint m_struct_version;

      rdo_dxt_format m_format;

      basis_uint m_quality;

      basis_uint m_alpha_component_indices[2];

      basis_uint m_lz_max_match_dist;
      basis_uint m_output_block_size;

      basis_uint m_num_color_endpoint_clusters;
      basis_uint m_num_color_selector_clusters;

      basis_uint m_num_alpha_endpoint_clusters;
      basis_uint m_num_alpha_selector_clusters;

      float m_l;
      float m_selector_rdo_quality_threshold;
      float m_endpoint_selector_rdo_quality_threshold;

      float m_selector_rdo_quality_threshold_low;
      float m_endpoint_selector_rdo_quality_threshold_low;

      float m_block_max_y_std_dev_rdo_quality_scaler;

      basis_uint m_endpoint_refinement_steps;
      basis_uint m_selector_refinement_steps;
      basis_uint m_final_block_refinement_steps;

      float m_adaptive_tile_color_psnr_derating;
      float m_adaptive_tile_alpha_psnr_derating;

      basis_uint m_endpoint_rdo_max_search_distance;

      rdo_dxt_bool m_optimize_final_endpoint_clusters;
      rdo_dxt_bool m_optimize_final_selector_clusters;

      rdo_dxt_bool m_srgb_metrics;
      rdo_dxt_bool m_debugging;
      rdo_dxt_bool m_debug_output;
      rdo_dxt_bool m_hierarchical_mode;
      rdo_dxt_bool m_multithreaded;
   };

   inline void rdo_dxt_params_set_to_defaults(rdo_dxt_params *p)
   {
      memset(p, 0, sizeof(rdo_dxt_params));

      p->m_struct_size = sizeof(rdo_dxt_params);
      p->m_struct_version = RDO_DXT_STRUCT_VERSION;

      p->m_format = cRDO_DXT1;

      p->m_quality = 128;

      p->m_alpha_component_indices[0] = 0;
      p->m_alpha_component_indices[1] = 1;

      p->m_l = .001f;

      p->m_selector_rdo_quality_threshold = 1.75f;
      p->m_endpoint_selector_rdo_quality_threshold = 1.75f;

      p->m_selector_rdo_quality_threshold_low = 1.3f;
      p->m_endpoint_selector_rdo_quality_threshold_low = 1.3f;

      p->m_block_max_y_std_dev_rdo_quality_scaler = 8.0f;

      p->m_lz_max_match_dist = 32768;
      p->m_output_block_size = 8;

      p->m_endpoint_refinement_steps = 2;
      p->m_selector_refinement_steps = 2;
      p->m_final_block_refinement_steps = 1;

      p->m_adaptive_tile_color_psnr_derating = 1.5f;
      p->m_adaptive_tile_alpha_psnr_derating = 1.5f;
      p->m_endpoint_rdo_max_search_distance = 8;

      p->m_optimize_final_endpoint_clusters = true;
      p->m_optimize_final_selector_clusters = true;

      p->m_hierarchical_mode = true;

      p->m_multithreaded = true;
   }

   const basis_uint RDO_DXT_MAX_IMAGE_DIMENSION = 16384;

   struct rdo_dxt_slice_desc
   {
      // Pixel dimensions of this slice. A slice may be a mipmap level, a cubemap face, a video frame, or whatever.
      basis_uint m_image_width;
      basis_uint m_image_height;
      basis_uint m_image_pitch_in_pixels;

      // Pointer to 32-bit raster image. Format in memory: RGBA (R is first byte, A is last)
      const void *m_pImage_pixels;
   };

} // namespace basis

extern "C" BASIS_DLL_EXPORT basis::basis_uint BASIS_CDECL basis_get_version();

extern "C" BASIS_DLL_EXPORT bool BASIS_CDECL basis_rdo_dxt_encode(
   const basis::rdo_dxt_params *pEncoder_params,
   basis::basis_uint total_input_image_slices, const basis::rdo_dxt_slice_desc *pInput_image_slices,
   void *pOutput_blocks, basis::basis_uint output_blocks_size_in_bytes);