# PM_SetLCDPower

## Syntax

      #include <nitro/spi.h>

      BOOL PM_SetLCDPower( PMLCDPower sw );

## Arguments

sw | LCD switch.

## Return Values

Returns `TRUE` if successful.

Returns `FALSE` if the attempt to turn ON the LCD fails. The failure occurs if an attempt is made to turn ON the LCD before 100 ms have elapsed since the LCD was turned OFF.

## Description

Toggles the LCD switch.

The sw argument is the LCD switch. This argument is a `PMLCDPower` enumerator type that can contain either one of the following values.

Value of sw | LCD Operation
--- | ---
`PM_LCD_POWER_ON` | Turns the LCD switch ON.
`PM_LCD_POWER_OFF` | Turns the LCD switch OFF.

Because of hardware restrictions, you cannot turn ON the LCD until at least approximately 100 ms have passed since it was turned OFF. If you attempt to switch the LCD ON before a sufficient amount of time has passed since the last time the LCD was turned OFF, nothing happens, and this function returns `FALSE`. After a sufficient amount of time has passed and the LCD can be successfully turned ON, this function returns `TRUE`. Note that this restriction does not apply when going from ON to OFF. This function always returns `TRUE`.
The `GX_DispOff` function must be called in advance when `PM_LCD_POWER_OFF` is specified as the sw argument and the LCD is switched off. If the `GX_DispOff` function is not called beforehand in this function, it is called internally automatically. Note, however, that a wait time equal to two V-blanks occurs.
(See Interval After the Screen Is Turned OFF by the GX_DispOff Function.)
For this reason, note that the `GX_DispOn` function must be called separately when setting `LCD ON` after `LCD OFF`.

The `GX_DispOn` function must be called before the LCD switch is turned off, but this restriction does not apply to the `GXS_DispOn` function. (However, applications will probably turn the upper and lower screen displays on or off at the same time.)

This function internally calls several PM functions. It continues calling these PM functions until they succeed. If another device is occupying the SPI and it is BUSY for a long time, there is sometimes a delay in returning control from this function.

This function can be used from an interrupt handler. This function cannot be used in interrupt-prohibited states other than interrupt handlers.

### Interval After the Screen Is Turned OFF by the GX_DispOff Function

If the time from turning the display OFF (using the `GX_DispOff` function) to the point where this function cuts power off to the LCD module (using `PM_SetLCDPower( PM_LCD_POWER_OFF )`) is two frames or less (if the time is not exactly two V-blanks), specifications call for a wait of two V-blanks to prevent ghosting the next time the display is turned OFF.
Therefore, be sure to note the point that the system waits exactly two V-blanks if the application itself does not call the `GX_DispOff` function before calling this function.

### Regarding Sound When the LCD Is OFF

When the LCD is turned OFF, the power supply to the sound amp also turns OFF, so sound no longer emits from the speakers. However, if headphones were inserted while the LCD was ON and the LCD is then turned OFF, it is possible to hear sound from the headphones. Note that on TWL, headphone audio output is guaranteed even if the headphone jack is inserted while the LCD is OFF. This is not true for NITRO. (For details, see the notes for each type of power control in the programming guidelines.)

## Internal Operation

Accesses the `GX_POWCNT` register to toggle the LCD switch.

## See Also

`PM_Init`
`PM_GetLCDPower`

## Revision History

2009/06/03 Removed a description of the `PM_Init` function (because `OS_Init` is now required).
2009/04/13 Added information on the `GXS_DispOff` function.
2009/02/03 Added a description of processing when the LCD is switched from OFF to ON.
2009/01/16 Revised an explanation related to calling the `GX_DispOff` function.
2009/01/13 Revised text to say that the `GX_DispOff` function should be called before the LCD is turned off.
2008/12/05 Added a note related to use when interrupts are prohibited.
2008/11/02 Added a note about sound.
2008/08/23 Clarified the possibility of delays while BUSY.
2008/06/25 Added a description of the time interval with the `GX_DispOff` function.
2008/03/18 Deleted a description of the LED state.
2004/09/17 Changed a description of the LED state.
2004/08/07 Initial version.

CONFIDENTIAL