nx_zigzag.nx source

1// nx_zigzag.nx -- canonical 8x8 zigzag scan order (JPEG/MPEG/H.264). 2// 3// After a 2D DCT, energy concentrates in the low-frequency corner 4// (top-left); high-frequency coefficients are mostly zero after 5// quantisation. The zigzag scan re-orders the 64 coefficients so 6// low-frequency entries come first and high-frequency entries last, 7// turning sparse 8x8 blocks into 64-element vectors with long runs 8// of zeros at the tail -- perfect for run-length encoding. 9// 10// Layout (row-major position -> position in zigzag stream): 11// 12// 0, 1, 5, 6, 14, 15, 27, 28, 13// 2, 4, 7, 13, 16, 26, 29, 42, 14// 3, 8, 12, 17, 25, 30, 41, 43, 15// 9, 11, 18, 24, 31, 40, 44, 53, 16// 10, 19, 23, 32, 39, 45, 52, 54, 17// 20, 22, 33, 38, 46, 51, 55, 60, 18// 21, 34, 37, 47, 50, 56, 59, 61, 19// 35, 36, 48, 49, 57, 58, 62, 63 20// 21// Equivalently, position-in-stream k -> (row, col) via the inverse 22// table below. We expose both directions. 23// 24// genealogy_id: jpeg_iso_10918_1992 + h261_itu_1990 + h263_itu_1996 + 25// nx_dct8_q10 26// lineage_id: nishi_zigzag_q10 27 28// nx_safety_envelope: 29// intended_use: AUTO_APPLIED -- primitive-specific tuning queued 30// sil_target: SIL1 31// evidence: [bulk_applied_2026-05-16, see-file-comment-for-detail] 32// verdict: NOT_YET_EVALUATED 33 34import "nx_syscalls.nx" 35 36// Sealed verdict. 37const NX_ZIGZAG_VERDICT_UNKNOWN: i64 = 0 38const NX_ZIGZAG_VERDICT_OK: i64 = 1 39const NX_ZIGZAG_VERDICT_BAD_PARAMS: i64 = 2 40const NX_ZIGZAG_VERDICT_N: i64 = 3 41 42// Fill `out_to_zz` (64 i64) such that out_to_zz[r*8+c] = position in 43// the zigzag stream for the (r,c) pixel. And `out_from_zz[k]` = 44// row-major position of stream entry k. 45func nx_zigzag_init(to_zz: *i64, from_zz: *i64) -> i64 { 46 // Row-major position -> stream position. 47 let tz: i64 = 0 48 to_zz[ 0]= 0; to_zz[ 1]= 1; to_zz[ 2]= 5; to_zz[ 3]= 6 49 to_zz[ 4]=14; to_zz[ 5]=15; to_zz[ 6]=27; to_zz[ 7]=28 50 to_zz[ 8]= 2; to_zz[ 9]= 4; to_zz[10]= 7; to_zz[11]=13 51 to_zz[12]=16; to_zz[13]=26; to_zz[14]=29; to_zz[15]=42 52 to_zz[16]= 3; to_zz[17]= 8; to_zz[18]=12; to_zz[19]=17 53 to_zz[20]=25; to_zz[21]=30; to_zz[22]=41; to_zz[23]=43 54 to_zz[24]= 9; to_zz[25]=11; to_zz[26]=18; to_zz[27]=24 55 to_zz[28]=31; to_zz[29]=40; to_zz[30]=44; to_zz[31]=53 56 to_zz[32]=10; to_zz[33]=19; to_zz[34]=23; to_zz[35]=32 57 to_zz[36]=39; to_zz[37]=45; to_zz[38]=52; to_zz[39]=54 58 to_zz[40]=20; to_zz[41]=22; to_zz[42]=33; to_zz[43]=38 59 to_zz[44]=46; to_zz[45]=51; to_zz[46]=55; to_zz[47]=60 60 to_zz[48]=21; to_zz[49]=34; to_zz[50]=37; to_zz[51]=47 61 to_zz[52]=50; to_zz[53]=56; to_zz[54]=59; to_zz[55]=61 62 to_zz[56]=35; to_zz[57]=36; to_zz[58]=48; to_zz[59]=49 63 to_zz[60]=57; to_zz[61]=58; to_zz[62]=62; to_zz[63]=63 64 65 // Invert: from_zz[stream_pos] = row-major index. 66 var i: i64 = 0 67 while i < 64 { 68 from_zz[to_zz[i]] = i 69 i = i + 1 70 } 71 return NX_ZIGZAG_VERDICT_OK 72} 73 74// Scan an 8x8 row-major block of i64 into a 64-entry stream. 75func nx_zigzag_scan(block: *i64, to_zz: *i64, stream: *i64) -> i64 { 76 var i: i64 = 0 77 while i < 64 { 78 stream[to_zz[i]] = block[i] 79 i = i + 1 80 } 81 return NX_ZIGZAG_VERDICT_OK 82} 83 84// Inverse: 64-entry stream back into row-major block. 85func nx_zigzag_unscan(stream: *i64, from_zz: *i64, block: *i64) -> i64 { 86 var i: i64 = 0 87 while i < 64 { 88 block[from_zz[i]] = stream[i] 89 i = i + 1 90 } 91 return NX_ZIGZAG_VERDICT_OK 92} 93 94func nx_zigzag_verdict_is_valid(v: i64) -> i64 { 95 if v < 0 { return 0 } 96 if v >= NX_ZIGZAG_VERDICT_N { return 0 } 97 return 1 98}