Browse files

Delete params.json

  • Loading branch information...
1 parent d11e102 commit c828c4df5ca9399e3f1dd5738e7284905d56249f @mental committed Jun 1, 2014
Showing with 0 additions and 1 deletion.
  1. +0 −1 params.json
@@ -1 +0,0 @@
-{"name":"Retrograph","tagline":"8-bit style graphics library","body":"== What is Retrograph? ==\r\n\r\nRetrograph is a Ruby library which emulates the video\r\ndisplay unit from a hypothetical late-80s 8-bit game\r\nconsole. It is similar in capability to the Sega Master\r\nSystem's VDP, with some additional features and direct\r\nsupport for text modes.\r\n\r\nRetrograph doesn't do its own screen output but rather\r\nworks with other libraries. Currently, it supports\r\nRuby/SDL, but other output targets are planned for the\r\nfuture.\r\n\r\n== Where can I get it? ==\r\n\r\nRetrograph is available via RubyGems, or via Rubyforge\r\ndownloads:\r\n\r\n\r\n\r\nCursory documentation is available on the\r\ncorresponding github wiki:\r\n\r\n\r\n\r\n== Feature Overview ==\r\n\r\n * 256x244 pixel display\r\n * 16k VRAM\r\n * 64 colors total\r\n * max 31 simultaneous colors (16 background, 15 sprite)\r\n * 40x25 and 32x28 text modes\r\n * 32x32 tile background, 8x8 pixel tiles\r\n * 64 8x8 sprites, max 8 per scanline\r\n\r\n== Usage ==\r\n\r\nRetrograph's simulated Video Display Unit (or VDU) is\r\nrepresented by an instance of the Retrograph::VDU class.\r\nYou can interact with the VDU by writing byte strings\r\ninto its memory using Retrograph::VDU#write, which takes\r\na start address (in the VDU's 16-bit address space) and\r\na string to write. The method Retrograph::VDU#write_byte\r\nis also provided for writing individual bytes.\r\n\r\n(See the end of this document for a map of registers and\r\nmemory locations within the VDU's address space.)\r\n\r\nTo render a frame of video with SDL, use\r\nRetrograph::VDU#render_frame_sdl, which returns an\r\nSDL::Surface containing the VDU output. The returned\r\nsurface remains valid until the next call to\r\nRetrograph::VDU#render_frame_sdl on the same VDU instance.\r\n\r\nScanline-based effects are possible if you provide a block\r\nto Retrograph::VDU#render_frame_sdl. Ordinarily, rendering\r\nwill not begin until the block completes, but within the\r\nblock you can call Retrograph::VDU#wait_scanlines to render\r\na given number of scanlines before continuing. This allows\r\nyou to make changes to the VDU state part-way through\r\nrendering a frame.\r\n\r\nFor example, if we wanted palette entry 0 to be blue within\r\nthe top half of the display and red within the bottom half\r\nof the display, we could write:\r\n\r\n require 'retrograph/sdl'\r\n\r\n vdu =\r\n vdu.write_byte(0x7f00, 0x03)\r\n output = vdu.render_frame_sdl do\r\n vdu.wait_scanlines(Retrograph::DISPLAY_HEIGHT/2)\r\n vdu.write_byte(0x7f00, 0x30)\r\n end\r\n\r\n(It is still necessary at this point to copy output to the\r\nscreen.)\r\n\r\n== Important Notes ==\r\n\r\nNothing is displayed by default. To be shown, the\r\nbackground layer (and the sprite, in graphical modes) must\r\nbe explicitly enabled by setting bit 2 (bit 3 for sprites)\r\nof register $7FF8.\r\n\r\nPatterns and name tables may overlap in memory (which is\r\nin fact unavoidable in graphics modes); typically you\r\ncannot have simultaneously valid pattern and name data at\r\nthe same location, so in such cases you will need to\r\nsacrifice particular name or pattern entries.\r\n\r\nIn text modes, you will need to load your own font into the\r\npattern table; the VDU does not provide one by default.\r\n\r\nSprites patterns are always 4bpp, even in the 2bpp mode.\r\nIn Graphics A, one half of VRAM is occupied by 512 2bpp\r\npatterns (for the background), and the other half by 256\r\n4bpp patterns for sprites. In Graphics B, the entirety\r\nof VRAM is occupied by just 512 4bpp patterns, with the\r\nupper half of those available to sprites.\r\n\r\nWhen scrolling horizontally, the leftmost background\r\ncolumn will not be displayed if it is partway offscreen,\r\na (mis)feature shared with the Sega Master System.\r\n\r\nUnlike most authentic 8-bit systems, any register or memory\r\nlocation may be changed in between scanlines, including the\r\nvertical scroll register and even the video mode. This\r\npermits fairly powerful split-screen effects.\r\n\r\nAlso unlike most authentic 8-bit systems, Retrograph uses a\r\npacked rather than a planar representation for pattern\r\ndata. Additionally, within each byte of pattern data, the\r\nleftmost pixels are in the least significant position,\r\nwhich may be backwards from what you expect.\r\n\r\nLastly, unlike a real 8-bit system, there is no deadline\r\nimposed on code running in between scanlines or in between\r\nframes. On real hardware, if you have code running\r\nin between scanlines (that is, during horizontal retrace)\r\nyou will only have a short period of time available before\r\nthe next scanline will begin rendering, whether or not you\r\nare finished what you are doing. However, such a\r\nlimitation would be very difficult to recreate in Ruby.\r\n\r\n== VDU Memory Map ==\r\n\r\n$0000 - $3FFF: VRAM (16 kbytes)\r\n$4000 - $7DFF: VRAM (mirror) (16 kbytes - 512 bytes)\r\n$7E00 - $7EFF: Sprite Table* (256 bytes)\r\n$7F00 - $7F0F: BG Palette (16 bytes)\r\n$7F10 - $7F1F: BG/Sprite Palette* (16 bytes)\r\n$7F20 - $7FF7: unused (216 bytes)\r\n$7FF8 - $7FFF: VDU Registers (8 bytes)\r\n $7FF8: Flags\r\n 4-7: unused\r\n 3: Enable Sprites*\r\n 2: Enable BG\r\n 0-1: Mode\r\n 00 - Text A (40x25)\r\n 01 - Text B (32x28)\r\n 10 - Graphics A (2bpp)\r\n 11 - Graphics B (4bpp)\r\n $7FF9: Pattern Table Base\r\n Text A + B:\r\n addr = (base & 0b00110000) << 8\r\n addr may be one of:\r\n $0000, $1000, $2000, or $3000\r\n Graphics A + B:\r\n addr = (base & 0b00100000) << 8\r\n addr may be one of:\r\n $0000 or $2000\r\n $7FFA: Name Table Base\r\n addr = ((base & 0b00110000) |\r\n 0b00001000) << 8\r\n addr may be one of:\r\n $0800, $1800, $2800, or $3800\r\n $7FFB: unused\r\n $7FFC: BG scroll X*\r\n $7FFD: BG scroll Y**\r\n $7FFE-7FFF: unused\r\n$8000 - $FFFF: mirror of $0000 - $7FFF\r\n\r\nNotes:\r\n *Ignored in text modes\r\n **In text modes, the lower 3 bits of the vertical scroll\r\n register are ignored and it wraps at 200 (Text A) or\r\n 224 (Text B)\r\n\r\n=== Pattern Table ===\r\n\r\nThe starting address of the pattern table is determined by\r\nregister $7FF9.\r\n\r\nThe rows constituting each pattern in the table are given\r\nin sequence from top to bottom. Within each byte, the\r\nleftmost pixel is in the least significant position. For\r\nexample, for a 4bpp tile, the following row would display\r\nwith the pixels of color 1 on the *left* side, and the\r\npixels of color 0 on the *right* side:\r\n\r\n 0x00001111\r\n\r\n(little-endian byte ordering is assumed)\r\n\r\nDifferent display modes have different pattern bit depths:\r\n\r\nText A: 256 patterns * 8 bytes per pattern = 2k\r\n 6x8 pixel patterns\r\n 1 byte per pattern row, 1 bit per pixel\r\n most significant 2 bits ignored\r\n\r\nText B: 256 patterns * 8 bytes per pattern = 2k\r\n 8x8 pixel patterns\r\n 1 byte per patern row, 1 bit per pixel\r\n\r\nGraphics A: 512 bg patterns * 16 bytes per pattern +\r\n 256 sprite patterns * 32 bytes/pattern = 16k\r\n 8x8 pixel patterns\r\n 2 bytes/pattern row, 2 bits/pixel (bg)\r\n 4 bytes/pattern row, 4 bits/pixel (sprites)\r\n\r\nGraphics B: 512 patterns * 32 bytes per pattern = 16k\r\n 8x8 pixel patterns\r\n 4 bytes/pattern row, 4 bits/pixel\r\n last 256 patterns shared with sprites\r\n\r\n=== Name Table ===\r\n\r\nThe starting address of the name table is determined by\r\nregister $7FFA.\r\n\r\nTable sizes:\r\n\r\n Text A: 40x25 characters * 2 bytes/character = 2000 bytes\r\n Text B: 32x28 characters * 2 bytes/character = 1792 bytes\r\n Graphics A + B: 32x32 tiles * 2 bytes per tile = 2k\r\n\r\nCell formats:\r\n\r\n Text: pppppppp bbbbffff\r\n p - pattern index\r\n f - foreground color\r\n b - background color\r\n\r\n Graphics: pppppppp -bhvcccP\r\n p - low byte of pattern index\r\n P - high bit of pattern index\r\n c - high bits of color\r\n h - horizontal flip\r\n v - vertical flip\r\n b - background priority\r\n\r\nIn graphics modes, the color is computed by taking the high\r\ncolor bits and oring them with the pattern color to get a\r\ncolor in the range 0-31 (with the upper 16 colors coming\r\nfrom the sprite palette):\r\n\r\n color = pattern_color | (high_bits << 2)\r\n\r\n(However, a pattern color of 0 is always transparent\r\nregardless of the high color bits.)\r\n\r\n=== Sprite Table ===\r\n\r\nSprite patterns start 2048 bytes after the pattern table\r\nbase address specified in register $7FF9. The sprite\r\ntable itself always begins at $7E00.\r\n\r\n4 bytes * 64 sprites = 256 bytes\r\n\r\nxxxxxxxx yyyyyyyy pppppppp --hvHVcc\r\n\r\n x - X position (left edge)\r\n y - Y position + 1 (top edge) (0 = hidden)\r\n p - pattern index\r\n h - horizontal flip\r\n v - vertical flip\r\n H - double size horizontally\r\n V - double size vertically\r\n c - high bits of color\r\n\r\nSprite colors are computed as follows:\r\n\r\n color = pattern_color | (high_bits << 2) | 16;\r\n\r\n(As with tiles, a pattern color of 0 is always transparent.)\r\n\r\n=== Palette Table ===\r\n\r\nThe palette table always begins at $7F00.\r\n\r\n1 byte * 32 colors (16 bg, 16 bg/sprite)\r\n\r\n--rrggbb\r\n\r\nr - red\r\ng - green\r\nb - blue\r\n\r\nNote that the first sprite color (color 16) is effectively\r\nnever used.\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}

0 comments on commit c828c4d

Please sign in to comment.