A fork of https://github.com/crosspoint-reader/crosspoint-reader
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

Replace book and section bin format images with ImHex hexpat definition (#189)

## Summary

* Replace book and section bin format images with ImHex hexpat
definition
* This should give readers an understanding of the file format but also
supply some utility when validating content/output

authored by

Dave Allie and committed by
GitHub
04ad4e5a 6e9ba100

+214 -2
+214 -2
docs/file-formats.md
··· 2 2 3 3 ## `book.bin` 4 4 5 - ![](./images/file-formats/book-bin.png) 5 + ### Version 3 6 + 7 + ImHex Pattern: 8 + 9 + ```c++ 10 + import std.mem; 11 + import std.string; 12 + import std.core; 13 + 14 + // === Configuration === 15 + #define EXPECTED_VERSION 3 16 + #define MAX_STRING_LENGTH 65535 17 + 18 + // === String Structure === 19 + 20 + struct String { 21 + u32 length [[hidden, comment("String byte length")]]; 22 + if (length > MAX_STRING_LENGTH) { 23 + std::warning(std::format("Unusually large string length: {} bytes", length)); 24 + } 25 + char data[length] [[comment("UTF-8 string data")]]; 26 + } [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]]; 27 + 28 + fn format_string(String s) { 29 + return s.data; 30 + }; 31 + 32 + // === Metadata Structure === 33 + 34 + struct Metadata { 35 + String title [[comment("Book title")]]; 36 + String author [[comment("Book author")]]; 37 + String coverItemHref [[comment("Path to cover image")]]; 38 + String textReferenceHref [[comment("Path to guided first text reference")]]; 39 + } [[comment("Book metadata information")]]; 40 + 41 + // === Spine Entry Structure === 42 + 43 + struct SpineEntry { 44 + String href [[comment("Resource path")]]; 45 + u32 cumulativeSize [[comment("Cumulative size in bytes"), color("FF6B6B")]]; 46 + s16 tocIndex [[comment("Index into TOC (-1 if none)"), color("4ECDC4")]]; 47 + } [[comment("Spine entry defining reading order")]]; 48 + 49 + // === TOC Entry Structure === 50 + 51 + struct TocEntry { 52 + String title [[comment("Chapter/section title")]]; 53 + String href [[comment("Resource path")]]; 54 + String anchor [[comment("Fragment identifier")]]; 55 + u8 level [[comment("Nesting level (0-255)"), color("95E1D3")]]; 56 + s16 spineIndex [[comment("Index into spine (-1 if none)"), color("F38181")]]; 57 + } [[comment("Table of contents entry")]]; 58 + 59 + // === Book Bin Structure === 60 + 61 + struct BookBin { 62 + // Header 63 + u8 version [[comment("Format version"), color("FFD93D")]]; 64 + 65 + // Version validation 66 + if (version != EXPECTED_VERSION) { 67 + std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION)); 68 + } 69 + 70 + u32 lutOffset [[comment("Offset to lookup tables"), color("6BCB77")]]; 71 + u16 spineCount [[comment("Number of spine entries"), color("4D96FF")]]; 72 + u16 tocCount [[comment("Number of TOC entries"), color("FF6B9D")]]; 73 + 74 + // Metadata section 75 + Metadata metadata [[comment("Book metadata")]]; 76 + 77 + // Validate LUT offset alignment 78 + u32 currentOffset = $; 79 + if (currentOffset != lutOffset) { 80 + std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset)); 81 + } 82 + 83 + // Lookup Tables 84 + u32 spineLut[spineCount] [[comment("Spine entry offsets"), color("4D96FF")]]; 85 + u32 tocLut[tocCount] [[comment("TOC entry offsets"), color("FF6B9D")]]; 86 + 87 + // Data Entries 88 + SpineEntry spines[spineCount] [[comment("Spine entries (reading order)")]]; 89 + TocEntry toc[tocCount] [[comment("Table of contents entries")]]; 90 + }; 91 + 92 + // === File Parsing === 93 + 94 + BookBin book @ 0x00; 95 + 96 + // Validate we've consumed the entire file 97 + u32 fileSize = std::mem::size(); 98 + u32 parsedSize = $; 99 + 100 + if (parsedSize != fileSize) { 101 + std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize)); 102 + } 103 + ``` 6 104 7 105 ## `section.bin` 8 106 9 - ![](./images/file-formats/section-bin.png) 107 + ### Version 8 108 + 109 + ImHex Pattern: 110 + 111 + ```c++ 112 + import std.mem; 113 + import std.string; 114 + import std.core; 115 + 116 + // === Configuration === 117 + #define EXPECTED_VERSION 8 118 + #define MAX_STRING_LENGTH 65535 119 + 120 + // === String Structure === 121 + 122 + struct String { 123 + u32 length [[hidden, comment("String byte length")]]; 124 + if (length > MAX_STRING_LENGTH) { 125 + std::warning(std::format("Unusually large string length: {} bytes", length)); 126 + } 127 + char data[length] [[comment("UTF-8 string data")]]; 128 + } [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]]; 129 + 130 + fn format_string(String s) { 131 + return s.data; 132 + }; 133 + 134 + // === Page Structure === 135 + 136 + enum StorageType : u8 { 137 + PageLine = 1 138 + }; 139 + 140 + enum WordStyle : u8 { 141 + REGULAR = 0, 142 + BOLD = 1, 143 + ITALIC = 2, 144 + BOLD_ITALIC = 3 145 + }; 146 + 147 + enum BlockStyle : u8 { 148 + JUSTIFIED = 0, 149 + LEFT_ALIGN = 1, 150 + CENTER_ALIGN = 2, 151 + RIGHT_ALIGN = 3, 152 + }; 153 + 154 + struct PageLine { 155 + s16 xPos; 156 + s16 yPos; 157 + u16 wordCount; 158 + String words[wordCount]; 159 + u16 wordXPos[wordCount]; 160 + WordStyle wordStyle[wordCount]; 161 + BlockStyle blockStyle; 162 + }; 163 + 164 + struct PageElement { 165 + u8 pageElementType; 166 + if (pageElementType == 1) { 167 + PageLine pageLine [[inline]]; 168 + } else { 169 + std::error(std::format("Unknown page element type: {}", pageElementType)); 170 + } 171 + }; 172 + 173 + struct Page { 174 + u16 elementCount; 175 + PageElement elements[elementCount] [[inline]]; 176 + }; 177 + 178 + // === Section Bin Structure === 179 + 180 + struct SectionBin { 181 + // Header 182 + u8 version [[comment("Format version"), color("FFD93D")]]; 183 + 184 + // Version validation 185 + if (version != EXPECTED_VERSION) { 186 + std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION)); 187 + } 188 + 189 + // Cache busting parameters 190 + s32 fontId; 191 + float lineCompression; 192 + bool extraParagraphSpacing; 193 + u16 viewportWidth; 194 + u16 vieportHeight; 195 + u16 pageCount; 196 + u32 lutOffset; 197 + 198 + Page page[pageCount]; 199 + 200 + // Validate LUT offset alignment 201 + u32 currentOffset = $; 202 + if (currentOffset != lutOffset) { 203 + std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset)); 204 + } 205 + 206 + // Lookup Tables 207 + u32 lut[pageCount]; 208 + }; 209 + 210 + // === File Parsing === 211 + 212 + SectionBin book @ 0x00; 213 + 214 + // Validate we've consumed the entire file 215 + u32 fileSize = std::mem::size(); 216 + u32 parsedSize = $; 217 + 218 + if (parsedSize != fileSize) { 219 + std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize)); 220 + } 221 + ```
docs/images/file-formats/book-bin.png

This is a binary file and will not be displayed.

docs/images/file-formats/section-bin.png

This is a binary file and will not be displayed.