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


short GrayMode (short mode);

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.

short IsGrayMode (void);

Checks whether the grayscale mode is active.

IsGrayMode returns TRUE if the grayscale mode is active, else returns FALSE.

void *GetPlane (short plane);

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!

void SetPlane (short plane);

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.

void GrayAdjust (short adjustment);

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


enum Bool

Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};

enum GrayModes

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};

enum GrayPlanes

GrayPlanes is enumerated type for describing legal grayscale planes. It is defined as
enum GrayPlanes {LIGHT_PLANE, DARK_PLANE};

Return to the main index