[Main]
Name=GrayOn
Type=Function
Subtype=tigcc.a
Header Files=gray.h
Definition=short GrayOn (void);
See Also=gray.h/GrayOff, gray.h/GrayOnThrow

[Library Call]
Asm=1

[Description]
Activates grayscale mode with four shades of gray.

[Explanation]
GrayOn activates grayscale mode. This works on both hardware version 1 and 2
calculators because the calculator type is detected automatically.
See <A HREF="$$LINK(gray.h/GrayAdjust)">GrayAdjust</A> for information on how to reduce flickering
on HW2 calculators as much as possible.
<BR><BR>
The <A HREF="$$LINK(gray.h/GrayMode)">GrayMode</A> function as well as the constants defined in the enum <A HREF="$$LINK(gray.h/GrayModes)">GrayModes</A> still exist
to maintain compatibility with programs written before TIGCC v0.91. In fact, <A HREF="$$LINK(gray.h/GrayMode)">GrayMode</A> is
now defined as a macro which optimizes into a call to GrayOn or <A HREF="$$LINK(gray.h/GrayOff)">GrayOff</A> if you call it with
a constant value.
<BR><BR>
GrayOn returns <A HREF="$$LINK(alloc.h/Bool)">FALSE</A> if there was an error in switching to grayscale
mode, otherwise it returns <A HREF="$$LINK(alloc.h/Bool)">TRUE</A>. Don't forget to switch off grayscale mode
before your program terminates, or your TI will crash very soon!
<BR><BR>
Here is an example of a program for testing grayscale mode (called "Gray Test Project"), which displays 3 squares on the
screen, each with a different level of gray (see other functions from this header file and
from the <A HREF="$$LINK(graph.h/)">graph.h</A> header file for an explanation about how it works):
$$EXAMPLE(Gray Test.c)
Starting from release 2.2 of the library, it is safe to call GrayOn
even if grayscale mode is already on, and to call <A HREF="$$LINK(gray.h/GrayOff)">GrayOff</A>
even if grayscale mode is already off.

[References]
Out=alloc.h/HeapAllocHigh, alloc.h/HeapDeref, graph.h/PortSet
In=gray.h/GrayMode, gray.h/GrayOnThrow
