[ANN] retrograph-0.5

=3D=3D What is Retrograph? =3D=3D

Retrograph is a Ruby library which emulates the video
display unit from a hypothetical late-80s 8-bit game
console.  It is similar in capability to the Sega Master
System's VDP, with some additional features and direct
support for text modes.

Retrograph doesn't do its own screen output but rather
works with other libraries.  Currently, it supports
Ruby/SDL, but other output targets are planned for the
future.

=3D=3D Where can I get it? =3D=3D

Retrograph is available via RubyGems, or via Rubyforge
downloads:

 http://rubyforge.org/frs/?group_id=3D8410

Cursory documentation is available on the
corresponding github wiki:

 http://wiki.github.com/mental/retrograph

=3D=3D Feature Overview =3D=3D

 * 256x244 pixel display
 * 16k VRAM
 * 64 colors total
 * max 31 simultaneous colors (16 background, 15 sprite)
 * 40x25 and 32x28 text modes
 * 32x32 tile background, 8x8 pixel tiles
 * 64 8x8 sprites, max 8 per scanline

=3D=3D Usage =3D=3D

Retrograph's simulated Video Display Unit (or VDU) is
represented by an instance of the Retrograph::VDU class.
You can interact with the VDU by writing byte strings
into its memory using Retrograph::VDU#write, which takes
a start address (in the VDU's 16-bit address space) and
a string to write.  The method Retrograph::VDU#write_byte
is also provided for writing individual bytes.

(See the wiki for a map of memory locations.)

To render a frame of video with SDL, use
Retrograph::VDU#render_frame_sdl, which returns an
SDL::Surface containing the VDU output.  The returned
surface remains valid until the next call to
Retrograph::VDU#render_frame_sdl on the same VDU instance.

Scanline-based effects are possible if you provide a block
to Retrograph::VDU#render_frame_sdl.  Ordinarily, rendering
will not begin until the block completes, but within the
block you can call Retrograph::VDU#wait_scanlines to render
a given number of scanlines before continuing.  This allows
you to make changes to the VDU state part-way through
rendering a frame.

For example, if we wanted palette entry 0 to be blue within
the top half of the display and red within the bottom half
of the display, we could write:

 require 'retrograph/sdl'

 vdu.write_byte(0x7f00, 0x03)
 output =3D vdu.render_frame_sdl do
   vdu.wait_scanlines(Retrograph::DISPLAY_HEIGHT/2)
   vdu.write_byte(0x7f00, 0x30)
 end

(For display, is still necessary at this point to copy the
output surface to the screen.)

Love,
-mental