[Main]
Name=GrayAdjust
Type=Function
Subtype=Macro
Header Files=gray.h
Definition=void GrayAdjust (short adjustment);
Real Definition=#define GrayAdjust(x) ((void) (*(volatile unsigned char*)0x600013 = 128 - (signed char)(x)))

[Description]
Adjusts grayscale support to make it flickerless.

[Explanation]
<B>Note:</B> This function has become more or less obsolete since the effect is hardly
visible with the new HW2 grayscale support.
<BR><BR>
This function is introduced to improve grayscale support on HW2 calculators, i.e. to make
it more flickerless (it can be used on HW1 calculators too, but HW1 grayscale support is
usually satisfactorily flickerless by default). Namely, if the plane switching frequency is
not well synchronized with the LCD refresh frequency, the flickering may be too ugly.
Unfortunately, it is not possible to use hardwired values because this frequency drifts
with the battery strength, so a value which is good if the batteries are full is not good if the
batteries are worn out, and vice versa. So the only solution is to make the frequency ratio
adjustable. This trick was used in Universal OS by Julien Muchembled to produce quite
flickerless grayscale support on HW2 calculators (many thanks to him for telling to me about
this). His grayscale support allows adjusting the LCD refresh frequency (by changing the
logical height of the display) using the keys DIAMOND+LEFT/RIGHT.
<BR><BR>
This solution was a bit unflexible to me, so I decided to use slightly modified variant of
Julien's method.
I introduced the function GrayAdjust for fine adjusting of the grayscale quality. This
function does exactly the same as pressing DIAMOND+LEFT/RIGHT in Universal OS,
i.e. it adjusts the LCD refresh frequency. The default value for <I>adjustment</I> is 0, which
means "factory settings". Values less than 0 increases and values greater than 0 decreases
the LCD refresh frequency. Legal values for <I>adjustment</I> range from -28 to 127 on
TI-89 and from 0 to 127 on TI-92+ (although only slight variations around 0 are meaningful,
for example from -10 to +10). Note that values less than 0 are not allowed on the TI-92+, else
strange things would happen with the screen (use macros from <A HREF="$$LINK(compat.h/)">compat.h</A>
to check the calculator model).
<BR><BR>
So how would one use this function? You can put an option into your program which displays
a grayscale picture, and ask the user to adjust the quality. Here is a simplified example (called "Adjust Grayscale")
of the program which displays the full screen filled with dark gray, then allows adjusting the
quality using the <CODE>'+'</CODE> and <CODE>'-'</CODE> keys (use <CODE>'ESC'</CODE> for exit):
$$EXAMPLE(Adjust Grayscale.c)
This program does not have to be embedded in your program: as the LCD refresh frequency is kept
in the hardware register, it will still be valid after exiting from the program, so this
example may be used as a standalone adjusting program. However, the factory
settings are restored each time the calculator is turned on. If you embed the adjustment
code in your program, it is not a bad idea to use the same adjustment key as used in
Universal OS (DIAMOND+LEFT/RIGHT), due to conformance.  These keys may be checked
easily using pseudoconstants from the <A HREF="$$LINK(compat.h/)">compat.h</A> header file, as in
<PRE>if (key == KEY_DIAMOND + KEY_LEFT) ...
</PRE>
<B>Note:</B> Changing <I>adjustment</I>
also has influence to the lightness of the display, but you always can change the contrast
the usual way. Increasing <I>adjustment</I> makes the display lighter, and decreasing
it makes the display darker. Anyway, do not use this function for adjusting the display lightness.
Its purpose is just to estabilish precise synchronization.
