Scarfski/basis_universal
1
0
Fork 0
mirror of https://github.com/BinomialLLC/basis_universal.git synced 2026-07-12 17:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
b50b394845bfecb5ed72f005d3eedcd7fefe1341
basis_universal/transcoder/basisu_xbc7_decoder.inl
Richard Geldreich 069e065454 formatting fix
2026-07-01 23:43:00 -04:00

1516 lines
53 KiB
C++
Raw Blame History

// File: basisu_xbc7_decoder.inl
// XBC7 decoder implementation. #included at the END of basisu_transcoder.cpp
// (the transcoder stays a single .cpp). Declarations live in
// basisu_xbc7_decoder.h. Decoding REQUIRES zstd (BASISD_SUPPORT_KTX2_ZSTD); when
// that is disabled the public entry points fail with an error.
namespace basist {
namespace xbc7 {
bool eval_weight_predictor(
uint32_t cand_index, uint32_t amp_code,
uint32_t bx, uint32_t by, uint32_t num_blocks_x,
const tile_bounds& tile, // every block reference is clamped to this AABB (encoder: the job's tile; decoder: whole image)
const vector2D<basist::bc7u::log_bc7_block>& log_blks,
uint32_t p, int pOut_preds[16])
{
BASISU_NOTE_UNUSED(num_blocks_x); // bounds now come from the tile
assert(cand_index != cCandAbsolute);
assert(cand_index < cTotalCandidates);
assert(amp_code < 4);
assert(tile.contains((int)bx, (int)by));
auto fetch_w = [](const basist::bc7u::log_bc7_block* pBlk, uint32_t plane, uint32_t w) -> int
{
const uint32_t sp = pBlk->is_dual_plane() ? plane : 0;
return basist::bc7u::dequant_weight(pBlk->m_weights[sp][w], pBlk->m_weight_bits[sp]);
};
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;
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_log_blk = tile.contains((int)bx - 1, (int)by) ? &log_blks(bx - 1, by) : nullptr;
const basist::bc7u::log_bc7_block* pCand_log_blk = nullptr;
if (cand_index == cCandAbsolute)
{
}
else if (cand_index >= cCandFirstXYDelta)
{
// generic causal block reference (copy); subsumes the old
// left/up/left-diag/right-diag copy candidates
const xbc7_xy_delta& delta = g_xbc7_xy_deltas[cand_index - cCandFirstXYDelta];
const int nx = (int)bx + delta.m_dx;
const int ny = (int)by + delta.m_dy;
if (tile.contains(nx, ny))
pCand_log_blk = &log_blks(nx, ny);
if (!pCand_log_blk)
return false;
}
else
{
if (cand_index == cCandLeftEdge)
pCand_log_blk = pLeft_log_blk; // left edge
else if (cand_index == cCandUpperEdge)
pCand_log_blk = pUp_log_blk; // upper edge
else if (cand_index == cCandLUBlend)
pCand_log_blk = (pLeft_log_blk && pUp_log_blk) ? pLeft_log_blk : nullptr; // left+upper edge blend
else if (cand_index == cCandReflectLeft)
pCand_log_blk = pLeft_log_blk; // reflect left
else if (cand_index == cCandReflectUpper)
pCand_log_blk = pUp_log_blk; // reflect upper
else if (cand_index == cCandLUAvg)
pCand_log_blk = (pLeft_log_blk && pUp_log_blk) ? pLeft_log_blk : nullptr; // left+upper edge avg
else if (cand_index == cCandLUBlendStrong)
pCand_log_blk = (pLeft_log_blk && pUp_log_blk) ? pLeft_log_blk : nullptr; // left+upper edge stronger distance blend
else if (cand_index == cCandGradient)
pCand_log_blk = (pLeft_log_blk && pUp_log_blk && pLeft_diag_log_blk) ? pLeft_log_blk : nullptr; // gradient
else if (cand_index == cCandGradientDamped)
pCand_log_blk = (pLeft_log_blk && pUp_log_blk && pLeft_diag_log_blk) ? pLeft_log_blk : nullptr; // damped gradient
else if (cand_index == cCandDiagAvg)
pCand_log_blk = (pLeft_diag_log_blk && pRight_diag_log_blk) ? pLeft_diag_log_blk : nullptr; // left/right diagonal avg
else if (cand_index == cCandDiagEdgeBlend)
pCand_log_blk = (pLeft_diag_log_blk && pRight_diag_log_blk) ? pLeft_diag_log_blk : nullptr; // diagonal edge blend
else if (cand_index == cCandUpperDiagEdgeBlend)
pCand_log_blk = (pUp_log_blk && pLeft_diag_log_blk && pRight_diag_log_blk) ? pLeft_diag_log_blk : nullptr; // upper + diagonal edge blend
else if ((cand_index == cCandMED) || (cand_index == cCandGAB))
pCand_log_blk = (pLeft_log_blk && pUp_log_blk && pLeft_diag_log_blk) ? pLeft_log_blk : nullptr; // MED / gradient-adaptive blend
else if (cand_index == cCandPlaneFit)
pCand_log_blk = (pLeft_log_blk && pUp_log_blk) ? pLeft_log_blk : nullptr; // LS plane fit
else if ((cand_index == cCandDDL) && pUp_log_blk && pRight_diag_log_blk)
pCand_log_blk = pUp_log_blk;
else if (cand_index == cCandDDR)
pCand_log_blk = (pLeft_log_blk && pUp_log_blk && pLeft_diag_log_blk) ? pLeft_log_blk : nullptr;
if (!pCand_log_blk)
return false;
}
int* pWeight_predictions = nullptr;
int weight_preds[16];
if (pCand_log_blk)
{
for (uint32_t w = 0; w < 16; w++)
{
weight_preds[w] = fetch_w(pCand_log_blk, p, w);
}
int orig_weight_preds[16];
memcpy(orig_weight_preds, weight_preds, sizeof(orig_weight_preds));
if (cand_index == cCandLeftEdge)
{
// left edge
for (uint32_t y = 0; y < 4; y++)
for (uint32_t x = 0; x < 4; x++)
weight_preds[index_from_xy(x, y)] = orig_weight_preds[index_from_xy(3, y)];
}
else if (cand_index == cCandUpperEdge)
{
// upper edge
for (uint32_t y = 0; y < 4; y++)
for (uint32_t x = 0; x < 4; x++)
weight_preds[index_from_xy(x, y)] = orig_weight_preds[index_from_xy(x, 3)];
}
else if ((cand_index == cCandLUBlend) || (cand_index == cCandLUAvg) || (cand_index == cCandLUBlendStrong))
{
// left+upper edge blend variants.
// pCand_log_blk is pLeft_log_blk here, so orig_weight_preds contains the left block.
// Pull upper edge directly from pUp_log_blk.
int upper_edge[4];
for (uint32_t x = 0; x < 4; x++)
{
const uint32_t w = index_from_xy(x, 3); // upper block's bottom edge
upper_edge[x] = fetch_w(pUp_log_blk, p, w);
}
for (uint32_t y = 0; y < 4; y++)
{
const int left_val = orig_weight_preds[index_from_xy(3, y)]; // left block's right edge
for (uint32_t x = 0; x < 4; x++)
{
const int upper_val = upper_edge[x];
int pred;
if (cand_index == cCandLUBlend)
{
// Existing distance-weighted blend.
const int wl = 4 - static_cast<int>(x); // 4,3,2,1
const int wu = 4 - static_cast<int>(y); // 4,3,2,1
const int den = wl + wu;
pred = (wl * left_val + wu * upper_val + (den >> 1)) / den;
}
else if (cand_index == cCandLUAvg)
{
// Simple average.
pred = (left_val + upper_val + 1) >> 1;
}
else // cCandLUBlendStrong
{
// Stronger distance weighting: trust the nearest edge more.
const int dx = 4 - static_cast<int>(x); // 4,3,2,1
const int dy = 4 - static_cast<int>(y); // 4,3,2,1
const int wl = dx * dx; // 16,9,4,1
const int wu = dy * dy; // 16,9,4,1
const int den = wl + wu;
pred = (wl * left_val + wu * upper_val + (den >> 1)) / den;
}
weight_preds[index_from_xy(x, y)] = pred;
}
}
}
else if (cand_index == cCandReflectLeft)
{
// reflect left
for (uint32_t y = 0; y < 4; y++)
for (uint32_t x = 0; x < 4; x++)
weight_preds[index_from_xy(x, y)] = orig_weight_preds[index_from_xy(3 - x, y)];
}
else if (cand_index == cCandReflectUpper)
{
// reflect upper
for (uint32_t y = 0; y < 4; y++)
for (uint32_t x = 0; x < 4; x++)
weight_preds[index_from_xy(x, y)] = orig_weight_preds[index_from_xy(x, 3 - y)];
}
else if ((cand_index == cCandGradient) || (cand_index == cCandGradientDamped) || (cand_index == cCandMED) || (cand_index == cCandGAB))
{
int upper_edge[4];
for (uint32_t x = 0; x < 4; x++)
{
const uint32_t w = index_from_xy(x, 3); // upper block's bottom edge
upper_edge[x] = fetch_w(pUp_log_blk, p, w);
}
const uint32_t corner_w = index_from_xy(3, 3); // upper-left block's bottom-right
int corner_val;
corner_val = fetch_w(pLeft_diag_log_blk, p, corner_w);
for (uint32_t y = 0; y < 4; y++)
{
const int left_val = orig_weight_preds[index_from_xy(3, y)]; // left block's right edge
for (uint32_t x = 0; x < 4; x++)
{
const int upper_val = upper_edge[x];
if (cand_index == cCandGradient)
{
int grad = left_val + upper_val - corner_val;
grad = basisu::clamp<int>(grad, 0, 64);
weight_preds[index_from_xy(x, y)] = grad;
}
else if (cand_index == cCandGradientDamped)
{
int grad = left_val + upper_val - corner_val;
grad = basisu::clamp<int>(grad, 0, 64);
// Damped gradient: blend gradient with the proven #7 predictor.
const int wl = 4 - static_cast<int>(x);
const int wu = 4 - static_cast<int>(y);
const int den = wl + wu;
const int blend7 = (wl * left_val + wu * upper_val + (den >> 1)) / den;
weight_preds[index_from_xy(x, y)] = (grad + blend7 + 1) >> 1;
}
else if (cand_index == cCandMED)
{
// MED (Median Edge Detector, JPEG-LS / LOCO-I).
// Plane predictor wrapped in a per-sample edge switch:
// if the corner is the local extreme, an edge passes
// between the neighbors -- predict from the neighbor on
// the current sample's side instead of extrapolating
// through the edge (which is #12's overshoot failure).
const int mn = basisu::minimum(left_val, upper_val);
const int mx = basisu::maximum(left_val, upper_val);
int pred;
if (corner_val >= mx)
pred = mn;
else if (corner_val <= mn)
pred = mx;
else
pred = left_val + upper_val - corner_val; // in (mn, mx) here, cannot overshoot
weight_preds[index_from_xy(x, y)] = basisu::clamp<int>(pred, 0, 64);
}
else // cCandGAB
{
// GAB: gradient-adaptive blend (CALIC-spirit, 3 samples).
// |left-corner| large => a horizontal edge crossed between
// the corner row and this row, so the left sample is on the
// current sample's side of it: trust it more. Symmetrically
// for |upper-corner| and vertical edges. A self-normalizing
// soft MED whose weights come from the data, not position.
const int wl = basisu::iabs(left_val - corner_val) + 1;
const int wu = basisu::iabs(upper_val - corner_val) + 1;
const int den = wl + wu;
const int pred = (wl * left_val + wu * upper_val + (den >> 1)) / den;
weight_preds[index_from_xy(x, y)] = pred; // convex blend of in-range values: already in [0,64]
}
}
}
}
else if (cand_index == cCandDiagAvg)
{
// Average upper-left and upper-right diagonal blocks.
// pCand_log_blk is pLeft_diag_log_blk here, so orig_weight_preds contains upper-left.
// Pull upper-right directly from pRight_diag_log_blk.
for (uint32_t w = 0; w < 16; w++)
{
int right_diag_val;
right_diag_val = fetch_w(pRight_diag_log_blk, p, w);
weight_preds[w] = (orig_weight_preds[w] + right_diag_val + 1) >> 1;
}
}
else if (cand_index == cCandDiagEdgeBlend)
{
// Blend upper-left block's right edge with upper-right block's left edge.
// pCand_log_blk is pLeft_diag_log_blk, so orig_weight_preds contains upper-left.
// Pull upper-right left edge directly from pRight_diag_log_blk.
//
// For each row y:
// L = upper-left[3,y]
// R = upper-right[0,y]
// Then interpolate across x.
int right_diag_left_edge[4];
for (uint32_t y = 0; y < 4; y++)
{
const uint32_t w = index_from_xy(0, y); // upper-right block's left edge
right_diag_left_edge[y] = fetch_w(pRight_diag_log_blk, p, w);
}
for (uint32_t y = 0; y < 4; y++)
{
const int left_val = orig_weight_preds[index_from_xy(3, y)]; // upper-left right edge
const int right_val = right_diag_left_edge[y]; // upper-right left edge
for (uint32_t x = 0; x < 4; x++)
{
// x=0 mostly left_val, x=3 mostly right_val.
// Use 4-sample interpolation: 3/0, 2/1, 1/2, 0/3.
const int pred = ((3 - static_cast<int>(x)) * left_val +
static_cast<int>(x) * right_val + 1) / 3;
weight_preds[index_from_xy(x, y)] = pred;
}
}
}
else if (cand_index == cCandUpperDiagEdgeBlend)
{
// Blend upper edge predictor with diagonal edge blend.
//
// upper_edge[x] = upper block's bottom edge
// diag_blend[x,y] = horizontal interpolation between:
// upper-left block's right edge and upper-right block's left edge
//
// This combines direct top continuation with previous-row lateral structure.
int upper_edge[4];
int right_diag_left_edge[4];
for (uint32_t x = 0; x < 4; x++)
{
const uint32_t up_w = index_from_xy(x, 3); // upper block's bottom edge
upper_edge[x] = fetch_w(pUp_log_blk, p, up_w);
}
for (uint32_t y = 0; y < 4; y++)
{
const uint32_t rd_w = index_from_xy(0, y); // upper-right block's left edge
right_diag_left_edge[y] = fetch_w(pRight_diag_log_blk, p, rd_w);
}
for (uint32_t y = 0; y < 4; y++)
{
const int left_diag_right_val = orig_weight_preds[index_from_xy(3, y)]; // upper-left right edge
const int right_diag_left_val = right_diag_left_edge[y];
for (uint32_t x = 0; x < 4; x++)
{
// Same as #15: lateral predictor from upper-left/right diagonal edges.
const int diag_blend =
((3 - static_cast<int>(x)) * left_diag_right_val +
static_cast<int>(x) * right_diag_left_val + 1) / 3;
// Same as #6: direct upper edge replicated downward.
const int up_val = upper_edge[x];
// Trust upper edge more near y=0, trust diagonal lateral structure more lower in the block.
const int wu = 4 - static_cast<int>(y); // 4,3,2,1
const int wd = 1 + static_cast<int>(y); // 1,2,3,4
const int den = wu + wd; // always 5
weight_preds[index_from_xy(x, y)] =
(wu * up_val + wd * diag_blend + (den >> 1)) / den;
}
}
}
else if (cand_index == cCandPlaneFit)
{
// LS plane fit through left + upper edges.
// pCand_log_blk is pLeft_log_blk, so orig_weight_preds holds the left block.
int upper_edge[4];
for (uint32_t x = 0; x < 4; x++)
{
const uint32_t w = index_from_xy(x, 3); // upper block's bottom edge
upper_edge[x] = fetch_w(pUp_log_blk, p, w);
}
int left_edge[4];
for (uint32_t y = 0; y < 4; y++)
left_edge[y] = orig_weight_preds[index_from_xy(3, y)]; // left block's right edge
const int sum_u = upper_edge[0] + upper_edge[1] + upper_edge[2] + upper_edge[3];
const int sum_l = left_edge[0] + left_edge[1] + left_edge[2] + left_edge[3];
// LS slopes * 10
const int gx10 = -3 * upper_edge[0] - upper_edge[1] + upper_edge[2] + 3 * upper_edge[3];
const int gy10 = -3 * left_edge[0] - left_edge[1] + left_edge[2] + 3 * left_edge[3];
const int base = 5 * (sum_u + sum_l); // mean*40, anchored at edge centroid (.25,.25)
for (uint32_t y = 0; y < 4; y++)
{
for (uint32_t x = 0; x < 4; x++)
{
const int num = base + gx10 * (4 * (int)x - 1) + gy10 * (4 * (int)y - 1);
// round-half-up = floor((num + 20) / 40); numerator can be negative
// (negative slopes), and C++ '/' truncates toward zero, so force floor.
const int t = num + 20;
const int pred_unclamped = (t >= 0) ? (t / 40) : -((-t + 39) / 40);
weight_preds[index_from_xy(x, y)] = basisu::clamp<int>(pred_unclamped, 0, 64);
}
}
}
else if (cand_index == cCandDDL)
{
// Diagonal-down-left (H.264 4x4 intra mode 3 analog): propagate the
// extended top row (upper block's bottom edge + upper-RIGHT block's
// bottom edge) down-left at 45 degrees, with 1-2-1 smoothing along the
// diagonal. Captures 45-degree edges/stripes entering from the top-right
// quadrant -- a direction nothing else in the bank can represent.
// pCand_log_blk is pUp_log_blk; requires pRight_diag_log_blk.
int T[8];
for (uint32_t x = 0; x < 4; x++)
{
const uint32_t w = index_from_xy(x, 3);
T[x] = fetch_w(pUp_log_blk, p, w);
T[4 + x] = fetch_w(pRight_diag_log_blk, p, w);
}
for (uint32_t y = 0; y < 4; y++)
{
for (uint32_t x = 0; x < 4; x++)
{
const uint32_t d = x + y; // 0..6
int pred;
if (d == 6)
pred = (T[6] + 3 * T[7] + 2) >> 2;
else
pred = (T[d] + 2 * T[d + 1] + T[d + 2] + 2) >> 2;
weight_preds[index_from_xy(x, y)] = pred; // smoothed avg of [0,64] values: in range
}
}
}
else if (cand_index == cCandDDR)
{
// Diagonal-down-right (H.264 4x4 intra mode 4 analog): propagate at 45
// degrees from the top-left, sourcing the left column, the corner, and
// the top row, 1-2-1 smoothed. Captures 45-degree structure entering
// from the top-left quadrant.
// pCand_log_blk is pLeft_log_blk; requires pUp_log_blk and pLeft_diag_log_blk.
// A[0..8]: A[0..3] = left column bottom-to-top, A[4] = corner, A[5..8] = top row.
int A[9];
for (uint32_t y = 0; y < 4; y++)
A[3 - y] = orig_weight_preds[index_from_xy(3, y)]; // left block's right edge, reversed
{
const uint32_t cw = index_from_xy(3, 3);
A[4] = fetch_w(pLeft_diag_log_blk, p, cw);
}
for (uint32_t x = 0; x < 4; x++)
{
const uint32_t w = index_from_xy(x, 3);
A[5 + x] = fetch_w(pUp_log_blk, p, w);
}
for (uint32_t y = 0; y < 4; y++)
{
for (uint32_t x = 0; x < 4; x++)
{
const int d = 4 + (int)x - (int)y; // 1..7; texels on diagonal k share A-index k
const int pred = (A[d - 1] + 2 * A[d] + A[d + 1] + 2) >> 2;
weight_preds[index_from_xy(x, y)] = pred;
}
}
}
pWeight_predictions = weight_preds;
}
if ((amp_code) && (pWeight_predictions))
{
// Amplitude code: generalization of the old inversion flag.
// All transforms are about the prediction's own mean (per
// plane), so they negate/scale the ACs while leaving the DC
// for the DC coefficient -- the old 64-w flip also
// complemented the DC, forcing a DC correction symbol
// whenever the content mean wasn't complementary.
int sum = 0;
for (uint32_t i = 0; i < 16; i++)
sum += pWeight_predictions[i];
const int mean = (sum + 8) >> 4;
for (uint32_t i = 0; i < 16; i++)
{
const int w = pWeight_predictions[i];
int v;
if (amp_code == 1)
{
// flip about mean (s = -1): pure AC negation
v = basisu::clamp<int>(2 * mean - w, 0, 64);
//v = 64 - w;
}
else if (amp_code == 2)
{
// half contrast (s = +1/2): mean + (w - mean)/2, half-up
v = (w + mean + 1) >> 1; // closed in [0,64], no clamp needed
}
else // amp_code == 3
{
// half contrast of the flip (s = -1/2): compose 1 then 2
const int f = basisu::clamp<int>(2 * mean - w, 0, 64);
v = (f + mean + 1) >> 1;
}
pWeight_predictions[i] = v;
}
}
if (!pWeight_predictions)
return false;
memcpy(pOut_preds, pWeight_predictions, 16 * sizeof(int));
return true;
}
static inline int unpack_coeff_b(uint32_t v)
{
assert(v <= 255);
return (int)v;
}
// LSB-first bit reader matching basisu::bitwise_coder's packing exactly
// (first bit written lands in bit 0 of byte 0; values may cross byte
// boundaries). Total: reads past the end return false.
struct lsb_bit_reader
{
const uint8_t* m_p = nullptr;
uint64_t m_total_bits = 0;
uint64_t m_bit_ofs = 0;
void init(const uint8_t* p, size_t size_bytes) { m_p = p; m_total_bits = (uint64_t)size_bytes * 8; m_bit_ofs = 0; }
// seek to a bit range [start_bit, end_bit) within the blob -- used for
// per-stripe decoding (the stripe's bits occupy exactly this range)
void init_range(const uint8_t* p, uint64_t start_bit, uint64_t end_bit) { m_p = p; m_bit_ofs = start_bit; m_total_bits = end_bit; }
bool get_bits(uint32_t n, uint32_t& v)
{
assert(n <= 32);
v = 0;
if (n > (m_total_bits - m_bit_ofs))
return false;
if (!n)
return true;
const uint64_t byte_idx = m_bit_ofs >> 3;
const uint32_t bit_idx = (uint32_t)(m_bit_ofs & 7);
const uint32_t num_bytes = (bit_idx + n + 7) >> 3; // 1..5
uint64_t bits = 0;
for (uint32_t i = 0; i < num_bytes; i++)
bits |= ((uint64_t)m_p[byte_idx + i]) << (i * 8);
v = (uint32_t)((bits >> bit_idx) & ((1ull << n) - 1ull));
m_bit_ofs += n;
return true;
}
// at most 7 zero pad bits may remain
bool is_fully_consumed() const { return (m_total_bits - m_bit_ofs) < 8; }
};
// forward byte cursor over one blob; total
struct byte_cursor
{
const uint8_t* m_p = nullptr;
uint32_t m_size = 0, m_ofs = 0;
void init(const blob_stream_reader& rdr, uint32_t id) { m_p = rdr.get_ptr(id); m_size = rdr.get_size(id); m_ofs = 0; }
// seek to a byte range [start, end) within the blob -- per-stripe decode
void init_range(const blob_stream_reader& rdr, uint32_t id, uint32_t start, uint32_t end) { m_p = rdr.get_ptr(id); m_ofs = start; m_size = end; }
bool get(uint8_t& b) { if (m_ofs >= m_size) return false; b = m_p[m_ofs++]; return true; }
bool is_fully_consumed() const { return m_ofs == m_size; }
};
bool blob_stream_reader::init_internal(const void* pData, size_t data_size, uint64_t max_total_uncomp)
{
clear();
const uint8_t* pBytes = static_cast<const uint8_t*>(pData);
if ((!pBytes) || (data_size < 3)) // magic + count + magic minimum
return false;
uint64_t ofs = 0;
if (pBytes[ofs++] != BLOB_STREAM_MAGIC_BEGIN)
return false;
const uint32_t num_blobs = pBytes[ofs++];
// pass 1: walk + validate the directory, total the arena size
struct entry { uint32_t id, uncomp_size, stored_size; uint64_t data_ofs; };
entry entries[255];
uint64_t total_arena = 0;
for (uint32_t i = 0; i < num_blobs; i++)
{
if (ofs >= data_size)
return false;
entry& e = entries[i];
const uint8_t id_flag = pBytes[ofs++];
e.id = id_flag & 0x7Fu;
const bool compressed = (id_flag & 0x80u) != 0;
if (!read_varint(pBytes, data_size, ofs, e.uncomp_size))
return false;
e.stored_size = 0;
if (compressed)
{
if (!read_varint(pBytes, data_size, ofs, e.stored_size))
return false;
if (!e.stored_size)
return false;
}
e.data_ofs = ofs;
if (!e.uncomp_size)
return false; // empty blobs are never stored
if (m_sizes[e.id] || m_ptrs[e.id])
return false; // duplicate id
const uint64_t stored_bytes = e.stored_size ? e.stored_size : e.uncomp_size;
if ((ofs + stored_bytes) > data_size)
return false;
ofs += stored_bytes;
if (e.stored_size)
{
if (e.stored_size >= e.uncomp_size)
return false; // compressed must be strictly smaller (writer guarantees it)
total_arena += e.uncomp_size;
if (total_arena > max_total_uncomp)
return false;
}
// mark id as seen (real ptr/size set in pass 2)
m_sizes[e.id] = e.uncomp_size;
m_ptrs[e.id] = pBytes; // placeholder, nonzero for dup detection
}
// end marker must be the exact final byte: rejects truncation,
// trailing garbage, and directory/data length disagreements
if ((ofs != (data_size - 1)) || (pBytes[ofs] != BLOB_STREAM_MAGIC_END))
return false;
// pass 2: single arena allocation, decompress, wire up pointers
if (!m_arena.try_resize((size_t)total_arena))
return false;
uint64_t arena_ofs = 0;
for (uint32_t i = 0; i < num_blobs; i++)
{
const entry& e = entries[i];
if (!e.stored_size)
{
m_ptrs[e.id] = pBytes + e.data_ofs; // raw: zero copy into input
}
else
{
uint8_t* pDst = m_arena.data() + arena_ofs;
#if BASISD_SUPPORT_KTX2_ZSTD
const size_t res = ZSTD_decompress(pDst, e.uncomp_size, pBytes + e.data_ofs, e.stored_size);
if (ZSTD_isError(res) || (res != e.uncomp_size))
return false;
#else
BASISU_NOTE_UNUSED(pDst);
return false; // zstd disabled at compile time
#endif
m_ptrs[e.id] = pDst;
arena_ofs += e.uncomp_size;
}
}
return true;
}
bool image_unpacker::init(
const byte_span& comp,
decode_init_callback_ptr pInit_callback, void* pInit_callback_data,
decode_block_callback_ptr pBlock_callback, void* pBlock_callback_data)
{
m_initialized = false; // set true ONLY on full success below; every failure path leaves it false
m_tiny_mip = false;
m_block_cb = pBlock_callback;
m_block_data = pBlock_callback_data;
#if !BASISD_SUPPORT_KTX2_ZSTD
BASISU_DEVEL_ERROR("xbc7::unpack_image: XBC7 decoding requires zstd (BASISD_SUPPORT_KTX2_ZSTD is 0)");
return false;
#endif
// ---- format dispatch on the leading byte ----
// 0xB7 = blob container (blob_stream_reader validates this marker itself).
// 0xB8/0xB9 = tiny-mip ([marker][num_blocks_x:u8][num_blocks_y:u8] then 16
// bytes per packed BC7 block); 0xB8 = no alpha, 0xB9 = has alpha
// (the has_alpha bit rides in the marker). Anything else: not XBC7.
if (comp.size() < 1)
return false;
#ifndef NDEBUG
// Debug builds: report the input buffer size and the stream type.
{
const char* pType = "regular (blob)";
if (comp[0] == 0xB8)
pType = "tiny-mip (no alpha)";
else if (comp[0] == 0xB9)
pType = "tiny-mip (alpha)";
else if (comp[0] != BLOB_STREAM_MAGIC_BEGIN)
pType = "unknown / invalid marker";
fmt_debug_printf("XBC7 decode: input {} bytes, type: {}\n", (uint64_t)comp.size(), pType);
}
#endif
if ((comp[0] == 0xB8) || (comp[0] == 0xB9))
return init_tiny_mip(comp, comp[0] == 0xB9, pInit_callback, pInit_callback_data);
if (comp[0] != BLOB_STREAM_MAGIC_BEGIN)
return false; // unknown format marker
if (!m_rdr.init(comp.data(), comp.size()))
return false;
// ---- header ----
if (m_rdr.get_size(cBlobHeader) != sizeof(xbc7_header))
return false;
xbc7_header hdr;
memcpy((void *)&hdr, m_rdr.get_ptr(cBlobHeader), sizeof(hdr));
const uint32_t width = hdr.m_width_in_texels;
const uint32_t height = hdr.m_height_in_texels;
m_global_q = hdr.m_dct_q;
if ((!width) || (!height))
return false;
const uint32_t XBC7_MAX_SUPPORTED_DIM = 16384;
if ((width > XBC7_MAX_SUPPORTED_DIM) || (height > XBC7_MAX_SUPPORTED_DIM))
return false;
if ((m_global_q < 1) || (m_global_q > 100))
return false;
if (hdr.m_flags & ~XBC7_FLAG_HAS_ALPHA)
return false; // unknown flags
m_width = width;
m_height = height;
m_has_alpha = (hdr.m_flags & XBC7_FLAG_HAS_ALPHA) != 0;
m_num_blocks_x = (width + 3) / 4;
m_num_blocks_y = (height + 3) / 4;
const uint32_t total_blocks = m_num_blocks_x * m_num_blocks_y; // <= 16384^2, no overflow
// ---- stripe geometry (also governs the implicit solid-block clamp) ----
m_num_stripes = hdr.m_num_stripes;
if ((!m_num_stripes) || (m_num_stripes > m_num_blocks_y))
return false;
if (m_num_stripes > XBC7_MAX_ENCODER_STRIPES)
return false;
compute_stripe_ranges(m_num_blocks_y, m_num_stripes, m_stripes);
// ---- paranoia gate: structural size check BEFORE any allocation ----
// One command byte per block makes this a necessary condition and
// transitively bounds every allocation, killing the huge-dims DoS.
if (m_rdr.get_size(cBlobCommands) != total_blocks)
return false;
// ---- per-stripe seek table ----
// m_seek(id, s) = start offset of stripe s in blob id (a BYTE offset,
// or a BIT offset for the three bit blobs); row m_num_stripes holds the
// end sentinel (blob byte size, or total bits). Stripe 0 starts at 0.
// Single-stripe files carry no table -- the whole blob is stripe 0.
const uint32_t SEEK_NUM_STREAMS = (uint32_t)cBlobStripeSeekTable - 1; // ids 1..25
m_seek.resize((uint32_t)cBlobStripeSeekTable, m_num_stripes + 1); // (id) x (stripe)
m_seek.set_all(0);
for (uint32_t id = 1; id < (uint32_t)cBlobStripeSeekTable; id++)
{
const bool bit_blob = (id == cBlobCoeffSigns) || (id == cBlobPBits) || (id == cBlobEPRaw);
m_seek(id, m_num_stripes) = bit_blob ? ((uint64_t)m_rdr.get_size(id) * 8) : (uint64_t)m_rdr.get_size(id);
}
if (m_num_stripes > 1)
{
if (m_rdr.get_size(cBlobStripeSeekTable) != m_num_stripes * SEEK_NUM_STREAMS * 4)
return false;
// Entries are DELTAS from the previous stripe's start, stripe-major,
// stored byte-plane (SoA) transposed: byte b of entry e lives at
// pT[b * num_entries + e] (the encoder's inverse of this layout).
// Reconstruct absolute offsets with a running prefix sum, validating
// as we go (all BEFORE any block decode): stripe 0's delta must be 0,
// and each running offset must stay within [0, blob_end] (blob_end =
// byte size, or total bits for the three bit blobs). Monotonicity is
// automatic -- deltas are unsigned, so the running sum never
// decreases. The range test rejects a corrupted table immediately; a
// wild byte/bit offset can never reach the cursor seek in decode_stripe.
const uint8_t* pT = m_rdr.get_ptr(cBlobStripeSeekTable);
const uint32_t num_entries = m_num_stripes * SEEK_NUM_STREAMS;
for (uint32_t id = 1; id < (uint32_t)cBlobStripeSeekTable; id++)
{
const uint64_t blob_end = m_seek(id, m_num_stripes); // sentinel set above
uint64_t running = 0;
for (uint32_t st = 0; st < m_num_stripes; st++)
{
const uint32_t e = st * SEEK_NUM_STREAMS + (id - 1);
const uint64_t delta = (uint64_t)pT[e] | ((uint64_t)pT[num_entries + e] << 8) |
((uint64_t)pT[2u * num_entries + e] << 16) | ((uint64_t)pT[3u * num_entries + e] << 24);
if ((st == 0) && (delta != 0))
return false; // stripe 0 must start at offset 0
running += delta; // unsigned add: offsets are monotonic by construction
if (running > blob_end)
return false; // offset past end of blob
m_seek(id, st) = running;
}
}
}
// ---- decode state + callbacks ----
// The decoder always maintains its own full-image logical-block buffer:
// causal prediction (endpoint DPCM / repeat / weight predictors) reads
// already-decoded neighbors. Finished blocks are streamed to the caller
// via the block callback; the caller owns any persistent storage/packing.
m_log_blks.resize(m_num_blocks_x, m_num_blocks_y);
// Hand the caller the header geometry/metadata exactly once, before any
// block, so it can validate and allocate. A false return aborts.
if (pInit_callback)
{
if (!pInit_callback(m_num_blocks_x, m_num_blocks_y, m_width, m_height, m_global_q, m_has_alpha, pInit_callback_data))
return false;
}
m_initialized = true;
return true;
}
bool image_unpacker::init_tiny_mip(
const byte_span& comp, bool has_alpha,
decode_init_callback_ptr pInit_callback, void* pInit_callback_data)
{
if (comp.size() < 3)
return false;
const uint32_t nbx = comp[1];
const uint32_t nby = comp[2];
if ((!nbx) || (!nby))
return false;
// exact-size tripwire: the 3-byte header plus exactly the BC7 blocks
const uint64_t expected = 3ull + (uint64_t)nbx * (uint64_t)nby * 16ull;
if ((uint64_t)comp.size() != expected)
return false;
m_tiny_mip = true;
// checked region pointer to all the BC7 blocks (validated once); aliases
// the span's underlying buffer, which must outlive the decoder
m_tiny_blocks = comp.checked_ptr(3, (size_t)nbx * (size_t)nby * 16); // -> first block
m_num_blocks_x = nbx;
m_num_blocks_y = nby;
m_num_stripes = 1;
m_width = nbx * 4; // block-aligned; tiny-mip stores no exact texel dims
m_height = nby * 4;
m_global_q = 0; // no DCT in tiny-mip
m_has_alpha = has_alpha; // from the stream marker (0xB8 = no alpha, 0xB9 = alpha)
if (pInit_callback)
{
if (!pInit_callback(m_num_blocks_x, m_num_blocks_y, m_width, m_height, m_global_q, m_has_alpha, pInit_callback_data))
return false;
}
m_initialized = true;
return true;
}
bool image_unpacker::decode_stripe(uint32_t stripe_index)
{
// must follow a successful init() -- guard in ALL builds (assert traps
// the bug in debug; the return false keeps release total)
assert(m_initialized && "decode_stripe() called without a successful init()");
if (!m_initialized)
return false;
assert(stripe_index < m_num_stripes);
if (stripe_index >= m_num_stripes)
return false;
// tiny-mip is a single conceptual stripe (m_num_stripes == 1): decode all
// its blocks straight from the raw BC7 data, no prediction/blobs involved.
if (m_tiny_mip)
return decode_tiny_mip();
const uint32_t first_row = m_stripes[stripe_index].m_first_block_row;
const uint32_t end_row = first_row + m_stripes[stripe_index].m_num_block_rows;
// every reference is clamped to this stripe AABB (mirrors the encoder)
const tile_bounds stripe_tile = { 0, (int)first_row, (int)m_num_blocks_x - 1, (int)end_row - 1 };
// aliases so the per-block body below resolves to member state
blob_stream_reader& rdr = m_rdr;
const uint32_t num_blocks_x = m_num_blocks_x;
const uint32_t global_q = m_global_q;
const bool has_alpha = m_has_alpha;
vector2D<basist::bc7u::log_bc7_block>& log_blks = m_log_blks;
// cursors seeked to this stripe's range [seek(id,s), seek(id,s+1))
const uint32_t s = stripe_index;
byte_cursor commands; commands.init_range(rdr, cBlobCommands, (uint32_t)m_seek(cBlobCommands, s), (uint32_t)m_seek(cBlobCommands, s + 1));
byte_cursor configs; configs.init_range(rdr, cBlobBC7BlockConfig, (uint32_t)m_seek(cBlobBC7BlockConfig, s), (uint32_t)m_seek(cBlobBC7BlockConfig, s + 1));
byte_cursor partitions2; partitions2.init_range(rdr, cBlobPartition2, (uint32_t)m_seek(cBlobPartition2, s), (uint32_t)m_seek(cBlobPartition2, s + 1));
byte_cursor partitions3; partitions3.init_range(rdr, cBlobPartition3, (uint32_t)m_seek(cBlobPartition3, s), (uint32_t)m_seek(cBlobPartition3, s + 1));
byte_cursor predictors; predictors.init_range(rdr, cBlobWeightPredictors, (uint32_t)m_seek(cBlobWeightPredictors, s), (uint32_t)m_seek(cBlobWeightPredictors, s + 1));
byte_cursor dc_coeffs; dc_coeffs.init_range(rdr, cBlobDCCoeffsSmall, (uint32_t)m_seek(cBlobDCCoeffsSmall, s), (uint32_t)m_seek(cBlobDCCoeffsSmall, s + 1)); // encoder writes ALL DC here
byte_cursor ac_coeffs; ac_coeffs.init_range(rdr, cBlobACCoeffs, (uint32_t)m_seek(cBlobACCoeffs, s), (uint32_t)m_seek(cBlobACCoeffs, s + 1));
byte_cursor solid_deltas; solid_deltas.init_range(rdr, cBlobSolidRGBADeltas, (uint32_t)m_seek(cBlobSolidRGBADeltas, s), (uint32_t)m_seek(cBlobSolidRGBADeltas, s + 1));
byte_cursor ep_block_index; ep_block_index.init_range(rdr, cBlobEPBlockIndex, (uint32_t)m_seek(cBlobEPBlockIndex, s), (uint32_t)m_seek(cBlobEPBlockIndex, s + 1));
byte_cursor raw_weights; raw_weights.init_range(rdr, cBlobRawWeightBits, (uint32_t)m_seek(cBlobRawWeightBits, s), (uint32_t)m_seek(cBlobRawWeightBits, s + 1));
byte_cursor wt_resid[3]; // DPCM weight residuals by bit width: [0]=2, [1]=3, [2]=4
wt_resid[0].init_range(rdr, cBlobDPCMWeightResid2, (uint32_t)m_seek(cBlobDPCMWeightResid2, s), (uint32_t)m_seek(cBlobDPCMWeightResid2, s + 1));
wt_resid[1].init_range(rdr, cBlobDPCMWeightResid3, (uint32_t)m_seek(cBlobDPCMWeightResid3, s), (uint32_t)m_seek(cBlobDPCMWeightResid3, s + 1));
wt_resid[2].init_range(rdr, cBlobDPCMWeightResid4, (uint32_t)m_seek(cBlobDPCMWeightResid4, s), (uint32_t)m_seek(cBlobDPCMWeightResid4, s + 1));
byte_cursor ep_deltas[8]; // [0..3] = Fine R,G,B,A; [4..7] = Coarse R,G,B,A
for (uint32_t i = 0; i < 4; i++)
{
ep_deltas[i].init_range(rdr, cBlobEPDeltaFineR + i, (uint32_t)m_seek(cBlobEPDeltaFineR + i, s), (uint32_t)m_seek(cBlobEPDeltaFineR + i, s + 1));
ep_deltas[4 + i].init_range(rdr, cBlobEPDeltaCoarseR + i, (uint32_t)m_seek(cBlobEPDeltaCoarseR + i, s), (uint32_t)m_seek(cBlobEPDeltaCoarseR + i, s + 1));
}
lsb_bit_reader coeff_signs; coeff_signs.init_range(rdr.get_ptr(cBlobCoeffSigns), m_seek(cBlobCoeffSigns, s), m_seek(cBlobCoeffSigns, s + 1));
lsb_bit_reader pbits; pbits.init_range(rdr.get_ptr(cBlobPBits), m_seek(cBlobPBits, s), m_seek(cBlobPBits, s + 1));
lsb_bit_reader ep_raw; ep_raw.init_range(rdr.get_ptr(cBlobEPRaw), m_seek(cBlobEPRaw, s), m_seek(cBlobEPRaw, s + 1));
xbc7::xbc7_weight_grid_dct_fixed weight_grid_dct_fixed;
weight_grid_dct_fixed.init();
xbc7::fxvec dct_work_fixed;
for (uint32_t by = first_row; by < end_row; by++)
{
for (uint32_t bx = 0; bx < num_blocks_x; bx++)
{
const basist::bc7u::log_bc7_block* pLeft_log_blk = stripe_tile.contains((int)bx - 1, (int)by) ? &log_blks(bx - 1, by) : nullptr;
const basist::bc7u::log_bc7_block* pUp_log_blk = stripe_tile.contains((int)bx, (int)by - 1) ? &log_blks(bx, by - 1) : nullptr;
const basist::bc7u::log_bc7_block* pLeft_diag_log_blk = stripe_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 = stripe_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);
uint8_t cmd_byte;
if (!commands.get(cmd_byte))
return false;
const uint32_t cmd = cmd_byte & 7;
const uint32_t ep_mode = (cmd_byte >> XBC7_COMMAND_ENDPOINT_MODE_SHIFT) & 7;
const uint32_t wt_mode = (cmd_byte >> XBC7_COMMAND_WEIGHT_MODE_SHIFT) & 1;
if (cmd_byte & 0x80)
return false; // P-frame flag: reserved in v0
// ---- simple commands: the whole byte is the command id ----
if (cmd <= (uint32_t)xbc7_command_id::cCmdSolidDPCM)
{
if (cmd_byte != cmd)
return false; // canonical: simple commands carry no EP/WT bits
if (cmd == (uint32_t)xbc7_command_id::cCmdRepeatLast)
{
if (!pLeft_log_blk)
return false;
log_blk = *pLeft_log_blk;
}
else if (cmd == (uint32_t)xbc7_command_id::cCmdRepeatUpper)
{
if (!pUp_log_blk)
return false;
log_blk = *pUp_log_blk;
}
else // cCmdSolidDPCM
{
// neighbor edge-average prediction in decoded-pixel space;
// mirrors the encoder exactly -- INCLUDING its stripe
// seam clamp, since this prediction is implicit (the
// encoder cannot read the stripe above, so neither may we)
int preds[4] = { 0, 0, 0, 0 };
int num_preds = 0;
if (pLeft_log_blk)
{
for (uint32_t y = 0; y < 4; y++)
{
basist::color_rgba px;
if (!basist::bc7u::unpack_bc7_texel(*pLeft_log_blk, px, 3, y))
return false;
preds[0] += px.r; preds[1] += px.g; preds[2] += px.b; preds[3] += px.a;
}
num_preds += 4;
}
if (pUp_log_blk) // pUp is already null above the stripe's first row
{
for (uint32_t x = 0; x < 4; x++)
{
basist::color_rgba px;
if (!basist::bc7u::unpack_bc7_texel(*pUp_log_blk, px, x, 3))
return false;
preds[0] += px.r; preds[1] += px.g; preds[2] += px.b; preds[3] += px.a;
}
num_preds += 4;
}
if (num_preds)
{
for (uint32_t c = 0; c < 4; c++)
preds[c] = (preds[c] + (num_preds / 2)) / num_preds;
}
basist::color_rgba solid_color;
for (uint32_t c = 0; c < (has_alpha ? 4u : 3u); c++)
{
uint8_t delta;
if (!solid_deltas.get(delta))
return false;
solid_color[c] = (uint8_t)(delta + preds[c]);
}
if (!has_alpha)
solid_color.a = 255;
basist::bc7u::create_solid_blk(log_blk, solid_color);
}
}
else
{
// ---- config ----
if (cmd == (uint32_t)xbc7_command_id::cCmdNewConfig)
{
uint8_t config_byte;
if (!configs.get(config_byte))
return false;
if (config_byte & 0xC0)
return false; // reserved bits
const uint32_t mode = config_byte & 7;
const uint32_t rot = (config_byte >> 3) & 3;
const uint32_t sel = (config_byte >> 5) & 1;
basist::bc7u::init_log_blk(log_blk, mode);
if (log_blk.m_num_planes == 2)
log_blk.m_dp_rotation_index = (uint8_t)rot;
else if (rot)
return false; // rotation on a non-dual-plane mode
if (mode == 4)
log_blk.m_mode4_index_selector = (uint8_t)sel;
else if (sel)
return false; // selector outside mode 4
}
else // reuse config from a neighbor
{
const basist::bc7u::log_bc7_block* pSrc = nullptr;
if (cmd == (uint32_t)xbc7_command_id::cCmdReuseConfigLeft)
pSrc = pLeft_log_blk;
else if (cmd == (uint32_t)xbc7_command_id::cCmdReuseConfigUpper)
pSrc = pUp_log_blk;
else if (cmd == (uint32_t)xbc7_command_id::cCmdReuseConfigLeftDiagonal)
pSrc = pLeft_diag_log_blk;
else // cCmdReuseConfigRightDiagonal
pSrc = pRight_diag_log_blk;
if (!pSrc)
return false;
basist::bc7u::init_log_blk(log_blk, pSrc->m_mode);
log_blk.m_dp_rotation_index = pSrc->m_dp_rotation_index;
log_blk.m_mode4_index_selector = pSrc->m_mode4_index_selector;
}
// ---- partition index (always sent for partitioned modes) ----
if (log_blk.m_num_partitions == 2)
{
uint8_t pat;
if (!partitions2.get(pat))
return false;
if (pat >= 64)
return false;
log_blk.m_pattern_index = pat;
}
else if (log_blk.m_num_partitions == 3)
{
uint8_t pat;
if (!partitions3.get(pat))
return false;
if (pat >= (1u << log_blk.m_pattern_bits))
return false; // mode 0: index < 16
log_blk.m_pattern_index = pat;
}
const basist::bc7u::endpoint_format& fmt = basist::bc7u::g_endpoint_formats[log_blk.m_mode];
const uint32_t num_comps = log_blk.get_num_comps();
// ---- endpoints ----
if (ep_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointRaw)
{
for (uint32_t subset = 0; subset < log_blk.m_num_partitions; subset++)
{
for (uint32_t c = 0; c < num_comps; c++)
{
for (uint32_t e = 0; e < 2; e++)
{
uint32_t v;
if (!ep_raw.get_bits(log_blk.m_endpoint_bits[c == 3], v))
return false;
log_blk.m_endpoints[subset][e][c] = (uint8_t)v;
}
}
}
for (uint32_t pb = 0; pb < log_blk.m_num_pbits; pb++)
{
uint32_t v;
if (!ep_raw.get_bits(1, v))
return false;
if (pb < 6) // to shut up gcc bogus warning
log_blk.m_pbits[pb] = (uint8_t)v;
}
}
else
{
// resolve the endpoint predictor block (mirrors the encoder
// sweep); ep_mode is 3 bits, and 1..7 are all DPCM modes
const basist::bc7u::log_bc7_block* pEP_pred_blk = nullptr;
uint32_t ep_pred_subset = 0;
if (ep_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMLeft)
pEP_pred_blk = pLeft_log_blk;
else if (ep_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMUp)
pEP_pred_blk = pUp_log_blk;
else if (ep_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMLeftDiagonal)
pEP_pred_blk = pLeft_diag_log_blk;
else if (ep_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMRightDiagonal)
pEP_pred_blk = pRight_diag_log_blk;
else if (ep_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMLeftSubset1)
{
pEP_pred_blk = pLeft_log_blk;
ep_pred_subset = 1;
}
else if (ep_mode == (uint32_t)xbc7_command_endpoint_mode::cCmdEndpointDPCMUpSubset1)
{
pEP_pred_blk = pUp_log_blk;
ep_pred_subset = 1;
}
else // cCmdEndpointDPCMBlockIndex
{
uint8_t delta_index;
if (!ep_block_index.get(delta_index))
return false;
if (delta_index >= NUM_XY_DELTAS)
return false; // top 3 bits reserved-zero
const xbc7_xy_delta& delta = g_xbc7_xy_deltas[delta_index];
const int nx = (int)bx + delta.m_dx;
const int ny = (int)by + delta.m_dy;
// must reference a block inside this stripe (the encoder
// never emits a cross-stripe reference); also keeps a
// worker from reading another stripe's rows
if (!stripe_tile.contains(nx, ny))
return false; // reference outside the stripe: malformed stream
pEP_pred_blk = &log_blks(nx, ny);
}
if (!pEP_pred_blk)
return false;
// subset-1 references require a partitioned predictor
if ((ep_pred_subset) && (pEP_pred_blk->m_num_partitions < 2))
return false;
const bool fine = (log_blk.m_endpoint_bits[0] >= 6);
for (uint32_t subset = 0; subset < log_blk.m_num_partitions; subset++)
{
uint8_t residuals[8];
uint32_t num_residuals = num_comps * 2;
if ((!has_alpha) && (log_blk.m_mode == 6))
{
assert(num_residuals == 8);
num_residuals = 6;
residuals[6] = 0;
residuals[7] = 0;
}
for (uint32_t i = 0; i < num_residuals; i += 2)
{
const uint32_t chan = i >> 1;
byte_cursor& strm = ep_deltas[(fine ? 0 : 4) + chan];
if (!strm.get(residuals[i + 0]))
return false;
if (!strm.get(residuals[i + 1]))
return false;
}
uint8_t residual_pbits[2] = { 0, 0 };
for (uint32_t pb = 0; pb < fmt.m_num_pbits; pb++)
{
uint32_t v;
if (!pbits.get_bits(1, v))
return false;
residual_pbits[pb] = (uint8_t)v;
}
uint32_t num_residuals_out, num_residual_pbits_out;
basist::bc7u::endpoint_dpcm(true,
*pEP_pred_blk, ep_pred_subset, // mirrors the encoder (subset 1 for EP modes 6/7)
log_blk, subset,
residuals, num_residuals_out, residual_pbits, num_residual_pbits_out);
if ((!has_alpha) && (log_blk.m_mode == 6))
{
log_blk.m_endpoints[0][0][3] = 127;
log_blk.m_endpoints[0][1][3] = 127;
}
}
}
// ---- weights: residual DCT (wt bit 1) or lossless residual DPCM (wt bit 0) ----
uint8_t pred_byte;
if (!predictors.get(pred_byte))
return false;
if (pred_byte >= cTotalCandidates * 4)
return false;
const uint32_t cand_index = pred_byte % cTotalCandidates;
const uint32_t amp_code = pred_byte / cTotalCandidates;
if ((amp_code) && (cand_index == cCandAbsolute))
return false;
int weight_preds[16];
int* pWeight_predictions = nullptr;
for (uint32_t p = 0; p < log_blk.m_num_planes; p++)
{
if (cand_index != cCandAbsolute)
{
// the decoder may reference ANY causal block (whole-image
// tile): the encoder simply never emits a reference
// that crosses one of its tile boundaries
if (!eval_weight_predictor(cand_index, amp_code, bx, by, num_blocks_x, stripe_tile, log_blks, p, weight_preds))
return false; // candidate unavailable here: malformed stream
pWeight_predictions = weight_preds;
}
if (wt_mode != (uint32_t)xbc7_command_weight_mode::cCmdWeightDCT)
{
// ---- lossless residual DPCM weights ----
// Predictions are quantized to the plane's bit depth and
// the wrapped n-bit index residuals (or, for the absolute
// predictor, the raw indices) are read back. Exact.
const uint32_t num_bits = log_blk.m_weight_bits[p];
const uint32_t mask = (1u << num_bits) - 1;
byte_cursor& strm = (cand_index == cCandAbsolute) ? raw_weights : wt_resid[num_bits - 2];
uint8_t syms[16];
if (num_bits == 2)
{
for (uint32_t i = 0; i < 16; i += 4)
{
uint8_t b;
if (!strm.get(b))
return false;
syms[i + 0] = b & 3;
syms[i + 1] = (b >> 2) & 3;
syms[i + 2] = (b >> 4) & 3;
syms[i + 3] = (uint8_t)(b >> 6);
}
}
else
{
for (uint32_t i = 0; i < 16; i += 2)
{
uint8_t b;
if (!strm.get(b))
return false;
const uint8_t lo = b & 0xF, hi = (uint8_t)(b >> 4);
if ((num_bits == 3) && ((lo > 7) || (hi > 7)))
return false; // nibble bit 3 reserved-zero
syms[i + 0] = lo;
syms[i + 1] = hi;
}
}
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;
log_blk.m_weights[p][i] = (uint8_t)((syms[i] + pred_index) & mask);
}
continue; // next plane
}
// ---- DC ----
uint8_t dc_byte;
if (!dc_coeffs.get(dc_byte))
return false;
int dc = unpack_coeff_b(dc_byte);
if (pred_byte != cCandAbsolute) // joint index 0 == absolute: DC is unsigned
{
uint32_t sign;
if (!coeff_signs.get_bits(1, sign))
return false;
if (sign)
dc = -dc;
}
// ---- ACs ----
xbc7::dct_syms syms;
syms.clear();
syms.m_dc = (int16_t)dc;
uint32_t zig_idx = 1;
while (zig_idx < 16)
{
uint8_t b;
if (!ac_coeffs.get(b))
return false;
if (b == 0xFF)
{
// trailing zeros to the end of the scan
xbc7::coeff cf;
cf.m_num_zeros = (int16_t)(16 - zig_idx);
cf.m_coeff = INT16_MAX;
syms.m_ac_vals.push_back(cf);
break;
}
const uint32_t run = b;
if ((zig_idx + run) > 15)
return false; // a real coefficient must land at position <= 15
uint8_t mag_byte;
if (!ac_coeffs.get(mag_byte))
return false;
const int mag = unpack_coeff_b(mag_byte);
if (!mag)
return false; // zero coefficients are never coded
uint32_t sign;
if (!coeff_signs.get_bits(1, sign))
return false;
xbc7::coeff cf;
cf.m_num_zeros = (int16_t)run;
cf.m_coeff = (int16_t)(sign ? -mag : mag);
syms.m_ac_vals.push_back(cf);
zig_idx += run + 1;
}
bool status = weight_grid_dct_fixed.inverse(
basist::fixed16_16::from_int(global_q), p, pWeight_predictions, syms, log_blk, dct_work_fixed);
if (!status)
return false;
} // p
}
// ---- single emit point: every block path (repeat-last,
// repeat-upper, solid, config) falls through to here, so the
// caller's block callback is invoked EXACTLY ONCE per block,
// after the logical block is stored in m_log_blks. The caller may
// pack a physical BC7 block, store it, compare it vs a reference,
// transcode it, etc. A false return aborts the decode. ----
if (m_block_cb && !m_block_cb(bx, by, log_blk, m_block_data))
return false;
} // bx
} // by
// ---- per-stripe desync tripwires: each stream consumed exactly its
// range (cursors were bounded to [seek(s), seek(s+1))) ----
if (!commands.is_fully_consumed()) return false;
if (!configs.is_fully_consumed()) return false;
if (!partitions2.is_fully_consumed()) return false;
if (!partitions3.is_fully_consumed()) return false;
if (!predictors.is_fully_consumed()) return false;
if (!dc_coeffs.is_fully_consumed()) return false;
if (!ac_coeffs.is_fully_consumed()) return false;
if (!solid_deltas.is_fully_consumed()) return false;
if (!ep_block_index.is_fully_consumed()) return false;
if (!raw_weights.is_fully_consumed()) return false;
for (uint32_t i = 0; i < 3; i++)
if (!wt_resid[i].is_fully_consumed()) return false;
for (uint32_t i = 0; i < 8; i++)
if (!ep_deltas[i].is_fully_consumed()) return false;
if (!coeff_signs.is_fully_consumed()) return false;
if (!pbits.is_fully_consumed()) return false;
if (!ep_raw.is_fully_consumed()) return false;
return true;
} // decode_stripe
bool image_unpacker::decode_tiny_mip()
{
for (uint32_t by = 0; by < m_num_blocks_y; by++)
{
for (uint32_t bx = 0; bx < m_num_blocks_x; bx++)
{
const uint8_t* p = m_tiny_blocks + ((size_t)by * m_num_blocks_x + bx) * 16;
basist::bc7u::log_bc7_block log_blk;
if (!basist::bc7u::unpack_bc7(p, log_blk))
return false;
if (m_block_cb && !m_block_cb(bx, by, log_blk, m_block_data))
return false;
}
}
return true;
}
bool image_unpacker::decode_all()
{
// guard here too: with no successful init(), m_num_stripes is 0 and the
// loop would otherwise return true (false success) without decoding
assert(m_initialized && "decode_all() called without a successful init()");
if (!m_initialized)
return false;
for (uint32_t s = 0; s < m_num_stripes; s++)
if (!decode_stripe(s))
return false;
return true;
}
// Single-threaded one-shot: prep + serial decode.
bool unpack_image(
const byte_span& comp,
decode_init_callback_ptr pInit_callback, void* pInit_callback_data,
decode_block_callback_ptr pBlock_callback, void* pBlock_callback_data)
{
#if !BASISD_SUPPORT_KTX2_ZSTD
BASISU_NOTE_UNUSED(comp); BASISU_NOTE_UNUSED(pInit_callback); BASISU_NOTE_UNUSED(pInit_callback_data);
BASISU_NOTE_UNUSED(pBlock_callback); BASISU_NOTE_UNUSED(pBlock_callback_data);
BASISU_DEVEL_ERROR("xbc7::unpack_image: XBC7 decoding requires zstd (BASISD_SUPPORT_KTX2_ZSTD is 0)");
return false;
#else
image_unpacker dec;
if (!dec.init(comp, pInit_callback, pInit_callback_data, pBlock_callback, pBlock_callback_data))
return false;
return dec.decode_all();
#endif
}
// Threaded: caller owns `dec` (it must outlive the spawned jobs). init + spawn
// one job per stripe via the spawner; returns false only on init failure and
// does NOT wait. The caller waits on its own pool, then inspects results.
bool unpack_image_threaded(
image_unpacker& dec,
const byte_span& comp,
job_spawner& spawner,
decode_init_callback_ptr pInit_callback, void* pInit_callback_data,
decode_block_callback_ptr pBlock_callback, void* pBlock_callback_data)
{
#if !BASISD_SUPPORT_KTX2_ZSTD
BASISU_NOTE_UNUSED(dec); BASISU_NOTE_UNUSED(comp); BASISU_NOTE_UNUSED(spawner);
BASISU_NOTE_UNUSED(pInit_callback); BASISU_NOTE_UNUSED(pInit_callback_data);
BASISU_NOTE_UNUSED(pBlock_callback); BASISU_NOTE_UNUSED(pBlock_callback_data);
BASISU_DEVEL_ERROR("xbc7::unpack_image_threaded: XBC7 decoding requires zstd (BASISD_SUPPORT_KTX2_ZSTD is 0)");
return false;
#else
if (!dec.init(comp, pInit_callback, pInit_callback_data, pBlock_callback, pBlock_callback_data))
return false;
const uint32_t num_stripes = dec.get_num_stripes();
for (uint32_t stripe_index = 0; stripe_index < num_stripes; stripe_index++)
spawner.spawn_job(dec, stripe_index);
return true;
#endif
}
} // namespace xbc7
} // namespace basist
Reference in New Issue View Git Blame Copy Permalink