Google Git
Sign in
skia/external/github.com/BinomialLLC/basis_universal/fc3a67a5c028c19f24099dac77f4f78290f2bd0f/./encoder/basisu_xbc7_encode.cpp
blob: 035e722ee673935c2cfaf32b91bb6fe1891982af [file]
// File: basisu_xbc7_encode.cpp
#include "basisu_xbc7_encode.h"
#include "../transcoder/basisu_transcoder.h"
#include "../zstd/zstd.h"
#include "../transcoder/basisu_xbc7_decoder.h"
#include "basisu_bc7e_scalar.h"
using basist::fixed16_16;
namespace basisu {
namespace xbc7
{
using namespace basist::xbc7; // shared XBC7 defs (DCT/syms/enums/eval) now live in basist::xbc7
class blob_stream_writer
{
public:
blob_stream_writer() {}
void clear() { m_blobs.clear(); }
inline uint8_vec& get_blob_vec(uint32_t id)
{
assert(id < BLOB_STREAM_MAX_IDS);
if (id >= m_blobs.size())
m_blobs.resize(id + 1);
return m_blobs[id];
}
// Hot path: append one byte to blob `id`. id must be < 128.
inline void put_byte(uint32_t id, uint8_t b)
{
assert(id < BLOB_STREAM_MAX_IDS);
if (id >= m_blobs.size())
m_blobs.resize(id + 1);
m_blobs[id].push_back(b);
}
inline void put_bytes(uint32_t id, const void* p, size_t n)
{
assert(id < BLOB_STREAM_MAX_IDS);
if (id >= m_blobs.size())
m_blobs.resize(id + 1);
m_blobs[id].append(static_cast<const uint8_t*>(p), n);
}
void append_bytes(uint32_t id, const uint8_vec& blob)
{
assert(id < BLOB_STREAM_MAX_IDS);
if (id >= m_blobs.size())
m_blobs.resize(id + 1);
m_blobs[id].append(blob);
}
// for the per-stream byte accounting / stats dashboard
inline size_t get_blob_size(uint32_t id) const { return (id < m_blobs.size()) ? m_blobs[id].size() : 0; }
inline uint32_t get_num_ids() const { return m_blobs.size_u32(); }
inline const uint8_vec* get_blob_data(uint32_t id) const { return (id < m_blobs.size()) ? &m_blobs[id] : nullptr; }
// Compress (where it helps) and serialize everything to `out`.
// Returns false only on internal error (blob > 4GB etc).
bool serialize(uint8_vec& out, int zstd_level = 19, uint32_t* pStored_sizes = nullptr) const // pStored_sizes: optional [BLOB_STREAM_MAX_IDS] array, receives stored (post-compression) payload bytes per id
{
out.resize(0);
uint32_t num_stored = 0;
for (uint32_t id = 0; id < m_blobs.size(); id++)
if (m_blobs[id].size())
num_stored++;
if (num_stored > 255)
return false;
out.push_back(BLOB_STREAM_MAGIC_BEGIN);
out.push_back((uint8_t)num_stored);
uint8_vec comp_buf;
for (uint32_t id = 0; id < m_blobs.size(); id++)
{
const uint8_vec& blob = m_blobs[id];
if (!blob.size())
continue;
if (blob.size() > UINT32_MAX)
return false;
const uint32_t uncomp_size = (uint32_t)blob.size();
// Try Zstd; keep it only if it's worth it. Small blobs keep any
// win, but a LARGE blob must shrink by at least 1/400 (0.25%):
// raw blobs are zero-copy at decode (no Zstd frame to walk, no
// arena bytes), so a marginal win costs more than it saves.
const uint8_t* pStored = blob.data();
uint32_t stored_size = 0; // 0 == raw
const size_t bound = ZSTD_compressBound(blob.size());
comp_buf.resize(bound);
const size_t comp_res = ZSTD_compress(comp_buf.data(), bound, blob.data(), blob.size(), zstd_level);
if ((!ZSTD_isError(comp_res)) && (comp_res < blob.size()))
{
const uint32_t BLOB_RATIO_CHECK_MIN_SIZE = 128; // blobs <= this keep any win
const uint32_t BLOB_MIN_SAVINGS_DENOM = 400; // larger blobs must save >= size/400
const uint64_t saved_bytes = (uint64_t)blob.size() - comp_res;
if ((blob.size() <= BLOB_RATIO_CHECK_MIN_SIZE) || ((saved_bytes * BLOB_MIN_SAVINGS_DENOM) >= (uint64_t)blob.size()))
{
pStored = comp_buf.data();
stored_size = (uint32_t)comp_res;
}
}
if (pStored_sizes)
pStored_sizes[id] = stored_size ? stored_size : uncomp_size;
// directory entry: id+flag byte, then varint size(s)
out.push_back((uint8_t)(id | (stored_size ? 0x80u : 0u)));
if (stored_size)
{
push_varint(out, uncomp_size);
push_varint(out, stored_size);
}
else
push_varint(out, uncomp_size);
out.append(pStored, stored_size ? stored_size : uncomp_size);
}
out.push_back(BLOB_STREAM_MAGIC_END);
return true;
}
private:
basisu::vector<uint8_vec> m_blobs;
static inline void push_varint(uint8_vec& v, uint32_t x)
{
while (x >= 0x80u)
{
v.push_back((uint8_t)(x | 0x80u));
x >>= 7;
}
v.push_back((uint8_t)x);
}
};
static const char* g_cand_names[cCandFirstXYDelta] =
{
"absolute", "left edge", "upper edge", "L+U blend", "reflect left", "reflect upper",
"L+U avg", "L+U strong blend", "gradient", "damped gradient", "diag avg",
"diag edge blend", "upper+diag edge blend", "MED", "GAB", "plane fit",
"diag down-left", "diag down-right"
};
// Post-quantization DCT coefficient statistics, collected from the WINNING
// candidate of each non-solid block, per coded plane. Gives the picture the
// run/coeff/sign stream design needs: where surviving ACs sit in zigzag
// order, their amplitudes and signs, run lengths, and DC behavior.
struct xbc7_dct_stats
{
uint64_t m_total_planes = 0;
// DC (range is [-256, 256] by construction)
uint64_t m_dc_zero = 0, m_dc_pos = 0, m_dc_neg = 0;
uint64_t m_dc_sum_abs = 0;
int m_dc_min = 257, m_dc_max = -257;
uint64_t m_dc_mag_hist[10] = {};
// AC
uint64_t m_total_acs = 0;
uint64_t m_ac_pos = 0, m_ac_neg = 0;
uint64_t m_ac_sum_abs = 0;
int m_ac_min = 257, m_ac_max = -257;
uint64_t m_ac_mag_hist[10] = {};
uint64_t m_ac_count_hist[16] = {}; // nonzero ACs per plane, 0..15
uint64_t m_zig_pos_hist[16] = {}; // zigzag position (1..15) of each nonzero AC
uint64_t m_run_hist[16] = {}; // zero-run length coded before each nonzero AC
uint64_t m_eob_markers = 0; // trailing-zeros records
// |v| -> bucket: 1, 2, 3, 4, 5-8, 9-16, 17-32, 33-64, 65-128, 129+
static uint32_t mag_bucket(uint32_t m)
{
if (m <= 4) return m - 1;
if (m <= 8) return 4;
if (m <= 16) return 5;
if (m <= 32) return 6;
if (m <= 64) return 7;
if (m <= 128) return 8;
return 9;
}
void record_plane(const dct_syms& syms)
{
m_total_planes++;
const int dc = syms.m_dc;
if (!dc) m_dc_zero++; else if (dc > 0) m_dc_pos++; else m_dc_neg++;
m_dc_sum_abs += (uint64_t)basisu::iabs(dc);
m_dc_min = basisu::minimum(m_dc_min, dc);
m_dc_max = basisu::maximum(m_dc_max, dc);
if (dc)
m_dc_mag_hist[mag_bucket((uint32_t)basisu::iabs(dc))]++;
uint32_t num_acs = 0;
uint32_t zig_idx = 1;
for (uint32_t i = 0; i < syms.m_ac_vals.size_u32(); i++)
{
const uint32_t run_len = (uint32_t)syms.m_ac_vals[i].m_num_zeros;
const int c = syms.m_ac_vals[i].m_coeff;
if (c == INT16_MAX)
{
m_eob_markers++;
break;
}
zig_idx += run_len;
assert(zig_idx < 16);
if (zig_idx >= 16)
break;
m_run_hist[basisu::minimum<uint32_t>(run_len, 15)]++;
m_zig_pos_hist[zig_idx]++;
if (c > 0) m_ac_pos++; else m_ac_neg++;
m_ac_sum_abs += (uint64_t)basisu::iabs(c);
m_ac_min = basisu::minimum(m_ac_min, c);
m_ac_max = basisu::maximum(m_ac_max, c);
m_ac_mag_hist[mag_bucket((uint32_t)basisu::iabs(c))]++;
num_acs++;
zig_idx++;
}
m_total_acs += num_acs;
m_ac_count_hist[basisu::minimum<uint32_t>(num_acs, 15)]++;
}
// accumulate another collector (per-job stats -> totals); counters add,
// extrema take min/max
void merge(const xbc7_dct_stats& o)
{
m_total_planes += o.m_total_planes;
m_dc_zero += o.m_dc_zero; m_dc_pos += o.m_dc_pos; m_dc_neg += o.m_dc_neg;
m_dc_sum_abs += o.m_dc_sum_abs;
m_dc_min = basisu::minimum(m_dc_min, o.m_dc_min);
m_dc_max = basisu::maximum(m_dc_max, o.m_dc_max);
for (uint32_t i = 0; i < 10; i++)
m_dc_mag_hist[i] += o.m_dc_mag_hist[i];
m_total_acs += o.m_total_acs;
m_ac_pos += o.m_ac_pos; m_ac_neg += o.m_ac_neg;
m_ac_sum_abs += o.m_ac_sum_abs;
m_ac_min = basisu::minimum(m_ac_min, o.m_ac_min);
m_ac_max = basisu::maximum(m_ac_max, o.m_ac_max);
for (uint32_t i = 0; i < 10; i++)
m_ac_mag_hist[i] += o.m_ac_mag_hist[i];
for (uint32_t i = 0; i < 16; i++)
{
m_ac_count_hist[i] += o.m_ac_count_hist[i];
m_zig_pos_hist[i] += o.m_zig_pos_hist[i];
m_run_hist[i] += o.m_run_hist[i];
}
m_eob_markers += o.m_eob_markers;
}
void print() const
{
static const char* s_mag_labels[10] = { "1", "2", "3", "4", "5-8", "9-16", "17-32", "33-64", "65-128", "129+" };
fmt_debug_printf("---- WEIGHTS: DCT coefficient statistics (winning candidates, per coded plane) ----\n");
const float inv_p = m_total_planes ? (100.0f / (float)m_total_planes) : 0.0f;
const float inv_a = m_total_acs ? (100.0f / (float)m_total_acs) : 0.0f;
fmt_debug_printf("Coded planes: {}, total nonzero ACs: {}, avg ACs/plane: {}\n",
m_total_planes, m_total_acs, m_total_planes ? ((float)m_total_acs / (float)m_total_planes) : 0.0f);
fmt_debug_printf("DC: zero: {} ({}%), pos: {} ({}%), neg: {} ({}%), range [{}, {}], mean |DC| (all planes): {}\n",
m_dc_zero, (float)m_dc_zero * inv_p, m_dc_pos, (float)m_dc_pos * inv_p, m_dc_neg, (float)m_dc_neg * inv_p,
m_dc_min, m_dc_max, m_total_planes ? ((float)m_dc_sum_abs / (float)m_total_planes) : 0.0f);
fmt_debug_printf("DC magnitude histogram (nonzero DCs): ");
for (uint32_t i = 0; i < 10; i++)
if (m_dc_mag_hist[i])
fmt_debug_printf("{}:{} ", s_mag_labels[i], m_dc_mag_hist[i]);
fmt_debug_printf("\n");
fmt_debug_printf("AC: pos: {} ({}%), neg: {} ({}%), range [{}, {}], mean |AC| (per nonzero AC): {}\n",
m_ac_pos, (float)m_ac_pos * inv_a, m_ac_neg, (float)m_ac_neg * inv_a,
m_ac_min, m_ac_max, m_total_acs ? ((float)m_ac_sum_abs / (float)m_total_acs) : 0.0f);
fmt_debug_printf("AC magnitude histogram: ");
for (uint32_t i = 0; i < 10; i++)
if (m_ac_mag_hist[i])
fmt_debug_printf("{}:{} ({}%) ", s_mag_labels[i], m_ac_mag_hist[i], (float)m_ac_mag_hist[i] * inv_a);
fmt_debug_printf("\n");
fmt_debug_printf("Nonzero ACs per plane: ");
for (uint32_t i = 0; i < 16; i++)
if (m_ac_count_hist[i])
fmt_debug_printf("{}:{} ({}%) ", i, m_ac_count_hist[i], (float)m_ac_count_hist[i] * inv_p);
fmt_debug_printf("\n");
fmt_debug_printf("Zigzag position of nonzero ACs (1..15): ");
for (uint32_t i = 1; i < 16; i++)
fmt_debug_printf("{}:{} ", i, m_zig_pos_hist[i]);
fmt_debug_printf("\n");
fmt_debug_printf("Zero-run length before each AC: ");
for (uint32_t i = 0; i < 16; i++)
if (m_run_hist[i])
fmt_debug_printf("{}:{} ({}%) ", i, m_run_hist[i], (float)m_run_hist[i] * inv_a);
fmt_debug_printf("\n");
fmt_debug_printf("Trailing-zeros (EOB) markers: {} ({}% of planes)\n", m_eob_markers, (float)m_eob_markers * inv_p);
}
};
// ---- debug-image color palettes (encode-time visualization only) ----
// The command byte is split into three field-specific color images rather
// than one hard-to-read grayscale; each image carries a drawn legend.
// CORE command id (xbc7_command_id, command bits 0-2).
static const color_rgba g_xbc7_command_vis_colors[8] =
{
color_rgba( 0, 0, 255, 255), // 0 RepeatLast - blue
color_rgba( 0, 255, 255, 255), // 1 RepeatUpper - cyan
color_rgba(128, 128, 128, 255), // 2 SolidDPCM - gray
color_rgba(255, 0, 0, 255), // 3 NewConfig - red
color_rgba( 0, 255, 0, 255), // 4 ReuseConfigLeft - green
color_rgba(255, 255, 0, 255), // 5 ReuseConfigUpper - yellow
color_rgba(255, 0, 255, 255), // 6 ReuseConfigLeftDiagonal - magenta
color_rgba(255, 128, 0, 255), // 7 ReuseConfigRightDiagonal - orange
};
// ENDPOINT prediction mode (xbc7_command_endpoint_mode, command bits 3-5).
static const color_rgba g_xbc7_endpoint_mode_vis_colors[8] =
{
color_rgba(255, 0, 0, 255), // 0 Raw - red
color_rgba( 0, 200, 0, 255), // 1 DPCM-Left - green
color_rgba( 0, 128, 255, 255), // 2 DPCM-Up - blue
color_rgba(255, 255, 0, 255), // 3 DPCM-LeftDiag - yellow
color_rgba(255, 0, 255, 255), // 4 DPCM-RightDiag - magenta
color_rgba( 0, 255, 255, 255), // 5 DPCM-Index - cyan
color_rgba(255, 128, 0, 255), // 6 DPCM-Left-Sub1 - orange
color_rgba(160, 0, 255, 255), // 7 DPCM-Up-Sub1 - purple
};
// WEIGHT mode (xbc7_command_weight_mode, command bit 6).
static const color_rgba g_xbc7_weight_mode_vis_colors[2] =
{
color_rgba( 0, 200, 0, 255), // 0 Raw/DPCM (lossless) - green
color_rgba(255, 0, 0, 255), // 1 DCT (lossy) - red
};
// Blocks with no endpoint/weight fields (fully predicted: RepeatLast/
// RepeatUpper/SolidDPCM) in the endpoint/weight-mode images.
static const color_rgba g_xbc7_vis_na_color(40, 40, 40, 255);
// AC-COUNT heatmap: number of nonzero DCT weight ACs in a block (DCT-coded
// blocks only). Bucketed via xbc7_ac_count_bucket().
static const color_rgba g_xbc7_ac_count_vis_colors[6] =
{
color_rgba( 0, 0, 128, 255), // 0 ACs - dark blue (flat / DC only)
color_rgba( 0, 128, 255, 255), // 1-2 ACs - blue
color_rgba( 0, 200, 0, 255), // 3-5 ACs - green
color_rgba(255, 255, 0, 255), // 6-10 ACs - yellow
color_rgba(255, 128, 0, 255), // 11-20 ACs - orange
color_rgba(255, 0, 0, 255), // 21+ ACs - red
};
static inline uint32_t xbc7_ac_count_bucket(uint32_t num_acs)
{
if (num_acs == 0) return 0;
if (num_acs <= 2) return 1;
if (num_acs <= 5) return 2;
if (num_acs <= 10) return 3;
if (num_acs <= 20) return 4;
return 5;
}
// PREDICTOR categories: the ~50 weight predictors (absolute, 17 synthetic,
// 32 block references) collapsed into a handful of buckets; the 32 block
// refs are split by their causal direction.
enum xbc7_pred_category
{
cPredCatAbsolute = 0, // no prediction
cPredCatSynthetic, // edge/gradient synthetic predictors
cPredCatRefLeft, // block ref, same row (dy==0)
cPredCatRefUp, // block ref, straight up (dx==0)
cPredCatRefUpLeft, // block ref, up-and-left
cPredCatRefUpRight, // block ref, up-and-right
cNumPredCategories
};
static const color_rgba g_xbc7_predictor_vis_colors[cNumPredCategories] =
{
color_rgba(255, 0, 0, 255), // Absolute - red
color_rgba(255, 128, 0, 255), // Synthetic - orange
color_rgba( 0, 200, 0, 255), // BlockRef Left - green
color_rgba( 0, 128, 255, 255), // BlockRef Up - blue
color_rgba( 0, 255, 255, 255), // BlockRef Up-Left - cyan
color_rgba(255, 0, 255, 255), // BlockRef Up-Right - magenta
};
// Map a (cand + amp*cTotalCandidates) predictor index to its category.
static inline uint32_t xbc7_predictor_category(uint32_t pred_index)
{
const uint32_t cand = pred_index % cTotalCandidates;
if (cand == cCandAbsolute)
return cPredCatAbsolute;
if (cand < cCandFirstXYDelta)
return cPredCatSynthetic;
const xbc7_xy_delta d = g_xbc7_xy_deltas[cand - cCandFirstXYDelta];
if (d.m_dy == 0) return cPredCatRefLeft; // dx<0, same row
if (d.m_dx == 0) return cPredCatRefUp; // straight up
return (d.m_dx < 0) ? cPredCatRefUpLeft : cPredCatRefUpRight;
}
// Weighted RGBA PSNR of a 16-pixel (4x4) block vs the source, using the
// caller's per-channel weights (pack_options::m_weights), exactly mirroring
// basisu_astc_ldr_encode.cpp's WSSE->PSNR: per-pixel WSSE via
// color_rgba::get_weighted_dist2(), wmse = wsse / (sum_weights * num_pixels),
// then 20*log10(255/sqrt(wmse)), capped for ~zero error. Used by the BC7
// alt-pack and endpoint-DPCM RDO passes.
static inline float xbc7_block_wsse_psnr(const color_rgba* pOrig, const color_rgba* pDec, const uint32_t comp_weights[4])
{
uint64_t wsse = 0;
for (uint32_t i = 0; i < 16; i++)
wsse += pDec[i].get_weighted_dist2(pOrig[i], comp_weights);
const float total_comp_weights = (float)(comp_weights[0] + comp_weights[1] + comp_weights[2] + comp_weights[3]);
const float wmse = (float)wsse / (total_comp_weights * 16.0f);
return (wmse > 1e-5f) ? (20.0f * log10f(255.0f / sqrtf(wmse))) : 10000.0f;
}
// Standalone: recompute the optimal per-texel weights of a BC7 logical block
// for its FIXED config + endpoints, ignoring its existing (possibly stale)
// weights. out_blk receives in_blk's config + endpoints with freshly optimized
// weights. comp_weights[4] are the per-channel RGBA error weights. No
// dependency on pack_options, so this can be lifted into shared code later.
//
// Per plane: each texel's weight independently selects its interpolation
// between the fixed endpoints, so setting all texels to the same value w and
// decoding reveals every texel's value at w in one decode; sweeping w over all
// 1<<m_weight_bits[plane] values and keeping each texel's lowest WSSE yields
// the per-texel optimum. Error is summed ONLY over the channels this plane
// drives (get_decoded_channel_weight_plane) -- critical for dual-plane modes,
// where planes 0/1 control disjoint channels (with mode 4/5 rotation/CCS).
[[maybe_unused]] static bool optimize_block_weights(const basist::bc7u::log_bc7_block& in_blk, const color_rgba orig_pixels[16], const uint32_t comp_weights[4], basist::bc7u::log_bc7_block& out_blk)
{
out_blk = in_blk; // same config + endpoints; weights overwritten below
for (uint32_t p = 0; p < in_blk.m_num_planes; p++)
{
const uint32_t num_weight_vals = in_blk.get_num_weight_vals(p); // 4, 8, or 16
basist::bc7u::log_bc7_block scratch(in_blk);
// neutralize the OTHER plane so the decode is well-defined; the
// channel masking below means it can't affect this plane's WSSE anyway
if (in_blk.is_dual_plane())
memset(scratch.m_weights[1u - p], 0, sizeof(scratch.m_weights[0]));
uint64_t best_err[16];
uint8_t best_weight[16];
for (uint32_t i = 0; i < 16; i++)
{
best_err[i] = UINT64_MAX;
best_weight[i] = 0;
}
for (uint32_t w = 0; w < num_weight_vals; w++)
{
for (uint32_t i = 0; i < 16; i++)
scratch.m_weights[p][i] = (uint8_t)w;
basist::color_rgba dec[16];
if (!basist::bc7u::unpack_bc7(scratch, dec))
{
assert(0); // a valid config+endpoints block must always decode
return false;
}
for (uint32_t i = 0; i < 16; i++)
{
uint64_t err = 0;
for (uint32_t c = 0; c < 4; c++)
{
if (in_blk.get_decoded_channel_weight_plane(c) != p)
continue; // only the channels this plane drives
const int d = (int)dec[i][c] - (int)orig_pixels[i][c];
err += (uint64_t)(d * d) * comp_weights[c];
}
if (err < best_err[i])
{
best_err[i] = err;
best_weight[i] = (uint8_t)w;
}
}
}
for (uint32_t i = 0; i < 16; i++)
out_blk.m_weights[p][i] = best_weight[i];
}
return true;
}
// Encode-time visualization targets (debug only). Each member is null unless
// m_debug_images is set. One 4x4 pixel block per BC7 block; stripes fill
// disjoint block rows, so writing these from stripe jobs is thread-safe.
struct xbc7_debug_image_set
{
image* m_pCommand = nullptr; // core command id (bits 0-2)
image* m_pEndpoint_mode = nullptr; // endpoint pred mode (bits 3-5); n/a for predicted blocks
image* m_pWeight_mode = nullptr; // weight mode (bit 6): DCT vs lossless; n/a for predicted blocks
image* m_pAC_count = nullptr; // # nonzero DCT weight ACs; n/a unless DCT-coded
image* m_pPredictor = nullptr; // weight predictor category; n/a for predicted blocks
};
// Fill one BC7 block's 4x4 region in a (possibly null) debug image.
static inline void xbc7_vis_fill_block(image* pImg, uint32_t bx, uint32_t by, const color_rgba& c)
{
if (pImg)
pImg->fill_box(bx * 4, by * 4, 4, 4, c);
}
// Color-fill a block across all debug images from its final command byte.
// has_ep_wt is false for fully-predicted blocks (RepeatLast/RepeatUpper/
// SolidDPCM), which carry no endpoint/weight fields. pred_index is the weight
// predictor (UINT32_MAX == none); ac_count is the nonzero DCT-weight AC count
// (UINT32_MAX == not DCT-coded). UINT32_MAX maps to the n/a color.
static inline void xbc7_vis_fill_command(const xbc7_debug_image_set& dbg, uint32_t bx, uint32_t by,
uint8_t command_byte, bool has_ep_wt, uint32_t pred_index, uint32_t ac_count)
{
xbc7_vis_fill_block(dbg.m_pCommand, bx, by, g_xbc7_command_vis_colors[command_byte & 7]);
if (has_ep_wt)
{
xbc7_vis_fill_block(dbg.m_pEndpoint_mode, bx, by, g_xbc7_endpoint_mode_vis_colors[(command_byte >> XBC7_COMMAND_ENDPOINT_MODE_SHIFT) & 7]);
xbc7_vis_fill_block(dbg.m_pWeight_mode, bx, by, g_xbc7_weight_mode_vis_colors[(command_byte >> XBC7_COMMAND_WEIGHT_MODE_SHIFT) & 1]);
}
else
{
xbc7_vis_fill_block(dbg.m_pEndpoint_mode, bx, by, g_xbc7_vis_na_color);
xbc7_vis_fill_block(dbg.m_pWeight_mode, bx, by, g_xbc7_vis_na_color);
}
xbc7_vis_fill_block(dbg.m_pPredictor, bx, by,
(pred_index == UINT32_MAX) ? g_xbc7_vis_na_color : g_xbc7_predictor_vis_colors[xbc7_predictor_category(pred_index)]);
xbc7_vis_fill_block(dbg.m_pAC_count, bx, by,
(ac_count == UINT32_MAX) ? g_xbc7_vis_na_color : g_xbc7_ac_count_vis_colors[xbc7_ac_count_bucket(ac_count)]);
}
// ---- legend drawn into a strip at the bottom of each debug image ----
const uint32_t XBC7_VIS_LEGEND_ROW_H = 10; // px per entry (8px glyph + 2px gap)
static inline uint32_t xbc7_vis_legend_height(uint32_t num_entries) { return num_entries * XBC7_VIS_LEGEND_ROW_H + 4; }
struct xbc7_vis_legend_entry { color_rgba m_color; const char* m_pLabel; };
// Draws a swatch+label list into the BOTTOM strip of img, overwriting the
// block pixels there (the image stays the source resolution). Everything
// clips, so it's safe even if the strip is taller than the whole image.
static void xbc7_vis_draw_legend(image& img, const xbc7_vis_legend_entry* pEntries, uint32_t num_entries)
{
const uint32_t legend_h = xbc7_vis_legend_height(num_entries);
const uint32_t top_y = (img.get_height() >= legend_h) ? (img.get_height() - legend_h) : 0;
img.fill_box(0, top_y, img.get_width(), img.get_height() - top_y, color_rgba(16, 16, 16, 255));
for (uint32_t i = 0; i < num_entries; i++)
{
const uint32_t y = top_y + 2 + i * XBC7_VIS_LEGEND_ROW_H;
img.fill_box(2, y, 8, 8, pEntries[i].m_color);
img.debug_text(14, y, 1, 1, color_rgba(255, 255, 255, 255), nullptr, false, "%s", pEntries[i].m_pLabel);
}
}
// ---------------- encoder striping ----------------
// The main coding pass splits into 1..XBC7_MAX_ENCODER_STRIPES horizontal
// stripes of whole block rows, one job per stripe. Each stripe is coded
// causally from scratch (the encoder never emits references above a
// stripe's first row), so thin stripes cost compression: small images stay
// serial, and once striping kicks in every stripe gets at least
// XBC7_MIN_STRIPE_BLOCK_ROWS rows.
// (XBC7_MAX_ENCODER_STRIPES is shared with the decoder -- defined in
// basisu_xbc7_decode.h.)
// images shorter than this many TEXEL rows always encode as one stripe
const uint32_t XBC7_MIN_IMAGE_TEXEL_ROWS_TO_STRIPE = 128;
// minimum BLOCK rows per stripe once striping kicks in (bounds the
// per-seam compression loss); 16 block rows == 64 texel rows
const uint32_t XBC7_MIN_STRIPE_BLOCK_ROWS = 16;
// Computes the encoder's stripe count (1..XBC7_MAX_ENCODER_STRIPES) and
// each stripe's contiguous block-row range. Deliberately a function of
// the image dimensions ONLY -- not of thread availability -- so the
// encoded output is reproducible across machines; with fewer pool threads
// than stripes the extra jobs simply queue.
static uint32_t compute_encoder_stripes(
uint32_t height_in_texels, uint32_t num_blocks_y,
basisu::vector<stripe_range>& stripes)
{
uint32_t num_stripes = 1;
if (height_in_texels >= XBC7_MIN_IMAGE_TEXEL_ROWS_TO_STRIPE)
{
num_stripes = num_blocks_y / XBC7_MIN_STRIPE_BLOCK_ROWS;
num_stripes = basisu::clamp<uint32_t>(num_stripes, 1, XBC7_MAX_ENCODER_STRIPES);
}
num_stripes = basisu::minimum(num_stripes, basisu::maximum(1u, num_blocks_y));
compute_stripe_ranges(num_blocks_y, num_stripes, stripes);
return num_stripes;
}
// Highest stripe count this image can carry without violating the striping
// rules: at least XBC7_MIN_STRIPE_BLOCK_ROWS per stripe (so none is tiny or
// empty), no more than XBC7_MAX_ENCODER_STRIPES, and 1 for images too short
// to stripe usefully. Mirrors the bound compute_encoder_stripes uses.
static uint32_t max_stripes_for_image(uint32_t height_in_texels, uint32_t num_blocks_y)
{
if (height_in_texels < XBC7_MIN_IMAGE_TEXEL_ROWS_TO_STRIPE)
return 1;
const uint32_t by_min_size = num_blocks_y / XBC7_MIN_STRIPE_BLOCK_ROWS; // each stripe >= min block rows
return basisu::clamp<uint32_t>(by_min_size, 1, XBC7_MAX_ENCODER_STRIPES);
}
uint32_t pack_options::set_num_stripes_for_image(const image& img, uint32_t desired_num_stripes)
{
const uint32_t height = img.get_height();
const uint32_t num_blocks_y = (height + 3) / 4;
const uint32_t max_stripes = max_stripes_for_image(height, num_blocks_y);
m_num_stripes = basisu::clamp<uint32_t>(desired_num_stripes, 1, max_stripes);
return m_num_stripes;
}
void pack_options::set_rdo_level(uint32_t rdo_level)
{
rdo_level = basisu::minimum<uint32_t>(rdo_level, 100);
if (!rdo_level)
{
// RDO fully disabled: flags off, all drops zero.
m_bc7_alt_pack_enabled = false;
m_endpoint_rdo_enabled = false;
m_repeat_rdo_enabled = false;
m_solid_rdo_enabled = false;
m_bc7_alt_max_psnr_drop = 0.0f;
m_endpoint_rdo_max_psnr_drop = 0.0f;
m_repeat_rdo_max_psnr_drop = 0.0f;
m_solid_rdo_max_psnr_drop = 0.0f;
m_ac_trunc_rdo_max_psnr_drop = 0.0f;
return;
}
const float frac = (float)rdo_level / 100.0f; // (0, 1]
const float general_drop = 10.0f * frac; // BC7 alt-pack / endpoint-DPCM / AC-trunc -> up to 10 dB
const float reuse_drop = 4.0f * frac; // repeat / solid block reuse -> up to 4 dB
m_bc7_alt_pack_enabled = true;
m_bc7_alt_max_psnr_drop = general_drop;
m_endpoint_rdo_enabled = true;
m_endpoint_rdo_max_psnr_drop = general_drop;
m_ac_trunc_rdo_max_psnr_drop = general_drop; // no enable flag; >0 enables
m_repeat_rdo_enabled = true;
m_repeat_rdo_max_psnr_drop = reuse_drop;
m_solid_rdo_enabled = true;
m_solid_rdo_max_psnr_drop = reuse_drop;
}
// ------------------------- XBC7 encoding statistics -------------------------
// Populated inline during pack_image (negligible cost), printed when
// opts.m_print_stats is set. Three layers: where the bytes go (per-blob
// accounting), what the encoder chose (command/mode/predictor histograms),
// and why (residual and coefficient distributions).
struct xbc7_pack_stats
{
// context
uint32_t m_width = 0, m_height = 0, m_total_blocks = 0, m_dct_q = 0;
bool m_has_alpha = false;
basisu::vector<stripe_range> m_stripes;
// choices
uint64_t m_cmd_hist[8] = {};
uint64_t m_mode_hist[8] = {}; // coded (non-repeat, non-solid) blocks
uint64_t m_pred_hist[cTotalCandidates * 4] = {};
uint64_t m_ep_raw_blocks = 0, m_ep_dpcm_blocks = 0, m_ep_dpcm_subsets = 0;
// AC-truncation RDO
uint64_t m_ac_trunc_pruned = 0; // weight-DCT AC coeffs zeroed
uint64_t m_ac_trunc_blocks = 0; // blocks where >=1 coeff was pruned
uint64_t m_ep_mode_hist[8] = {}; // xbc7_command_endpoint_mode of every coded block
uint64_t m_ep_index_hist[NUM_XY_DELTAS] = {}; // XY-delta table index of every EP block reference
uint64_t m_pbit_delta_bits = 0, m_pbit_delta_nonzero = 0;
// distributions: EP residuals by [width class][stream channel slot],
// wrapped bytes interpreted as int8 (the zero-peaked reading)
uint64_t m_ep_resid_count[2][4] = {}; // [0]=fine, [1]=coarse
uint64_t m_ep_resid_sum_abs[2][4] = {};
uint64_t m_ep_resid_zero[2][4] = {};
uint64_t m_solid_delta_count[4] = {};
uint64_t m_solid_delta_sum_abs[4] = {};
uint64_t m_solid_delta_zero[4] = {};
// weights: residual DCT vs lossless DPCM decision + tuning data
uint32_t m_wt_alpha_pct = 0;
uint64_t m_wt_dct_blocks = 0, m_wt_dpcm_blocks = 0;
uint64_t m_wt_dct_est_bits_total = 0, m_wt_dpcm_est_bits_total = 0, m_wt_chosen_est_bits = 0;
uint64_t m_wt_block_acs_hist_dct[33] = {}; // total ACs per block (clamped), split by which mode won
uint64_t m_wt_block_acs_hist_dpcm[33] = {};
uint64_t m_wt_dpcm_pred_hist[cTotalCandidates * 4] = {};
uint64_t m_wt_resid_count[3] = {}, m_wt_resid_zero[3] = {}, m_wt_resid_sum_abs[3] = {}; // [weight_bits - 2]
uint64_t m_wt_resid_mag_hist[3][9] = {}; // [weight_bits - 2][min(|centered resid|, 8)]
xbc7_dct_stats m_dct_stats; // winning-candidate coefficient stats
// where the bytes go (filled at serialize time)
uint32_t m_blob_raw_size[BLOB_STREAM_MAX_IDS] = {};
uint32_t m_blob_stored_size[BLOB_STREAM_MAX_IDS] = {};
uint32_t m_total_file_size = 0;
// order-0 byte histograms of the pre-Zstd blob contents
uint64_t m_blob_hist[cBlobFirstUnused][256] = {};
void record_blob_bytes(uint32_t id, const uint8_vec* pBlob)
{
if ((id >= (uint32_t)cBlobFirstUnused) || (!pBlob))
return;
for (size_t i = 0; i < pBlob->size(); i++)
m_blob_hist[id][(*pBlob)[i]]++;
}
void record_ep_residuals(bool fine_class, const uint8_t* pResiduals, uint32_t num_residuals)
{
const uint32_t cls = fine_class ? 0 : 1;
for (uint32_t i = 0; i < num_residuals; i++)
{
const uint32_t chan = i >> 1;
const int v = (int8_t)pResiduals[i];
m_ep_resid_count[cls][chan]++;
m_ep_resid_sum_abs[cls][chan] += (uint64_t)basisu::iabs(v);
if (!v)
m_ep_resid_zero[cls][chan]++;
}
}
// Accumulate a per-stripe (per-job) collector into this one. Pure
// counters only: the context fields (dims/Q/stripes/alpha) and the
// blob size/histogram arrays are owned by the final stats object and
// filled outside the jobs.
void merge(const xbc7_pack_stats& o)
{
for (uint32_t i = 0; i < 8; i++)
{
m_cmd_hist[i] += o.m_cmd_hist[i];
m_mode_hist[i] += o.m_mode_hist[i];
m_ep_mode_hist[i] += o.m_ep_mode_hist[i];
}
for (uint32_t i = 0; i < cTotalCandidates * 4; i++)
{
m_pred_hist[i] += o.m_pred_hist[i];
m_wt_dpcm_pred_hist[i] += o.m_wt_dpcm_pred_hist[i];
}
m_ep_raw_blocks += o.m_ep_raw_blocks;
m_ep_dpcm_blocks += o.m_ep_dpcm_blocks;
m_ep_dpcm_subsets += o.m_ep_dpcm_subsets;
m_ac_trunc_pruned += o.m_ac_trunc_pruned;
m_ac_trunc_blocks += o.m_ac_trunc_blocks;
for (uint32_t i = 0; i < NUM_XY_DELTAS; i++)
m_ep_index_hist[i] += o.m_ep_index_hist[i];
m_pbit_delta_bits += o.m_pbit_delta_bits;
m_pbit_delta_nonzero += o.m_pbit_delta_nonzero;
for (uint32_t cls = 0; cls < 2; cls++)
{
for (uint32_t c = 0; c < 4; c++)
{
m_ep_resid_count[cls][c] += o.m_ep_resid_count[cls][c];
m_ep_resid_sum_abs[cls][c] += o.m_ep_resid_sum_abs[cls][c];
m_ep_resid_zero[cls][c] += o.m_ep_resid_zero[cls][c];
}
}
for (uint32_t c = 0; c < 4; c++)
{
m_solid_delta_count[c] += o.m_solid_delta_count[c];
m_solid_delta_sum_abs[c] += o.m_solid_delta_sum_abs[c];
m_solid_delta_zero[c] += o.m_solid_delta_zero[c];
}
m_wt_dct_blocks += o.m_wt_dct_blocks;
m_wt_dpcm_blocks += o.m_wt_dpcm_blocks;
m_wt_dct_est_bits_total += o.m_wt_dct_est_bits_total;
m_wt_dpcm_est_bits_total += o.m_wt_dpcm_est_bits_total;
m_wt_chosen_est_bits += o.m_wt_chosen_est_bits;
for (uint32_t i = 0; i <= 32; i++)
{
m_wt_block_acs_hist_dct[i] += o.m_wt_block_acs_hist_dct[i];
m_wt_block_acs_hist_dpcm[i] += o.m_wt_block_acs_hist_dpcm[i];
}
for (uint32_t cls = 0; cls < 3; cls++)
{
m_wt_resid_count[cls] += o.m_wt_resid_count[cls];
m_wt_resid_zero[cls] += o.m_wt_resid_zero[cls];
m_wt_resid_sum_abs[cls] += o.m_wt_resid_sum_abs[cls];
for (uint32_t m = 0; m < 9; m++)
m_wt_resid_mag_hist[cls][m] += o.m_wt_resid_mag_hist[cls][m];
}
m_dct_stats.merge(o.m_dct_stats);
}
// fmt_variants rejects format specs on strings, so pad manually
static std::string pad(const char* pStr, size_t n)
{
std::string s(pStr);
if (s.size() < n)
s.resize(n, ' ');
return s;
}
void print() const
{
static const char* s_blob_names[cBlobFirstUnused] =
{
"header", "commands", "cfg: block_config", "cfg: partition2", "cfg: partition3",
"wt: predictors", "wt-dct: dc_small", "wt-dct: dc_large", "wt-dct: ac_coeffs",
"wt-dct: signs", "ep: pbits",
"ep: fine_r", "ep: fine_g", "ep: fine_b", "ep: fine_a",
"ep: coarse_r", "ep: coarse_g", "ep: coarse_b", "ep: coarse_a",
"ep: raw", "ep: blk_index", "wt-dpcm: absolute", "solid: rgba_deltas",
"wt-dpcm: resid_2", "wt-dpcm: resid_3", "wt-dpcm: resid_4", "seek_table"
};
static const char* s_cmd_names[8] =
{
"repeat_last", "repeat_upper", "solid_dpcm", "new_config",
"reuse_left", "reuse_upper", "reuse_ldiag", "reuse_rdiag"
};
const float inv_blocks = m_total_blocks ? (100.0f / (float)m_total_blocks) : 0.0f;
fmt_debug_printf("\n========== XBC7 pack stats ==========\n");
fmt_debug_printf("{}x{}, {} blocks, Q={}, has_alpha={}\n",
m_width, m_height, m_total_blocks, m_dct_q, m_has_alpha);
{
std::string s(string_format("encoder stripes: %u", m_stripes.size_u32()));
for (uint32_t i = 0; i < m_stripes.size_u32(); i++)
s += string_format("%s block rows %u-%u", i ? "," : " --", m_stripes[i].m_first_block_row, m_stripes[i].m_first_block_row + m_stripes[i].m_num_block_rows - 1);
fmt_debug_printf("{}\n", s);
}
// ---- per-blob byte accounting ----
fmt_debug_printf("\n---- blob accounting (raw -> stored after Zstd) ----\n");
fmt_debug_printf("{}{}{}{}{}{}\n",
pad("blob", 20), pad("raw", 10), pad("stored", 10), pad("ratio", 8), pad("%file", 8), "bits/blk");
uint64_t total_raw = 0, total_stored = 0;
for (uint32_t id = 0; id < (uint32_t)cBlobFirstUnused; id++)
{
if (!m_blob_raw_size[id])
continue;
total_raw += m_blob_raw_size[id];
total_stored += m_blob_stored_size[id];
fmt_debug_printf("{}{}{}{}{}{.3}\n",
pad(s_blob_names[id], 20),
pad(string_format("%u", m_blob_raw_size[id]).c_str(), 10),
pad(string_format("%u", m_blob_stored_size[id]).c_str(), 10),
pad(string_format("%.3f", m_blob_stored_size[id] ? ((float)m_blob_raw_size[id] / (float)m_blob_stored_size[id]) : 0.0f).c_str(), 8),
pad(string_format("%.2f", m_total_file_size ? ((float)m_blob_stored_size[id] * 100.0f / (float)m_total_file_size) : 0.0f).c_str(), 8),
m_total_blocks ? ((float)m_blob_stored_size[id] * 8.0f / (float)m_total_blocks) : 0.0f);
}
const uint64_t overhead = (uint64_t)m_total_file_size - total_stored;
fmt_debug_printf("{}{}{}\n", pad("TOTAL", 20),
pad(string_format("%llu", (unsigned long long)total_raw).c_str(), 10),
pad(string_format("%llu", (unsigned long long)total_stored).c_str(), 10));
fmt_debug_printf("container+dir overhead: {} bytes\n", overhead);
fmt_debug_printf("file: {} bytes, {.3} bits/block, {.4} bpp\n",
m_total_file_size,
m_total_blocks ? ((float)m_total_file_size * 8.0f / (float)m_total_blocks) : 0.0f,
(m_width && m_height) ? ((float)m_total_file_size * 8.0f / (float)(m_width * m_height)) : 0.0f);
// ---- group rollup: where the bytes go, raw vs stored ----
{
// m_super buckets the fine groups into the coarse summary:
// 0 = commands+config, 1 = endpoints/pbits, 2 = weights, 3 = other
struct group_def { const char* m_pName; uint8_t m_super; uint8_t m_ids[12]; uint32_t m_num_ids; };
static const group_def s_groups[] =
{
{ "commands", 0, { cBlobCommands }, 1 },
{ "config/partition", 0, { cBlobBC7BlockConfig, cBlobPartition2, cBlobPartition3 }, 3 },
{ "endpoints/pbits", 1, { cBlobEPDeltaFineR, cBlobEPDeltaFineG, cBlobEPDeltaFineB, cBlobEPDeltaFineA,
cBlobEPDeltaCoarseR, cBlobEPDeltaCoarseG, cBlobEPDeltaCoarseB, cBlobEPDeltaCoarseA,
cBlobEPRaw, cBlobEPBlockIndex, cBlobPBits }, 11 },
{ "wt predictors", 2, { cBlobWeightPredictors }, 1 },
{ "wt dct", 2, { cBlobDCCoeffsSmall, cBlobDCCoeffsLarge, cBlobACCoeffs, cBlobCoeffSigns }, 4 },
{ "wt dpcm", 2, { cBlobRawWeightBits, cBlobDPCMWeightResid2, cBlobDPCMWeightResid3, cBlobDPCMWeightResid4 }, 4 },
{ "solid", 3, { cBlobSolidRGBADeltas }, 1 },
{ "header", 3, { cBlobHeader }, 1 },
{ "seek_table", 3, { cBlobStripeSeekTable }, 1 },
};
const uint32_t num_groups = (uint32_t)(sizeof(s_groups) / sizeof(s_groups[0]));
const float inv_file = m_total_file_size ? (100.0f / (float)m_total_file_size) : 0.0f;
fmt_debug_printf("\n---- group rollup ----\n");
fmt_debug_printf("{}{}{}{}\n", pad("group", 19), pad("raw", 10), pad("stored", 10), "%file");
uint64_t group_stored_total = 0;
uint64_t super_raw[4] = {}, super_stored[4] = {};
for (uint32_t g = 0; g < num_groups; g++)
{
uint64_t raw = 0, stored = 0;
for (uint32_t i = 0; i < s_groups[g].m_num_ids; i++)
{
raw += m_blob_raw_size[s_groups[g].m_ids[i]];
stored += m_blob_stored_size[s_groups[g].m_ids[i]];
}
group_stored_total += stored;
super_raw[s_groups[g].m_super] += raw;
super_stored[s_groups[g].m_super] += stored;
if (!raw)
continue;
fmt_debug_printf("{}{}{}{.2}\n",
pad(s_groups[g].m_pName, 19),
pad(string_format("%llu", (unsigned long long)raw).c_str(), 10),
pad(string_format("%llu", (unsigned long long)stored).c_str(), 10),
(float)stored * inv_file);
}
const uint64_t container_ovh = (uint64_t)m_total_file_size - group_stored_total;
fmt_debug_printf("{}{}{}{.2}\n", pad("container", 19), pad("", 10),
pad(string_format("%llu", (unsigned long long)container_ovh).c_str(), 10), (float)container_ovh * inv_file);
fmt_debug_printf("{}{}{}{}\n", pad("TOTAL", 19), pad("", 10),
pad(string_format("%u", m_total_file_size).c_str(), 10), "100.00");
// coarse three-bucket summary
static const char* s_super_names[4] = { "= commands+config", "= endpoints/pbits", "= weights (all)", "= other" };
fmt_debug_printf("\n");
for (uint32_t s = 0; s < 4; s++)
{
if (!super_raw[s])
continue;
fmt_debug_printf("{}{}{}{.2}\n",
pad(s_super_names[s], 19),
pad(string_format("%llu", (unsigned long long)super_raw[s]).c_str(), 10),
pad(string_format("%llu", (unsigned long long)super_stored[s]).c_str(), 10),
(float)super_stored[s] * inv_file);
}
}
// ---- per-blob order-0 symbol stats ----
// H = Shannon entropy of the raw byte stream (bits/byte); ideal = the
// order-0 entropy-coded size. stored/ideal < 1 means Zstd's matches +
// higher-order context beat a memoryless coder; > 1 means an entropy
// coder (FSE/rANS over this alphabet) would beat what Zstd achieves.
fmt_debug_printf("\n---- blob symbol stats (order-0, pre-Zstd) ----\n");
fmt_debug_printf("{}{}{}{}{}{}{}\n",
pad("blob", 20), pad("bytes", 10), pad("syms", 6), pad("H b/byte", 10), pad("ideal", 10), pad("stored", 10), "st/id");
for (uint32_t id = 0; id < (uint32_t)cBlobFirstUnused; id++)
{
uint64_t n = 0;
uint32_t distinct = 0;
for (uint32_t s = 0; s < 256; s++)
{
n += m_blob_hist[id][s];
if (m_blob_hist[id][s])
distinct++;
}
if (!n)
continue;
double entropy = 0.0;
for (uint32_t s = 0; s < 256; s++)
{
if (!m_blob_hist[id][s])
continue;
const double p = (double)m_blob_hist[id][s] / (double)n;
entropy -= p * std::log2(p);
}
const uint64_t ideal_bytes = (uint64_t)std::ceil(entropy * (double)n / 8.0);
fmt_debug_printf("{}{}{}{}{}{}{.3}\n",
pad(s_blob_names[id], 20),
pad(string_format("%llu", (unsigned long long)n).c_str(), 10),
pad(string_format("%u", distinct).c_str(), 6),
pad(string_format("%.3f", entropy).c_str(), 10),
pad(string_format("%llu", (unsigned long long)ideal_bytes).c_str(), 10),
pad(string_format("%u", m_blob_stored_size[id]).c_str(), 10),
ideal_bytes ? ((float)m_blob_stored_size[id] / (float)ideal_bytes) : 0.0f);
// condensed top symbols: up to 6, plus a count of the rest
uint64_t hist[256];
memcpy(hist, m_blob_hist[id], sizeof(hist));
std::string tops(" top:");
uint32_t shown = 0;
uint64_t shown_count = 0;
for (; shown < 6; shown++)
{
uint32_t best_s = 0;
uint64_t best_c = 0;
for (uint32_t s = 0; s < 256; s++)
{
if (hist[s] > best_c)
{
best_c = hist[s];
best_s = s;
}
}
if (!best_c)
break;
hist[best_s] = 0;
shown_count += best_c;
tops += string_format(" %u:%llu(%.1f%%)", best_s, (unsigned long long)best_c, (double)best_c * 100.0 / (double)n);
}
if (distinct > shown)
tops += string_format(" +%u more (%.1f%%)", distinct - shown, (double)(n - shown_count) * 100.0 / (double)n);
fmt_debug_printf("{}\n", tops);
}
// ---- commands / modes ----
fmt_debug_printf("\n---- COMMANDS: per-block command histogram ----\n");
for (uint32_t i = 0; i < 8; i++)
if (m_cmd_hist[i])
fmt_debug_printf("{}: {} ({.2}%)\n", pad(s_cmd_names[i], 13), m_cmd_hist[i], (float)m_cmd_hist[i] * inv_blocks);
fmt_debug_printf("\n---- CONFIG: BC7 modes of coded blocks ----\n");
for (uint32_t i = 0; i < 8; i++)
if (m_mode_hist[i])
fmt_debug_printf("mode {}: {} ({.2}%)\n", i, m_mode_hist[i], (float)m_mode_hist[i] * inv_blocks);
// ---- endpoints ----
fmt_debug_printf("\n---- ENDPOINTS: predictor modes + residuals ----\n");
fmt_debug_printf("raw blocks: {}, dpcm blocks: {} ({} subsets)\n", m_ep_raw_blocks, m_ep_dpcm_blocks, m_ep_dpcm_subsets);
fmt_debug_printf("ep modes: raw {}, left {}, up {}, ldiag {}, rdiag {}, index {}, left_s1 {}, up_s1 {}\n",
m_ep_mode_hist[0], m_ep_mode_hist[1], m_ep_mode_hist[2], m_ep_mode_hist[3], m_ep_mode_hist[4], m_ep_mode_hist[5],
m_ep_mode_hist[6], m_ep_mode_hist[7]);
if (m_ep_mode_hist[(uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMBlockIndex])
{
std::string idx_line("ep index deltas:");
for (uint32_t i = 0; i < NUM_XY_DELTAS; i++)
if (m_ep_index_hist[i])
idx_line += string_format(" (%i,%i):%llu", (int)g_xbc7_xy_deltas[i].m_dx, (int)g_xbc7_xy_deltas[i].m_dy, (unsigned long long)m_ep_index_hist[i]);
fmt_debug_printf("{}\n", idx_line);
}
if (m_pbit_delta_bits)
fmt_debug_printf("pbit deltas: {} bits, nonzero: {} ({.2}%)\n",
m_pbit_delta_bits, m_pbit_delta_nonzero, (float)m_pbit_delta_nonzero * 100.0f / (float)m_pbit_delta_bits);
static const char* s_class_names[2] = { "fine", "coarse" };
static const char* s_chan_names[4] = { "R", "G", "B", "A" };
for (uint32_t cls = 0; cls < 2; cls++)
{
for (uint32_t c = 0; c < 4; c++)
{
if (!m_ep_resid_count[cls][c])
continue;
fmt_debug_printf("ep resid {} {}: n={}, mean|d|={.3}, zero={.2}%\n",
pad(s_class_names[cls], 6), s_chan_names[c],
m_ep_resid_count[cls][c],
(float)m_ep_resid_sum_abs[cls][c] / (float)m_ep_resid_count[cls][c],
(float)m_ep_resid_zero[cls][c] * 100.0f / (float)m_ep_resid_count[cls][c]);
}
}
// ---- weight predictors (DCT-mode blocks; DPCM-mode predictors are in the next section) ----
fmt_debug_printf("\n---- WEIGHTS: DCT-mode predictors ----\n");
{
uint64_t class_totals[3] = { 0, 0, 0 }; // absolute / synthetic / dictionary
uint64_t amp_totals[4] = { 0, 0, 0, 0 };
uint64_t coded_blocks = 0;
for (uint32_t c = 0; c < cTotalCandidates; c++)
{
for (uint32_t a = 0; a < 4; a++)
{
const uint64_t t = m_pred_hist[c + a * cTotalCandidates];
amp_totals[a] += t;
coded_blocks += t;
if (c == cCandAbsolute)
class_totals[0] += t;
else if (c >= cCandFirstXYDelta)
class_totals[2] += t;
else
class_totals[1] += t;
}
}
const float inv_coded = coded_blocks ? (100.0f / (float)coded_blocks) : 0.0f;
fmt_debug_printf("classes: absolute {} ({.2}%), synthetic {} ({.2}%), dictionary {} ({.2}%)\n",
class_totals[0], (float)class_totals[0] * inv_coded,
class_totals[1], (float)class_totals[1] * inv_coded,
class_totals[2], (float)class_totals[2] * inv_coded);
fmt_debug_printf("amp codes: identity {}, flip {}, half {}, half-flip {}\n",
amp_totals[0], amp_totals[1], amp_totals[2], amp_totals[3]);
// top 12 joint (cand, amp) symbols
fmt_debug_printf("top predictors:\n");
uint32_t idx[cTotalCandidates * 4];
for (uint32_t i = 0; i < cTotalCandidates * 4; i++)
idx[i] = i;
std::sort(idx, idx + cTotalCandidates * 4,
[&](uint32_t a, uint32_t b) { return m_pred_hist[a] > m_pred_hist[b]; });
for (uint32_t r = 0; r < 12; r++)
{
const uint32_t i = idx[r];
if (!m_pred_hist[i])
break;
const uint32_t cand = i % cTotalCandidates, amp = i / cTotalCandidates;
static const char* s_amp_names[4] = { "", " (flip)", " (half)", " (half-flip)" };
std::string name;
if (cand < cCandFirstXYDelta)
name = g_cand_names[cand];
else
{
const xbc7_xy_delta& dlt = g_xbc7_xy_deltas[cand - cCandFirstXYDelta];
name = string_format("copy (%i,%i)", (int)dlt.m_dx, (int)dlt.m_dy);
}
name += s_amp_names[amp];
fmt_debug_printf(" {}: {} ({.2}%)\n", pad(name.c_str(), 28), m_pred_hist[i], (float)m_pred_hist[i] * inv_coded);
}
}
// ---- weight coding mode ----
fmt_debug_printf("\n---- WEIGHTS: DCT vs lossless DPCM decision ----\n");
{
const uint64_t wt_coded = m_wt_dct_blocks + m_wt_dpcm_blocks;
const float inv_wt = wt_coded ? (100.0f / (float)wt_coded) : 0.0f;
fmt_debug_printf("dct: {} ({.2}%), dpcm: {} ({.2}%) [decision: dpcm_bits*100 <= dct_bits*{}]\n",
m_wt_dct_blocks, (float)m_wt_dct_blocks * inv_wt, m_wt_dpcm_blocks, (float)m_wt_dpcm_blocks * inv_wt, m_wt_alpha_pct);
fmt_debug_printf("est bits -- all DCT: {}, all DPCM: {}, chosen: {}\n",
m_wt_dct_est_bits_total / 8, m_wt_dpcm_est_bits_total / 8, m_wt_chosen_est_bits / 8);
std::string l1("ACs/block when DCT won: ");
std::string l2("ACs/block when DPCM won: ");
for (uint32_t i = 0; i <= 32; i++)
{
if (m_wt_block_acs_hist_dct[i])
l1 += string_format("%u:%llu ", i, (unsigned long long)m_wt_block_acs_hist_dct[i]);
if (m_wt_block_acs_hist_dpcm[i])
l2 += string_format("%u:%llu ", i, (unsigned long long)m_wt_block_acs_hist_dpcm[i]);
}
fmt_debug_printf("{}\n", l1);
if (m_wt_dpcm_blocks)
fmt_debug_printf("{}\n", l2);
for (uint32_t cls = 0; cls < 3; cls++)
{
if (!m_wt_resid_count[cls])
continue;
fmt_debug_printf("dpcm resid {}b: n={}, mean|d|={.3}, zero={.2}%\n",
cls + 2, m_wt_resid_count[cls],
(float)m_wt_resid_sum_abs[cls] / (float)m_wt_resid_count[cls],
(float)m_wt_resid_zero[cls] * 100.0f / (float)m_wt_resid_count[cls]);
std::string mh(string_format("dpcm resid %ub |mag| hist:", cls + 2));
for (uint32_t m = 0; m < 9; m++)
if (m_wt_resid_mag_hist[cls][m])
mh += string_format(" %u:%.3f%%", m, (double)m_wt_resid_mag_hist[cls][m] * 100.0 / (double)m_wt_resid_count[cls]);
fmt_debug_printf("{}\n", mh);
}
if (m_wt_dpcm_blocks)
{
uint32_t idx[cTotalCandidates * 4];
for (uint32_t i = 0; i < cTotalCandidates * 4; i++)
idx[i] = i;
std::sort(idx, idx + cTotalCandidates * 4,
[&](uint32_t a, uint32_t b) { return m_wt_dpcm_pred_hist[a] > m_wt_dpcm_pred_hist[b]; });
std::string tops("top dpcm predictors:");
for (uint32_t r = 0; r < 8; r++)
{
const uint32_t i = idx[r];
if (!m_wt_dpcm_pred_hist[i])
break;
const uint32_t cand = i % cTotalCandidates, amp = i / cTotalCandidates;
static const char* s_amp_suffix[4] = { "", "/flip", "/half", "/half-flip" };
std::string name;
if (cand < cCandFirstXYDelta)
name = g_cand_names[cand];
else
{
const xbc7_xy_delta& dlt = g_xbc7_xy_deltas[cand - cCandFirstXYDelta];
name = string_format("copy(%i,%i)", (int)dlt.m_dx, (int)dlt.m_dy);
}
tops += string_format(" %s%s:%llu", name.c_str(), s_amp_suffix[amp], (unsigned long long)m_wt_dpcm_pred_hist[i]);
}
fmt_debug_printf("{}\n", tops);
}
}
// ---- solid ----
if (m_cmd_hist[(uint32_t)xbc7_command_id::cCmdSolidDPCM])
{
fmt_debug_printf("\n---- SOLID: color deltas vs neighbor edge prediction ----\n");
for (uint32_t c = 0; c < 4; c++)
{
if (!m_solid_delta_count[c])
continue;
fmt_debug_printf("{}: n={}, mean|d|={.3}, zero={.2}%\n",
s_chan_names[c], m_solid_delta_count[c],
(float)m_solid_delta_sum_abs[c] / (float)m_solid_delta_count[c],
(float)m_solid_delta_zero[c] * 100.0f / (float)m_solid_delta_count[c]);
}
}
// ---- DCT coefficient stats ----
fmt_debug_printf("\n");
m_dct_stats.print();
fmt_debug_printf("=====================================\n\n");
}
};
// NOTE: prev-emission coherence biasing of the predictor/mode sweeps was
// tried here (prefer the previously-emitted symbol within a cost margin,
// to cluster the predictor/command/index streams into Zstd-friendly runs)
// and MEASURED WORSE at every margin including pure tie-breaking: the
// existing earliest-candidate tie-break already concentrates ties onto a
// few globally-frequent symbols, and that global skew compresses better
// than local runs. Don't re-try without a new mechanism.
// The mechanism that DOES work, generalized: a later sweep candidate must
// beat the incumbent by more than this margin to displace it, so ties and
// near-ties collapse onto the lowest-index candidates GLOBALLY (global
// symbol skew is what Zstd prices). For the endpoint sweep the low-index
// candidates are also the dedicated neighbor modes, which don't spend an
// index byte. The weight-DCT sweep has its own long-standing equivalent
// (ERR_SWITCH_MARGIN_PERMILLE).
const uint32_t XBC7_SWEEP_SWITCH_MARGIN_PERMILLE = 30;
// ---- effort-driven weight-predictor pruning ----------------------------
// The per-block weight-grid sweeps (pack_weights / pack_weights_dpcm) try
// every (cand_index, amp_code) predictor; the DCT sweep re-runs a forward+
// inverse DCT per candidate, so it dominates encode time at Q < 100. The
// effort knob prunes WHICH candidates are tried (not the iteration ORDER --
// the sweeps still walk cand_index 0..cTotalCandidates and merely SKIP the
// disabled ones, so the earliest-candidate tie-break is preserved and effort
// 10 reproduces the pre-knob output exactly).
//
// g_xbc7_pred_priority lists candidates most-valuable first, derived from
// winning-predictor histograms across many images at Q=1/10/80 (opaque +
// alpha). The dictionary "copy(dx,dy)" predictors collectively win ~2/3 of
// blocks, so the high-value core deliberately mixes the strongest synthetic
// predictors (left/upper edge, diag avg) with the nearest causal copies.
// cCandAbsolute is first -- it's the no-prediction fallback and must always
// be available. Any candidate not listed here is appended in natural order
// by xbc7_build_pred_mask (so the table need only spell out the head).
static const uint8_t g_xbc7_pred_priority[] =
{
cCandAbsolute, cCandLeftEdge, cCandUpperEdge,
cCandFirstXYDelta + 0, cCandFirstXYDelta + 1, cCandDiagAvg, // <-- core 6 (effort 0)
cCandFirstXYDelta + 6, cCandFirstXYDelta + 2, cCandFirstXYDelta + 7,
cCandFirstXYDelta + 8, cCandReflectLeft, cCandFirstXYDelta + 4,
cCandFirstXYDelta + 5, cCandReflectUpper, cCandPlaneFit,
cCandFirstXYDelta + 3, cCandLUBlendStrong, cCandDDR, cCandDDL,
cCandGradient, cCandGradientDamped, cCandLUBlend, cCandLUAvg,
cCandUpperDiagEdgeBlend, cCandDiagEdgeBlend, cCandMED, cCandGAB,
};
// Build the enabled-candidate bitmask for an effort level [0,10]. effort 0
// enables the core 6; the count ramps linearly to the full set at effort 10
// (where the mask is all-ones -> the sweeps are byte-for-byte unchanged).
// cTotalCandidates < 64, so a single uint64_t holds the whole set.
static uint64_t xbc7_build_pred_mask(uint32_t effort)
{
static_assert(cTotalCandidates <= 64, "predictor mask must fit in uint64_t");
effort = basisu::minimum<uint32_t>(effort, 10);
const uint32_t cCoreCands = 6;
uint32_t count = cCoreCands + ((cTotalCandidates - cCoreCands) * effort + 5) / 10;
count = basisu::minimum<uint32_t>(count, cTotalCandidates);
// priority head, then any remaining candidate in natural order -> a valid
// permutation of [0, cTotalCandidates) regardless of what the head omits
uint8_t order[cTotalCandidates];
bool used[cTotalCandidates] = { false };
uint32_t n = 0;
for (uint32_t i = 0; i < sizeof(g_xbc7_pred_priority); i++)
{
const uint8_t c = g_xbc7_pred_priority[i];
assert((c < cTotalCandidates) && !used[c]); // head must be unique & in-range
used[c] = true;
order[n++] = c;
}
for (uint32_t c = 0; c < cTotalCandidates; c++)
if (!used[c])
order[n++] = (uint8_t)c;
assert(n == cTotalCandidates);
uint64_t mask = 0;
for (uint32_t i = 0; i < count; i++)
mask |= (1ull << order[i]);
assert(mask & (1ull << cCandAbsolute)); // fallback always present
return mask;
}
// Amp codes the per-block sweeps try, by effort [0,10]. The amp loop runs in
// descending win-share order (0=identity, 1=flip, 2=half-contrast, 3=half-
// flip -- confirmed by histograms), so trying the first N keeps the most
// valuable. effort 10 -> 4 (the full set -> output unchanged vs pre-knob).
static uint32_t xbc7_amp_codes_for_effort(uint32_t effort)
{
static const uint8_t tbl[11] = { 1, 1, 1, 1, 2, 2, 3, 3, 4, 4, 4 };
return tbl[basisu::minimum<uint32_t>(effort, 10)];
}
bool pack_weights(
uint32_t bx, uint32_t by, uint32_t num_blocks_x,
const tile_bounds& tile,
const color_rgba orig_block[16],
const vector2D<basist::bc7u::log_bc7_block> &log_blks,
dct_syms best_syms[2], basist::bc7u::log_bc7_block &best_cand_log_blk, uint32_t& best_predictor_index,
xbc7_weight_grid_dct_fixed &weight_grid_dct_fixed, fxvec &dct_work_fixed, const pack_options& opts,
uint64_t enabled_pred_mask, uint32_t num_amp_codes)
{
best_predictor_index = 0;
const uint32_t global_q = opts.m_dct_q;
const uint64_t ERR_SWITCH_MARGIN_PERMILLE = 20;
const uint32_t TOTAL_AMP_CODES = num_amp_codes; // 0=identity, 1=flip, 2=half contrast, 3=half of flip (effort-pruned)
const basist::bc7u::log_bc7_block& log_blk = log_blks(bx, by);
best_syms[0].clear();
best_syms[1].clear();
best_cand_log_blk = log_blk;
uint64_t best_err = UINT64_MAX;
uint32_t best_num_ac_syms = UINT32_MAX;
for (uint32_t amp_code = 0; amp_code < TOTAL_AMP_CODES; amp_code++)
{
for (uint32_t cand_index = 0; cand_index < cTotalCandidates; cand_index++)
{
if ((amp_code) && (cand_index == cCandAbsolute))
continue;
// effort pruning: skip predictors not in this effort's enabled set
// (mask is all-ones at effort 10, so this never fires there)
if (!((enabled_pred_mask >> cand_index) & 1u))
continue;
basist::bc7u::log_bc7_block cand_log_blk(log_blk);
uint32_t cand_total_ac_syms = 0;
dct_syms cand_syms[2];
cand_syms[0].clear();
cand_syms[1].clear();
for (uint32_t p = 0; p < cand_log_blk.m_num_planes; p++)
{
int weight_preds[16];
int* pWeight_predictions = nullptr;
if (cand_index != cCandAbsolute)
{
bool eval_status = eval_weight_predictor(
cand_index, amp_code,
bx, by, num_blocks_x,
tile,
log_blks,
p, weight_preds);
if (!eval_status)
goto skip_cand;
pWeight_predictions = weight_preds;
}
dct_syms syms;
weight_grid_dct_fixed.forward(basist::fixed16_16::from_int(global_q), p, pWeight_predictions, cand_log_blk, syms, dct_work_fixed);
memset(cand_log_blk.m_weights[p], 0, 16);
bool status = weight_grid_dct_fixed.inverse(basist::fixed16_16::from_int(global_q), p, pWeight_predictions, syms, cand_log_blk, dct_work_fixed);
if (!status)
{
assert(0);
return false;
}
uint32_t total_acs = syms.m_ac_vals.size_u32();
if (total_acs && (syms.m_ac_vals[total_acs - 1].m_coeff == INT16_MAX))
total_acs--;
cand_total_ac_syms += total_acs;
cand_syms[p] = syms;
} // p
// scoped so 'goto skip_cand' leaps over (not into) these inits -- required under /permissive-
{
color_rgba cand_block_pixels[16];
if (!basist::bc7u::unpack_bc7(cand_log_blk, (basist::color_rgba*)cand_block_pixels))
{
assert(0);
return false;
}
uint64_t cand_err = 0;
for (uint32_t i = 0; i < 16; i++)
cand_err += cand_block_pixels[i].get_weighted_dist2(orig_block[i], opts.m_weights);
if ((cand_total_ac_syms < best_num_ac_syms) ||
((cand_total_ac_syms == best_num_ac_syms) && ((cand_err * 1000) < (best_err * (1000 - ERR_SWITCH_MARGIN_PERMILLE)))))
{
best_cand_log_blk = cand_log_blk;
best_predictor_index = cand_index + amp_code * cTotalCandidates;
best_num_ac_syms = cand_total_ac_syms;
best_err = cand_err;
best_syms[0] = cand_syms[0];
best_syms[1] = cand_syms[1];
}
} // end candidate-eval scope
skip_cand:
;
} // cand_index
} // amp_code
assert(best_syms[0].m_ac_vals.size());
return true;
}
// Estimated per-symbol coding costs in 1/8-bit units ("octobits"), measured
// on the kodim corpus via the stats dashboard.
//
// DPCM weight residual cost, [weight_bits - 2][min(|centered resid|, 8)]:
// -log2 of each symbol's probability (the magnitude's mass split across
// +/-), measured at Q=100 where EVERY block codes DPCM, so the
// distributions carry no mode-decision selection bias. Order-0 model;
// Zstd lands within ~13% of it on these streams.
static const uint32_t g_dpcm_resid_cost_obits[3][9] =
{
{ 8, 17, 47, 47, 47, 47, 47, 47, 47 }, // 2-bit (centered range [-2,1])
{ 12, 19, 27, 38, 63, 63, 63, 63, 63 }, // 3-bit (centered range [-4,3])
{ 12, 25, 29, 33, 38, 44, 52, 61, 81 }, // 4-bit (centered range [-8,7])
};
// DCT stream bytes priced at their measured post-Zstd cost (Q 60..95):
// DC bytes ~4.7 bits with the 6-bit DC quantization below (was ~6.4 at
// 8-bit DC), AC run/magnitude stream bytes 3.1..3.8 bits (3.5 used).
// Sign bits are incompressible noise: exactly 1 bit each.
const uint32_t DCT_DC_BYTE_COST_OBITS = 38;
const uint32_t DCT_AC_BYTE_COST_OBITS = 28;
// Lossless residual DPCM weight coding: predict the dequantized [0,64] grid
// with the shared predictor bank, quantize the prediction to the plane's bit
// depth (quant_weight), then wrap-difference the quantized indices mod 2^n.
// Reconstruction is exact, so the predictor choice affects ONLY compressed
// size: pick the candidate minimizing the estimated emitted cost (octobit
// table above) -- a content-adaptive estimate, since zero-heavy residual
// grids are far cheaper than the stream average. cand 0 (absolute,
// predictor index 0) is always available, emits the raw indices to a
// separate blob, and is priced at its raw stored size.
struct dpcm_weights
{
uint32_t m_pred_index = 0; // joint (cand + amp * cTotalCandidates) byte
uint8_t m_syms[2][16] = {}; // wrapped n-bit symbols (raw indices if absolute), [plane][texel]
uint64_t m_est_cost_obits = 0; // estimated emitted cost of the winning candidate, 1/8-bit units
};
static void pack_weights_dpcm(
uint32_t bx, uint32_t by, uint32_t num_blocks_x,
const tile_bounds& tile,
const vector2D<basist::bc7u::log_bc7_block>& log_blks,
dpcm_weights& result,
uint64_t enabled_pred_mask, uint32_t num_amp_codes)
{
const uint32_t TOTAL_AMP_CODES = num_amp_codes;
const basist::bc7u::log_bc7_block& log_blk = log_blks(bx, by);
uint64_t best_cost = UINT64_MAX;
for (uint32_t amp_code = 0; amp_code < TOTAL_AMP_CODES; amp_code++)
{
for (uint32_t cand_index = 0; cand_index < cTotalCandidates; cand_index++)
{
if ((amp_code) && (cand_index == cCandAbsolute))
continue;
// effort pruning (see pack_weights): all-ones at effort 10
if (!((enabled_pred_mask >> cand_index) & 1u))
continue;
uint64_t cost = 0;
uint8_t syms[2][16] = {}; // zeroed so single-plane blocks never copy indeterminate plane-1 bytes
bool valid = true;
for (uint32_t p = 0; p < log_blk.m_num_planes; p++)
{
const uint32_t num_bits = log_blk.m_weight_bits[p];
const uint32_t mask = (1u << num_bits) - 1;
const int half = 1 << (num_bits - 1);
int weight_preds[16];
int* pWeight_predictions = nullptr;
if (cand_index != cCandAbsolute)
{
if (!eval_weight_predictor(cand_index, amp_code, bx, by, num_blocks_x, tile, log_blks, p, weight_preds))
{
valid = false;
break;
}
pWeight_predictions = weight_preds;
}
for (uint32_t i = 0; i < 16; i++)
{
const uint32_t pred_index = pWeight_predictions ? basist::bc7u::quant_weight(pWeight_predictions[i], num_bits) : 0;
const uint32_t sym = (log_blk.m_weights[p][i] - pred_index) & mask;
syms[p][i] = (uint8_t)sym;
if (pWeight_predictions)
{
const int v = (sym >= (uint32_t)half) ? ((int)sym - (int)(mask + 1)) : (int)sym;
cost += g_dpcm_resid_cost_obits[num_bits - 2][basisu::minimum<int>(basisu::iabs(v), 8)];
}
else
{
// absolute: raw indices at their stored size (2 bits,
// or 4 for the nibble-expanded 3-bit class, or 4)
cost += 8u * ((num_bits == 2) ? 2u : 4u);
}
}
} // p
if (!valid)
continue;
// later candidates must beat the incumbent by the switch margin
// (UINT64_MAX guard: the multiply would wrap before any winner)
if ((best_cost == UINT64_MAX) || ((cost * 1000) < (best_cost * (1000 - (uint64_t)XBC7_SWEEP_SWITCH_MARGIN_PERMILLE))))
{
best_cost = cost;
result.m_pred_index = cand_index + amp_code * cTotalCandidates;
memcpy(result.m_syms, syms, sizeof(syms));
}
} // cand_index
} // amp_code
result.m_est_cost_obits = best_cost;
}
// per-stripe (per-job) output state; merged in stripe order after the jobs join
struct stripe_output
{
blob_stream_writer m_blob_writer;
basisu::bitwise_coder m_coeff_signs;
basisu::bitwise_coder m_pbits;
basisu::bitwise_coder m_raw_endpoint_bits;
xbc7_pack_stats m_stats;
};
// Optional block-reuse RDO pre-pass: runs after the BC7 base pack, BEFORE the
// endpoint RDO (once a whole block is reused there's no point trying cheaper
// endpoints). In raster order per stripe (honoring boundaries), for each
// non-solid block it tries the cheapest whole-block representations and adopts
// the best acceptable one: a REPEAT (exact copy of the left/upper causal
// neighbor -> 1-byte command; preferred) or SOLID (the block's mean color ->
// cheap SolidDPCM). "Acceptable" = weighted RGBA PSNR >= the shared floor AND
// within the per-mode tolerated drop vs the block's current PSNR. Modifies
// log_blks in place; serial (causal). Returns false on a decode failure.
static bool block_reuse_rdo_pass(
const image& orig_img,
basisu::vector2D<basist::bc7u::log_bc7_block>& log_blks,
uint32_t num_blocks_x,
const basisu::vector<stripe_range>& stripes,
const pack_options& opts)
{
const uint32_t* comp_weights = opts.m_weights;
const float min_block_psnr = opts.m_rdo_min_block_psnr;
const bool has_alpha = orig_img.has_alpha();
uint32_t changed_repeat = 0, changed_solid = 0;
for (uint32_t st = 0; st < stripes.size(); st++)
{
const uint32_t first_row = stripes[st].m_first_block_row;
const uint32_t end_row = first_row + stripes[st].m_num_block_rows;
for (uint32_t by = first_row; by < end_row; by++)
{
for (uint32_t bx = 0; bx < num_blocks_x; bx++)
{
basist::bc7u::log_bc7_block& log_blk = log_blks(bx, by);
// NOTE: solid blocks are NOT skipped -- a RepeatLast/RepeatUpper
// command (1 byte) is cheaper than SolidDPCM, and pack_stripe checks
// Repeat before Solid, so we aggressively reuse a neighbor even for a
// solid block when it passes the PSNR test (VQ-style).
color_rgba src_pixels[16];
orig_img.extract_block_clamped(src_pixels, bx * 4, by * 4, 4, 4);
color_rgba dec[16];
if (!basist::bc7u::unpack_bc7(log_blk, (basist::color_rgba*)dec))
{
assert(0);
return false;
}
const float orig_psnr = xbc7_block_wsse_psnr(src_pixels, dec, comp_weights);
// ---- Repeat: copy a causal neighbor wholesale (cheapest command) ----
if (opts.m_repeat_rdo_enabled)
{
const basist::bc7u::log_bc7_block* preds[2] = { nullptr, nullptr };
if (bx >= 1) preds[0] = &log_blks(bx - 1, by); // left -> RepeatLast
if (by > first_row) preds[1] = &log_blks(bx, by - 1); // upper -> RepeatUpper
const basist::bc7u::log_bc7_block* best = nullptr;
float best_psnr = 0.0f;
for (uint32_t i = 0; i < 2; i++)
{
if (!preds[i])
continue;
if (!basist::bc7u::unpack_bc7(*preds[i], (basist::color_rgba*)dec))
{
assert(0);
return false;
}
const float p = xbc7_block_wsse_psnr(src_pixels, dec, comp_weights);
if ((p >= min_block_psnr) && (p >= orig_psnr - opts.m_repeat_rdo_max_psnr_drop) && ((!best) || (p > best_psnr)))
{
best = preds[i];
best_psnr = p;
}
}
if (best)
{
log_blk = *best; // bit-identical -> pack_stripe emits Repeat
changed_repeat++;
continue; // Repeat is the cheapest -- done with this block
}
}
// ---- Solid: replace with the block's mean color (next cheapest) ----
// (skip if already solid -- it already codes cheaply as SolidDPCM)
if (opts.m_solid_rdo_enabled && !basist::bc7u::is_solid_blk(log_blk))
{
uint32_t sum[4] = { 0, 0, 0, 0 };
for (uint32_t i = 0; i < 16; i++)
for (uint32_t c = 0; c < 4; c++)
sum[c] += src_pixels[i][c];
color_rgba mean((sum[0] + 8) >> 4, (sum[1] + 8) >> 4, (sum[2] + 8) >> 4, (sum[3] + 8) >> 4);
if (!has_alpha)
mean.a = 255;
basist::bc7u::log_bc7_block cand;
cand.clear();
basist::bc7u::create_solid_blk(cand, (const basist::color_rgba&)mean);
if (!basist::bc7u::unpack_bc7(cand, (basist::color_rgba*)dec))
{
assert(0);
return false;
}
const float p = xbc7_block_wsse_psnr(src_pixels, dec, comp_weights);
if ((p >= min_block_psnr) && (p >= orig_psnr - opts.m_solid_rdo_max_psnr_drop))
{
log_blk = cand;
changed_solid++;
}
}
}
}
}
if (opts.m_debug_output)
{
uint32_t total_blocks = 0;
for (uint32_t st = 0; st < stripes.size(); st++)
total_blocks += num_blocks_x * stripes[st].m_num_block_rows;
if (opts.m_repeat_rdo_enabled)
fmt_debug_printf("repeat RDO: {} blocks changed ({.2}%)\n", changed_repeat, total_blocks ? (changed_repeat * 100.0f / (float)total_blocks) : 0.0f);
if (opts.m_solid_rdo_enabled)
fmt_debug_printf("solid RDO: {} blocks changed ({.2}%)\n", changed_solid, total_blocks ? (changed_solid * 100.0f / (float)total_blocks) : 0.0f);
}
return true;
}
// Optional endpoint-prediction RDO pre-pass: runs after the BC7 base pack but
// BEFORE stripe coding. In raster order (per stripe, honoring its boundaries)
// it tries forcing each block's endpoints to a causal neighbor's prediction
// (left/upper/left-diag/right-diag) via a zero-residual endpoint DPCM, and
// re-optimizes that candidate's weights for the new endpoints, and adopts the
// best candidate when its weighted RGBA PSNR drops by no more than
// max_psnr_drop dB. The matching zero residuals then cost almost nothing in
// the coding pass (often collapsing to a Repeat). Solid blocks are skipped --
// they have their own cheaper SolidDPCM path. Modifies log_blks in place;
// serial, since each block predicts from already-finalized causal neighbors.
// Returns false on an (unexpected) decode failure.
static bool endpoint_dpcm_rdo_pass(
const image& orig_img,
basisu::vector2D<basist::bc7u::log_bc7_block>& log_blks,
uint32_t num_blocks_x,
const basisu::vector<stripe_range>& stripes,
const pack_options& opts)
{
const uint32_t* comp_weights = opts.m_weights;
const float max_psnr_drop = opts.m_endpoint_rdo_max_psnr_drop;
const float min_block_psnr = opts.m_rdo_min_block_psnr;
uint32_t changed_blocks = 0; // blocks whose endpoints+weights were rewritten
#if defined(DEBUG) || defined(_DEBUG)
// sanity: re-optimizing a candidate's weights can never RAISE its WSSE
// (the original weights are in the swept set); count any case where it does
uint64_t dbg_weight_opt_cands = 0, dbg_weight_opt_worse = 0;
#endif
for (uint32_t st = 0; st < stripes.size(); st++)
{
const uint32_t first_row = stripes[st].m_first_block_row;
const uint32_t end_row = first_row + stripes[st].m_num_block_rows;
for (uint32_t by = first_row; by < end_row; by++)
{
for (uint32_t bx = 0; bx < num_blocks_x; bx++)
{
basist::bc7u::log_bc7_block& log_blk = log_blks(bx, by);
// solid blocks have a dedicated, cheaper command -- leave them alone
if (basist::bc7u::is_solid_blk(log_blk))
continue;
// already identical to a causal neighbor (e.g. from the block-reuse
// RDO, or naturally) -- it'll code as a cheap Repeat, so don't
// disturb its endpoints
if (((bx >= 1) && basist::bc7u::compare_block_full(log_blk, log_blks(bx - 1, by))) ||
((by > first_row) && basist::bc7u::compare_block_full(log_blk, log_blks(bx, by - 1))))
continue;
color_rgba src_pixels[16];
orig_img.extract_block_clamped(src_pixels, bx * 4, by * 4, 4, 4);
color_rgba orig_pixels[16];
if (!basist::bc7u::unpack_bc7(log_blk, (basist::color_rgba*)orig_pixels))
{
assert(0);
return false;
}
const float orig_psnr = xbc7_block_wsse_psnr(src_pixels, orig_pixels, comp_weights);
// causal neighbor predictors valid within this stripe, in order:
// left, upper, left-diag, right-diag (upper rows must stay in-stripe)
const basist::bc7u::log_bc7_block* preds[4] = { nullptr, nullptr, nullptr, nullptr };
if (bx >= 1) preds[0] = &log_blks(bx - 1, by);
if (by > first_row) preds[1] = &log_blks(bx, by - 1);
if ((bx >= 1) && (by > first_row)) preds[2] = &log_blks(bx - 1, by - 1);
if ((bx + 1 < num_blocks_x) && (by > first_row)) preds[3] = &log_blks(bx + 1, by - 1);
basist::bc7u::log_bc7_block best_cand{}; // value-init silences a C4701 false positive (only read when have_cand)
float best_cand_psnr = 0.0f;
bool have_cand = false;
for (uint32_t i = 0; i < 4; i++)
{
if (!preds[i])
continue;
// copy keeps mode/config/weights; only endpoints+pbits change
basist::bc7u::log_bc7_block cand(log_blk);
for (uint32_t s = 0; s < cand.m_num_partitions; s++)
{
uint8_t residuals[8] = { 0 }; // zero residuals -> endpoints become the prediction
uint8_t pbits[2] = { 0 };
uint32_t num_residuals = 0, num_pbits = 0;
basist::bc7u::endpoint_dpcm(true, *preds[i], 0, cand, s, residuals, num_residuals, pbits, num_pbits);
}
#if defined(DEBUG) || defined(_DEBUG)
// WSSE with the now-stale weights, before re-optimization
uint64_t dbg_wsse_before = 0;
{
color_rgba pre[16];
if (!basist::bc7u::unpack_bc7(cand, (basist::color_rgba*)pre))
{
assert(0);
return false;
}
for (uint32_t k = 0; k < 16; k++)
dbg_wsse_before += pre[k].get_weighted_dist2(src_pixels[k], comp_weights);
}
#endif
// the slammed endpoints leave the copied weights stale -- recompute
// the optimal weights for the new endpoints (can only help vs. stale)
basist::bc7u::log_bc7_block cand_opt;
if (!optimize_block_weights(cand, src_pixels, comp_weights, cand_opt))
return false; // already asserted inside
cand = cand_opt;
color_rgba cand_pixels[16];
if (!basist::bc7u::unpack_bc7(cand, (basist::color_rgba*)cand_pixels))
{
assert(0);
return false;
}
#if defined(DEBUG) || defined(_DEBUG)
{
uint64_t dbg_wsse_after = 0;
for (uint32_t k = 0; k < 16; k++)
dbg_wsse_after += cand_pixels[k].get_weighted_dist2(src_pixels[k], comp_weights);
dbg_weight_opt_cands++;
if (dbg_wsse_after > dbg_wsse_before)
dbg_weight_opt_worse++; // weight re-optimization must never make WSSE worse
}
#endif
const float cand_psnr = xbc7_block_wsse_psnr(src_pixels, cand_pixels, comp_weights);
if ((!have_cand) || (cand_psnr > best_cand_psnr))
{
have_cand = true;
best_cand_psnr = cand_psnr;
best_cand = cand;
}
}
// adopt the best candidate if quality drops by no more than allowed
// (a gain is of course also accepted)
if (have_cand && (best_cand_psnr >= min_block_psnr) && (best_cand_psnr >= orig_psnr - max_psnr_drop))
{
log_blk = best_cand;
changed_blocks++;
}
}
}
}
if (opts.m_debug_output)
{
uint32_t total_blocks = 0;
for (uint32_t st = 0; st < stripes.size(); st++)
total_blocks += num_blocks_x * stripes[st].m_num_block_rows;
fmt_debug_printf("endpoint RDO: {} blocks changed ({.2}%)\n", changed_blocks, total_blocks ? (changed_blocks * 100.0f / (float)total_blocks) : 0.0f);
}
#if defined(DEBUG) || defined(_DEBUG)
fmt_debug_printf("endpoint RDO weight re-opt: {} candidates, {} got WORSE (expected 0)\n", dbg_weight_opt_cands, dbg_weight_opt_worse);
// assert(!dbg_weight_opt_worse); // intentionally NOT asserted -- probably too strong; observe via the stat above instead
#endif
return true;
}
// Optional weight-DCT AC-truncation RDO. Run ONCE on the winning DCT symbols
// (after pack_weights, NOT inside its candidate sweep). Zeros the highest-
// frequency weight-DCT AC coefficients one at a time in reverse zigzag order,
// protecting the 2x2 low-freq corner (DC,(1,0),(0,1),(1,1) -> zigzag {0,1,2,4}),
// while the decoded weighted RGBA PSNR stays within m_ac_trunc_rdo_max_psnr_drop
// dB of the un-truncated block AND >= the shared floor. Updates best_syms
// (pruned) and best_cand_log_blk (weights rebuilt via the same inverse() the
// decoder uses, so it round-trips). Returns false on an unexpected decode failure.
static bool ac_truncate_rdo(
dct_syms best_syms[2],
basist::bc7u::log_bc7_block& best_cand_log_blk,
uint32_t best_predictor_index,
const color_rgba orig_block[16],
uint32_t bx, uint32_t by, uint32_t num_blocks_x,
const tile_bounds& tile,
const vector2D<basist::bc7u::log_bc7_block>& log_blks,
xbc7_weight_grid_dct_fixed& weight_grid_dct_fixed,
fxvec& dct_work,
const pack_options& opts,
xbc7_pack_stats& stats)
{
const uint32_t num_planes = best_cand_log_blk.m_num_planes;
// winning predictor -> per-plane predictions (pack_weights left untouched;
// eval_weight_predictor asserts non-absolute, so absolute -> null preds)
const uint32_t cand_index = best_predictor_index % cTotalCandidates;
const uint32_t amp_code = best_predictor_index / cTotalCandidates;
int preds[2][16];
const int* pPreds[2] = { nullptr, nullptr };
if (cand_index != cCandAbsolute)
{
for (uint32_t p = 0; p < num_planes; p++)
{
if (!eval_weight_predictor(cand_index, amp_code, bx, by, num_blocks_x, tile, log_blks, p, preds[p]))
{
assert(0);
return false;
}
pPreds[p] = preds[p];
}
}
// baseline PSNR of the un-truncated DCT-coded block
color_rgba dec[16];
if (!basist::bc7u::unpack_bc7(best_cand_log_blk, (basist::color_rgba*)dec))
{
assert(0);
return false;
}
const float orig_psnr = xbc7_block_wsse_psnr(orig_block, dec, opts.m_weights);
int flat[2][16];
for (uint32_t p = 0; p < num_planes; p++)
xbc7_syms_to_flat(best_syms[p], flat[p]);
const float drop = opts.m_ac_trunc_rdo_max_psnr_drop;
const float floor_psnr = opts.m_rdo_min_block_psnr;
uint64_t pruned_here = 0;
// reverse zigzag, skipping protected low-freq slots (zigzag 1,2,4; 0 = DC)
for (uint32_t zz = 15; zz >= 1; zz--)
{
if ((zz == 1) || (zz == 2) || (zz == 4))
continue;
const uint32_t nat = g_zigzag4x4_xy[zz][0] + g_zigzag4x4_xy[zz][1] * 4;
// skip if this coefficient is already zero in every plane
bool any_nonzero = false;
for (uint32_t p = 0; p < num_planes; p++)
if (flat[p][nat] != 0)
any_nonzero = true;
if (!any_nonzero)
continue;
int saved[2] = { 0, 0 };
for (uint32_t p = 0; p < num_planes; p++)
{
saved[p] = flat[p][nat];
flat[p][nat] = 0;
}
// rebuild the candidate from the tentatively-truncated grids
basist::bc7u::log_bc7_block trial_blk = best_cand_log_blk; // config + endpoints kept
dct_syms trial_syms[2];
for (uint32_t p = 0; p < num_planes; p++)
{
xbc7_flat_to_syms(flat[p], trial_syms[p]);
memset(trial_blk.m_weights[p], 0, 16);
if (!weight_grid_dct_fixed.inverse(basist::fixed16_16::from_int(opts.m_dct_q), p, pPreds[p], trial_syms[p], trial_blk, dct_work))
{
assert(0);
return false;
}
}
if (!basist::bc7u::unpack_bc7(trial_blk, (basist::color_rgba*)dec))
{
assert(0);
return false;
}
const float psnr = xbc7_block_wsse_psnr(orig_block, dec, opts.m_weights);
if ((psnr >= floor_psnr) && (psnr >= orig_psnr - drop))
{
best_cand_log_blk = trial_blk;
for (uint32_t p = 0; p < num_planes; p++)
{
best_syms[p] = trial_syms[p];
if (saved[p])
pruned_here++;
}
}
else
{
for (uint32_t p = 0; p < num_planes; p++)
flat[p][nat] = saved[p]; // revert this coefficient
break; // stop at the first unacceptable truncation
}
}
stats.m_ac_trunc_pruned += pruned_here;
if (pruned_here)
stats.m_ac_trunc_blocks++;
return true;
}
// with every causal reference clamped to the stripe (the decoder mirrors
// the one IMPLICIT cross-row prediction -- solid blocks -- via the header
// stripe count; explicit references are simply never emitted across a
// stripe boundary). All scratch state is local or lives in `out`.
static bool pack_stripe(
const image& orig_img,
const pack_options& opts,
bool has_alpha,
uint32_t num_blocks_x,
const stripe_range& stripe,
vector2D<basist::bc7u::log_bc7_block>& log_blks,
vector2D<basist::bc7u::log_bc7_block>* pCoded_log_blocks,
const vector2D<uint8_t>& base_used_lut, // per-block: 1 if the bc7e_scalar base pack used its endpoint LUTs (force DPCM)
stripe_output& out,
const xbc7_debug_image_set& dbg_imgs) // debug only; members null unless m_debug_images. Stripes write disjoint rows, so filling is thread-safe.
{
const uint32_t first_row = stripe.m_first_block_row;
const uint32_t end_row = stripe.m_first_block_row + stripe.m_num_block_rows;
// this stripe as an inclusive block AABB (full width, for now); ALL
// causal references in this pass are gated through tile.contains()
const tile_bounds tile = { 0, (int)first_row, (int)num_blocks_x - 1, (int)end_row - 1 };
blob_stream_writer& blob_writer = out.m_blob_writer;
basisu::bitwise_coder& coeff_signs = out.m_coeff_signs;
basisu::bitwise_coder& pbits = out.m_pbits;
basisu::bitwise_coder& raw_endpoint_bits = out.m_raw_endpoint_bits;
xbc7_pack_stats& stats = out.m_stats;
xbc7_weight_grid_dct_fixed weight_grid_dct_fixed;
weight_grid_dct_fixed.init();
fxvec dct_work_fixed;
// hoisted so the per-block visualization calls compile out entirely when disabled
const bool debug_images = opts.m_debug_images;
// effort -> enabled weight-predictor set + amp-code count (constant for the
// whole stripe; at effort 10 both are full so the sweeps are unchanged)
const uint64_t enabled_pred_mask = xbc7_build_pred_mask(opts.m_effort_level);
const uint32_t num_amp_codes = xbc7_amp_codes_for_effort(opts.m_effort_level);
for (uint32_t by = first_row; by < end_row; by++)
{
for (uint32_t bx = 0; bx < num_blocks_x; bx++)
{
// causal neighbors, clamped to the tile AABB: blocks outside it
// belong to another coding unit and are off limits
const basist::bc7u::log_bc7_block* pLeft_log_blk = tile.contains((int)bx - 1, (int)by) ? &log_blks(bx - 1, by) : nullptr;
const basist::bc7u::log_bc7_block* pUp_log_blk = tile.contains((int)bx, (int)by - 1) ? &log_blks(bx, by - 1) : nullptr;
const basist::bc7u::log_bc7_block* pLeft_diag_log_blk = tile.contains((int)bx - 1, (int)by - 1) ? &log_blks(bx - 1, by - 1) : nullptr;
const basist::bc7u::log_bc7_block* pRight_diag_log_blk = tile.contains((int)bx + 1, (int)by - 1) ? &log_blks(bx + 1, by - 1) : nullptr;
basist::bc7u::log_bc7_block& log_blk = log_blks(bx, by);
if (pUp_log_blk && basist::bc7u::compare_block_full(log_blk, *pUp_log_blk))
{
blob_writer.put_byte(cBlobCommands, (uint8_t)xbc7_command_id::cCmdRepeatUpper);
stats.m_cmd_hist[(uint32_t)xbc7_command_id::cCmdRepeatUpper]++;
if (debug_images)
xbc7_vis_fill_command(dbg_imgs, bx, by, (uint8_t)xbc7_command_id::cCmdRepeatUpper, false, UINT32_MAX, UINT32_MAX);
if (pCoded_log_blocks)
{
(*pCoded_log_blocks)(bx, by) = log_blk;
}
continue;
}
if (pLeft_log_blk && basist::bc7u::compare_block_full(log_blk, *pLeft_log_blk))
{
blob_writer.put_byte(cBlobCommands, (uint8_t)xbc7_command_id::cCmdRepeatLast);
stats.m_cmd_hist[(uint32_t)xbc7_command_id::cCmdRepeatLast]++;
if (debug_images)
xbc7_vis_fill_command(dbg_imgs, bx, by, (uint8_t)xbc7_command_id::cCmdRepeatLast, false, UINT32_MAX, UINT32_MAX);
if (pCoded_log_blocks)
{
(*pCoded_log_blocks)(bx, by) = log_blk;
}
continue;
}
if (basist::bc7u::is_solid_blk(log_blk))
{
int preds[4] = {};
int num_preds = 0;
if (pLeft_log_blk)
{
for (uint32_t y = 0; y < 4; y++)
{
basist::color_rgba p;
if (!basist::bc7u::unpack_bc7_texel(*pLeft_log_blk, p, 3, y))
{
assert(0);
return false;
}
preds[0] += p.r;
preds[1] += p.g;
preds[2] += p.b;
preds[3] += p.a;
}
num_preds += 4;
}
if (pUp_log_blk)
{
for (uint32_t x = 0; x < 4; x++)
{
basist::color_rgba p;
if (!basist::bc7u::unpack_bc7_texel(*pUp_log_blk, p, x, 3))
{
assert(0);
return false;
}
preds[0] += p.r;
preds[1] += p.g;
preds[2] += p.b;
preds[3] += p.a;
}
num_preds += 4;
}
if (num_preds)
{
for (uint32_t c = 0; c < 4; c++)
preds[c] = (preds[c] + (num_preds / 2)) / num_preds;
}
blob_writer.put_byte(cBlobCommands, (uint8_t)xbc7_command_id::cCmdSolidDPCM);
stats.m_cmd_hist[(uint32_t)xbc7_command_id::cCmdSolidDPCM]++;
if (debug_images)
xbc7_vis_fill_command(dbg_imgs, bx, by, (uint8_t)xbc7_command_id::cCmdSolidDPCM, false, UINT32_MAX, UINT32_MAX);
basist::color_rgba solid_color;
if (!basist::bc7u::unpack_bc7_texel(log_blk, solid_color, 0, 0))
{
assert(0);
return false;
}
if (!has_alpha)
solid_color.a = 255; // important in case a p-bit set a=254
for (uint32_t c = 0; c < (has_alpha ? 4u : 3u); c++)
{
const uint8_t delta = (uint8_t)(solid_color[c] - preds[c]);
blob_writer.put_byte(cBlobSolidRGBADeltas, delta);
stats.m_solid_delta_count[c]++;
stats.m_solid_delta_sum_abs[c] += (uint64_t)basisu::iabs((int8_t)delta);
if (!delta)
stats.m_solid_delta_zero[c]++;
}
basist::bc7u::create_solid_blk(log_blk, solid_color);
if (pCoded_log_blocks)
{
(*pCoded_log_blocks)(bx, by) = log_blk;
}
continue;
}
color_rgba orig_block[16];
orig_img.extract_block_clamped(orig_block, bx * 4, by * 4, 4, 4);
uint8_t command_byte = 0;
// Code config
if ((pLeft_log_blk) && (basist::bc7u::compare_block_configs(log_blk, *pLeft_log_blk, false)))
{
command_byte = (uint8_t)xbc7_command_id::cCmdReuseConfigLeft;
}
else if ((pUp_log_blk) && (basist::bc7u::compare_block_configs(log_blk, *pUp_log_blk, false)))
{
command_byte = (uint8_t)xbc7_command_id::cCmdReuseConfigUpper;
}
else if ((pLeft_diag_log_blk) && (basist::bc7u::compare_block_configs(log_blk, *pLeft_diag_log_blk, false)))
{
command_byte = (uint8_t)xbc7_command_id::cCmdReuseConfigLeftDiagonal;
}
else if ((pRight_diag_log_blk) && (basist::bc7u::compare_block_configs(log_blk, *pRight_diag_log_blk, false)))
{
command_byte = (uint8_t)xbc7_command_id::cCmdReuseConfigRightDiagonal;
}
else
{
command_byte = (uint8_t)xbc7_command_id::cCmdNewConfig;
uint32_t config_byte = log_blk.m_mode | (log_blk.m_dp_rotation_index << 3) | (log_blk.m_mode4_index_selector << 5);
blob_writer.put_byte(cBlobBC7BlockConfig, (uint8_t)config_byte);
}
stats.m_cmd_hist[command_byte & 7]++;
stats.m_mode_hist[log_blk.m_mode]++;
// Code partition pattern index
if (log_blk.m_num_partitions == 2)
blob_writer.put_byte(cBlobPartition2, log_blk.m_pattern_index);
else if (log_blk.m_num_partitions == 3)
blob_writer.put_byte(cBlobPartition3, log_blk.m_pattern_index);
// Endpoint coding: sweep every causal DPCM predictor -- the four
// dedicated neighbor modes, then the 32 XY-delta block references --
// and keep the one minimizing the SSE of the residual bytes that
// will actually be emitted (int8 reading, post G-decorrelation,
// alpha bytes that the opaque mode 6 rule suppresses excluded).
// Dedicated modes are evaluated first and replacement is strict
// less-than, so an XY delta aliasing a dedicated neighbor can never
// win a tie and waste an index byte.
const basist::bc7u::log_bc7_block* pEP_pred_blk = nullptr;
uint32_t ep_pred_mode = (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointRaw;
uint32_t ep_pred_delta_index = 0;
uint32_t ep_pred_subset = 0;
{
uint64_t best_ep_cost = UINT64_MAX;
auto eval_ep_predictor = [&](const basist::bc7u::log_bc7_block& pred_blk, uint32_t pred_subset) -> uint64_t
{
uint64_t cost = 0;
for (uint32_t s = 0; s < log_blk.m_num_partitions; s++)
{
uint8_t residuals[8];
uint32_t num_residuals;
uint8_t residual_pbits[2];
uint32_t num_residual_pbits;
basist::bc7u::endpoint_dpcm(false,
pred_blk, pred_subset, // mirrors the emission below
log_blk, s,
residuals, num_residuals, residual_pbits, num_residual_pbits);
uint32_t num_costed = num_residuals;
if ((log_blk.m_mode == 6) && (!has_alpha))
num_costed = 6; // alpha residuals are never sent
for (uint32_t i = 0; i < num_costed; i++)
{
const int v = (int8_t)residuals[i];
cost += (uint64_t)((int64_t)v * v);
}
// NOTE: residual_pbits are deliberately NOT costed.
// Penalizing pbit mismatches was tried and measured
// a wash at best (penalty 1: ~0%, penalty 2: +0.4%
// WORSE): the delta stream is raw 1 bit/pbit either
// way, so the only possible win is making its packed
// bytes Zstd-compressible -- but at 8 deltas/byte
// even a 30% nonzero rate leaves ~7 bits/byte of
// entropy, and the residual bytes traded away to
// get there cost more.
}
return cost;
};
const basist::bc7u::log_bc7_block* neighbor_preds[4] = { pLeft_log_blk, pUp_log_blk, pLeft_diag_log_blk, pRight_diag_log_blk };
const xbc7_command_endpoint_mode neighbor_modes[4] =
{
xbc7_command_endpoint_mode::cCmdEndpointDPCMLeft, xbc7_command_endpoint_mode::cCmdEndpointDPCMUp,
xbc7_command_endpoint_mode::cCmdEndpointDPCMLeftDiagonal, xbc7_command_endpoint_mode::cCmdEndpointDPCMRightDiagonal
};
for (uint32_t i = 0; i < 4; i++)
{
if (!neighbor_preds[i])
continue;
const uint64_t cost = eval_ep_predictor(*neighbor_preds[i], 0);
if ((!pEP_pred_blk) || ((cost * 1000) < (best_ep_cost * (1000 - (uint64_t)XBC7_SWEEP_SWITCH_MARGIN_PERMILLE))))
{
best_ep_cost = cost;
pEP_pred_blk = neighbor_preds[i];
ep_pred_mode = (uint32_t)neighbor_modes[i];
ep_pred_subset = 0;
}
}
// Subset-1 variants of left/up (EP modes 6/7), legal only when
// the neighbor is partitioned; swept AFTER the subset-0 modes
// so the switch margin keeps them losing ties. NOTE: a much
// stricter dedicated margin was tried and measured WORSE --
// these modes' SSE wins are nearly always decisive, so the
// filter barely fires; the (small) net cost on rare content
// with hyper-skewed command streams is an SSE-vs-bytes
// mismatch that only rate-based EP selection would fix.
const basist::bc7u::log_bc7_block* s1_preds[2] = { pLeft_log_blk, pUp_log_blk };
const xbc7_command_endpoint_mode s1_modes[2] =
{
xbc7_command_endpoint_mode::cCmdEndpointDPCMLeftSubset1, xbc7_command_endpoint_mode::cCmdEndpointDPCMUpSubset1
};
for (uint32_t i = 0; i < 2; i++)
{
if ((!s1_preds[i]) || (s1_preds[i]->m_num_partitions < 2))
continue;
const uint64_t cost = eval_ep_predictor(*s1_preds[i], 1);
if ((!pEP_pred_blk) || ((cost * 1000) < (best_ep_cost * (1000 - (uint64_t)XBC7_SWEEP_SWITCH_MARGIN_PERMILLE))))
{
best_ep_cost = cost;
pEP_pred_blk = s1_preds[i];
ep_pred_mode = (uint32_t)s1_modes[i];
ep_pred_subset = 1;
}
}
for (uint32_t i = 0; i < NUM_XY_DELTAS; i++)
{
const xbc7_xy_delta& delta = g_xbc7_xy_deltas[i];
const int nx = (int)bx + delta.m_dx;
const int ny = (int)by + delta.m_dy;
if (!tile.contains(nx, ny))
continue;
const basist::bc7u::log_bc7_block& pred_blk = log_blks(nx, ny);
const uint64_t cost = eval_ep_predictor(pred_blk, 0);
if ((!pEP_pred_blk) || ((cost * 1000) < (best_ep_cost * (1000 - (uint64_t)XBC7_SWEEP_SWITCH_MARGIN_PERMILLE))))
{
best_ep_cost = cost;
pEP_pred_blk = &pred_blk;
ep_pred_mode = (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMBlockIndex;
ep_pred_delta_index = i;
ep_pred_subset = 0;
}
}
}
if (pEP_pred_blk)
{
command_byte |= (uint8_t)(ep_pred_mode << XBC7_COMMAND_ENDPOINT_MODE_SHIFT);
stats.m_ep_dpcm_blocks++;
stats.m_ep_mode_hist[ep_pred_mode]++;
if (ep_pred_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMBlockIndex)
{
blob_writer.put_byte(cBlobEPBlockIndex, (uint8_t)ep_pred_delta_index);
stats.m_ep_index_hist[ep_pred_delta_index]++;
}
for (uint32_t s = 0; s < log_blk.m_num_partitions; s++)
{
uint8_t residuals[8];
uint32_t num_residuals;
uint8_t residual_pbits[2];
uint32_t num_residual_pbits;
basist::bc7u::endpoint_dpcm(false,
*pEP_pred_blk, ep_pred_subset, // subset 1 for EP modes 6/7
log_blk, s,
residuals, num_residuals, residual_pbits, num_residual_pbits);
{
basist::bc7u::log_bc7_block temp_log_blk(log_blk);
memset(temp_log_blk.m_endpoints, 0, sizeof(temp_log_blk.m_endpoints));
basist::bc7u::endpoint_dpcm(true,
*pEP_pred_blk, ep_pred_subset, // subset 1 for EP modes 6/7
temp_log_blk, s,
residuals, num_residuals, residual_pbits, num_residual_pbits);
#if defined(DEBUG) || defined(_DEBUG)
for (uint32_t e = 0; e < 2; e++)
{
for (uint32_t c = 0; c < 4; c++)
{
if (log_blk.m_endpoints[s][e][c] != temp_log_blk.m_endpoints[s][e][c])
{
fmt_error_printf("DPCM endpoint decomp failed");
assert(0);
return false;
}
}
}
#endif
}
assert((num_residuals % 2) == 0);
if ((log_blk.m_mode == 6) && (!has_alpha))
{
assert(num_residuals == 8);
if ((log_blk.m_endpoints[0][0][3] != 127) || (log_blk.m_endpoints[0][1][3] != 127))
{
assert(0);
return false;
}
#if 0
if ((residuals[6] != 0) || (residuals[7] != 0))
{
assert(0);
return false;
}
#endif
num_residuals = 6;
}
stats.m_ep_dpcm_subsets++;
stats.record_ep_residuals(log_blk.m_endpoint_bits[0] >= 6, residuals, num_residuals);
if (log_blk.m_endpoint_bits[0] >= 6)
{
for (uint32_t i = 0; i < num_residuals; i += 2)
{
const uint32_t chan = i >> 1;
blob_writer.put_byte(cBlobEPDeltaFineR + chan, residuals[i + 0]);
blob_writer.put_byte(cBlobEPDeltaFineR + chan, residuals[i + 1]);
}
}
else
{
for (uint32_t i = 0; i < num_residuals; i += 2)
{
const uint32_t chan = i >> 1;
blob_writer.put_byte(cBlobEPDeltaCoarseR + chan, residuals[i + 0]);
blob_writer.put_byte(cBlobEPDeltaCoarseR + chan, residuals[i + 1]);
}
}
for (uint32_t p = 0; p < num_residual_pbits; p++)
{
pbits.put_bits(residual_pbits[p], 1);
stats.m_pbit_delta_bits++;
stats.m_pbit_delta_nonzero += residual_pbits[p];
}
}
}
else
{
command_byte |= ((uint8_t)xbc7::xbc7_command_endpoint_mode::cCmdEndpointRaw << XBC7_COMMAND_ENDPOINT_MODE_SHIFT);
stats.m_ep_raw_blocks++;
stats.m_ep_mode_hist[(uint32_t)xbc7_command_endpoint_mode::cCmdEndpointRaw]++;
for (uint32_t s = 0; s < log_blk.m_num_partitions; s++)
{
for (uint32_t c = 0; c < log_blk.get_num_comps(); c++)
{
for (uint32_t e = 0; e < 2; e++)
{
raw_endpoint_bits.put_bits(log_blk.m_endpoints[s][e][c], log_blk.m_endpoint_bits[c == 3]);
}
}
}
for (uint32_t p = 0; p < log_blk.m_num_pbits; p++)
raw_endpoint_bits.put_bits(log_blk.m_pbits[p], 1);
}
// Weights: residual DCT vs lossless residual DPCM, chosen per
// block by estimated emitted size (see decision below). Q >= 100
// is the lossless mode: weights are ALWAYS residual DPCM -- the
// whole file is then exact relative to the input BC7 logical
// blocks -- and the expensive DCT candidate search is skipped.
//
// We ALSO force lossless DPCM (and skip the DCT search) for any block
// the bc7e_scalar base pack flagged as using its one-color endpoint
// LUTs: those extreme endpoints only "land" with exact weights, so the
// lossy weight DCT would decode them to "trap" artifacts. (LUTs are
// already disabled at Q < 100; this also covers the always-LUT solid
// path. At Q == 100 DPCM is forced anyway, so LUTs are harmless there.)
const bool force_dpcm = (opts.m_dct_q >= 100) || (base_used_lut(bx, by) != 0);
dct_syms best_syms[2];
// value-init silences a C4701 false positive: best_cand_log_blk is only
// read on the DCT path (!force_dpcm), where pack_weights() assigns it
// first; the DPCM path 'continue's before the read.
basist::bc7u::log_bc7_block best_cand_log_blk{};
uint32_t best_predictor_index = 0;
uint64_t dct_est_obits = 0;
uint32_t block_total_acs = 0;
if (!force_dpcm)
{
bool pack_status = pack_weights(bx, by, num_blocks_x,
tile,
orig_block,
log_blks,
best_syms, best_cand_log_blk, best_predictor_index,
weight_grid_dct_fixed, dct_work_fixed, opts, enabled_pred_mask, num_amp_codes);
if (!pack_status)
return false;
// Estimated DCT emission cost, mirroring the writes below:
// each stream byte at its measured post-Zstd cost, plus the
// exact (incompressible) sign bits.
for (uint32_t p = 0; p < log_blk.m_num_planes; p++)
{
uint32_t num_acs = 0, num_eobs = 0;
for (uint32_t c = 0; c < best_syms[p].m_ac_vals.size(); c++)
{
if (best_syms[p].m_ac_vals[c].m_coeff == INT16_MAX)
num_eobs++;
else
num_acs++;
}
dct_est_obits += DCT_DC_BYTE_COST_OBITS + (2 * (uint64_t)DCT_AC_BYTE_COST_OBITS) * num_acs + (uint64_t)DCT_AC_BYTE_COST_OBITS * num_eobs +
8 * ((uint64_t)num_acs + ((best_predictor_index != cCandAbsolute) ? 1 : 0));
block_total_acs += num_acs;
}
stats.m_wt_dct_est_bits_total += dct_est_obits;
}
dpcm_weights dpcm;
pack_weights_dpcm(bx, by, num_blocks_x, tile, log_blks, dpcm, enabled_pred_mask, num_amp_codes);
stats.m_wt_dpcm_est_bits_total += dpcm.m_est_cost_obits;
// Both estimates are in measured post-Zstd octobits, so 100 is
// the neutral operating point. Ties go to DPCM: it's lossless,
// so a tie is a free quality win.
bool use_dpcm = force_dpcm || ((dpcm.m_est_cost_obits * 100) <= (dct_est_obits * opts.m_wt_dpcm_alpha_pct));
if (use_dpcm)
{
// the weight-mode command bit is cCmdWeightRaw == 0: nothing to OR in
stats.m_wt_dpcm_blocks++;
stats.m_wt_block_acs_hist_dpcm[basisu::minimum<uint32_t>(block_total_acs, 32)]++;
stats.m_wt_chosen_est_bits += dpcm.m_est_cost_obits;
stats.m_wt_dpcm_pred_hist[dpcm.m_pred_index]++;
blob_writer.put_byte(cBlobWeightPredictors, (uint8_t)dpcm.m_pred_index);
const bool is_absolute = (dpcm.m_pred_index == (uint32_t)cCandAbsolute);
for (uint32_t p = 0; p < log_blk.m_num_planes; p++)
{
const uint32_t num_bits = log_blk.m_weight_bits[p];
const uint32_t blob_id = is_absolute ? (uint32_t)cBlobRawWeightBits :
((num_bits == 2) ? (uint32_t)cBlobDPCMWeightResid2 :
(num_bits == 3) ? (uint32_t)cBlobDPCMWeightResid3 : (uint32_t)cBlobDPCMWeightResid4);
if (!is_absolute)
{
const uint32_t cls = num_bits - 2;
const int half = 1 << (num_bits - 1);
for (uint32_t i = 0; i < 16; i++)
{
const int sym = dpcm.m_syms[p][i];
const int v = (sym >= half) ? (sym - (1 << num_bits)) : sym;
stats.m_wt_resid_count[cls]++;
stats.m_wt_resid_sum_abs[cls] += (uint64_t)iabs(v);
if (!v)
stats.m_wt_resid_zero[cls]++;
stats.m_wt_resid_mag_hist[cls][basisu::minimum<int>(iabs(v), 8)]++;
}
}
if (num_bits == 2)
{
// 4 per byte, LSB first
for (uint32_t i = 0; i < 16; i += 4)
{
blob_writer.put_byte(blob_id, (uint8_t)(dpcm.m_syms[p][i] |
(dpcm.m_syms[p][i + 1] << 2) | (dpcm.m_syms[p][i + 2] << 4) | (dpcm.m_syms[p][i + 3] << 6)));
}
}
else
{
// 3-bit expanded to nibbles / 4-bit: 2 per byte, LSB first
for (uint32_t i = 0; i < 16; i += 2)
{
blob_writer.put_byte(blob_id, (uint8_t)(dpcm.m_syms[p][i] | (dpcm.m_syms[p][i + 1] << 4)));
}
}
} // p
// lossless: reconstruction == input, no weight write-back needed
if (pCoded_log_blocks)
{
(*pCoded_log_blocks)(bx, by) = log_blk;
}
if (debug_images)
xbc7_vis_fill_command(dbg_imgs, bx, by, command_byte, true, dpcm.m_pred_index, UINT32_MAX); // lossless DPCM weights: no DCT ACs
blob_writer.put_byte(cBlobCommands, command_byte);
continue;
}
command_byte |= ((uint8_t)xbc7::xbc7_command_weight_mode::cCmdWeightDCT << XBC7_COMMAND_WEIGHT_MODE_SHIFT);
// optional AC-truncation RDO: prune high-freq weight-DCT ACs from the
// winning symbols (once per block), within the configured PSNR drop
if (opts.m_ac_trunc_rdo_max_psnr_drop > 0.0f)
{
if (!ac_truncate_rdo(best_syms, best_cand_log_blk, best_predictor_index, orig_block,
bx, by, num_blocks_x, tile, log_blks, weight_grid_dct_fixed, dct_work_fixed, opts, stats))
return false;
// refresh the AC count for the histogram below (pruning changed it)
block_total_acs = 0;
for (uint32_t p = 0; p < log_blk.m_num_planes; p++)
{
uint32_t n = best_syms[p].m_ac_vals.size_u32();
if (n && (best_syms[p].m_ac_vals[n - 1].m_coeff == INT16_MAX))
n--;
block_total_acs += n;
}
}
stats.m_wt_dct_blocks++;
stats.m_wt_block_acs_hist_dct[basisu::minimum<uint32_t>(block_total_acs, 32)]++;
stats.m_wt_chosen_est_bits += dct_est_obits;
blob_writer.put_byte(cBlobWeightPredictors, (uint8_t)best_predictor_index);
stats.m_pred_hist[best_predictor_index]++;
for (uint32_t p = 0; p < log_blk.m_num_planes; p++)
{
stats.m_dct_stats.record_plane(best_syms[p]);
assert(iabs(best_syms[p].m_dc) <= 255);
// TODO: Always writing full precision DC
blob_writer.put_byte(cBlobDCCoeffsSmall, (uint8_t)iabs(best_syms[p].m_dc));
if (best_predictor_index == cCandAbsolute)
{
assert(best_syms[p].m_dc >= 0);
}
else
{
coeff_signs.put_bits((best_syms[p].m_dc < 0) ? 1 : 0, 1);
}
assert(best_syms[p].m_ac_vals.size());
for (uint32_t c = 0; c < best_syms[p].m_ac_vals.size(); c++)
{
uint32_t num_zeros = best_syms[p].m_ac_vals[c].m_num_zeros;
int ac_coeff = best_syms[p].m_ac_vals[c].m_coeff;
if (ac_coeff == INT16_MAX)
{
blob_writer.put_byte(cBlobACCoeffs, 0xFF);
}
else
{
assert(iabs(ac_coeff) <= 255);
blob_writer.put_byte(cBlobACCoeffs, (uint8_t)num_zeros);
blob_writer.put_byte(cBlobACCoeffs, (uint8_t)iabs(ac_coeff));
coeff_signs.put_bits((ac_coeff < 0) ? 1 : 0, 1);
}
} // c
} // p
log_blk = best_cand_log_blk;
if (pCoded_log_blocks)
{
(*pCoded_log_blocks)(bx, by) = best_cand_log_blk;
}
if (debug_images)
xbc7_vis_fill_command(dbg_imgs, bx, by, command_byte, true, best_predictor_index, block_total_acs); // DCT weights
blob_writer.put_byte(cBlobCommands, command_byte);
} // bx
} // by
return true;
}
// Packs a single 4x4 RGBA block into a physical BC7 block using whichever BC7
// base encoder is selected in opts: cBC7F is the built-in fast real-time
// packer; cBC7E_Scalar is the higher-quality scalar bc7e encoder (whose
// per-level params must be prebuilt once into bc7e_params before threading).
// Either way it returns a standard physical BC7 block, identical in form to
// what bc7f produces, so the rest of the pipeline is unaffected.
static inline void xbc7_pack_bc7_base_block(
basist::bc7u::phys_bc7_block& phys_blk,
const color_rgba* pPixels,
const pack_options& opts,
const bc7e_scalar::bc7e_compress_block_params& bc7e_params,
bool& used_lut)
{
used_lut = false;
if (opts.m_bc7_encoder == bc7_encoder_type::cBC7E_Scalar)
{
// bc7e writes via a uint64_t*; phys_bc7_block::m_bytes has no alignment
// guarantee, so encode into an aligned local and copy the 16 bytes back.
// pUsed_lut reports whether the winning encoding used bc7e's one-color
// endpoint LUTs on any subset (a "this block may be weird" hint).
uint64_t blk64[2];
uint8_t lut_flag = 0;
bc7e_scalar::bc7e_compress_blocks(1, blk64, (const uint32_t*)pPixels, &bc7e_params, &lut_flag);
memcpy(phys_blk.m_bytes, blk64, sizeof(phys_blk.m_bytes));
used_lut = (lut_flag != 0);
}
else
{
// bc7f does not use the one-color endpoint LUTs.
basist::bc7f::fast_pack_bc7_auto_rgba(phys_blk.m_bytes, (basist::color_rgba*)pPixels, opts.m_bc7_pack_flags);
}
}
bool pack_image(
const image& orig_img,
const pack_options& opts,
uint8_vec &comp_bytes,
vector2D<basist::bc7u::log_bc7_block> &coded_log_blocks)
{
#if !BASISD_SUPPORT_KTX2_ZSTD
// XBC7 is entirely zstd-based: the stream is zstd-compressed (serialize) and
// decoding/validation requires zstd too. We do not support uncompressed XBC7
// streams, so without BASISD_SUPPORT_KTX2_ZSTD there is nothing we can do --
// fail the encode cleanly. (The zstd-using body below isn't compiled here, so
// the encoder still links: serialize() ends up unreferenced.)
BASISU_NOTE_UNUSED(orig_img); BASISU_NOTE_UNUSED(opts);
BASISU_NOTE_UNUSED(comp_bytes); BASISU_NOTE_UNUSED(coded_log_blocks);
fmt_error_printf("XBC7 pack_image: XBC7 requires zstd (BASISD_SUPPORT_KTX2_ZSTD=0) -- cannot encode\n");
return false;
#else
// Internal pointer alias for the caller-provided reference (guaranteed
// non-null): pack_stripe() and the threaded lambdas below thread the coded
// logical blocks through as a pointer. The encoder always populates these
// and then validates the encoded stream decodes back to them exactly.
vector2D<basist::bc7u::log_bc7_block>* pCoded_log_blocks = &coded_log_blocks;
const uint32_t width = orig_img.get_width();
const uint32_t height = orig_img.get_height();
if ((!width) || (width > UINT16_MAX) || (!height) || (height > UINT16_MAX))
{
assert(0);
return false;
}
if ((opts.m_dct_q < 1) || (opts.m_dct_q > 100))
{
assert(0);
return false;
}
if (!opts.m_pJob_pool)
{
assert(0);
return false;
}
const bool use_threading = (opts.m_pJob_pool->get_total_threads() > 1);
const uint32_t block_width = 4;
const uint32_t block_height = 4;
const uint32_t num_blocks_x = (width + block_width - 1) / block_width;
const uint32_t num_blocks_y = (height + block_height - 1) / block_height;
const uint32_t total_blocks = num_blocks_x * num_blocks_y;
const bool has_alpha = orig_img.has_alpha();
if (opts.m_debug_output)
fmt_debug_printf("XBC7 pack: {}x{} texels, alpha: {}, block: {}x{}, blocks: {}x{} = {} total\n",
width, height, has_alpha, block_width, block_height, num_blocks_x, num_blocks_y, total_blocks);
// Dump the full set of pack_options that were passed in.
if (opts.m_debug_output)
{
fmt_debug_printf("---- XBC7 pack_options ----\n");
fmt_debug_printf(" dct_q: {}\n", opts.m_dct_q);
{
const uint64_t dbg_mask = xbc7_build_pred_mask(opts.m_effort_level);
uint32_t dbg_num_preds = 0;
for (uint32_t c = 0; c < cTotalCandidates; c++)
dbg_num_preds += (uint32_t)((dbg_mask >> c) & 1u);
fmt_debug_printf(" effort_level: {} (weight predictors: {}/{}, amp codes: {}/4)\n",
opts.m_effort_level, dbg_num_preds, (uint32_t)cTotalCandidates, xbc7_amp_codes_for_effort(opts.m_effort_level));
}
fmt_debug_printf(" weights[RGBA]: {} {} {} {}\n", opts.m_weights[0], opts.m_weights[1], opts.m_weights[2], opts.m_weights[3]);
fmt_debug_printf(" optimize_weights_after_bc7f: {}\n", opts.m_optimize_weights_after_bc7f);
fmt_debug_printf(" bc7_encoder: {} (bc7e_scalar level: {}, perceptual: {})\n",
(opts.m_bc7_encoder == bc7_encoder_type::cBC7E_Scalar) ? "bc7e_scalar" : "bc7f", opts.m_bc7e_scalar_level, opts.m_perceptual);
fmt_debug_printf(" self_validate: {}\n", opts.m_self_validate);
fmt_debug_printf(" bc7_pack_flags: 0x{X}\n", opts.m_bc7_pack_flags);
fmt_debug_printf(" bc7_alt_pack_enabled: {}, bc7_pack_flags_alt: 0x{X}, bc7_alt_max_psnr_drop: {.3}\n",
opts.m_bc7_alt_pack_enabled, opts.m_bc7_pack_flags_alt, opts.m_bc7_alt_max_psnr_drop);
fmt_debug_printf(" repeat_rdo_enabled: {}, repeat_rdo_max_psnr_drop: {.3}\n", opts.m_repeat_rdo_enabled, opts.m_repeat_rdo_max_psnr_drop);
fmt_debug_printf(" solid_rdo_enabled: {}, solid_rdo_max_psnr_drop: {.3}\n", opts.m_solid_rdo_enabled, opts.m_solid_rdo_max_psnr_drop);
fmt_debug_printf(" endpoint_rdo_enabled: {}, endpoint_rdo_max_psnr_drop: {.3}\n", opts.m_endpoint_rdo_enabled, opts.m_endpoint_rdo_max_psnr_drop);
fmt_debug_printf(" ac_trunc_rdo_max_psnr_drop: {.3}\n", opts.m_ac_trunc_rdo_max_psnr_drop);
fmt_debug_printf(" rdo_min_block_psnr: {.3}\n", opts.m_rdo_min_block_psnr);
fmt_debug_printf(" wt_dpcm_alpha_pct: {}\n", opts.m_wt_dpcm_alpha_pct);
fmt_debug_printf(" num_stripes (0=auto): {}\n", opts.m_num_stripes);
fmt_debug_printf(" job_pool total threads: {}\n", opts.m_pJob_pool ? (uint32_t)opts.m_pJob_pool->get_total_threads() : 0);
fmt_debug_printf(" print_stats: {}, debug_images: {}, debug_file_prefix: '{}'\n",
opts.m_print_stats, opts.m_debug_images, opts.m_debug_file_prefix.c_str());
}
vector2D<basist::bc7u::log_bc7_block> log_blks(num_blocks_x, num_blocks_y);
// Per-block flag: 1 if the bc7e_scalar base pack used its one-color endpoint
// LUTs on the block (pack_stripe forces lossless DPCM for these). Function
// scope so it survives from the base pack into the stripe coding pass.
vector2D<uint8_t> base_used_lut(num_blocks_x, num_blocks_y);
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: BC7 base pack ({} blocks{})...\n", total_blocks, opts.m_bc7_alt_pack_enabled ? ", alt-pack RDO" : "");
// BC7 base pack + canonicalize. Every block is independent and writes
// only its own pre-sized log_blks slot, so this pass parallelizes with
// simple atomic row stealing; all per-block state lives on each job's
// stack. The packer/unpack/canonicalize helpers are pure functions of
// their inputs (shared state is const tables initialized at startup).
{
// Prebuild the bc7e_scalar params once (shared, read-only across the
// pack jobs); only used when that encoder is selected. The level [0,6]
// picks one of its speed/quality presets (0=ultrafast .. 6=slowest).
// A one-time global table init is required before the first encode.
bc7e_scalar::bc7e_compress_block_params bc7e_params;
memset(&bc7e_params, 0, sizeof(bc7e_params));
if (opts.m_bc7_encoder == bc7_encoder_type::cBC7E_Scalar)
{
bc7e_scalar::bc7e_compress_block_init();
typedef void (*bc7e_params_init_func)(bc7e_scalar::bc7e_compress_block_params*, bool);
static const bc7e_params_init_func s_bc7e_level_init[BC7E_SCALAR_MAX_LEVEL + 1] =
{
&bc7e_scalar::bc7e_compress_block_params_init_ultrafast, // 0
&bc7e_scalar::bc7e_compress_block_params_init_veryfast, // 1
&bc7e_scalar::bc7e_compress_block_params_init_fast, // 2
&bc7e_scalar::bc7e_compress_block_params_init_basic, // 3
&bc7e_scalar::bc7e_compress_block_params_init_slow, // 4
&bc7e_scalar::bc7e_compress_block_params_init_veryslow, // 5
&bc7e_scalar::bc7e_compress_block_params_init_slowest, // 6
};
const uint32_t lvl = clamp<uint32_t>(opts.m_bc7e_scalar_level, BC7E_SCALAR_MIN_LEVEL, BC7E_SCALAR_MAX_LEVEL);
// For perceptual (sRGB) sources, run bc7e in its built-in perceptual
// error mode and leave its channel weights at the preset defaults. For
// linear sources, run bc7e in linear mode and honor the explicit XBC7
// channel weights. (bc7f supports neither, so this only affects bc7e.)
s_bc7e_level_init[lvl](&bc7e_params, opts.m_perceptual);
if (!opts.m_perceptual)
{
for (uint32_t i = 0; i < 4; i++)
bc7e_params.m_weights[i] = opts.m_weights[i];
}
// bc7e's aggressive one-color endpoint LUTs place endpoints at extreme
// positions that only "land" with exact weights. Only allow them at
// lossless Q (m_dct_q == 100, weights coded losslessly); at lower Q the
// lossy weight DCT can't reproduce them and the block decodes to a
// "trap" artifact, so disable the LUTs there.
bc7e_params.m_use_luts = (opts.m_dct_q >= 100);
}
image raw_bc7_debug_image;
if (opts.m_debug_images || (opts.m_debug_output && opts.m_print_stats))
{
raw_bc7_debug_image.resize(orig_img.get_width(), orig_img.get_height());
}
std::atomic<uint32_t> cur_row;
cur_row.store(0);
std::atomic<bool> pack_failed_flag;
pack_failed_flag.store(false);
std::atomic<uint32_t> alt_changed_blocks; // BC7 alt-pack RDO: blocks where the alternate was kept
alt_changed_blocks.store(0);
std::atomic<uint32_t> lut_block_count; // bc7e_scalar: blocks whose winning encoding used the endpoint LUTs
lut_block_count.store(0);
std::atomic<uint32_t> lut_block_count_nonsolid; // same, but excluding solid blocks (all 16 source pixels equal)
lut_block_count_nonsolid.store(0);
auto pack_rows_func = [num_blocks_x, num_blocks_y, &opts,
&cur_row, &pack_failed_flag, &alt_changed_blocks, &lut_block_count, &lut_block_count_nonsolid,
&orig_img, &log_blks, &raw_bc7_debug_image, &bc7e_params, &base_used_lut]()
{
for ( ; ; )
{
if (pack_failed_flag)
return;
const uint32_t by = cur_row.fetch_add(1);
if (by >= num_blocks_y)
break;
for (uint32_t bx = 0; bx < num_blocks_x; bx++)
{
color_rgba orig_block[16];
orig_img.extract_block_clamped(orig_block, bx * 4, by * 4, 4, 4);
basist::bc7u::phys_bc7_block phys_blk;
bool used_lut = false;
xbc7_pack_bc7_base_block(phys_blk, orig_block, opts, bc7e_params, used_lut);
base_used_lut(bx, by) = used_lut ? (uint8_t)1 : (uint8_t)0;
if (used_lut)
{
lut_block_count.fetch_add(1, std::memory_order_relaxed);
// A block is "solid" if all 16 source pixels are equal.
bool is_solid = true;
for (uint32_t i = 1; i < 16; i++)
{
if ((orig_block[i].r != orig_block[0].r) || (orig_block[i].g != orig_block[0].g) ||
(orig_block[i].b != orig_block[0].b) || (orig_block[i].a != orig_block[0].a))
{
is_solid = false;
break;
}
}
if (!is_solid)
lut_block_count_nonsolid.fetch_add(1, std::memory_order_relaxed);
}
if (raw_bc7_debug_image.get_width())
{
basist::color_rgba unpacked_block[16];
bool as = basist::bc7u::unpack_bc7(&phys_blk, unpacked_block);
assert(as);
BASISU_NOTE_UNUSED(as);
raw_bc7_debug_image.set_block_clipped((color_rgba *)unpacked_block, bx * 4, by * 4, 4, 4);
}
// Optional poor-man's RDO: also pack with the alternate
// (typically cheaper) flags and keep IT unless the primary's
// RGBA PSNR is at least the threshold dB higher.
if (opts.m_bc7_alt_pack_enabled)
{
basist::bc7u::phys_bc7_block phys_alt;
basist::bc7f::fast_pack_bc7_auto_rgba(phys_alt.m_bytes, (basist::color_rgba*)orig_block, opts.m_bc7_pack_flags_alt);
basist::color_rgba dec_primary[16], dec_alt[16];
if ((!basist::bc7u::unpack_bc7(phys_blk.m_bytes, dec_primary)) ||
(!basist::bc7u::unpack_bc7(phys_alt.m_bytes, dec_alt)))
{
assert(0);
pack_failed_flag.store(true);
return;
}
const float psnr_primary = xbc7_block_wsse_psnr(orig_block, (const color_rgba*)dec_primary, opts.m_weights);
const float psnr_alt = xbc7_block_wsse_psnr(orig_block, (const color_rgba*)dec_alt, opts.m_weights);
if ((psnr_alt >= opts.m_rdo_min_block_psnr) && ((psnr_primary - psnr_alt) < opts.m_bc7_alt_max_psnr_drop))
{
phys_blk = phys_alt; // above the quality floor and drop within tolerance -- keep the cheaper block
alt_changed_blocks.fetch_add(1, std::memory_order_relaxed);
}
}
basist::bc7u::log_bc7_block& log_blk = log_blks(bx, by);
bool unpack_status = basist::bc7u::unpack_bc7(&phys_blk, log_blk);
if (!unpack_status)
{
assert(0);
pack_failed_flag.store(true);
return;
}
#if defined(DEBUG) || defined(_DEBUG)
{
// sanity check canonicalization code
basist::bc7u::log_bc7_block temp_log_blk(log_blk);
basist::bc7u::canonicalize_endpoints(temp_log_blk);
color_rgba ap[16], bp[16];
bool as = basist::bc7u::unpack_bc7(log_blk, (basist::color_rgba*)ap);
assert(as);
bool bs = basist::bc7u::unpack_bc7(temp_log_blk, (basist::color_rgba*)bp);
assert(bs);
if (memcmp(ap, bp, sizeof(color_rgba) * 16) != 0)
{
assert(0);
pack_failed_flag.store(true);
return;
}
}
#endif
basist::bc7u::canonicalize_endpoints(log_blk);
// optional: re-optimize the weights for bc7f's endpoints.
// bc7f is a fast real-time packer, so its weights aren't
// per-texel optimal -- this exhaustively re-derives them
// (slower, but threaded with the base pack). Endpoints/config
// unchanged, so it can only hold or improve quality.
if (opts.m_optimize_weights_after_bc7f)
{
basist::bc7u::log_bc7_block opt_blk;
if (!optimize_block_weights(log_blk, orig_block, opts.m_weights, opt_blk))
{
assert(0);
pack_failed_flag.store(true);
return;
}
log_blk = opt_blk;
}
} // bx
}
};
if ((use_threading) && (num_blocks_y > 1))
{
const uint32_t num_threads = (uint32_t)opts.m_pJob_pool->get_total_threads();
// one job per worker; each drains rows via the atomic counter
for (uint32_t job_index = 0; job_index < num_threads; job_index++)
opts.m_pJob_pool->add_job(pack_rows_func);
opts.m_pJob_pool->wait_for_all();
}
else
{
pack_rows_func();
}
if (pack_failed_flag)
return false;
if (opts.m_debug_output && opts.m_bc7_alt_pack_enabled)
{
const uint32_t n = alt_changed_blocks.load();
fmt_debug_printf("BC7 alt-pack RDO: {} blocks changed ({.2}%)\n", n, total_blocks ? (n * 100.0f / (float)total_blocks) : 0.0f);
}
if (opts.m_debug_output && (opts.m_bc7_encoder == bc7_encoder_type::cBC7E_Scalar))
{
const uint32_t n = lut_block_count.load();
const uint32_t n_nonsolid = lut_block_count_nonsolid.load();
fmt_debug_printf("bc7e_scalar: {} of {} blocks used endpoint LUTs ({.2}%); {} excluding solid blocks ({.2}%) [m_use_luts={}]\n",
n, total_blocks, total_blocks ? (n * 100.0f / (float)total_blocks) : 0.0f,
n_nonsolid, total_blocks ? (n_nonsolid * 100.0f / (float)total_blocks) : 0.0f, bc7e_params.m_use_luts);
}
if (raw_bc7_debug_image.get_width())
{
if (opts.m_debug_images)
save_png(opts.m_debug_file_prefix + "vis_raw_bc7.png", raw_bc7_debug_image);
if ((opts.m_debug_output) && (opts.m_print_stats))
{
fmt_debug_printf("\nRaw packed BC7 image stats:\n");
print_image_metrics(orig_img, raw_bc7_debug_image);
}
}
}
// Stripe geometry for the main coding pass. The count is a pure function
// of m_num_stripes (or the image dimensions when it's 0), NOT of the pool
// size, so the output is reproducible regardless of thread count. Pass
// m_num_stripes = 1 for the single-stripe (no seam cost, no seek table)
// format. More stripes than pool threads simply queue.
basisu::vector<stripe_range> stripes;
uint32_t num_stripes;
if (opts.m_num_stripes)
{
// caller forced a specific count -- clamp to what the format and the
// image can hold (can't exceed the block-row count or the max)
num_stripes = basisu::clamp<uint32_t>(opts.m_num_stripes, 1, basisu::minimum(num_blocks_y, XBC7_MAX_ENCODER_STRIPES));
compute_stripe_ranges(num_blocks_y, num_stripes, stripes);
}
else
{
num_stripes = compute_encoder_stripes(height, num_blocks_y, stripes);
}
// optional block-reuse RDO: replace whole blocks with a Repeat of a neighbor
// or a solid color where quality allows -- runs FIRST (cheapest commands)
if (opts.m_repeat_rdo_enabled || opts.m_solid_rdo_enabled)
{
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: block-reuse RDO pass (repeat/solid)...\n");
if (!block_reuse_rdo_pass(orig_img, log_blks, num_blocks_x, stripes, opts))
return false;
}
// optional endpoint-prediction RDO: rewrite block endpoints toward their
// causal neighbors (zero-residual DPCM) + re-optimize weights where quality
// allows, BEFORE coding
if (opts.m_endpoint_rdo_enabled)
{
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: endpoint-DPCM RDO pass...\n");
if (!endpoint_dpcm_rdo_pass(orig_img, log_blks, num_blocks_x, stripes, opts))
return false;
}
if (pCoded_log_blocks)
{
pCoded_log_blocks->resize(num_blocks_x, num_blocks_y);
for (uint32_t y = 0; y < num_blocks_y; y++)
{
for (uint32_t x = 0; x < num_blocks_x; x++)
{
(*pCoded_log_blocks)(x, y).clear();
(*pCoded_log_blocks)(x, y).m_mode = -1;
}
}
}
blob_stream_writer blob_writer;
basisu::bitwise_coder coeff_signs;
coeff_signs.reserve(1024);
basisu::bitwise_coder pbits;
pbits.reserve(1024);
basisu::bitwise_coder raw_endpoint_bits;
raw_endpoint_bits.reserve(1024);
xbc7_pack_stats stats;
stats.m_width = width;
stats.m_height = height;
stats.m_total_blocks = total_blocks;
stats.m_dct_q = opts.m_dct_q;
stats.m_has_alpha = has_alpha;
stats.m_wt_alpha_pct = opts.m_wt_dpcm_alpha_pct;
stats.m_stripes = stripes;
// ---- main coding pass: one job per stripe ----
// Each stripe codes into its own stripe_output (disjoint vector
// elements, pre-sized here, so the jobs never touch shared mutable
// state outside their own log_blks/pCoded rows).
basisu::vector<stripe_output> stripe_outputs(num_stripes);
// optional per-block debug visualizations (one 4x4 pixel block per BC7
// block), each with a drawn legend strip below the block grid. Shared
// across stripe jobs, but each stripe fills disjoint rows.
image vis_command_img, vis_ep_mode_img, vis_wt_mode_img, vis_ac_count_img, vis_predictor_img;
xbc7_debug_image_set dbg_imgs;
if (opts.m_debug_images)
{
// same resolution as the source image; the legend is drawn into the
// bottom strip afterward (overwriting a few block rows -- all clipped)
vis_command_img.resize(width, height);
vis_ep_mode_img.resize(width, height);
vis_wt_mode_img.resize(width, height);
vis_ac_count_img.resize(width, height);
vis_predictor_img.resize(width, height);
dbg_imgs.m_pAC_count = &vis_ac_count_img;
dbg_imgs.m_pPredictor = &vis_predictor_img;
dbg_imgs.m_pCommand = &vis_command_img;
dbg_imgs.m_pEndpoint_mode = &vis_ep_mode_img;
dbg_imgs.m_pWeight_mode = &vis_wt_mode_img;
}
std::atomic<bool> stripe_failed_flag;
stripe_failed_flag.store(false);
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: main coding pass ({} stripe{}, {})...\n",
num_stripes, (num_stripes == 1) ? "" : "s", ((use_threading) && (num_stripes > 1)) ? "threaded" : "serial");
if ((use_threading) && (num_stripes > 1))
{
for (uint32_t stripe_index = 0; stripe_index < num_stripes; stripe_index++)
{
opts.m_pJob_pool->add_job([stripe_index, has_alpha, num_blocks_x,
&stripes, &stripe_outputs, &stripe_failed_flag,
&orig_img, &opts, &log_blks, pCoded_log_blocks, &base_used_lut, dbg_imgs]
{
if (!pack_stripe(orig_img, opts, has_alpha, num_blocks_x,
stripes[stripe_index], log_blks, pCoded_log_blocks, base_used_lut, stripe_outputs[stripe_index], dbg_imgs))
{
stripe_failed_flag.store(true);
}
});
}
opts.m_pJob_pool->wait_for_all();
}
else
{
for (uint32_t stripe_index = 0; stripe_index < num_stripes; stripe_index++)
{
if (!pack_stripe(orig_img, opts, has_alpha, num_blocks_x,
stripes[stripe_index], log_blks, pCoded_log_blocks, base_used_lut, stripe_outputs[stripe_index], dbg_imgs))
{
stripe_failed_flag.store(true);
break;
}
}
}
if (stripe_failed_flag)
return false;
if (opts.m_debug_images)
{
const xbc7_vis_legend_entry cmd_legend[8] =
{
{ g_xbc7_command_vis_colors[0], "0 RepeatLast" },
{ g_xbc7_command_vis_colors[1], "1 RepeatUpper" },
{ g_xbc7_command_vis_colors[2], "2 SolidDPCM" },
{ g_xbc7_command_vis_colors[3], "3 NewConfig" },
{ g_xbc7_command_vis_colors[4], "4 ReuseConfig Left" },
{ g_xbc7_command_vis_colors[5], "5 ReuseConfig Up" },
{ g_xbc7_command_vis_colors[6], "6 ReuseConfig LeftDiag" },
{ g_xbc7_command_vis_colors[7], "7 ReuseConfig RightDiag" },
};
const xbc7_vis_legend_entry ep_legend[9] =
{
{ g_xbc7_endpoint_mode_vis_colors[0], "0 Raw" },
{ g_xbc7_endpoint_mode_vis_colors[1], "1 DPCM Left" },
{ g_xbc7_endpoint_mode_vis_colors[2], "2 DPCM Up" },
{ g_xbc7_endpoint_mode_vis_colors[3], "3 DPCM LeftDiag" },
{ g_xbc7_endpoint_mode_vis_colors[4], "4 DPCM RightDiag" },
{ g_xbc7_endpoint_mode_vis_colors[5], "5 DPCM BlockIndex" },
{ g_xbc7_endpoint_mode_vis_colors[6], "6 DPCM Left Subset1" },
{ g_xbc7_endpoint_mode_vis_colors[7], "7 DPCM Up Subset1" },
{ g_xbc7_vis_na_color, "n/a (fully predicted block)" },
};
const xbc7_vis_legend_entry wt_legend[3] =
{
{ g_xbc7_weight_mode_vis_colors[0], "0 Raw/DPCM weights (lossless)" },
{ g_xbc7_weight_mode_vis_colors[1], "1 DCT weights (lossy)" },
{ g_xbc7_vis_na_color, "n/a (fully predicted block)" },
};
const xbc7_vis_legend_entry ac_legend[7] =
{
{ g_xbc7_ac_count_vis_colors[0], "0 ACs (flat / DC only)" },
{ g_xbc7_ac_count_vis_colors[1], "1-2 ACs" },
{ g_xbc7_ac_count_vis_colors[2], "3-5 ACs" },
{ g_xbc7_ac_count_vis_colors[3], "6-10 ACs" },
{ g_xbc7_ac_count_vis_colors[4], "11-20 ACs" },
{ g_xbc7_ac_count_vis_colors[5], "21+ ACs" },
{ g_xbc7_vis_na_color, "n/a (not DCT-coded)" },
};
const xbc7_vis_legend_entry pred_legend[7] =
{
{ g_xbc7_predictor_vis_colors[cPredCatAbsolute], "Absolute (no prediction)" },
{ g_xbc7_predictor_vis_colors[cPredCatSynthetic], "Synthetic edge/gradient" },
{ g_xbc7_predictor_vis_colors[cPredCatRefLeft], "BlockRef Left" },
{ g_xbc7_predictor_vis_colors[cPredCatRefUp], "BlockRef Up" },
{ g_xbc7_predictor_vis_colors[cPredCatRefUpLeft], "BlockRef Up-Left" },
{ g_xbc7_predictor_vis_colors[cPredCatRefUpRight], "BlockRef Up-Right" },
{ g_xbc7_vis_na_color, "n/a (fully predicted block)" },
};
xbc7_vis_draw_legend(vis_command_img, cmd_legend, 8);
xbc7_vis_draw_legend(vis_ep_mode_img, ep_legend, 9);
xbc7_vis_draw_legend(vis_wt_mode_img, wt_legend, 3);
xbc7_vis_draw_legend(vis_ac_count_img, ac_legend, 7);
xbc7_vis_draw_legend(vis_predictor_img, pred_legend, 7);
save_png(opts.m_debug_file_prefix + "vis_xbc7_command.png", vis_command_img);
save_png(opts.m_debug_file_prefix + "vis_xbc7_endpoint_mode.png", vis_ep_mode_img);
save_png(opts.m_debug_file_prefix + "vis_xbc7_weight_mode.png", vis_wt_mode_img);
save_png(opts.m_debug_file_prefix + "vis_xbc7_weight_ac_count.png", vis_ac_count_img);
save_png(opts.m_debug_file_prefix + "vis_xbc7_weight_predictor.png", vis_predictor_img);
}
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: merging stripe streams{}...\n", (num_stripes > 1) ? " + building seek table" : "");
// Per-stripe seek table: for each stripe, the start offset of its data
// in every per-stripe stream id 1..25 -- a BYTE offset for byte blobs,
// a BIT offset for the three bit blobs (signs/pbits/ep_raw, which stay
// bit-merged with no padding). Recorded BEFORE each stripe is appended.
// Built only when there's more than one stripe.
const uint32_t SEEK_NUM_STREAMS = (uint32_t)cBlobStripeSeekTable - 1; // ids 1..25
basisu::vector<basisu::packed_uint<4>> seek_table; // [stripe * SEEK_NUM_STREAMS + (id-1)], little-endian DELTAS from prev stripe
if (num_stripes > 1)
seek_table.resize(num_stripes * SEEK_NUM_STREAMS);
// running start offset of the PREVIOUS stripe in each stream (indexed by
// blob id), so each table entry can be stored as a small delta
uint64_t prev_seek_ofs[(uint32_t)cBlobStripeSeekTable] = {};
// ---- merge the per-stripe streams, strictly in stripe (raster) order ----
for (uint32_t stripe_index = 0; stripe_index < num_stripes; stripe_index++)
{
const stripe_output& so = stripe_outputs[stripe_index];
if (num_stripes > 1)
{
for (uint32_t id = 1; id < (uint32_t)cBlobStripeSeekTable; id++)
{
uint64_t ofs;
if (id == cBlobCoeffSigns)
ofs = coeff_signs.get_total_bits(); // bit offset
else if (id == cBlobPBits)
ofs = pbits.get_total_bits(); // bit offset
else if (id == cBlobEPRaw)
ofs = raw_endpoint_bits.get_total_bits(); // bit offset
else
ofs = blob_writer.get_blob_size(id); // byte offset
// store the delta from the previous stripe's start (stripe 0 -> 0).
// offsets are monotonic, so the delta is non-negative and small;
// packed_uint<4> keeps the low 32 bits, little-endian.
seek_table[stripe_index * SEEK_NUM_STREAMS + (id - 1)] = ofs - prev_seek_ofs[id];
prev_seek_ofs[id] = ofs;
}
}
for (uint32_t id = 0; id < BLOB_STREAM_MAX_IDS; id++)
{
const uint8_vec* pBlob = so.m_blob_writer.get_blob_data(id);
if ((pBlob) && (pBlob->size()))
blob_writer.append_bytes(id, *pBlob);
}
// bit streams: append() carries each stripe's unflushed partial bit
// buffer, so the merged streams contain NO padding at the seams --
// the decoder still reads single continuous LSB-first streams, and
// the seek table addresses stripe starts at BIT granularity
coeff_signs.append(so.m_coeff_signs);
pbits.append(so.m_pbits);
raw_endpoint_bits.append(so.m_raw_endpoint_bits);
stats.merge(so.m_stats);
}
if (raw_endpoint_bits.get_total_bits())
{
raw_endpoint_bits.flush();
blob_writer.get_blob_vec(cBlobEPRaw) = raw_endpoint_bits.get_bytes();
}
if (pbits.get_total_bits())
{
pbits.flush();
blob_writer.get_blob_vec(cBlobPBits) = pbits.get_bytes();
}
if (coeff_signs.get_total_bits())
{
coeff_signs.flush();
blob_writer.get_blob_vec(cBlobCoeffSigns) = coeff_signs.get_bytes();
}
// emit the seek table, byte-plane (SoA) transposed: all entries' byte 0
// first, then every byte 1, then byte 2, then byte 3. The deltas are
// small, so the upper planes are near-all-zero and Zstd crushes them --
// much better than the interleaved little-endian layout. Lossless
// reordering; the decoder reverses it before reading the deltas.
if (num_stripes > 1)
{
const uint32_t num_entries = (uint32_t)seek_table.size(); // num_stripes * SEEK_NUM_STREAMS
const uint8_t* pSrc = (const uint8_t*)seek_table.data(); // little-endian, 4 bytes/entry
uint8_vec planed(num_entries * 4);
for (uint32_t plane = 0; plane < 4; plane++)
for (uint32_t e = 0; e < num_entries; e++)
planed[plane * num_entries + e] = pSrc[e * 4 + plane];
blob_writer.put_bytes(cBlobStripeSeekTable, planed.data(), planed.size());
}
xbc7_header hdr;
clear_obj(hdr);
hdr.m_dct_q = (uint8_t)opts.m_dct_q;
hdr.m_flags = 0;
if (has_alpha)
hdr.m_flags = hdr.m_flags | (uint8_t)XBC7_FLAG_HAS_ALPHA;
hdr.m_width_in_texels = orig_img.get_width();
hdr.m_height_in_texels = orig_img.get_height();
hdr.m_num_stripes = (uint8_t)num_stripes;
blob_writer.put_bytes(cBlobHeader, &hdr, sizeof(hdr));
for (uint32_t id = 0; id < BLOB_STREAM_MAX_IDS; id++)
{
stats.m_blob_raw_size[id] = (uint32_t)blob_writer.get_blob_size(id);
stats.record_blob_bytes(id, blob_writer.get_blob_data(id));
}
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: serializing + Zstd compressing blobs...\n");
if (!blob_writer.serialize(comp_bytes, 19, stats.m_blob_stored_size))
return false;
stats.m_total_file_size = comp_bytes.size_u32();
if (opts.m_debug_output && (opts.m_ac_trunc_rdo_max_psnr_drop > 0.0f))
fmt_debug_printf("AC-trunc RDO: {} coeffs pruned across {} blocks ({.2}% of blocks)\n",
stats.m_ac_trunc_pruned, stats.m_ac_trunc_blocks, total_blocks ? (stats.m_ac_trunc_blocks * 100.0f / (float)total_blocks) : 0.0f);
// m_debug_output is the master gate; m_print_stats selects the dashboard
if (opts.m_debug_output && opts.m_print_stats)
stats.print();
if (pCoded_log_blocks)
{
for (uint32_t by = 0; by < num_blocks_y; by++)
{
for (uint32_t bx = 0; bx < num_blocks_x; bx++)
{
if (!basist::bc7u::compare_block_full((*pCoded_log_blocks)(bx, by), log_blks(bx, by)))
{
assert(0);
return false;
}
}
}
}
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: tiny-mip size check...\n");
// Tiny-mip fallback: for the smallest levels the blob container's fixed
// overhead can exceed a raw packed-BC7 encoding. If a tiny-mip stream --
// [marker][num_blocks_x:u8][num_blocks_y:u8] followed by 16 bytes per BC7
// block -- is smaller (and the block dims fit a byte), emit that instead.
// The decoder distinguishes streams by the leading byte: 0xB7 = blob,
// 0xB8 = tiny-mip without alpha, 0xB9 = tiny-mip with alpha (so the
// has_alpha bit rides in the marker). The packed blocks are the FINAL
// logical blocks (identical to pCoded_log_blocks), so the decode round-
// trips exactly (pack<->unpack of a logical block is lossless).
if ((num_blocks_x <= 255) && (num_blocks_y <= 255))
{
const size_t tiny_size = 3 + (size_t)total_blocks * 16;
const uint32_t blob_size = comp_bytes.size_u32();
if (tiny_size < (size_t)blob_size)
{
comp_bytes.resize(0);
comp_bytes.reserve((uint32_t)tiny_size);
comp_bytes.push_back(has_alpha ? (uint8_t)0xB9 : (uint8_t)0xB8); // marker carries the alpha bit
comp_bytes.push_back((uint8_t)num_blocks_x);
comp_bytes.push_back((uint8_t)num_blocks_y);
for (uint32_t by = 0; by < num_blocks_y; by++)
{
for (uint32_t bx = 0; bx < num_blocks_x; bx++)
{
basist::bc7u::phys_bc7_block phys;
if (!basist::bc7u::pack_bc7(log_blks(bx, by), &phys))
{
assert(0);
return false;
}
comp_bytes.append(phys.m_bytes, sizeof(phys.m_bytes));
// The tiny-mip decoder reconstructs each block by UNPACKING
// the stored physical block. BC7 pack<->unpack is pixel-
// lossless but can re-canonicalize the LOGICAL fields
// (endpoint swap + weight complement -> identical pixels,
// different struct). So the coded reference must be the
// unpacked form -- exactly what the decoder will yield --
// not the original log_blks, or a per-block logical compare
// would spuriously fail.
if (pCoded_log_blocks)
{
if (!basist::bc7u::unpack_bc7(&phys, (*pCoded_log_blocks)(bx, by)))
{
assert(0);
return false;
}
}
}
}
assert(comp_bytes.size() == tiny_size);
if (opts.m_debug_output)
fmt_debug_printf("XBC7 tiny-mip selected: {} blocks, {} bytes (blob path was {} bytes)\n",
total_blocks, comp_bytes.size_u32(), blob_size);
}
}
if (opts.m_debug_output)
fmt_debug_printf("XBC7 output: {} bytes, {} bits/pixel\n",
comp_bytes.size_u32(), ((float)comp_bytes.size() * 8.0f) / (float)orig_img.get_total_pixels());
// Self-validation (opts.m_self_validate, ON by default): decode the stream we
// just produced through the transcoder and verify EVERY logical BC7 block
// round-trips exactly to the coded reference (coded_log_blocks). This
// guarantees that every emitted XBC7 stream is valid and unpacks correctly
// during encoding. It exercises whichever stream format was written above --
// the blob format or the tiny-mip format (coded_log_blocks already holds the
// form the decoder yields in each case, including the tiny-mip's
// re-canonicalized blocks).
if (opts.m_self_validate)
{
if (opts.m_debug_output)
fmt_debug_printf("XBC7 progress: decode self-validation...\n");
struct verify_ctx
{
const vector2D<basist::bc7u::log_bc7_block>* m_pRef;
uint32_t m_expected_nbx, m_expected_nby;
bool m_dims_ok;
bool m_blocks_ok;
} vctx;
vctx.m_pRef = &coded_log_blocks;
vctx.m_expected_nbx = num_blocks_x;
vctx.m_expected_nby = num_blocks_y;
vctx.m_dims_ok = true;
vctx.m_blocks_ok = true;
auto verify_init_cb = [](uint32_t nbx, uint32_t nby, uint32_t, uint32_t, uint32_t, bool, void* pData) -> bool
{
verify_ctx& c = *(verify_ctx*)pData;
if ((nbx != c.m_expected_nbx) || (nby != c.m_expected_nby))
{
c.m_dims_ok = false;
return false; // abort decode: dimensions disagree with what we encoded
}
return true;
};
auto verify_block_cb = [](uint32_t bx, uint32_t by, const basist::bc7u::log_bc7_block& decoded_blk, void* pData) -> bool
{
verify_ctx& c = *(verify_ctx*)pData;
if (!basist::bc7u::compare_block_full((*c.m_pRef)(bx, by), decoded_blk))
{
c.m_blocks_ok = false;
return false; // abort decode: a block did not round-trip
}
return true;
};
const bool decode_ok = basist::xbc7::unpack_image(
basist::xbc7::byte_span(comp_bytes),
verify_init_cb, &vctx,
verify_block_cb, &vctx);
if ((!decode_ok) || (!vctx.m_dims_ok) || (!vctx.m_blocks_ok))
{
assert(0 && "XBC7 pack_image: encoded stream failed decode self-validation");
fmt_error_printf("XBC7 pack_image: SELF-VALIDATION FAILED -- the encoded stream did not decode back to the expected BC7 logical blocks (decode_ok={}, dims_ok={}, blocks_ok={})\n",
decode_ok, vctx.m_dims_ok, vctx.m_blocks_ok);
return false;
}
if (opts.m_debug_output)
fmt_debug_printf("XBC7 self-validation: decode round-trip OK ({} blocks)\n", total_blocks);
}
return true;
#endif // BASISD_SUPPORT_KTX2_ZSTD
}
} // namespace xbc7
} // namespace basisu