1 /* 2 * Copyright 2012 Intel Corporation 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining a 5 * copy of this software and associated documentation files (the "Software"), 6 * to deal in the Software without restriction, including without limitation 7 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 8 * and/or sell copies of the Software, and to permit persons to whom the 9 * Software is furnished to do so, subject to the following conditions: 10 * 11 * The above copyright notice and this permission notice (including the next 12 * paragraph) shall be included in all copies or substantial portions of the 13 * Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 21 * IN THE SOFTWARE. 22 */ 23 24 /** 25 * \file 26 * 27 * \brief Utilities for the KTX file format. 28 * 29 * The KTX (Khronos texture) file format specifies a simple format for 30 * storing texture miptrees. The file format allows texture data for any 31 * GL texture format and any GL texture target. 32 * 33 * \see http://www.khronos.org/opengles/sdk/tools/KTX/file_format_spec/ 34 */ 35 36 #include <stdbool.h> 37 #include <stdio.h> 38 #include <stdint.h> 39 40 #include <piglit/gl_wrap.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 struct piglit_ktx; 47 48 struct piglit_ktx_info { 49 /** \brief Size in bytes of the raw KTX data. */ 50 size_t size; 51 52 /** 53 * \brief GL texture target. 54 * 55 * This is the `target` agument passed to glTexImage() It is 56 * completely determined by pixel_size, array_length, and num_faces. 57 * Valid values are 58 * - GL_TEXTURE_1D 59 * - GL_TEXTURE_1D_ARRAY 60 * - GL_TEXTURE_2D 61 * - GL_TEXTURE_2D_ARRAY 62 * - GL_TEXTURE_3D 63 * - GL_TEXTURE_CUBE_MAP 64 * - GL_TEXTURE_CUBE_MAP_ARRAY 65 */ 66 GLenum target; 67 68 /** 69 * For compressed textures, gl_type is 0. For non-compressed textures, 70 * gl_type is the 'type' argument passed to glTexImage(). For example, 71 * GL_FLOAT. 72 */ 73 uint32_t gl_type; 74 75 /** 76 * For compressed textures, gl_type_size is 1. For non-compressed 77 * textures, gl_type_size is the size in bytes of gl_type. For example, 78 * if gl_type is GL_FLOAT, gl_type_size is 4. 79 */ 80 uint32_t gl_type_size; 81 82 /** 83 * For compressed textures, gl_format is 0. For non-compressed textures, 84 * gl_format is the 'format' argument passed to glTexImage(). For 85 * example, GL_RGBA. 86 */ 87 uint32_t gl_format; 88 89 /** 90 * For compressed and non-compressed textures, gl_internal_format is the 91 * 'internal_format' argument passed to glTexImage(). For 92 * non-compressed textures, this is always a sized format. For example, 93 * GL_RGBA32F. 94 */ 95 uint32_t gl_internal_format; 96 97 /** 98 * For compressed textures, gl_base_internal_format is the same as 99 * gl_internal_format. For non-compressed textures, 100 * gl_base_internal_format is the same as gl_internal_format. 101 * 102 * (I (chadv) dont' understand what purpose this field serves, But 103 * the KTX spec requires it in the header). 104 */ 105 uint32_t gl_base_internal_format; 106 107 /** 108 * \name Size of texture, in pixels. 109 * \{ 110 * 111 * For 1D textures, height and depth are 0. For 2D and cube textures, 112 * depth is 0. For block compressed textures, the sizes are not 113 * rounded to block size. 114 * 115 * Note: The sizes here are those in the KTX header, which differ from 116 * the sizes passed to glTexImage(). 117 */ 118 uint32_t pixel_width; 119 uint32_t pixel_height; 120 uint32_t pixel_depth; 121 /** \} */ 122 123 /** 124 * If the texture is not an array texture, then array_lengthis 0. 125 */ 126 uint32_t array_length; 127 128 /** 129 * For cubemaps and cubemap arrays, num_faces is 6. For all other 130 * textures, it is 1. 131 */ 132 uint32_t num_faces; 133 134 /** 135 * For non-mipmapped textures, num_miplevels is 1. 136 */ 137 uint32_t num_miplevels; 138 139 /** 140 * For non-array cubemaps, the number of images is 6 * num_miplevels. 141 * For all other textures, the number of images and miplevels is the 142 * same. 143 */ 144 uint32_t num_images; 145 }; 146 147 struct piglit_ktx_image { 148 /** 149 * \brief The raw image data. 150 * 151 * This points to the image located in piglit_ktx_info::data. It may 152 * be passed as the 'data' argument to glTexImage(). 153 */ 154 const void *data; 155 156 /** 157 * \brief Size of image, in bytes. 158 * 159 * This is 'imageSize' argument passed to glTexImage(). It does not 160 * include any padding which may be present in ktx_info::bytes. 161 */ 162 size_t size; 163 164 /** 165 * In range [0, num_miplevels). 166 */ 167 uint32_t miplevel; 168 169 /** 170 * For non-array cubemap textures, `face` is in range [0, 6). For all 171 * other textures, it is 0. 172 */ 173 uint32_t face; 174 175 /** 176 * \name Size of image, in pixels. 177 * \{ 178 * 179 * These are the sizes passed to glTexImage(). 180 * Note: These sizes differ from those in the KTX header. 181 */ 182 uint32_t pixel_width; 183 uint32_t pixel_height; 184 uint32_t pixel_depth; 185 /** \} */ 186 }; 187 188 void 189 piglit_ktx_destroy(struct piglit_ktx *self); 190 191 /** 192 * \brief Read KTX data from a file. 193 * 194 * The file is read until EOF. 195 * 196 * Return null on error, including I/O error and invalid data. 197 */ 198 struct piglit_ktx* 199 piglit_ktx_read_file(const char *filename); 200 201 /** 202 * \brief Read KTX data from a byte array. 203 * 204 * Read at most \a size bytes. 205 * 206 * The given \a size is not used to calculate the expected length of the KTX 207 * data; that is completely determined by the content of the KTX header. 208 * Instead, the given \a size is a safeguard against reading out-of-bounds 209 * memory when incorrect data is present into the header. 210 * 211 * Return null on error, including invalid data and insufficient \a size. 212 */ 213 struct piglit_ktx* 214 piglit_ktx_read_bytes(const void *bytes, size_t size); 215 216 /** 217 * \brief Write KTX data to a file. 218 * 219 * The number of bytes written is `piglit_ktx_get_info()->size`. 220 */ 221 bool 222 piglit_ktx_write_file(struct piglit_ktx *self, const char *filename); 223 224 /** 225 * \brief Write KTX data to a byte array. 226 * 227 * The number of bytes written is `piglit_ktx_get_info()->size`. 228 */ 229 bool 230 piglit_ktx_write_bytes(struct piglit_ktx *self, void *bytes); 231 232 const struct piglit_ktx_info* 233 piglit_ktx_get_info(struct piglit_ktx *self); 234 235 /** 236 * \brief Get a texture image from a KTX file. 237 * 238 * The given \a miplevel must be in the range `[0, 239 * piglit_ktx_info::num_miplevels)`. For cubemap non-array textures, \a 240 * cube_face must be in the range [0, 5]. For all other textures, \a 241 * cube_face must be 0. If the above is not satisfied, an error is produced. 242 * 243 * Note: For cubemap array textures, \a cube_face must be 0 because 244 * piglit_ktx_image::data is the data that would be passed to glTexImage3D(), 245 * which is not separated into individual faces. 246 */ 247 const struct piglit_ktx_image* 248 piglit_ktx_get_image(struct piglit_ktx *self, 249 int miplevel, 250 int cube_face); 251 252 /** 253 * \brief Load texture into the GL with glTexImage(). 254 * 255 * If \a *tex_name is non-zero, then that texture is bound to 256 * `piglit_ktx_info::target` and the texture images are loaded into it with 257 * glTexImage(). If \a *tex_name is 0, then a new texture is first created. 258 * The new texture name is returned \a tex_name. 259 * 260 * Return false on failure. If failure is due to a GL error and \a gl_error is 261 * not null, then the value of glGetError() is returned in \a gl_error. 262 */ 263 bool 264 piglit_ktx_load_texture(struct piglit_ktx *self, 265 GLuint *tex_name, 266 GLenum *gl_error); 267 268 #ifdef __cplusplus 269 } 270 #endif 271