Genesis-Plus-GX/core/ntsc/sms_ntsc.txt

sms_ntsc 0.2.3: Sega Master System NTSC Video Filter
----------------------------------------------------
Author  : Shay Green <gblargg@gmail.com>
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 <gblargg@gmail.com>