! \ingroup Initialization
  @{

! \ingroup Initialization
 Important GPU features which may not be supported depending on a device's extension support.  Can be bitwise OR'd together.
 \see GPU_IsFeatureEnabled()
 \see GPU_SetRequiredFeatures()

!
 \defgroup Initialization Initialization
 \defgroup Logging Debugging, Logging, and Error Handling
 \defgroup RendererSetup Renderer Setup
 \defgroup RendererControls Renderer Controls
 \defgroup ContextControls Context Controls
 \defgroup TargetControls Target Controls
 \defgroup SurfaceControls Surface Controls
 \defgroup ImageControls Image Controls
 \defgroup Conversions Surface, Image, and Target Conversions
 \defgroup Matrix Matrix Controls
 \defgroup Rendering Rendering
 \defgroup Shapes Shapes
 \defgroup ShaderInterface Shader Interface
! \ingroup Rendering
 A struct representing a rectangular area with floating point precision.
 \see GPU_MakeRect()

! \ingroup Initialization
 \ingroup RendererSetup
 \ingroup RendererControls
 Renderer ID object for identifying a specific renderer.
 \see GPU_MakeRendererID()
 \see GPU_InitRendererByID()

! \ingroup ImageControls
 Blend mode storage struct

! \ingroup ImageControls
 Image object for containing pixel/texture data.
 A GPU_Image can be created with GPU_CreateImage(), GPU_LoadImage(), GPU_CopyImage(), or GPU_CopyImageFromSurface().
 Free the memory with GPU_FreeImage() when you're done.
 \see GPU_CreateImage()
 \see GPU_LoadImage()
 \see GPU_CopyImage()
 \see GPU_CopyImageFromSurface()
 \see GPU_Target

! \ingroup ImageControls
 A backend-neutral type that is intended to hold a backend-specific handle/pointer to a texture.
 \see GPU_CreateImageUsingTexture()
 \see GPU_GetTextureHandle()

! \ingroup TargetControls
 Camera object that determines viewing transform.
 \see GPU_SetCamera()
 \see GPU_GetDefaultCamera()
 \see GPU_GetCamera()

! \ingroup ShaderInterface
 Container for the built-in shader attribute and uniform locations (indices).
 \see GPU_LoadShaderBlock()
 \see GPU_SetShaderBlock()

! \ingroup Matrix
 Matrix stack data structure for global vertex transforms.

! \ingroup ContextControls
 Rendering context data.  Only GPU_Targets which represent windows will store this.

! \ingroup Initialization
 Important GPU features which may not be supported depending on a device's extension support.  Can be bitwise OR'd together.
 \see GPU_IsFeatureEnabled()
 \see GPU_SetRequiredFeatures()

! \ingroup Initialization
 Initialization flags for changing default init parameters.  Can be bitwise OR'ed together.
 Default (0) is to use late swap vsync and double buffering.
 \see GPU_SetPreInitFlags()
 \see GPU_GetPreInitFlags()

! \ingroup Rendering
 Primitive types for rendering arbitrary geometry.  The values are intentionally identical to the GL_ primitives.
 \see GPU_PrimitiveBatch()
 \see GPU_PrimitiveBatchV()

! Bit flags for geometry batching.
 \see GPU_TriangleBatch()
 \see GPU_TriangleBatchX()
 \see GPU_PrimitiveBatch()
 \see GPU_PrimitiveBatchV()

! Bit flags for blitting into a rectangular region.
 \see GPU_BlitRect
 \see GPU_BlitRectX

! \ingroup ShaderInterface
 Type enumeration for GPU_AttributeFormat specifications.

! \ingroup ShaderInterface

! \ingroup ShaderInterface

! \ingroup ShaderInterface

! \ingroup Logging

! The window corresponding to 'windowID' will be used to create the rendering context instead of creating a new window.

! Returns the window ID that has been set via GPU_SetInitWindow().

! Set special flags to use for initialization. Set these before calling GPU_Init().
 \param GPU_flags An OR'ed combination of GPU_InitFlagEnum flags.  Default flags (0) enable late swap vsync and double buffering.

! Returns the current special flags to use for initialization.

! Set required features to use for initialization. Set these before calling GPU_Init().
 \param features An OR'ed combination of GPU_FeatureEnum flags.  Required features will force GPU_Init() to create a renderer that supports all of the given flags or else fail.

! Returns the current required features to use for initialization.

! Gets the default initialization renderer IDs for the current platform copied into the 'order' array and the number of renderer IDs into 'order_size'.  Pass NULL for 'order' to just get the size of the renderer order array.  Will return at most GPU_RENDERER_ORDER_MAX renderers.

! Gets the current renderer ID order for initialization copied into the 'order' array and the number of renderer IDs into 'order_size'.  Pass NULL for 'order' to just get the size of the renderer order array.

! Sets the renderer ID order to use for initialization.  If 'order' is NULL, it will restore the default order.

! Initializes SDL's video subsystem (if necessary) and all of SDL_gpu's internal structures.
 Chooses a renderer and creates a window with the given dimensions and window creation flags.
 A pointer to the resulting window's render target is returned.
 
 \param w Desired window width in pixels
 \param h Desired window height in pixels
 \param SDL_flags The bit flags to pass to SDL when creating the window.  Use GPU_DEFAULT_INIT_FLAGS if you don't care.
 \return On success, returns the new context target (i.e. render target backed by a window).  On failure, returns NULL.
 
 Initializes these systems:
  The 'error queue': Stores error codes and description strings.
  The 'renderer registry': An array of information about the supported renderers on the current platform,
    such as the renderer name and id and its life cycle functions.
  The SDL library and its video subsystem: Calls SDL_Init() if SDL has not already been initialized.
    Use SDL_InitSubsystem() to initialize more parts of SDL.
  The current renderer:  Walks through each renderer in the renderer registry and tries to initialize them until one succeeds.
 
 \see GPU_RendererID
 \see GPU_InitRenderer()
 \see GPU_InitRendererByID()
 \see GPU_SetRendererOrder()
 \see GPU_PushErrorCode()

! Initializes SDL and SDL_gpu.  Creates a window and the requested renderer context.

! Initializes SDL and SDL_gpu.  Creates a window and the requested renderer context.
 By requesting a renderer via ID, you can specify the major and minor versions of an individual renderer backend.
 \see GPU_MakeRendererID

! Checks for important GPU features which may not be supported depending on a device's extension support.  Feature flags (GPU_FEATURE_) can be bitwise OR'd together.
 \return 1 if all of the passed features are enabled/supported
 \return 0 if any of the passed features are disabled/unsupported

! Clean up the renderer state.

! Clean up the renderer state and shut down SDL_gpu.

! \ingroup Logging
  @{
! Sets the global debug level.
 GPU_DEBUG_LEVEL_0: Normal
 GPU_DEBUG_LEVEL_1: Prints messages when errors are pushed via GPU_PushErrorCode()
 GPU_DEBUG_LEVEL_2: Elevates warning logs to error priority
 GPU_DEBUG_LEVEL_3: Elevates info logs to error priority

! Returns the current global debug level.

! Prints an informational log message.

! Prints a warning log message.

! Prints an error log message.

! Sets a custom callback for handling logging.  Use stdio's vsnprintf() to process the va_list into a string.  Passing NULL as the callback will reset to the default internal logging.

! Pushes a new error code into the error queue.  If the queue is full, the queue is not modified.
 \param function The name of the function that pushed the error
 \param error The error code to push on the error queue
 \param details Additional information string, can be NULL.

! Pops an error object from the error queue and returns it.  If the error queue is empty, it returns an error object with NULL function, GPU_ERROR_NONE error, and NULL details.

! Gets the string representation of an error code.

! Changes the maximum number of error objects that SDL_gpu will store.  This deletes all currently stored errors.

End of Logging
! @}
! \ingroup RendererSetup
  @{
! Returns an initialized GPU_RendererID.

! Gets the first registered renderer identifier for the given enum value.

! Gets the number of registered (available) renderers.

! Gets an array of identifiers for the registered (available) renderers.

! Prepares a renderer for use by SDL_gpu.

End of RendererSetup
! @}
! \ingroup RendererControls
  @{
! Gets the next enum ID that can be used for a custom renderer.

! Gets the number of active (created) renderers.

! Gets an array of identifiers for the active renderers.

! \return The current renderer

! Switches the current renderer to the renderer matching the given identifier.

! \return The renderer matching the given identifier.

! Reapplies the renderer state to the backend API (e.g. OpenGL, Direct3D).  Use this if you want SDL_gpu to be able to render after you've used direct backend calls.

! Sets the coordinate mode for this renderer.  Target and image coordinates will be either "inverted" (0,0 is the upper left corner, y increases downward) or "mathematical" (0,0 is the bottom-left corner, y increases upward).
 The default is inverted (0), as this is traditional for 2D graphics.
 \param inverted 0 is for inverted coordinates, 1 is for mathematical coordinates

! Sets the default image blitting anchor for newly created images.
 \see GPU_SetAnchor

! Returns the default image blitting anchor through the given variables.
 \see GPU_GetAnchor

End of RendererControls
! @}
Context / window controls
! \ingroup ContextControls
  @{
! \return The renderer's current context target.

! \return The target that is associated with the given windowID.

! Creates a separate context for the given window using the current renderer and returns a GPU_Target that represents it.

! Makes the given window the current rendering destination for the given context target.
 This also makes the target the current context for image loading and window operations.
 If the target does not represent a window, this does nothing.

! Change the actual size of the current context target's window.  This resets the virtual resolution and viewport of the context target.
 Aside from direct resolution changes, this should also be called in response to SDL_WINDOWEVENT_RESIZED window events for resizable windows.

! Enable/disable fullscreen mode for the current context target's window.
 On some platforms, this may destroy the renderer context and require that textures be reloaded.  Unfortunately, SDL does not provide a notification mechanism for this.
 \param enable_fullscreen If true, make the application go fullscreen.  If false, make the application go to windowed mode.
 \param use_desktop_resolution If true, lets the window change its resolution when it enters fullscreen mode (via SDL_WINDOW_FULLSCREEN_DESKTOP).
 \return 0 if the new mode is windowed, 1 if the new mode is fullscreen.

! Returns true if the current context target's window is in fullscreen mode.

! \return Returns the last active target.

! \return Sets the currently active target for matrix modification functions.

! Enables/disables alpha blending for shape rendering on the current window.

! Translates a blend preset into a blend mode.

! Sets the blending component functions for shape rendering.

! Sets the blending component equations for shape rendering.

! Sets the blending mode for shape rendering on the current window, if supported by the renderer.

! Sets the thickness of lines for the current context.
 \param thickness New line thickness in pixels measured across the line.  Default is 1.0f.
 \return The old thickness value

! Returns the current line thickness value.

End of ContextControls
! @}
! \ingroup TargetControls
  @{
! Creates a target that aliases the given target.  Aliases can be used to store target settings (e.g. viewports) for easy switching.
 GPU_FreeTarget() frees the alias's memory, but does not affect the original.

! Creates a new render target from the given image.  It can then be accessed from image->target.  This increments the internal refcount of the target, so it should be matched with a GPU_FreeTarget().

! Creates a new render target from the given image.  It can then be accessed from image->target.  This does not increment the internal refcount of the target, so it will be invalidated when the image is freed.

! Deletes a render target in the proper way for this renderer.

! Change the logical size of the given target.  Rendering to this target will be scaled as if the dimensions were actually the ones given.

! Query the logical size of the given target.

! Converts screen space coordinates (such as from mouse input) to logical drawing coordinates.  This interacts with GPU_SetCoordinateMode() when the y-axis is flipped (screen space is assumed to be inverted: (0,0) in the upper-left corner).

! Reset the logical size of the given target to its original value.

! \return A GPU_Rect with the given values.

! \return An SDL_Color with the given values.

! Sets the given target's viewport.

! Resets the given target's viewport to the entire target area.

! \return A GPU_Camera with position (0, 0, 0), angle of 0, zoom of 1, centered origin, and near/far clipping planes of -100 and 100.

! \return The camera of the given render target.  If target is NULL, returns the default camera.

! Sets the current render target's current camera.
 \param target A pointer to the target that will copy this camera.
 \param cam A pointer to the camera data to use or NULL to use the default camera.
 \return The old camera.

! Enables or disables using the built-in camera matrix transforms.

! Returns 1 if the camera transforms are enabled, 0 otherwise.

! Attach a new depth buffer to the given target so that it can use depth testing.  Context targets automatically have a depth buffer already.
  If successful, also enables depth testing for this target.

! Enables or disables the depth test, which will skip drawing pixels/fragments behind other fragments.  Disabled by default.
  This has implications for alpha blending, where compositing might not work correctly depending on render order.

! Enables or disables writing the depth (effective view z-coordinate) of new pixels to the depth buffer.  Enabled by default, but you must call GPU_SetDepthTest() to use it.

! Sets the operation to perform when depth testing.

! \return The RGBA color of a pixel.

! Sets the clipping rect for the given render target.

! Sets the clipping rect for the given render target.

! Turns off clipping for the given target.