sms_ntsc 0.2.3: Sega Master System NTSC Video Filter ---------------------------------------------------- Author : Shay Green Website : http://www.slack.net/~ant/ Forum : http://groups.google.com/group/blargg-sound-libs License : GNU Lesser General Public License (LGPL) Language: C or C++ Overview -------- To perform NTSC filtering, first allocate memory for a sms_ntsc_t object and call sms_ntsc_init(), then call sms_ntsc_blit() to perform filtering. You can call sms_ntsc_init() at any time to change image parameters. By default, sms_ntsc_blit() reads and writes pixels in 16-bit RGB. Edit sms_ntsc_config.h to change this. RGB Palette Generation ---------------------- A 4096-color RGB palette can be generated for use in a normal blitter. In your sms_ntsc_setup_t structure, point palette_out to a 12288-byte buffer (4096 * 3) to hold the palette, then call sms_ntsc_init(). If you only need the palette and aren't going to be using the NTSC blitter, pass 0 for the first parameter. Image Parameters ---------------- Many image parameters can be adjusted and presets are provided for composite video, S-video, RGB, and monochrome. Most are floating-point values with a general range of -1.0 to 1.0, where 0 is normal. The ranges are adjusted so that one parameter at an extreme (-1 or +1) and the rest at zero shouldn't result in any internal overflow (garbage pixels). Setting multiple parameters to their extreme can produce garbage. Put another way, the state space defined by all parameters within the range -1 to +1 is not fully usable, but some extreme corners are very useful so I don't want to reduce the parameter ranges. The sharpness and resolution parameters have similar effects. Resolution affects how crisp pixels are. Sharpness merely enhances the edges by increasing contrast, which makes things brighter at the edges. Artifacts sets how much "junk" is around the edges where colors and brightness change in the image, where -1 completely eliminates them. (Color) bleed affects how much colors blend together and the artifact colors at the edges of pixels surrounded by black. (Color) fringing affects how much color fringing occurs around the edges of bright objects, especially white text on a black background. When using custom settings, initialize your sms_ntsc_setup_t using one of the standard setups before customizing it. This will ensure that all fields are properly initialized, including any added in future releases of the library that your current code can't even know about. sms_ntsc_setup_t setup; setup = sms_ntsc_composite; /* do this first */ setup.sharpness = custom_sharpness; sms_ntsc_init( ntsc, &setup ); Image Size ---------- For proper aspect ratio, the image generated by the library must be doubled vertically. Use the SMS_NTSC_OUT_WIDTH() and SMS_NTSC_IN_WIDTH() macros to convert between input and output widths that the blitter uses. For example, if you are blitting an image 256 pixels wide, use SMS_NTSC_OUT_WIDTH( 256 ) to find out how many output pixels are written per row. Another example, use SMS_NTSC_IN_WIDTH( 640 ) to find how many input pixels will fit within 640 output pixels. Custom Blitter -------------- You can write your own blitter, allowing customization of how input pixels are obtained, the format of output pixels (15, 16, or 32-bit RGB), optimizations for your platform, and additional effects like efficient scanline doubling during blitting. Macros are included in sms_ntsc.h for writing your blitter so that your code can be carried over without changes to improved versions of the library. The default blitter at the end of sms_ntsc.c shows how to use the macros. Contact me for further assistance. The SMS_NTSC_BEGIN_ROW macro allows starting up to three pixels. The first pixel is cut off; its use is in specifying a background color other than black for the sliver on the left edge. The next two pixels can be used to handle the extra one or two pixels not handled by the main chunks of three pixels. For example if you want to blit 257 input pixels on a row (for whatever odd reason), you would start the first two with SMS_NTSC_BEGIN_ROW( ... sms_ntsc_black, line_in [0], line_in [1] ), then do the remaining 255 in chunks of three (255 is divisible by 3). Limitations ----------- The library's horizontal rescaling is too wide by about 3% in order to allow a much more optimal implementation. This means that a 248 pixel wide input image should appear as 563 output pixels, but with this library appears as 581 output pixels. TV aspect ratios probably vary by this much anyway. If you really need unscaled output, contact me and I'll see about adding it. Thanks ------ Thanks to NewRisingSun for his original code and explanations of NTSC, which was a starting point for me learning about NTSC video and decoding. Thanks to the Nesdev forum for feedback and encouragement. Thanks to Martin Freij (Nestopia author) and Charles MacDonald (SMS Plus author) for significant ongoing testing and feedback as the library has improved. Thanks to byuu (bsnes author) and pagefault (ZSNES team) for feedback about the SNES version. -- Shay Green