# CategoryControllerImage

This is a library that provides resolution-independent images for game
controller inputs, so games can show the correct visual markers for the
gamepad in the user's hand.

This is intended, for example, to let you show a "Press `image` to
continue" message, where `image` might be a yellow 'Y' if the user has an
Xbox controller and a green triangle if they have a PlayStation controller.
It is intended to work with whatever looks like a gamepad to SDL3, but it
requires artwork, in SVG format, for whatever controller the user happens
to be using. The standard ones--Xbox, PlayStation, Switch--are supplied,
and if we can't offer anything better, we'll aim for a generic Xbox 360
controller, under the assumption it _probably_ represents most generic
third-party devices.

ControllerImage depends on SDL3.

Using the library is simple:

- In your app near startup (preferably after SDL_Init), call
  [ControllerImage_Init](ControllerImage_Init)().
- Load in the controller and image data with
  [ControllerImage_AddDataFromFile](ControllerImage_AddDataFromFile)().
- Get image information for an SDL_Gamepad, probably once when you open the
  gamepad, with
  [ControllerImage_CreateGamepadDevice](ControllerImage_CreateGamepadDevice)().
- Get image data for specific buttons or axes on the gamepad. They come in
  as SDL_Surfaces, so you can manipulate them, or upload them to
  SDL_Textures. You choose the size of the image; a game running at 4K
  might want a larger one than a game running at 720p, so it always looks
  crisp on the display without scaling. Use
  [ControllerImage_CreateSurfaceForAxis](ControllerImage_CreateSurfaceForAxis)()
  and
  [ControllerImage_CreateSurfaceForButton](ControllerImage_CreateSurfaceForButton)().
- Done with a gamepad? Free resources with
  [ControllerImage_DestroyDevice](ControllerImage_DestroyDevice)().
- Done with the library? Call
  [ControllerImage_Quit](ControllerImage_Quit)() to clean up.

You will need a datafile, which you can build from the files that come with
the library's source code. Please see README.md in the root of the source
tree, or
[the wiki](https://wiki.icculus.org/ControllerImage/)
for the details on how to do that.

<!-- END CATEGORY DOCUMENTATION -->

## Functions

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryControllerImage, CategoryAPIFunction -->
- [ControllerImage_AddData](ControllerImage_AddData)
- [ControllerImage_AddDataFromFile](ControllerImage_AddDataFromFile)
- [ControllerImage_AddDataFromIOStream](ControllerImage_AddDataFromIOStream)
- [ControllerImage_CreateGamepadDevice](ControllerImage_CreateGamepadDevice)
- [ControllerImage_CreateGamepadDeviceByIdString](ControllerImage_CreateGamepadDeviceByIdString)
- [ControllerImage_CreateGamepadDeviceByInstance](ControllerImage_CreateGamepadDeviceByInstance)
- [ControllerImage_CreateSurfaceForAxis](ControllerImage_CreateSurfaceForAxis)
- [ControllerImage_CreateSurfaceForButton](ControllerImage_CreateSurfaceForButton)
- [ControllerImage_DestroyDevice](ControllerImage_DestroyDevice)
- [ControllerImage_DeviceHasArtworkForAxis](ControllerImage_DeviceHasArtworkForAxis)
- [ControllerImage_DeviceHasArtworkForButton](ControllerImage_DeviceHasArtworkForButton)
- [ControllerImage_GetDeviceType](ControllerImage_GetDeviceType)
- [ControllerImage_GetSVGForAxis](ControllerImage_GetSVGForAxis)
- [ControllerImage_GetSVGForButton](ControllerImage_GetSVGForButton)
- [ControllerImage_Init](ControllerImage_Init)
- [ControllerImage_Quit](ControllerImage_Quit)
- [ControllerImage_Version](ControllerImage_Version)
<!-- END CATEGORY LIST -->

## Datatypes

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryControllerImage, CategoryAPIDatatype -->
- [ControllerImage_Device](ControllerImage_Device)
<!-- END CATEGORY LIST -->

## Structs

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryControllerImage, CategoryAPIStruct -->
- (none.)
<!-- END CATEGORY LIST -->

## Enums

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryControllerImage, CategoryAPIEnum -->
- (none.)
<!-- END CATEGORY LIST -->

## Macros

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryControllerImage, CategoryAPIMacro -->
- [CONTROLLERIMAGE_MAJOR_VERSION](CONTROLLERIMAGE_MAJOR_VERSION)
- [CONTROLLERIMAGE_MICRO_VERSION](CONTROLLERIMAGE_MICRO_VERSION)
- [CONTROLLERIMAGE_MINOR_VERSION](CONTROLLERIMAGE_MINOR_VERSION)
- [CONTROLLERIMAGE_VERSION](CONTROLLERIMAGE_VERSION)
<!-- END CATEGORY LIST -->

----
[CategoryAPICategory](CategoryAPICategory)