PUSHK2 Cells Editor

Specialized tile editor for the .cells binary format — a scanline-interleaved tile format designed for SDRAM burst-access rendering on CMBoards hardware (STM32 + Xilinx FPGA + SDRAM).

Version: 0.1 test (V01G04A81, 2025–2026)

---

Table of Contents

• What is this?
• The .cells Format
  • Overview
  • Pixel Format: HRGB2222
  • Memory Layout
  • Why This Layout?
• Editor Features
  • Tile Editing
  • Color Tools
  • File Operations
  • ZX Screen Tools
  • Display Modes
• Target Audience
• CMBoards Platform
• Building & Running
• Related Projects
• Author

---

What is this?

PUSHK2 Cells Editor is a lightweight, purpose-built tile editor for the .cells binary format used in the CMBoards embedded hardware ecosystem.

Unlike general-purpose pixel art tools, this editor is aware of the hardware it targets: it understands the HRGB2222 pixel encoding, the scanline-interleaved memory layout, and platform-specific workflows like ZX Screen compatibility and font import.

If you are developing graphics for a CMBoards platform (STM32 + Xilinx FPGA + SDRAM + HDMI/TFT output), this is the native tool for that workflow.

---

The .cells Format

📄 Full specification: https://vigatron.github.io/formats/cells/

Overview

Property	Value
File extension	.cells
File size	Fixed — 16 384 bytes (16 KB)
Tile count	256 tiles
Tile dimensions	8 × 8 pixels
Pixel format	HRGB2222 (8 bits per pixel)
Compression	None — raw binary
Endianness	Little-endian

The file has no header and no metadata — it is a raw memory image intended to be loaded directly into SDRAM.

---

Pixel Format: HRGB2222

Each pixel is encoded in 1 byte using the HRGB2222 scheme:

Bit:  7   6   5   4   3   2   1   0
      H   H   R   R   G   G   B   B

Bits	Field	Description
7–6	H	Hardware modifier — forms an XOR mask applied to R, G, B
5–4	R	Red channel (2 bits)
3–2	G	Green channel (2 bits)
1–0	B	Blue channel (2 bits)

The H bits are not a simple alpha or palette index — they generate a COLXOR mask that is XOR'd against each expanded channel before final 8-bit output. This enables a compact hardware-driven color modifier without extra memory.

Color Conversion to RGB888

The reference implementation (vhcolors.hpp):

#define COL2B(X, SHL)   ( ( (X) >> SHL ) & 3 )
#define COLDBL(C2B)     ( ( (C2B) << 2 ) | (C2B) )
#define COLQRT(C4B)     ( ( (C4B) << 4 ) | (C4B) )
#define COLXOR(X)       ( ( ( (X) >> 5) & 4 ) | ( ( (X) >> 5) & 2) )
#define COLF8(X,N)      COLQRT( ( COLDBL( COL2B(X,N) ) ^ COLXOR(X) ) )

#define CLRR8(X)        COLF8((X), 4)
#define CLRG8(X)        COLF8((X), 2)
#define CLRB8(X)        COLF8((X), 0)

// Final RGB32 output (R in low byte):
#define CLR32RGB(X)     ( CLRR8(X) | (CLRG8(X) << 8) | (CLRB8(X) << 16) )
// Final BGR32 output (B in low byte):
#define CLR32BGR(X)     ( (CLRR8(X) << 16) | (CLRG8(X) << 8) | CLRB8(X) )

Pixel order within each tile row: left to right, from lowest address to highest.

---

Memory Layout

The .cells format uses a scanline-interleaved (row-interleaved) layout — tiles are not stored sequentially. Instead, row N of all 256 tiles is stored together before row N+1 of any tile.

Offset 0x0000  →  Row 0 of tile 0,   tile 1,   tile 2,   … tile 255   (2048 bytes)
Offset 0x0800  →  Row 1 of tile 0,   tile 1,   tile 2,   … tile 255   (2048 bytes)
Offset 0x1000  →  Row 2 of tile 0,   tile 1,   tile 2,   … tile 255   (2048 bytes)
...
Offset 0x3800  →  Row 7 of tile 0,   tile 1,   tile 2,   … tile 255   (2048 bytes)

Offset formula:

offset = row * 0x0800 + tile_index * 8

where:
  row        = 0 .. 7
  tile_index = 0 .. 255

Examples:

Tile	Row	Offset
0	0	0x000000
2	2	0x001010
5	3	0x001828
42	7	0x003950

---

Why This Layout?

This layout is specifically optimized for SDRAM burst-access in FPGA rendering pipelines.

When the FPGA activates a single SDRAM row (ACTIVATE command), it can then read all 256 tile scanlines for one pixel row in a single continuous burst — with no row switches and no latency penalties.

The number of tiles covered per burst depends on the SDRAM bus width:

	SDRAM Configuration	Tiles per burst
1×	SDRAM ×16 / A0-A7	up to 64 tiles / burst
2×	SDRAM ×16 / A0-A7	up to 128 tiles / burst
1×	SDRAM ×16 / A0-A8	up to 128 tiles / burst
2×	SDRAM ×16 / A0-A8	up to 256 tiles / burst
1×	SDRAM ×32 / A0-A7	up to 128 tiles / burst
2×	SDRAM ×32 / A0-A7	up to 256 tiles / burst
1×	SDRAM ×32 / A0-A8	up to 256 tiles / burst

This makes .cells a zero-seek, predictable-latency format ideal for real-time scanline rendering on FPGA.

---

Editor Features

Tile Editing

• Browse and select any of the 256 tiles from the tile grid view
• Shift cell line — shift pixels within the selected tile row:
  • Left / Right — horizontal shift with wrap
  • Up / Down — vertical shift with wrap
• Flip-X — mirror tile horizontally
• Flip-Y — mirror tile vertically
• Fill — flood-fill the selected tile with the active color
• Shift cells (global) — shift all tiles in the tileset: Left, Right, Up, Down

Color Tools

• Color palette — full HRGB2222 palette display (bottom panel)
  • Left panel: 256-color palette grid
  • Right panel: color picker organized by hue/brightness
• Fix Black color — replace a specific color index with true black
• Nonblack color — replace a color in all non-black positions
• Replace (From → To) — batch replace one color index with another across a tile range
• All Tiles checkbox — apply replace operation to all 256 tiles at once
• 16C mode — restrict display/editing to 16-color mode
• Highlight 256C — visually highlight colors that exceed 16C range

File Operations

Operation	Description
Load …	Open a .cells file from disk
Save	Save current tileset to the loaded file path
Save As	Save to a new file path
Convert 16C	Convert the tileset to 16-color HRGB2222 encoding
Import Font	Import a bitmap font as tiles (useful for text rendering)
Copy Cells SCR	Copy tile data to/from ZX Screen buffer
Move Cells SCR	Move tile data to/from ZX Screen buffer
Clip Sides	Trim/clip edge tiles (for overscan or display border removal)
Copy Cells group: N → Copy	Copy a named group of tiles to a target slot

ZX Screen Tools

The editor includes compatibility tools for ZX Spectrum-style screen format, allowing bidirectional transfer of tile data between .cells format and ZX Screen layout. This is relevant when working with retro-compatible content pipelines or porting assets between platforms.

• ZX Screen — open/view ZX Screen buffer
• Copy Cells SCR — copy tile content to ZX Screen format
• Move Cells SCR — move tile content to ZX Screen format

Display Modes

• 16C mode — activates 16-color constraint mode (useful for ZX-compatible palettes)
• Highlight 256C — highlights pixels using colors outside the 16-color range

---

Target Audience

This editor is intended for:

• CMBoards hardware developers building graphics for STM32 + FPGA + SDRAM platforms
• Embedded graphics engineers working with tile-based FPGA rendering pipelines
• Demo scene and retro graphics enthusiasts targeting custom hardware
• Game and visual effect authors for HDMI/TFT output on CMBoards variants
• Anyone working with the PUSHK ecosystem of tools and formats

---

CMBoards Platform

The .cells format is part of the CMBoards hardware ecosystem — a family of custom embedded boards combining STM32 microcontrollers, Xilinx Spartan-6 FPGAs, external SDRAM, and HDMI or TFT display outputs.

Board	MCU	FPGA	Memory	Display
HDM32F407HDMI	STM32F407	XC6SLX9	1× SDRAM ×16	HDMI out
HDM32F746HDMI	STM32F746	XC6SLX9	1× SDRAM ×32	HDMI out
HDM32H750HDMI	STM32H750	XC6SLX9	1× DDR ×32	HDMI out
HDM32F746TFT7	STM32F746	XC6SLX16	2× SDRAM ×16	TFT 7" 800x480
HDM32H750TFT7	STM32H750	XC6SLX16	1× DDR ×32	TFT 7" 800x480

📄 Board details: BRD32F407HDMIR3

---

Building & Running

⚠️ Source code and build instructions will be published in a future release.

Planned build system: CMake 3.16+ with C++17.

# Anticipated build steps (subject to change):
git clone https://github.com/vigatron/pushk2cellseditor
cd pushk2cellseditor
mkdir build && cd build
cmake ..
make

Dependencies (preliminary):

• C++17 compiler (GCC / Clang / MSVC)
• CMake 3.16+
• Qt or wxWidgets (GUI framework — TBD)

---

Related Projects

Project	Description
.cells Format Specification	Full binary format documentation
PUSHK Archiver	Specialized compressor/archiver for .cells and related formats
.cells editor project	Editor source code : C++ / Qt5 / CMake based
vigatron.github.io	Author's project hub — CMBoards, PUSHK ecosystem, and more

---

Author

Viktor Glebov (V01G04A81)

Part of the PUSHK / CMBoards ecosystem.

"Streaming-optimized tile layout for SDRAM-based rendering pipelines."

---

© 2025–2026 Viktor Glebov (V01G04A81) — MIT License