{"id":17187976,"url":"https://github.com/icculus/controllerimage","last_synced_at":"2025-04-05T16:10:26.928Z","repository":{"id":210462339,"uuid":"716732780","full_name":"icculus/ControllerImage","owner":"icculus","description":"A library for producing images of SDL controllers.","archived":false,"fork":false,"pushed_at":"2024-10-20T02:58:19.000Z","size":453,"stargazers_count":121,"open_issues_count":17,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T15:11:21.607Z","etag":null,"topics":["gamepad","sdl"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icculus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["icculus"],"patreon":"icculus"}},"created_at":"2023-11-09T18:55:01.000Z","updated_at":"2025-02-23T17:26:46.000Z","dependencies_parsed_at":"2025-02-03T17:49:57.994Z","dependency_job_id":"c64dec1e-463e-4e64-baba-5fcaa1bd39fa","html_url":"https://github.com/icculus/ControllerImage","commit_stats":null,"previous_names":["icculus/controllerimage"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2FControllerImage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2FControllerImage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2FControllerImage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2FControllerImage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icculus","download_url":"https://codeload.github.com/icculus/ControllerImage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361695,"owners_count":20926643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gamepad","sdl"],"created_at":"2024-10-15T01:07:47.791Z","updated_at":"2025-04-05T16:10:26.904Z","avatar_url":"https://github.com/icculus.png","language":"C","readme":"# ControllerImage\n\n## What is this?\n\nThis is a library that provides resolution-independent images for game\ncontroller inputs, so games can show the correct visual markers for the\ngamepad in the user's hand.\n\nThis is intended, for example, to let you show a \"Press `image` to continue\"\nmessage, where `image` might be a yellow 'Y' if the user has an Xbox\ncontroller and a green triangle if they have a PlayStation controller.\n\nIt is intended to work with whatever looks like a gamepad to SDL3, but it\nrequires artwork, in SVG format, for whatever controller the user happens to\nbe using. The standard ones--Xbox, PlayStation, Switch--are supplied, and if\nwe can't offer anything better, we'll aim for a generic Xbox 360 controller,\nunder the assumption it _probably_ represents most generic third-party devices.\n\nWe need submissions of more controller art! It must be in\n[SVG format](https://en.wikipedia.org/wiki/SVG), and ideally it's as small as\npossible while still looking as accurate as possible. If you can help,\nand offer artwork in the public domain, please get in touch.\n\n## How do I use the library?\n\n- This library relies on SDL3. If you are using SDL2, please upgrade. If you\n  aren't using SDL at all, this library won't be usable.\n- Build it. It's one C file and a few headers, you can copy them into your\n  project. Just compile controllerimage.c as part of your project. You don't\n  need to mess around with the CMake file to build a separate library if you\n  don't want to.\n- In your app near startup (preferably after SDL_Init)...\n  ```c\n  if (!ControllerImage_Init()) {\n      SDL_Log(\"ControllerImage_Init() failed! why='%s'\", SDL_GetError());\n  }\n  ```\n- Load in the controller and image data...\n  ```c\n  // there are also versions that can load from an SDL_IOStream or a memory buffer...\n  if (!ControllerImage_AddDataFromFile(\"controllerimages-standard.bin\")) {\n      SDL_Log(\"ControllerImage_AddDataFromFile() failed! why='%s'\", SDL_GetError());\n  }\n  ```\n- Have a controller? Prepare to get images for it, probably when you open the gamepad:\n  ```c\n  // There's a version that accepts a device instance ID and not an `SDL_Gamepad *`, too.\n  ControllerImage_Device *imgdev = ControllerImage_CreateGamepadDevice(mySdlGamepad);\n  if (!imgdev) {\n      SDL_Log(\"ControllerImage_CreateGamepadDevice() failed! why='%s'\", SDL_GetError());\n  }\n  ```\n- Get image data for specific buttons or axes on the gamepad. They come in as\n  SDL_Surfaces, so you can manipulate them, or upload them to SDL_Textures.\n  You choose the size of the image; a game running at 4K might want a larger\n  one than a game running at 720p, so it always looks crisp on the display\n  without scaling.\n  ```c\n  SDL_Surface *axissurf = ControllerImage_CreateSurfaceForAxis(imgdev, SDL_GAMEPAD_AXIS_LEFTX, 100, 100);\n  if (!axissurf) {\n      SDL_Log(\"Render axis failed! why='%s'\", SDL_GetError());\n  }\n  SDL_Surface *buttonsurf = ControllerImage_CreateSurfaceForButton(imgdev, SDL_GAMEPAD_BUTTON_GUIDE, 100, 100);\n  if (!buttonsurf) {\n      SDL_Log(\"Render button failed! why='%s'\", SDL_GetError());\n  }\n  ```\n- Done with this controller? Free up resources...\n  ```c\n  ControllerImage_DestroyDevice(imgdev);\n  ```\n- At app shutdown...\n  ```c\n  ControllerImage_Quit();  // safe even if ControllerImage_Init() failed!\n  ```\n\n## How do I get the data file I need?\n\nCompile the C file \"src/make-controllerimage-data.c\". It should compile\nwithout any dependencies.\n\nRun that with the \"art\" directory as its only command line argument.\nIt will produce a \"controllerimage-standard.bin\" file in the current working\ndirectory. This is the data you pass to the library. It will also build other\nthemes that can be overlayed on top of the \"standard\" theme; these are\noptional.\n\nThe library is designed to let you add to and replace existing data with\nmultiple files, so you can add more files that just fix things and add new\ncontrollers without having to replace earlier data files completely in a\npatch, and load them in order to get the same results, but a tool to generate\nsubsets of data hasn't been written yet.\n\n\n## What if I want to make my own art?\n\nNo problem! Lots of games want to have controller images that match their\nstyle.\n\nGenerally I would recommend you build out the most popular controllers, put\nthem in their own subdirectory under the \"art\" directory, and build it as\na second database. Ship both that file and the \"standard\" database with the\ngame, loading the \"standard\" one first, then your custom one second, so it\nreplaces pieces of the first database.\n\nThis way, the most common controllers will match your game's art style, your\nartists didn't have to build a massive amount of art, and if someone comes\nalong with an obscure controller, they still see the right thing, just perhaps\nwithout a perfect style match.\n\nIf you want to contribute your new art in the public domain, we will be happy\nto include it with this project, so other people making games with the same\nvibe can take advantage of it!\n\n","funding_links":["https://github.com/sponsors/icculus","https://patreon.com/icculus"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficculus%2Fcontrollerimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficculus%2Fcontrollerimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficculus%2Fcontrollerimage/lists"}