/*---------------------------------------------------------------------------*

  Copyright (C) Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/

// gx2Display.h
//
// Declares display-related types & functions for gx2 library.

#ifndef _CAFE_GX2_DISPLAY_H_
#define _CAFE_GX2_DISPLAY_H_

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus
/*
 * These are aliases for the MOV APIs which are deprecated 
 */
#define GX2GetSystemMOVMode     GX2GetSystemDRCMode
#define GX2CalcMOVSize          GX2CalcDRCSize
#define GX2SetMOVBuffer         GX2SetDRCBuffer
#define GX2SetMOVScale          GX2SetDRCScale
#define GX2SetMOVGamma          GX2SetDRCGamma
#define GX2SetMOVEnable         GX2SetDRCEnable    

/// @addtogroup GX2DisplayGroup
/// @{

/// @addtogroup GX2DisplayInfoGroup
/// @{

// ----------------------------------------------------------------------
// 1. Describing the system-set TV output mode (read-only)

/// \brief Query current TV video output mode (set by system control panel).
///
/// \return Current TV video scan (output) mode (read-only)
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2TVScanMode GX2API GX2GetSystemTVScanMode(void);

/// \brief Query current TV aspect ratio (set by system control panel).
///
/// \return Current TV aspect ratio (read-only)
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2AspectRatio GX2API GX2GetSystemTVAspectRatio(void);

/// \brief Query if HDMI/Analog output setting for TV output is finished.
///
/// \return GX2_TRUE if Video setting done and ready for output, else GX2_FALSE.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2Boolean GX2API GX2IsVideoOutReady(void);

/// \brief Query current DRC output mode.
///
/// \note This function nominally checks for the number of attached DRCs.
///       It may also indicate if a single DRC is in 30Hz update mode,
///       if this mode had been configured previously (by calling \ref
///       GX2SetDRCBuffer).
///
/// \return Current DRC output mode 
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2DRCMode GX2API GX2GetSystemDRCMode(void);

/// \brief Query current DRC video scan mode.
///
/// \note This function indicates current DRC scan mode regardless the DRC connection status.
///       DRC scan mode is configured by GX2SetDRCBuffer to match with DRC render mode.
/// \return Current DRC scan mode 
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2DRCMode GX2API GX2GetSystemDRCScanMode(void);

#define GX2_DRC_DETACH 0 
#define GX2_DRC_ATTACH 1 

/// \brief The callback function that notifies DRC is connected or disconnected for the specified channel.
///
/// \param chan  DRC channel number is passed
/// \param reason  When DRC is connected, GX2_DRC_ATTACH is passed; at disconnection, GX2_DRC_DETACH is passed.
/// \note \#define GX2_DRC_DETACH 0
/// \note \#define GX2_DRC_ATTACH 1 
///
typedef void (*GX2DRCConnectCB) (s32 chan, s32 reason);

/// \brief Register the callback function that notifies whether DRC is connected/disconnected.
/// 
/// \note The disconnection event is notified when application releases foreground at process switch.
/// \note The callback function registered with this function is canceled at process switch. Application needs to re-register 
/// callback function when it gains foreground.
///
/// \param chan  DRC channel number.
/// \param callback  The callback function that notifies DRC attach for the specified channel.
///
/// \return Pointer to the most recently registered callback function
///
/// \donotcall \notcallback \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
///
GX2DRCConnectCB GX2API GX2SetDRCConnectCallback(s32 chan, GX2DRCConnectCB callback);

/// \brief Return info about current DRC scan-out status.
///
/// \note Normally, you do not need to use this function.  However, it can be helpful to
///       avoid glitches when transitioning from TV-only to TV+DRC display mode.
/// \note This function call returns the current status.  However, to use it correctly,
///       you must know the relationship between now and when a scan buffer flip will occur
///       (i.e., you must know the exact depth of the display pipeline).
/// 
/// \param pVcount Will return the DRC current vertical count.
/// \param pVphase Will return 0 or 1 indicating if in the 1st or 2nd field of a DRC 30hz mode.
///                Always returns 0 if DRC mode is 60hz.
///
/// \donotcall \fgonly \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetDRCVerticalInfo( u32 *pVcount, u32 *pVphase );

/// \brief Return whether or not GX2 is using 1/4-size scan buffers.
///
/// This happens when performing 60/50 pull-down and using 720p or larger scan buffers.
/// You must call \ref GX2SetTVBuffer before this function can return useful results.
///
/// \return GX2_TRUE if scale-down mode is enabled, GX2_FALSE otherwise.
///
/// \donotcall \fgonly \threadsafe \devonly \enddonotcall
///
GX2Boolean GX2GetScaleDownModeEnabled(void);

// ----------------------------------------------------------------------
// 2. Describing the desired output mode

/// \brief Function to calculate framebuffer size needed for TV.
///
/// It takes into account double/triple buffering, as well as
/// the desired surface format.  Besides returning the size,
/// it also returns a parameter indicating if an automatic 2:1
/// reduction will be performed during copy-out.
///
/// \note If the current TV scan mode is 480i or 576i, then the scan
///       buffer resolution cannot be higher than 1280x720.
///
/// \note The buffering mode option may be removed in future releases.
///       Only double scan buffers are supported at the moment.
///
/// \param tvRenderMode  Desired TV render mode to support.
/// \param fmt           Desired surface format to use.
/// \param bufferingMode Specifies double or triple buffering.
/// \param size          Ptr for value containing returned size.
/// \param scaleNeeded   Returns if 2:1 reduction is needed during copy-out.
///
/// \donotcall \fgonly \threadsafe \devonly \enddonotcall
///
void GX2API GX2CalcTVSize(GX2TVRenderMode tvRenderMode, GX2SurfaceFormat fmt,
                          GX2BufferingMode bufferingMode,
                          u32 *size, GX2Boolean *scaleNeeded);

/// \brief Function to calculate framebuffer size needed for DRC.
///
/// It takes into account double/triple buffering, as well as
/// the desired surface format.  Besides returning the size,
/// it also returns a parameter indicating if an automatic 2:1
/// reduction will be performed during copy-out (FYI).
///
/// \note The buffering mode option may be removed in future releases.
///       Only double scan buffers are supported at the moment.
///
/// \param mode          Desired DRC render mode to support.
/// \param fmt           Desired surface format to use.
/// \param bufferingMode Specifies double or triple buffering.
/// \param size          Ptr for value containing returned size.
/// \param scaleNeeded   Returns if 2:1 reduction is needed during copy-out.
///
/// \donotcall \fgonly \threadsafe \devonly \enddonotcall
///
void GX2API GX2CalcDRCSize(GX2DRCMode mode, GX2SurfaceFormat fmt,
                           GX2BufferingMode bufferingMode,
                           u32 *size, GX2Boolean *scaleNeeded);

/// @}
/// @addtogroup GX2DisplayConfigGroup
/// @{

// ----------------------------------------------------------------------
// 3. Passing in scan buffers

/// \brief Function to set up the framebuffers for use for TV.
///
/// Sets up all necessary GX2 state to use the given memory area for
/// double/triple frame buffer output.
/// Calling this requires fade-out/disable/change/enable/fade-in sequence.
/// (if called from start, video should already be black & disabled.)
/// These functions will adjust the Display Controller (DC) scaler/output
/// registers as needed.
///
///
/// \note The buffering mode option may be removed in future releases.
///       Only double scan buffers are supported at the moment.
///
/// \param buffer        Ptr to memory area used to store scan buffers.
/// \param size          Size of the memory area in bytes.
/// \param tvRenderMode  Desired TV render mode to support.
/// \param fmt           Desired surface format to use.
/// \param bufferingMode Specifies double or triple buffering.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetTVBuffer(void *buffer, u32 size, GX2TVRenderMode tvRenderMode,
                           GX2SurfaceFormat fmt, GX2BufferingMode bufferingMode);

/// \brief Function to set up the framebuffers for use for DRC.
///
/// Sets up all necessary GX2 state to use the given memory area for
/// double/triple frame buffer output.
/// Calling this requires fade-out/disable/change/enable/fade-in sequence.
/// (if called from start, video should already be black & disabled.)
/// These functions will adjust the Display Controller (DC) scaler/output
/// registers as needed.
///
/// DRC camera needs to be turned off before calling this API to avoid the display corruption.
///
/// \note The buffering mode option may be removed in future releases.
///       Only double scan buffers are supported at the moment.
///
/// \param buffer        Ptr to memory area used to store scan buffers.
/// \param size          Size of the memory area in bytes.
/// \param mode          Desired DRC render mode to support.
/// \param fmt           Desired surface format to use.
/// \param bufferingMode Specifies double or triple buffering.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetDRCBuffer(void *buffer, u32 size, GX2DRCMode mode,
                            GX2SurfaceFormat fmt, GX2BufferingMode bufferingMode);

// ----------------------------------------------------------------------
// 4. Other set up functions

/// \brief Function to call if app wants to vary effective framebuffer size for TV.
///
/// Size must be less than or equal to current mode, but greater than next lower mode.
/// (You must stay within 4:1 limit of the Display Controller (DC) scaler, but also within limit of what looks okay.)
/// These functions will adjust the DC scaler/output registers.
/// In all cases, the entire framebuffer (as specified by this API) is mapped to the entire display,
/// except when the output device is a 4:3 SDTV and the mode is 16:9.
/// In that case, the framebuffer rectangle is mapped to the 16:9 letterboxed portion.
///
/// \note This function should only be called when the output is not enabled.
///       Otherwise, you will see the image jitter during changes.
///
/// \param actualWidth  Width of scan buffer image
/// \param actualHeight Height of scan buffer image
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetTVScale(u32 actualWidth, u32 actualHeight);

/// \brief Function to call if app wants to vary effective framebuffer size for DRC.
///
/// Size must be less than or equal to DRC resolution.
/// (You must stay within 4:1 limit of the Display Controller (DC) scaler, but also within limit of what looks okay.)
/// These functions will adjust the DC scaler/output registers.
/// In all cases, the entire framebuffer (as specified by this API) is mapped to the entire display.
///
/// \note This function should only be called when the output is not enabled.
///       Otherwise, you will see the image jitter during changes.
///
/// \param actualWidth  Width of scan buffer image
/// \param actualHeight Height of scan buffer image
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetDRCScale(u32 actualWidth, u32 actualHeight);

/// \brief Function for adjusting the Display Controller (DC) gamma for TV.
///
/// Note that there are multiple ways to adjust gamma.  Be sure they are coordinated.
/// This API adjusts the display controller setting.
///
/// Note: This function sets the display pipeline's response to: I' = I^(1/gamma).
/// [Larger values yield a brighter result on the display.]
/// 
/// Note: When TV scan resolution is 576I, the scan buffer format must be 
/// 8bit(GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB or GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM),
/// otherwise changing gamma cause flicker.
///
/// System preferences define a value as well.  The given argument is multiplied
/// by the system preference value before it is applied in the display controller.
/// Thus, this value should just be a relative modifier rather than an absolute value.
///
/// Note: the final display gamma is set to :display gamma = system preference(1.0)/gamma
/// and it is made discrete by using the range (0.7f - 1.3f) with 0.05 steps as below.
/// gamma = 1.428571,  display_gamma = 0.70
/// gamma = 1.333333,  display_gamma = 0.75
/// gamma = 1.250000,  display_gamma = 0.80
/// gamma = 1.176471,  display_gamma = 0.85
/// gamma = 1.111111,  display_gamma = 0.90
/// gamma = 1.052631,  display_gamma = 0.95
/// gamma = 1.000000,  display_gamma = 1.00
/// gamma = 0.952381,  display_gamma = 1.05
/// gamma = 0.909091,  display_gamma = 1.10
/// gamma = 0.869565,  display_gamma = 1.15
/// gamma = 0.833333,  display_gamma = 1.20
/// gamma = 0.800000,  display_gamma = 1.25
/// gamma = 0.769231,  display_gamma = 1.30
///
/// \param gamma Gamma value to use. Must be positive. Typical range (0.7f, 1.3f).
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetTVGamma(f32 gamma);

/// \brief Query the current Display Controller (DC) gamma for TV.
///
/// This function indicates current DC gamma for TV.
/// Note: When application acquires foreground from process switching, 
/// DC gamma obtained with this API might be the value set by previous foreground process. 
/// The gamma is reverted to the application's gamma at the first flip to application's scan buffer.
/// To get the gamma set by the application before the first flip happens, 
/// please use GX2GetTVGammaEx API. 
//
/// \param  gamma         Ptr for value containing returned gamma.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetTVGamma(f32* gamma);

/// \brief Query current gamma for TV.
///
/// This function indicates gamma for TV which is set by the application.
/// Note: When application acquires foreground from process switching, 
/// the gamma obtained with this API is different from actual the Display Controller (DC) gamma. 
/// The gamma is reverted to the application's gamma at the first flip to application's scan buffer.
//
/// \param  gamma         Ptr for value containing returned gamma.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetTVGammaEx(f32* gamma);

/// \brief Query current Display Controller (DC) gamma for DRC.
///
/// This function indicates current DC gamma for DRC.
/// Note: When application acquires foreground from process switching, 
/// DC gamma obtained with this API might be the value set by previous foreground process. 
/// The gamma is reverted to the application's gamma at the first flip to application's scan buffer.
/// To get the gamma set by the application before the first flip happens, 
/// please use GX2GetDRCGammaEx API. 
//
/// \param  gamma         Ptr for value containing returned gamma.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetDRCGamma(f32* gamma);

/// \brief Query current gamma for DRC.
///
/// This function indicates gamma for DRC which is set by the application.
/// Note: When application acquires foreground from process switching, 
/// the gamma obtained with this API is different from actual the Display Controller (DC) gamma. 
/// The gamma is reverted to the application's gamma at the first flip to application's scan buffer.
//
/// \param  gamma         Ptr for value containing returned gamma.
///

/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetDRCGammaEx(f32* gamma);

/// \brief Function for adjusting the Display Controller (DC) gamma for DRC.
///
/// Note that there are multiple ways to adjust gamma.  Be sure they are coordinated.
/// This API adjusts the display controller setting.
///
/// Note: This function sets the display pipeline's response to: I' = I^(1/gamma).
/// [Larger values yield a brighter result on the display.]
///
/// System preferences define a value as well.  The given argument is multiplied
/// by the system preference value before it is applied in the display controller.
/// Thus, this value should just be a relative modifier rather than an absolute value.
///
/// Note: the final display gamma is set to :display gamma = system preference(1.0)/gamma
/// and it is made discrete by using the range (0.7f - 1.3f) with 0.05 steps as below.
/// gamma = 1.428571,  display_gamma = 0.70
/// gamma = 1.333333,  display_gamma = 0.75
/// gamma = 1.250000,  display_gamma = 0.80
/// gamma = 1.176471,  display_gamma = 0.85
/// gamma = 1.111111,  display_gamma = 0.90
/// gamma = 1.052631,  display_gamma = 0.95
/// gamma = 1.000000,  display_gamma = 1.00
/// gamma = 0.952381,  display_gamma = 1.05
/// gamma = 0.909091,  display_gamma = 1.10
/// gamma = 0.869565,  display_gamma = 1.15
/// gamma = 0.833333,  display_gamma = 1.20
/// gamma = 0.800000,  display_gamma = 1.25
/// gamma = 0.769231,  display_gamma = 1.30
///
/// \param gamma Gamma value to use. Must be positive. Typical range (0.7f, 1.3f).
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetDRCGamma(f32 gamma);

/// \brief Function to enable/disable the TV display (like VISetBlack).
///
/// Disabling the display tells the Display Controller (DC) to output black.
/// Disabling also disassociates the DC output from a frame buffer.
/// This function must be called when changing framebuffer modes.
/// Upon startup, the blank is released but this function must still be called to enable the DC. 
/// When GX2 releases foreground, it saves the last frame only when the DC is enabled. 
///
/// \warning This function must be called when application acquires foreground,
/// otherwise last frame will not be saved on next foreground release.
///
/// \param enable True to scan out video data to TV; false to output black.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetTVEnable(GX2Boolean enable);

/// \brief Function to enable/disable the DRC display (like VISetBlack).
///
/// Disabling the display tells the Display Controller (DC) to output black.
/// Disabling also disassociates the DC output from a frame buffer.
/// This function must be called when changing framebuffer modes.
/// Upon startup, the blank is released but this function must still be called to enable the DC. 
/// When GX2 releases foreground, it saves the last frame only when the DC is enabled. 
///
/// \warning This function must be called when application acquires foreground,
/// otherwise last frame will not be saved on next foreground release.
///
/// \param enable True to scan out video data to DRC(s); false to output black.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
void GX2API GX2SetDRCEnable(GX2Boolean enable);

/// @}
/// @addtogroup GX2DisplaySwapGroup
/// @{

// ----------------------------------------------------------------------
// 5. Copying & swapping buffers

// GX2SwapBuffers is now:

/// \brief Function to copy a render buffer surface to a scan buffer.
///
/// Call this once per available scan target per frame.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \param renderBuffer Ptr to color buffer structure containing final rendered image.
/// \param target The desired scan buffer target that should output the rendered image.
///
/// \donotcall \nomulticore \gx2_dl \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
/// \notincompute
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2CopyColorBufferToScanBuffer(const GX2ColorBuffer *renderBuffer,
                                           GX2ScanTarget target);

/// \brief Function to call after all copying done for this frame.
///
/// It swaps all configured displays (scan targets).
///
/// \donotcall \nomulticore \gx2_dl \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
/// \warning If a GPU hang condition is detected, this will call \ref GX2ResetGPU.
///
void GX2API GX2SwapScanBuffers(void);

/// \brief Get information about how many swaps/flips have happened and when
///        the last buffer flip and vsync occurred.
///
/// \note A "swap" in this context means a request was made.  A "flip" is when
///       the requested swap actually happens.  The swap is delayed according
///       to the swap interval and the vsync period.
///
/// Also see notes at \ref GX2SetSwapInterval.
///
/// \param pSwapCount     place to store number of times GX2SwapScanBuffers() was called
/// \param pFlipCount     place to store number of times buffer flip has happened
/// \param pLastFlipTime  place to store time that last flip happened
/// \param pLastVsyncTime place to store time that last vsync happened
///
/// \donotcall \fgonly \notthreadsafe \devonly \enddonotcall
///
void GX2API GX2GetSwapStatus(u32 *pSwapCount, u32 *pFlipCount,
                             OSTime *pLastFlipTime, OSTime *pLastVsyncTime);

/// \brief Wait until the next buffer flip happens.
///
/// \note If the flip happens while the thread is being put to sleep, then
///       the function will not return until the next vertical sync period.
///       Also, this function cannot detect GPU hangs.  It's suggested to
///       use \ref GX2WaitForVsync (in a check loop) instead.
///
/// \donotcall \nomulticore \gx2_typical \enddonotcall
///
void GX2API GX2WaitForFlip(void);

/// \brief Wait until the next vertical sync happens.
///
/// \donotcall \gx2_typical \enddonotcall
///
void GX2API GX2WaitForVsync(void);

/// \brief Set the interval for how quickly buffer flips may happen
///        (based on number of 60hz vsync intervals).
///
/// A value of 0 is valid, and it means to enable single buffering and
/// disable any waiting for vsync to occur.  In this mode, the flipCount
/// is still valid, but the LastFlipTime is no longer valid.
///
/// \note Before setting the swap interval to 0, you *must* configure all
/// scan buffers using \ref GX2SetTVBuffer() and/or \ref GX2SetDRCBuffer().
///
/// \note Warning: Setting GX2SetSwapInterval() to 0 should only be used for 
/// debugging. A swap interval of 0 is supported for immediate flipping. 
/// Use of this setting will cause tearing, and is also not compatible with 
/// PAL output. Do not set GX2SetSwapInterval() to 0 in game submissions.
///
/// \donotcall \gx2_typical \enddonotcall
///
void GX2API GX2SetSwapInterval(u32 swapInterval);

/// \brief Return the current setting for swap interval.
///
/// \donotcall \fgonly \threadsafe \devonly \enddonotcall
///
u32 GX2API GX2GetSwapInterval(void);

/// \brief A helper function to perform the most common swap operation.
///
/// (That is: copy the given render buffer to the TV, then swap.)
/// \note No waiting for the swap is performed here.  For that, use
/// \ref GX2WaitForFlip, \ref GX2WaitForVsync, and/or \ref GX2GetSwapStatus.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \param renderBuffer Ptr to color buffer structure containing final rendered image.
///
/// \donotcall \nomulticore \gx2_dl \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
/// \notincompute
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2SwapBuffers(const GX2ColorBuffer *renderBuffer)
{
    GX2CopyColorBufferToScanBuffer(renderBuffer, GX2_SCAN_TARGET_TV);
    GX2SwapScanBuffers();
}

/// \brief This API tells DRC hardware explicitly about motion vector changes or enforces I-frame refresh.
///
/// Some application like web browser or 2D action game knows how application behaves in temporal frames. In such case, application can tell motion vector to hardware directly and increase DRC image quality by decreasing unnecessary computations.
///
/// \param hint_bitmap indicate which hint is valid in this command.
/// \param motion_vector_x Cluster motion vector for X axis. Precision is per 4 pixels. Direction referenced from new position to the old frame.
/// \param motion_vector_y Cluster motion vector for Y axis. Precision is per 4 pixels. Direction referenced from new position to the old frame.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \directwritesgpu
///
GX2Boolean GX2API GX2SetVideoEncodingHint( GX2DRCEncodingHint hint_bitmap, s8  motion_vector_x, s8  motion_vector_y );

/// \brief Retrieves the last frame image displayed by the previous process.
///
/// This API is used to transition between apps, launchers, and the home-button menu.
/// Whenever GX2 transitions to the background from one process, it will save the last
/// rendered frames away.  The new process that comes into the foreground can then
/// retrieve those images using this API.  They can then be worked into a nice
/// transition sequence as the new app starts up.
///
/// Parameters are provided to indicate whether the TV or DRC image should be retrieved.
/// If no image was available from the previous process, this API will return false.
/// In an image is available, then the provided texture structure is filled out.
/// Note that the returned image will always be in GX2_TILE_MODE_LINEAR_ALIGNED.
///
/// Note that the size of the returned last frame varies depending on the render mode of the previous process and TV scan resolution. 
/// For example, when the system performs automatic 2:1 reduction during copy-out for 576I or 480I 4:3, the last frame size will be the 2:1 on horizontal and vertical.

/// \param target  Indicates whether TV or DRC image should be retrieved.
/// \param texture Pointer to structure that will be filled out with the appropriate data.
/// \return        Boolean indicating true if a frame was available, or false otherwise.
///
/// \donotcall \fgonly \threadsafe \notinterrupt \devonly \nomulticore \enddonotcall
///
GX2Boolean GX2API GX2GetLastFrame(GX2ScanTarget target, GX2Texture * texture);

/// \brief Retrieves gamma value of the last frame displayed by the previous process.
///
/// The new process that comes into the foreground can retrieve the gamma value of those images.  
/// Using the value retrieved by this API, application can apply reverse gamma when it use the last frame
/// image if the gamma value of the last frame is different from the gamma application is using.
/// Parameters are provided to indicate whether the TV or DRC image should be retrieved.
/// If no image was available from the previous process, this API will return false.
/// In an image is available, then the gamma value is filled out.
///
/// \param target  Indicates whether TV or DRC image should be retrieved.
/// \param gamma   Pointer to value that will be filled out with the appropriate data.
/// \return        Boolean indicating true if a gamma was available, or false otherwise.
///
/// \donotcall \fgonly \threadsafe \notinterrupt \nomulticore \devonly \enddonotcall
///
GX2Boolean GX2API GX2GetLastFrameGamma(GX2ScanTarget target, f32* gamma);

/// @}
/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _CAFE_GX2_DISPLAY_H_