# ByteGrid Examples

This folder contains example files for the ByteGrid plugin.

## How to Use

1. Open the example file you want to use
2. **Select all** content and copy it
3. Create a code block in your Obsidian note:

   ````markdown
   ```bytegrid
   [paste here]
   ```
   ````

## Example Files

### Basic Examples

#### 1. simple-struct.yaml

- Simple 16-byte structure
- 4 fields (ID, Timestamp, Value, Checksum)
- 8 bytes/row layout

#### 2. wav-header.yaml

- WAV audio file header (44 bytes)
- 14 fields (RIFF, WAVE, fmt, data chunks)
- 16 bytes/row layout
- Includes audio format, sample rate, etc.

### Network Protocols

#### 3. tcp-header.yaml

- TCP protocol header (20 bytes)
- 10 fields (ports, sequence number, flags, etc.)
- **Bitfield example**: 8 TCP flags (CWR, ECE, URG, ACK, PSH, RST, SYN, FIN)
- 16 bytes/row layout

#### 4. ip-header.yaml

- IPv4 header (20 bytes)
- 10 fields (Version, DSCP, TTL, Protocol, IP addresses, etc.)
- **Bitfield example**: Version+IHL, DSCP+ECN, Flags+FragmentOffset
- Includes IP fragmentation flags (DF, MF)

### File System & Permissions

#### 5. file-attributes.yaml

- FAT32 file attributes (4 bytes)
- **Bitfield example**: 8 file attribute flags
- READ_ONLY, HIDDEN, SYSTEM, DIRECTORY, ARCHIVE, etc.

#### 6. unix-permissions.yaml

- Unix file permissions (2 bytes)
- **Bitfield example**: rwxrwxrwx (9 bits)
- Owner/Group/Others permissions (read/write/execute)

### Hardware & CPU

#### 7. cpu-flags.yaml

- x86 CPU FLAGS register (4 bytes)
- **Bitfield example**: 16 CPU flags
- CF, ZF, SF, IF, DF, OF, IOPL, etc.

### Auto Color Examples

#### 8. auto-color-examples.md

- **Interactive guide** with 4 examples showing automatic color assignment
- Open this file in Obsidian to see live examples
- Explains auto color modes and behavior

#### 9. auto-color-basic.yaml

- Basic auto color example (8 fields, 8 colors)
- Default behavior: colors assigned automatically

#### 10. auto-color-manual.yaml

- Manual color mode (`autoColor: false`)
- Only explicit colors shown, others gray

#### 11. auto-color-mixed.yaml

- Mixed mode: combine auto and manual colors
- Explicit colors take precedence

## Important Notes

⚠️ **Watch Out for Indentation When Copying**

Obsidian may automatically add indentation when pasting into code blocks.

**If you encounter issues:**

1. Switch to Obsidian **Source Mode** (Ctrl/Cmd + E)
2. Check the line after ` ```bytegrid`
3. There should be **no spaces** before `name:`
4. Remove any extra spaces if present

## Create Your Own

To visualize a new structure:

```yaml
name: Structure Name
size: total byte size
layout: 16 # bytes per row (optional, default: 16)
layoutUnit: byte # byte or bit (optional, auto-inferred from suffix)

# Color options
autoColor: true # auto-assign colors (optional, default: true)
colorScheme: default # default, dark, or light (optional, default: default)

# Legend options
legendPosition: right # right, left, bottom, none (optional, default: right)
legendColumns: 1 # number of columns in legend (optional, default: 1)

# Other options
showFooter: true # show/hide footer (optional, default: true)

fields:
  - offset: 0-3
    name: FieldName
    type: uint32_t
    color: blue # blue, cyan, yellow, green, orange, purple, mint, pink, gray (optional)
    description: 'Description' # optional
```

### Color Options Explained

**autoColor** (default: `true`):

- `true`: Fields without explicit colors get auto-assigned (blue, cyan, yellow, green, orange, purple, mint, pink)
- `false`: Fields without explicit colors default to gray

**colorScheme** (default: `default`):

- `default`: Original pastel colors
- `dark`: Reduced saturation and lightness (easier on eyes)
- `light`: Increased lightness (better for bright backgrounds)

**Tip**: Start with `autoColor: true` and only specify colors for fields you want to emphasize!

## Bit-Level Layout Examples

### 12. simple-bit-layout.yaml

- Basic bit-level layout test (16 bits)
- **Suffix notation**: `size: 16b`, `layout: 16b`, `offset: 0-7b`
- `layoutUnit` can be omitted (auto-inferred from suffix)

### 13. nibble-test.yaml

- 4-bit field (nibble) test
- Each nibble represented independently

### 14. mixed-bit-byte.yaml

- Mixed bit and byte offsets
- `0-3b` (bit), `1B` (Byte), `2-3` (byte, default)

### 15. ipv4-bit-layout.yaml

- IPv4 header in bit-level representation
- Sub-byte fields like Version(4bit) + IHL(4bit)

**Suffix Notation:**

- `b` (lowercase) = bit: `32b`, `0-7b`
- `B` (uppercase) = Byte: `4B`, `0-3B`
- no suffix = byte (default)

**layoutUnit field:**

- Can be omitted (auto-inferred from suffix)
- Can be explicit (use `layoutUnit: bit` or `layoutUnit: byte` if desired)