The <gray.h> header file
This header file contains the following functions:
GetPlane GrayAdjust GrayMode IsGrayMode
SetPlane
and the following predefined types:
Bool GrayModes GrayPlanes
Functions
Activates or deactivates grayscale mode.
GrayMode activates or deactivates grayscale mode. Possible values of parameter mode
are (these constants are defined in enum GrayModes):
GRAY_OFF |
Turns off the grayscale mode (i.e. switch to the standard black-and-white mode) |
GRAY_ON |
Turns on 4-level grayscale mode, which works on both Hardware Release 1 and 2
calculators (autodetecting is performed). See GrayAdjust for information
how to reduce flickering on HW2 calculators as much as possible.
|
Constants GRAY_HW1 and GRAY_HW2 introduced in tigcclib release 1.1 still exist,
but they are now both equivalent to GRAY_ON (GrayMode now performs autodetection
of hardware version).
GrayMode returns FALSE if there was an error in switching to grayscale
mode, else returns TRUE. Don't forget to switch off the grayscale mode
before the end of the program, else your TI will crash very soon after the program
terminates!
Here is an example of a program for testing grayscale mode, which displays 3 squares on the
screen, each with different level of gray (see other functions from this header file and
from graph.h header file for explanation how it works):
#define SAVE_SCREEN
#include <tigcclib.h>
int _ti89;
void _main(void)
{
if (!GrayMode (GRAY_ON)) return;
SetPlane (LIGHT_PLANE);
ClrScr ();
ScrRectFill (&(SCR_RECT){{20, 20, 40, 40}}, ScrRect, A_NORMAL);
ScrRectFill (&(SCR_RECT){{80, 20, 100, 40}}, ScrRect, A_NORMAL);
SetPlane (DARK_PLANE);
ClrScr ();
ScrRectFill (&(SCR_RECT){{50, 20, 70, 40}}, ScrRect,A_NORMAL);
ScrRectFill (&(SCR_RECT){{80, 20, 100, 40}}, ScrRect,A_NORMAL);
ngetchx ();
GrayMode (GRAY_OFF);
}
Starting from release 2.2, it is safe to call GrayMode (GRAY_ON)
even if the grayscale mode is already on, and to call GrayMode (GRAY_OFF)
even if the grayscale mode is already off.
Checks whether the grayscale mode is active.
IsGrayMode returns TRUE if the grayscale mode is active, else returns
FALSE.
Gets the address of the gray video plane.
GetPlane returns a pointer to the video plane plane. Valid values are
LIGHT_PLANE and DARK_PLANE
(to draw in black, draw in both planes).
NOTE: Do not assume that any plane is on 0x4C00 when use grayscale mode, due to
hardware version 2 support!
Forces graph routines to use selected plane.
SetPlane forces all graphic routines (from graph.h) to draw into
video plane plane (valid values are LIGHT_PLANE and
DARK_PLANE). So, you can use standard routines for drawing lines, circles
etc. in grayscale mode too.
NOTE: SetPlane is a macro which calls PortSet. There
was a bug in tigcclib release 1.1 which does not allow usage of this macro in "Doors"
mode. This is now fixed.
Adjust grayscale support to make it flickerless.
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 satisfactory 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 these frequences drift
with the battery strength, so value which is good if the batteries are good is not good if the
batteries are not good, and vice versa. So, the only solution is to make frequency ratio
adjustable. This trick is 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 keys DIAMOND+LEFT/RIGHT.
Such solution was a bit unflexible
to me, so I decided to use slightly modified variant of Julien's method.
I indroduced function GrayAdjust for fine adjusting of grayscale quality. This
function does exactly the same thing as pressing DIAMOND+LEFT/RIGHT in the Universal OS,
i.e. adjusts the LCD refresh frequency. Default value for adjustment is 0, which
means "factory settings". Values less than 0 increases and values greater than 0 decreases
the LCD refresh frequency. Legal values for adjustment are 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 TI-92+, else
strange things would happen with the screen (use macros from compat.h
to check the calculator model).
So, how to use this function? You can put into your program an option which would display
a grayscale picture, and to ask user to adjust the quality. Here is a simplified example
of the program which displays the full screen filled with dark gray, then allows adjusting the
quality using '+'
and '-'
keys (use 'ESC'
for exit):
#define SAVE_SCREEN
#include <tigcclib.h>
int _ti89, _ti92plus;
void _main (void)
{
int key, value = 0;
if (!GrayMode (GRAY_ON)) return;
GrayAdjust (value);
memset (GetPlane (DARK_PLANE), 255, LCD_SIZE); // Fill the dark plane and
memset (GetPlane (LIGHT_PLANE), 0, LCD_SIZE); // clear the light plane
while ((key = ngetchx ()) != KEY_ESC)
{
if (key == '+' && value < 127) value++;
if (key == '-' && value > (TI89 ? -28 : 0)) value--;
GrayAdjust(value);
}
GrayMode(GRAY_OFF);
}
This program need not to be embedded in your program: as 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 bad idea to use the same adjustment key as used in
the Universal OS (DIAMOND+LEFT/RIGHT), due to uniqueness. These keys may be checked
easily using pseudoconstants from compat.h header file, as in
if (key == KEY_DIAMOND + KEY_LEFT) ...
NOTE: Changing adjustment
also has influence to the lightness of the display (but you always can change the contrast
using usual way). Increasing adjustment makes the display lighter, and decreasing
it makes the display darker. Anyway, do not use this function for adjusting the display lightness. It purpose is just to
estabilish the precise synchronization.
Predefined types
Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};
GrayModes is enumerated type for describing legal grayscale modes. It is defined as
enum GrayModes {GRAY_OFF, GRAY_ON = 1, GRAY_HW1 = 1, GRAY_HW2 = 1};
GrayPlanes is enumerated type for describing legal grayscale planes. It is defined as
enum GrayPlanes {LIGHT_PLANE, DARK_PLANE};