cxd4 / pixd Goto Github PK

Binary "disassembler" interpreting as raster scan-lines and pixel maps.

Note:  GLUT is a run-time dependency of this software.  The 64-bit Windows build
will work with the GLUT32.DLL from here:  https://github.com/cxd4/glut/releases
(Non-Windows builds just need the "freeGLUT" package installed.)

It was created primarily because of a lack of featured alternatives for viewing
bitmap resources in memory, using Nintendo 64 DRAM dumps for most tests.

Objectively, this tool is not aimed to be N64-specific and should support the
various color encodings of other systems' graphics hardware (except for
primitive color-indexed palette stuff, like look-up tables for random colors,
in which case a dedicated GIF or PNG image palette editor should be used).

Command syntax:
    PixD [filepath] [entry point] [depth] [width] [height] [blend]

All arguments are optional and will assume default values if not specified.
Simply executing `PixD' with no parameters is NOT erroneous.  Default values:
    [filepath] -- The default input file is "data.bin".
    [entry point] -- The default offset is 0, so it disassembles from the start.
                     It must be a hexadecimal, with or without the `0x' prefix.
    [depth] -- You take 2 to the power of this number, from 0 to 7.  The default
               is 3, so the default color depth is 2*2*2 = 8 bits per pixel.
    [width], [height] -- If left unspecified, the end results are 256 pixels.
    [blend] -- Blend any partially (or completely) transparent pixels in the
               foreground against this background color (another hexadecimal).
               The default is 0x000000FF (100% black) and disables blending in
               case the user needs to ignore the alpha channel to see the proper
               image disassembly.  (Try also pressing capital 'A' at run-time.)

Example command:
    PixD "DRAM.BIN" 100000 4 320 240 FF00FF80
... opens a file named DRAM.BIN into the pixel diassembler, seeking 0x00100000
bytes deep into the file as a pixel map, initialized to a 16-bit 320x240
viewport which should be compatible with the N64's R5G5B5 frame buffer format.
Finally, the background color is semi-transparent magenta (0xFF00FF80), but how
the transparency is handled will depend on your OS, windowing system, etc.

You can also just press the keys 0 through 7 to change the color depth while
the program is already running, without typing it on the command line.
Scroll down to "Supported modes of pixel bitmap interpretation" for more info.

If N64's 16-bit is not desired (e.g., the intention is B5G5R5 or A1R5G5B5),
pressing 'e' (endianness) or 'p' (packing) at run-time will enable some features
that can achieve most other variations of 16-bit color.

Advantages over Jovis' N64 disassembler utility:
    * takes no time at all to upload pixels, rather than minutes
    * worst-case scenario compatible GDI fallback to Microsoft's software
      OpenGL implementation (still much faster though)
    * much more precise scrolling through the image, on exact intervals
    * other more conventional uses over Lemmy's disassembler, outlined next

Advantages over LemAsm:
    * many non-N64-specific color modes and bit depths supported
    * vertical flipping and un-flipping of the image ('f' and 'F')
    * OpenGL color channel component toggling ('rgba', 'RGBA' keys for on/off)
    * support for partially transparent pixels blended against any 32-bit canvas
    * byte-by-byte (not pixel-by-pixel) scrolling (left/right arrow keys)
    * scrolling on single scan-line intervals (up/down arrow keys)
    * scrolling by the size of all pixels fitting current screen size (PgUp/Dn)
    * incrementing and decrementing scan-line pitch, in pixels ('+' and '-')
    * cross-platform, hardware-accelerated OpenGL blits (no acceleration req.)
    * simple key press to write image to a 32-bit format storing alpha (F3 key)
    * real-time tracing of bitmap/viewport size and memory offset (F5 key)
    * available source code

Disadvantages (not yet supported):
    * RGB un-packing without the opacity channel (Greeks call this alpha?) in
      the scan-line pitch (should add 'p' and 'P' shortcut keys so that 3-, 6-,
      15-, 24-, 48-, and 96-bit-per-pixel color formats can be supported)
    * no way to zoom in on the pixels without using a smaller system resolution
    * lacks some less conventional pixel formats supported by Jovis' 64DISASM
    * forgot whether anything else was planned (your idea here?)

How to use the program:
    * Drag-and-drop. :)
    * should add other stuff for batch files and command line in the future
    * arrow keys and PageUp/PageDown to scroll through the pixels
    * to-do ?? implement functions for mouse move/click/drag?
    * Lowercase letters enable options; uppercase letters turn them back off.
      The octal digit '01234567' and some other keys can do some special stuff
      which may be documented later.

Supported modes of pixel bitmap interpretation:
    * 1-bit-per-pixel monochrome bitmaps (Press the '0' key.)
    * 2-bit chromatic intensity (Press '1'.)
    * 4-bit I1R1G1B1 and IBGR, compatible with Windows VGA (Press '2'.)
    * 8-bit intensity mask, not compatible with Microsoft's arbitrary B2G3R3
      (Press '3', and try 'RGBA' keys for toggling color channels on and off.)
    * 16-bit R5G5B5A1 or B5G5R5A1 (Press '4'.) or I8A8 (Press 'a'.)
    * 32-bit RGBA or BGRA pixels (Most people might want this.  Press '5'.)
    * 64-bit RGBA or BGRA pixels (Press '6'.)
    * 128-bit RGBA or BGRA pixels (Press '7'.)
Pressing '6' or '7' will resort to exotic, futuristic color bit depths which
we currently do not have PC monitors for, although it is a core feature to
OpenGL's RGBA rendering capacity.  It is not portable to OpenGL ES code, though
most of the remaining source code is portable to OpenGL ES 1.x.  Windows GDI+
does claim to support the 64-bit RGBA encoding for Windows bitmaps.  Thanks to
OpenGL 1.2 extensions, you can press 'e' and 'E' to toggle RGB/BGR endianness.
Currently the software lacks a 'p' flag to switch packing/pitch to exclude alpha
so that other bit depths like 3, 24, 48, or 96 bits per pixel can be supported.