diff --git a/include/coreinit/screen.h b/include/coreinit/screen.h index 515266e..421f3c1 100644 --- a/include/coreinit/screen.h +++ b/include/coreinit/screen.h @@ -4,6 +4,35 @@ /** * \defgroup coreinit_screen Screen * \ingroup coreinit + * + * + * Software-rendered graphics system, suitable for text output and simple + * graphics. + * + * OSScreen is much more straightforward than GX2, which makes it appealing for + * situations that do not require complex graphics. It can draw text and pixels + * (one at a time!) to both the Gamepad and TV. + * + * To use OSScreen, first call \link OSScreenInit \endlink. Then, allocate a + * memory area and pass it to OSScreen with \link OSScreenSetBufferEx \endlink - + * after enabling the screens with \link OSScreenEnableEx \endlink, the library + * will be ready to draw! Drawing is accomplished with \link + * OSScreenClearBufferEx \endlink, \link OSScreenPutFontEx \endlink and \link + * OSScreenPutPixelEx \endlink. Once drawing is complete, call \link + * OSScreenFlipBuffersEx \endlink to show the results on-screen. Rinse and + * repeat! + * + * * @{ */ @@ -11,44 +40,187 @@ extern "C" { #endif +//! Defines the ID of a display usable with OSScreen. typedef enum OSScreenID { + //! Represents the TV connected to the system. SCREEN_TV = 0, + //! Represents the screen in the DRC (gamepad). SCREEN_DRC = 1, } OSScreenID; +/** + * Initialises the OSScreen library for use. This function must be called before + * using any other OSScreen functions. + * + * \sa + */ void OSScreenInit(); +/** + * Cleans up and shuts down the OSScreen library. + * + * \sa + */ void OSScreenShutdown(); +/** + * Gets the amount of memory required to fit both buffers of a given screen. + * + * \param screen + * The ID of the screen to be sized. + * + * \sa + */ uint32_t OSScreenGetBufferSizeEx(OSScreenID screen); +/** + * Sets the memory location for both buffers of a given screen. This location + * must be of the size prescribed by \link OSScreenGetBufferSizeEx \endlink and + * at an address aligned to 0x100 bytes. + * + * \param screen + * The ID of the screen whose memory location should be changed. + * + * \param addr + * Pointer to the memory to use. This area must be 0x100 aligned, and of the + * size given by \link OSScreenGetBufferSizeEx \endlink. + * + * \sa + */ void OSScreenSetBufferEx(OSScreenID screen, void *addr); +/** + * Clear the work buffer of the given screen by setting all of its pixels to + * a given colour. + * + * \param screen + * The ID of the screen to clear. Only the work buffer will be cleared. + * + * \param colour + * The colour to use, in big-endian RGBX8 format - 0xRRGGBBXX, where X bits are + * ignored. + * + * \note + * Since this function only affects the work buffer, its effect will + * not appear on screen immediately. See \link OSScreenFlipBuffersEx \endlink. + * + * \sa + * + * + */ void OSScreenClearBufferEx(OSScreenID screen, uint32_t colour); +/** + * Swap the buffers of the given screen. The work buffer will become the visible + * buffer and will start being shown on-screen, while the visible buffer becomes + * the new work buffer. This operation is known as "flipping" the buffers. + * + * You must call this function once drawing is complete, otherwise draws will + * not appear on-screen. + * + * \param screen + * The ID of the screen to flip. + */ void OSScreenFlipBuffersEx(OSScreenID screen); +/** + * Draws text at the given position. The text will be drawn to the work + * buffer with a built-in monospace font, coloured white, and anti-aliased. + * The position coordinates are in characters, not pixels. + * + * \param screen + * The ID of the screen to draw to. Only the work buffer will be affected. + * + * \param row + * The row, in characters, to place the text in. 0 corresponds to the top of + * the screen. + * + * \param column + * The column, in characters, to place the text at. 0 corresponds to the left of + * the screen. + * + * \param buffer + * Pointer to the string of text to draw. Null-terminated. + * + * \note + * Since this function only affects the work buffer, its effect will + * not appear on screen immediately. See \link OSScreenFlipBuffersEx \endlink. + * + * \sa + */ void OSScreenPutFontEx(OSScreenID screen, uint32_t row, uint32_t column, const char *buffer); +/** + * Draws a single pixel at the given position. The pixel, a 32-bit RGBX + * colour, will be placed in the work buffer at the coordinates given. + * + * \param screen + * The ID of the screen to place the pixel in. + * + * \param x + * The x-coordinate, in pixels, to draw the pixel at. + * + * \param y + * The y-coordinate, in pixels, to draw the pixel at. + * + * \param colour + * The desired colour of the pixel to draw, in RGBX32 colour (0xRRGGBBXX, where + * the XX value is ignored). + * + * \note + * Since this function only affects the work buffer, its effect will + * not appear on screen immediately. See \link OSScreenFlipBuffersEx \endlink. + * + * \sa + */ void OSScreenPutPixelEx(OSScreenID screen, uint32_t x, uint32_t y, uint32_t colour); +/** + * Enables or disables a given screen. If a screen is disabled, it shows black. + * + * \param screen + * The ID of the screen to enable or disable. + * + * \param enable + * \c true if the screen should be enabled, otherwise false. + */ void OSScreenEnableEx(OSScreenID screen, BOOL enable);