/*
 * System Interface Library for games
 * Copyright (c) 2007-2020 Andrew Church <achurch@achurch.org>
 * Released under the GNU GPL version 3 or later; NO WARRANTY is provided.
 * See the file COPYING.txt for details.
 *
 * src/debug.h: Internal header for debugging routines.
 */

#ifndef SIL_SRC_DEBUG_H
#define SIL_SRC_DEBUG_H

#include "SIL/debug.h"  // Include the public header.

#ifdef DEBUG  // To the end of the file.

/*************************************************************************/
/*************************************************************************/

/* Constants for debug_cpu_record_phase(). */
typedef enum DebugCPUPhase {
    /* Time spent actively making render calls. */
    DEBUG_CPU_RENDER_START = 0,
    DEBUG_CPU_RENDER_END,
    /* Time spent on non-render processing (anything between
     * graphics_finish_frame() and the next graphics_start_frame()). */
    DEBUG_CPU_PROCESS_START,
    DEBUG_CPU_PROCESS_END,
    /* Time spent waiting for the graphics hardware to finish performing
     * all commands from the previous frame. */
    DEBUG_CPU_GPU_WAIT_START,
    DEBUG_CPU_GPU_WAIT_END,
} DebugCPUPhase;

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

/**
 * debug_init:  Initialize the debug interface.  This function always
 * succeeds.
 */
extern void debug_init(void);

/**
 * debug_cleanup:  Clean up debug interface resources.
 */
extern void debug_cleanup(void);

/**
 * debug_record_cpu_phase:  Indicate that processing has entered the given
 * phase.  These functions are called by graphics_start_frame() and
 * graphics_finish_frame() to record CPU usage information.
 *
 * In order for the debug interface to function properly, this function
 * _must_ be called with DEBUG_CPU_RENDER_END immediately before
 * terminating rendering for the current frame.
 *
 * [Parameters]
 *     phase: DEBUG_CPU_* constant indicating state change to record.
 */
extern void debug_record_cpu_phase(DebugCPUPhase phase);

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

#ifdef SIL_INCLUDE_TESTS

/**
 * TEST_debug_set_frame_period:  Set the frame period used by the CPU meter.
 *
 * [Parameters]
 *     period: Frame period to use, or 0 to use the system frame period.
 */
extern void TEST_debug_set_frame_period(float period);

/**
 * TEST_debug_capture_frame:  Capture the specified portion of the display
 * after performing all debug rendering for the current frame.  If called
 * multiple times during the same frame, only the last call is honored.
 * Sample usage:
 *
 *     TEST_debug_capture_frame(0, 0, width, height, pixels);
 *     graphics_finish_frame();
 *     // Pixel data is now valid.
 *
 * This serves as a substitute for graphics_read_pixels() in debug
 * interface tests, since that function cannot reliably be used after
 * graphics_finish_frame() but graphics_finish_frame() must be called to
 * trigger debug rendering.
 *
 * This function is only defined when tests are included.
 *
 * [Parameters]
 *     x, y, w, h: Display region to capture (like graphics_read_pixels()).
 *     pixels: Pixel buffer into which to store captured data, or NULL to
 *         cancel a pending capture.
 */
extern void TEST_debug_capture_frame(int x, int y, int w, int h, void *pixels);

#endif  // SIL_INCLUDE_TESTS

/*************************************************************************/
/*************************************************************************/

#endif  // DEBUG
#endif  // SIL_SRC_DEBUG_H