{"id":19238006,"url":"https://github.com/pikachuxxxx/soil","last_synced_at":"2025-07-08T12:04:54.346Z","repository":{"id":114745347,"uuid":"288099800","full_name":"Pikachuxxxx/SOIL","owner":"Pikachuxxxx","description":"Simple OpenGL Image Loading Library with  CMake build","archived":false,"fork":false,"pushed_at":"2020-08-25T17:06:41.000Z","size":161,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-01T10:42:05.026Z","etag":null,"topics":["image-loading-library","opengl","soil","soil-library","texture"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pikachuxxxx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-08-17T06:21:13.000Z","updated_at":"2024-06-09T19:01:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"25995ecc-73eb-449f-8726-8be83fd52ce8","html_url":"https://github.com/Pikachuxxxx/SOIL","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"1c1a8e8996d0694d370e2082bed3a0fb52918dc1"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pikachuxxxx%2FSOIL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pikachuxxxx%2FSOIL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pikachuxxxx%2FSOIL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pikachuxxxx%2FSOIL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pikachuxxxx","download_url":"https://codeload.github.com/Pikachuxxxx/SOIL/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250008209,"owners_count":21359948,"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":["image-loading-library","opengl","soil","soil-library","texture"],"created_at":"2024-11-09T16:29:00.709Z","updated_at":"2025-04-21T06:31:44.474Z","avatar_url":"https://github.com/Pikachuxxxx.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SOIL - **Simple OpenGL Image Library**\nSimple OpenGL Image Library with  CMake build\n### ![GitHub](https://img.shields.io/github/license/Pikachuxxxx/SOIL?style=for-the-badge)  ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/Pikachuxxxx/SOIL?color=E89393\u0026logoColor=E89393\u0026style=for-the-badge)\n\n**Introduction:**  \n\nSOIL is a tiny C library used primarily for uploading textures into OpenGL. It can load TGA and DDS files, and to perform common functions needed in loading OpenGL textures. SOIL can also be used to save and load images in a variety of formats.\n\nThis is a clone of Simple OpenGL Image Library from http://lonesock.net/soil.html which hasn't changed since July 7, 2008.\n\nI wanted to work with the code and seeing it was MIT license and the original svn repo is offline, I figured it was acceptable to post it here with some changes to the codebase and added the Cmake build file.\n\n**Features:** \n\n  *   Readable Image Formats: \n  *   BMP - non-1bpp, non-RLE (from stb_image documentation) \n  *   PNG - non-interlaced (from stb_image documentation) \n  *   JPG - JPEG baseline (from stb_image documentation) \n  *   TGA - greyscale or RGB or RGBA or indexed, uncompressed or RLE \n  *   DDS - DXT1/2/3/4/5, uncompressed, cubemaps (can't read 3D DDS files yet) \n  *   PSD - (from stb_image documentation) \n  *   HDR - converted to LDR, unless loaded with \\*HDR\\* functions (RGBE or RGBdivA or RGBdivA2) \n\nWriteable Image Formats: \n  *   TGA - Greyscale or RGB or RGBA, uncompressed \n  *   BMP - RGB, uncompressed \n  *   DDS - RGB as DXT1, or RGBA as DXT5\n  *   Can load an image file directly into a 2D OpenGL texture, optionally performing the following functions: \n  *   Can generate a new texture handle, or reuse one specified \n  *   Can automatically rescale the image to the next largest power-of-two size \n  *   Can automatically create MIPmaps \n  *   Can scale (not simply clamp) the RGB values into the \"safe range\" for NTSC displays (16 to 235, as recommended [here][1]) \n  *   Can multiply alpha on load (for more correct blending / compositing) \n  *   Can flip the image vertically \n  *   Can compress and upload any image as DXT1 or DXT5 (if EXT\\_texture\\_compression_s3tc is available), using an internal (very fast!) compressor \n  *   Can convert the RGB to YCoCg color space (useful with DXT5 compression: see [this link][2] from NVIDIA) \n  *   Will automatically downsize a texture if it is larger than GL\\_MAX\\_TEXTURE_SIZE \n  *   Can directly upload DDS files (DXT1/3/5/uncompressed/cubemap, with or without MIPmaps). Note: directly uploading the compressed DDS image will disable the other options (no flipping, no pre-multiplying alpha, no rescaling, no creation of MIPmaps, no auto-downsizing) \n  *   Can load rectangluar textures for GUI elements or splash screens (requires GL\\_ARB/EXT/NV\\_texture_rectangle) \n  *   Can decompress images from RAM (e.g. via [PhysicsFS][3] or similar) into an OpenGL texture (same features as regular 2D textures, above) \n  *   Can load cube maps directly into an OpenGL texture (same features as regular 2D textures, above) \n  *   Can take six image files directly into an OpenGL cube map texture \n  *   Can take a single image file where width = 6*height (or vice versa), split it into an OpenGL cube map texture \n  *   No external dependencies \n  *   Tiny \n  *   Cross platform (Windows, *nix, Mac OS X) \n  *   Public Domain \n\n**Installation:**  \n\nSOIL is meant to be used as a static library (as it's tiny). \n\nSimply include SOIL.h in your C or C++ file, link in the static library, and then use any of SOIL's functions. The file SOIL.h contains simple doxygen style documentation. (If you use the static library, no other header files are needed besides SOIL.h)\n\nYou can compile it like any other CMAKE project, simply make a folder named \"build\" and run\n```\ncmake ..\nmake\n\n```\n**Usage:**\nload an image file directly as a new OpenGL texture\n\n    GLuint tex_2d = SOIL_load_OGL_texture\n    (\n      \"img.png\",\n      SOIL_LOAD_AUTO,\n      SOIL_CREATE_NEW_ID,\n      SOIL_FLAG_MIPMAPS | SOIL_FLAG_INVERT_Y | SOIL_FLAG_NTSC_SAFE_RGB | SOIL_FLAG_COMPRESS_TO_DXT\n    );\n\ncheck for an error during the load process\n\n    if( 0 == tex_2d )\n    {\n      printf( \"SOIL loading error: '%s'\\n\", SOIL_last_result() );\n    }\n\nload another image, but into the same texture ID, overwriting the last one\n\n    tex_2d = SOIL_load_OGL_texture\n    (\n      \"some_other_img.dds\",\n      SOIL_LOAD_AUTO,\n      tex_2d,\n      SOIL_FLAG_DDS_LOAD_DIRECT\n    );\n\nload 6 images into a new OpenGL cube map, forcing RGB\n\n    GLuint tex_cube = SOIL_load_OGL_cubemap\n    (\n      \"xp.jpg\",\n      \"xn.jpg\",\n      \"yp.jpg\",\n      \"yn.jpg\",\n      \"zp.jpg\",\n      \"zn.jpg\",\n      SOIL_LOAD_RGB,\n      SOIL_CREATE_NEW_ID,\n      SOIL_FLAG_MIPMAPS\n    );\n\nload and split a single image into a new OpenGL cube map, default format\nface order = East South West North Up Down =\u003e \"ESWNUD\", case sensitive!\n\n    GLuint single_tex_cube = SOIL_load_OGL_single_cubemap\n    (\n      \"split_cubemap.png\",\n      \"EWUDNS\",\n      SOIL_LOAD_AUTO,\n      SOIL_CREATE_NEW_ID,\n      SOIL_FLAG_MIPMAPS\n    );\n\nactually, load a DDS cubemap over the last OpenGL cube map, default format\ntry to load it directly, but give the order of the faces in case that fails\nthe DDS cubemap face order is pre-defined as SOIL_DDS_CUBEMAP_FACE_ORDER\n\n    single_tex_cube = SOIL_load_OGL_single_cubemap\n    (\n      \"overwrite_cubemap.dds\",\n      SOIL_DDS_CUBEMAP_FACE_ORDER,\n      SOIL_LOAD_AUTO,\n      single_tex_cube,\n      SOIL_FLAG_MIPMAPS | SOIL_FLAG_DDS_LOAD_DIRECT\n    );\n\nload an image as a heightmap, forcing greyscale (so channels should be 1)\n\n    int width, height, channels;\n    unsigned char *ht_map = SOIL_load_image\n    (\n      \"terrain.tga\",\n      \u0026width, \u0026height, \u0026channels,\n      SOIL_LOAD_L\n    );\n\nsave that image as another type\n\n    int save_result = SOIL_save_image\n    (\n      \"new_terrain.dds\",\n      SOIL_SAVE_TYPE_DDS,\n      width, height, channels,\n      ht_map\n    );\n\nsave a screenshot of your awesome OpenGL game engine, running at 1024x768\n\n    save_result = SOIL_save_screenshot\n    (\n      \"awesomenessity.bmp\",\n      SOIL_SAVE_TYPE_BMP,\n      0, 0, 1024, 768\n    );\n\nloaded a file via PhysicsFS, need to decompress the image from RAM,\nwhere it's in a buffer: unsigned char *image_in_RAM\n\n    GLuint tex_2d_from_RAM = SOIL_load_OGL_texture_from_memory\n    (\n      image_in_RAM,\n      image_in_RAM_bytes,\n      SOIL_LOAD_AUTO,\n      SOIL_CREATE_NEW_ID,\n      SOIL_FLAG_MIPMAPS | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT\n    );\n\ndone with the heightmap, free up the RAM\n\n    SOIL_free_image_data( ht_map );\n\n\n  [1]: http://msdn2.microsoft.com/en-us/library/bb174608.aspx#NTSC_Suggestions\n  [2]: http://developer.nvidia.com/object/real-time-ycocg-dxt-compression.html\n  [3]: http://icculus.org/physfs/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpikachuxxxx%2Fsoil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpikachuxxxx%2Fsoil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpikachuxxxx%2Fsoil/lists"}