Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

cleaned up readme

  • Loading branch information...
commit 36f08f0b42d9498625b42c98e45acafb4695d74e 1 parent d4b398b
Kevin Branigan authored

Showing 1 changed file with 134 additions and 123 deletions. Show diff stats Hide diff stats

  1. +134 123 README.md
257 README.md
Source Rendered
@@ -6,33 +6,33 @@ Features:
6 6 =========
7 7
8 8 * Readable Image Formats:
9   - o BMP - non-1bpp, non-RLE (from stb_image documentation)
10   - o PNG - non-interlaced (from stb_image documentation)
11   - o JPG - JPEG baseline (from stb_image documentation)
12   - o TGA - greyscale or RGB or RGBA or indexed, uncompressed or RLE
13   - o DDS - DXT1/2/3/4/5, uncompressed, cubemaps (can't read 3D DDS files yet)
14   - o PSD - (from stb_image documentation)
15   - o HDR - converted to LDR, unless loaded with *HDR* functions (RGBE or RGBdivA or RGBdivA2)
  9 + * BMP - non-1bpp, non-RLE (from stb_image documentation)
  10 + * PNG - non-interlaced (from stb_image documentation)
  11 + * JPG - JPEG baseline (from stb_image documentation)
  12 + * TGA - greyscale or RGB or RGBA or indexed, uncompressed or RLE
  13 + * DDS - DXT1/2/3/4/5, uncompressed, cubemaps (can't read 3D DDS files yet)
  14 + * PSD - (from stb_image documentation)
  15 + * HDR - converted to LDR, unless loaded with *HDR* functions (RGBE or RGBdivA or RGBdivA2)
16 16 * Writeable Image Formats:
17   - o TGA - Greyscale or RGB or RGBA, uncompressed
18   - o BMP - RGB, uncompressed
19   - o DDS - RGB as DXT1, or RGBA as DXT5
  17 + * TGA - Greyscale or RGB or RGBA, uncompressed
  18 + * BMP - RGB, uncompressed
  19 + * DDS - RGB as DXT1, or RGBA as DXT5
20 20 * Can load an image file directly into a 2D OpenGL texture, optionally performing the following functions:
21   - o Can generate a new texture handle, or reuse one specified
22   - o Can automatically rescale the image to the next largest power-of-two size
23   - o Can automatically create MIPmaps
24   - o Can scale (not simply clamp) the RGB values into the "safe range" for NTSC displays (16 to 235, as recommended here)
25   - o Can multiply alpha on load (for more correct blending / compositing)
26   - o Can flip the image vertically
27   - o Can compress and upload any image as DXT1 or DXT5 (if EXT_texture_compression_s3tc is available), using an internal (very fast!) compressor
28   - o Can convert the RGB to YCoCg color space (useful with DXT5 compression: see this link from NVIDIA)
29   - o Will automatically downsize a texture if it is larger than GL_MAX_TEXTURE_SIZE
30   - o 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)
31   - o Can load rectangluar textures for GUI elements or splash screens (requires GL_ARB/EXT/NV_texture_rectangle)
  21 + * Can generate a new texture handle, or reuse one specified
  22 + * Can automatically rescale the image to the next largest power-of-two size
  23 + * Can automatically create MIPmaps
  24 + * Can scale (not simply clamp) the RGB values into the "safe range" for NTSC displays (16 to 235, as recommended here)
  25 + * Can multiply alpha on load (for more correct blending / compositing)
  26 + * Can flip the image vertically
  27 + * Can compress and upload any image as DXT1 or DXT5 (if EXT_texture_compression_s3tc is available), using an internal (very fast!) compressor
  28 + * Can convert the RGB to YCoCg color space (useful with DXT5 compression: see this link from NVIDIA)
  29 + * Will automatically downsize a texture if it is larger than GL_MAX_TEXTURE_SIZE
  30 + * 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)
  31 + * Can load rectangluar textures for GUI elements or splash screens (requires GL_ARB/EXT/NV_texture_rectangle)
32 32 * Can decompress images from RAM (e.g. via PhysicsFS or similar) into an OpenGL texture (same features as regular 2D textures, above)
33 33 * Can load cube maps directly into an OpenGL texture (same features as regular 2D textures, above)
34   - o Can take six image files directly into an OpenGL cube map texture
35   - o Can take a single image file where width = 6*height (or vice versa), split it into an OpenGL cube map texture
  34 + * Can take six image files directly into an OpenGL cube map texture
  35 + * Can take a single image file where width = 6*height (or vice versa), split it into an OpenGL cube map texture
36 36 * No external dependencies
37 37 * Tiny
38 38 * Cross platform (Windows, *nix, Mac OS X)
@@ -45,103 +45,114 @@ SOIL is meant to be used as a static library (as it's tiny and in the public dom
45 45
46 46 Simply 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) Below are some simple usage examples:
47 47
48   -/* load an image file directly as a new OpenGL texture */
49   -GLuint tex_2d = SOIL_load_OGL_texture
50   - (
51   - "img.png",
52   - SOIL_LOAD_AUTO,
53   - SOIL_CREATE_NEW_ID,
54   - SOIL_FLAG_MIPMAPS | SOIL_FLAG_INVERT_Y | SOIL_FLAG_NTSC_SAFE_RGB | SOIL_FLAG_COMPRESS_TO_DXT
55   - );
56   -
57   -/* check for an error during the load process */
58   -if( 0 == tex_2d )
59   -{
60   - printf( "SOIL loading error: '%s'\n", SOIL_last_result() );
61   -}
62   -
63   -/* load another image, but into the same texture ID, overwriting the last one */
64   -tex_2d = SOIL_load_OGL_texture
65   - (
66   - "some_other_img.dds",
67   - SOIL_LOAD_AUTO,
68   - tex_2d,
69   - SOIL_FLAG_DDS_LOAD_DIRECT
70   - );
71   -
72   -/* load 6 images into a new OpenGL cube map, forcing RGB */
73   -GLuint tex_cube = SOIL_load_OGL_cubemap
74   - (
75   - "xp.jpg",
76   - "xn.jpg",
77   - "yp.jpg",
78   - "yn.jpg",
79   - "zp.jpg",
80   - "zn.jpg",
81   - SOIL_LOAD_RGB,
82   - SOIL_CREATE_NEW_ID,
83   - SOIL_FLAG_MIPMAPS
84   - );
85   -
86   -/* load and split a single image into a new OpenGL cube map, default format */
87   -/* face order = East South West North Up Down => "ESWNUD", case sensitive! */
88   -GLuint single_tex_cube = SOIL_load_OGL_single_cubemap
89   - (
90   - "split_cubemap.png",
91   - "EWUDNS",
92   - SOIL_LOAD_AUTO,
93   - SOIL_CREATE_NEW_ID,
94   - SOIL_FLAG_MIPMAPS
95   - );
96   -
97   -/* actually, load a DDS cubemap over the last OpenGL cube map, default format */
98   -/* try to load it directly, but give the order of the faces in case that fails */
99   -/* the DDS cubemap face order is pre-defined as SOIL_DDS_CUBEMAP_FACE_ORDER */
100   -single_tex_cube = SOIL_load_OGL_single_cubemap
101   - (
102   - "overwrite_cubemap.dds",
103   - SOIL_DDS_CUBEMAP_FACE_ORDER,
104   - SOIL_LOAD_AUTO,
105   - single_tex_cube,
106   - SOIL_FLAG_MIPMAPS | SOIL_FLAG_DDS_LOAD_DIRECT
107   - );
108   -
109   -/* load an image as a heightmap, forcing greyscale (so channels should be 1) */
110   -int width, height, channels;
111   -unsigned char *ht_map = SOIL_load_image
112   - (
113   - "terrain.tga",
114   - &width, &height, &channels,
115   - SOIL_LOAD_L
116   - );
117   -
118   -/* save that image as another type */
119   -int save_result = SOIL_save_image
120   - (
121   - "new_terrain.dds",
122   - SOIL_SAVE_TYPE_DDS,
123   - width, height, channels,
124   - ht_map
125   - );
126   -
127   -/* save a screenshot of your awesome OpenGL game engine, running at 1024x768 */
128   -save_result = SOIL_save_screenshot
129   - (
130   - "awesomenessity.bmp",
131   - SOIL_SAVE_TYPE_BMP,
132   - 0, 0, 1024, 768
133   - );
134   -
135   -/* loaded a file via PhysicsFS, need to decompress the image from RAM, */
136   -/* where it's in a buffer: unsigned char *image_in_RAM */
137   -GLuint tex_2d_from_RAM = SOIL_load_OGL_texture_from_memory
138   - (
139   - image_in_RAM,
140   - image_in_RAM_bytes,
141   - SOIL_LOAD_AUTO,
142   - SOIL_CREATE_NEW_ID,
143   - SOIL_FLAG_MIPMAPS | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT
144   - );
145   -
146   -/* done with the heightmap, free up the RAM */
147   -SOIL_free_image_data( ht_map );
  48 +load an image file directly as a new OpenGL texture
  49 +
  50 + GLuint tex_2d = SOIL_load_OGL_texture
  51 + (
  52 + "img.png",
  53 + SOIL_LOAD_AUTO,
  54 + SOIL_CREATE_NEW_ID,
  55 + SOIL_FLAG_MIPMAPS | SOIL_FLAG_INVERT_Y | SOIL_FLAG_NTSC_SAFE_RGB | SOIL_FLAG_COMPRESS_TO_DXT
  56 + );
  57 +
  58 +check for an error during the load process
  59 +
  60 + if( 0 == tex_2d )
  61 + {
  62 + printf( "SOIL loading error: '%s'\n", SOIL_last_result() );
  63 + }
  64 +
  65 +load another image, but into the same texture ID, overwriting the last one
  66 +
  67 + tex_2d = SOIL_load_OGL_texture
  68 + (
  69 + "some_other_img.dds",
  70 + SOIL_LOAD_AUTO,
  71 + tex_2d,
  72 + SOIL_FLAG_DDS_LOAD_DIRECT
  73 + );
  74 +
  75 +load 6 images into a new OpenGL cube map, forcing RGB
  76 +
  77 + GLuint tex_cube = SOIL_load_OGL_cubemap
  78 + (
  79 + "xp.jpg",
  80 + "xn.jpg",
  81 + "yp.jpg",
  82 + "yn.jpg",
  83 + "zp.jpg",
  84 + "zn.jpg",
  85 + SOIL_LOAD_RGB,
  86 + SOIL_CREATE_NEW_ID,
  87 + SOIL_FLAG_MIPMAPS
  88 + );
  89 +
  90 +load and split a single image into a new OpenGL cube map, default format
  91 +face order = East South West North Up Down => "ESWNUD", case sensitive!
  92 +
  93 + GLuint single_tex_cube = SOIL_load_OGL_single_cubemap
  94 + (
  95 + "split_cubemap.png",
  96 + "EWUDNS",
  97 + SOIL_LOAD_AUTO,
  98 + SOIL_CREATE_NEW_ID,
  99 + SOIL_FLAG_MIPMAPS
  100 + );
  101 +
  102 +actually, load a DDS cubemap over the last OpenGL cube map, default format
  103 +try to load it directly, but give the order of the faces in case that fails
  104 +the DDS cubemap face order is pre-defined as SOIL_DDS_CUBEMAP_FACE_ORDER
  105 +
  106 + single_tex_cube = SOIL_load_OGL_single_cubemap
  107 + (
  108 + "overwrite_cubemap.dds",
  109 + SOIL_DDS_CUBEMAP_FACE_ORDER,
  110 + SOIL_LOAD_AUTO,
  111 + single_tex_cube,
  112 + SOIL_FLAG_MIPMAPS | SOIL_FLAG_DDS_LOAD_DIRECT
  113 + );
  114 +
  115 +load an image as a heightmap, forcing greyscale (so channels should be 1)
  116 +
  117 + int width, height, channels;
  118 + unsigned char *ht_map = SOIL_load_image
  119 + (
  120 + "terrain.tga",
  121 + &width, &height, &channels,
  122 + SOIL_LOAD_L
  123 + );
  124 +
  125 +save that image as another type
  126 +
  127 + int save_result = SOIL_save_image
  128 + (
  129 + "new_terrain.dds",
  130 + SOIL_SAVE_TYPE_DDS,
  131 + width, height, channels,
  132 + ht_map
  133 + );
  134 +
  135 +save a screenshot of your awesome OpenGL game engine, running at 1024x768
  136 +
  137 + save_result = SOIL_save_screenshot
  138 + (
  139 + "awesomenessity.bmp",
  140 + SOIL_SAVE_TYPE_BMP,
  141 + 0, 0, 1024, 768
  142 + );
  143 +
  144 +loaded a file via PhysicsFS, need to decompress the image from RAM,
  145 +where it's in a buffer: unsigned char *image_in_RAM
  146 +
  147 + GLuint tex_2d_from_RAM = SOIL_load_OGL_texture_from_memory
  148 + (
  149 + image_in_RAM,
  150 + image_in_RAM_bytes,
  151 + SOIL_LOAD_AUTO,
  152 + SOIL_CREATE_NEW_ID,
  153 + SOIL_FLAG_MIPMAPS | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT
  154 + );
  155 +
  156 +done with the heightmap, free up the RAM
  157 +
  158 + SOIL_free_image_data( ht_map );

0 comments on commit 36f08f0

Please sign in to comment.
Something went wrong with that request. Please try again.