1 /*************************************************************************/ 2 /* image.h */ 3 /*************************************************************************/ 4 /* This file is part of: */ 5 /* GODOT ENGINE */ 6 /* https://godotengine.org */ 7 /*************************************************************************/ 8 /* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur. */ 9 /* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md). */ 10 /* */ 11 /* Permission is hereby granted, free of charge, to any person obtaining */ 12 /* a copy of this software and associated documentation files (the */ 13 /* "Software"), to deal in the Software without restriction, including */ 14 /* without limitation the rights to use, copy, modify, merge, publish, */ 15 /* distribute, sublicense, and/or sell copies of the Software, and to */ 16 /* permit persons to whom the Software is furnished to do so, subject to */ 17 /* the following conditions: */ 18 /* */ 19 /* The above copyright notice and this permission notice shall be */ 20 /* included in all copies or substantial portions of the Software. */ 21 /* */ 22 /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ 23 /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ 24 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/ 25 /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ 26 /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ 27 /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ 28 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ 29 /*************************************************************************/ 30 31 #ifndef IMAGE_H 32 #define IMAGE_H 33 34 #include "core/color.h" 35 #include "core/math/rect2.h" 36 #include "core/pool_vector.h" 37 #include "core/resource.h" 38 39 /** 40 * @author Juan Linietsky <reduzio@gmail.com> 41 * 42 * Image storage class. This is used to store an image in user memory, as well as 43 * providing some basic methods for image manipulation. 44 * Images can be loaded from a file, or registered into the Render object as textures. 45 */ 46 47 class Image; 48 49 typedef Error (*SavePNGFunc)(const String &p_path, const Ref<Image> &p_img); 50 typedef PoolVector<uint8_t> (*SavePNGBufferFunc)(const Ref<Image> &p_img); 51 typedef Ref<Image> (*ImageMemLoadFunc)(const uint8_t *p_png, int p_size); 52 53 typedef Error (*SaveEXRFunc)(const String &p_path, const Ref<Image> &p_img, bool p_grayscale); 54 55 class Image : public Resource { 56 GDCLASS(Image, Resource); 57 58 public: 59 static SavePNGFunc save_png_func; 60 static SaveEXRFunc save_exr_func; 61 static SavePNGBufferFunc save_png_buffer_func; 62 63 enum { 64 MAX_WIDTH = 16384, // force a limit somehow 65 MAX_HEIGHT = 16384 // force a limit somehow 66 }; 67 68 enum Format { 69 70 FORMAT_L8, //luminance 71 FORMAT_LA8, //luminance-alpha 72 FORMAT_R8, 73 FORMAT_RG8, 74 FORMAT_RGB8, 75 FORMAT_RGBA8, 76 FORMAT_RGBA4444, 77 FORMAT_RGBA5551, 78 FORMAT_RF, //float 79 FORMAT_RGF, 80 FORMAT_RGBF, 81 FORMAT_RGBAF, 82 FORMAT_RH, //half float 83 FORMAT_RGH, 84 FORMAT_RGBH, 85 FORMAT_RGBAH, 86 FORMAT_RGBE9995, 87 FORMAT_DXT1, //s3tc bc1 88 FORMAT_DXT3, //bc2 89 FORMAT_DXT5, //bc3 90 FORMAT_RGTC_R, 91 FORMAT_RGTC_RG, 92 FORMAT_BPTC_RGBA, //btpc bc7 93 FORMAT_BPTC_RGBF, //float bc6h 94 FORMAT_BPTC_RGBFU, //unsigned float bc6hu 95 FORMAT_PVRTC2, //pvrtc 96 FORMAT_PVRTC2A, 97 FORMAT_PVRTC4, 98 FORMAT_PVRTC4A, 99 FORMAT_ETC, //etc1 100 FORMAT_ETC2_R11, //etc2 101 FORMAT_ETC2_R11S, //signed, NOT srgb. 102 FORMAT_ETC2_RG11, 103 FORMAT_ETC2_RG11S, 104 FORMAT_ETC2_RGB8, 105 FORMAT_ETC2_RGBA8, 106 FORMAT_ETC2_RGB8A1, 107 FORMAT_MAX 108 }; 109 110 static const char *format_names[FORMAT_MAX]; 111 enum Interpolation { 112 113 INTERPOLATE_NEAREST, 114 INTERPOLATE_BILINEAR, 115 INTERPOLATE_CUBIC, 116 INTERPOLATE_TRILINEAR, 117 INTERPOLATE_LANCZOS, 118 /* INTERPOLATE_TRICUBIC, */ 119 /* INTERPOLATE GAUSS */ 120 }; 121 122 enum CompressSource { 123 COMPRESS_SOURCE_GENERIC, 124 COMPRESS_SOURCE_SRGB, 125 COMPRESS_SOURCE_NORMAL, 126 COMPRESS_SOURCE_LAYERED, 127 }; 128 129 //some functions provided by something else 130 131 static ImageMemLoadFunc _png_mem_loader_func; 132 static ImageMemLoadFunc _jpg_mem_loader_func; 133 static ImageMemLoadFunc _webp_mem_loader_func; 134 static ImageMemLoadFunc _tga_mem_loader_func; 135 136 static void (*_image_compress_bc_func)(Image *, float, CompressSource p_source); 137 static void (*_image_compress_bptc_func)(Image *, float p_lossy_quality, CompressSource p_source); 138 static void (*_image_compress_pvrtc2_func)(Image *); 139 static void (*_image_compress_pvrtc4_func)(Image *); 140 static void (*_image_compress_etc1_func)(Image *, float); 141 static void (*_image_compress_etc2_func)(Image *, float, CompressSource p_source); 142 143 static void (*_image_decompress_pvrtc)(Image *); 144 static void (*_image_decompress_bc)(Image *); 145 static void (*_image_decompress_bptc)(Image *); 146 static void (*_image_decompress_etc1)(Image *); 147 static void (*_image_decompress_etc2)(Image *); 148 149 static PoolVector<uint8_t> (*lossy_packer)(const Ref<Image> &p_image, float p_quality); 150 static Ref<Image> (*lossy_unpacker)(const PoolVector<uint8_t> &p_buffer); 151 static PoolVector<uint8_t> (*lossless_packer)(const Ref<Image> &p_image); 152 static Ref<Image> (*lossless_unpacker)(const PoolVector<uint8_t> &p_buffer); 153 154 PoolVector<uint8_t>::Write write_lock; 155 156 protected: 157 static void _bind_methods(); 158 159 private: _create_empty(int p_width,int p_height,bool p_use_mipmaps,Format p_format)160 void _create_empty(int p_width, int p_height, bool p_use_mipmaps, Format p_format) { 161 create(p_width, p_height, p_use_mipmaps, p_format); 162 } 163 _create_from_data(int p_width,int p_height,bool p_use_mipmaps,Format p_format,const PoolVector<uint8_t> & p_data)164 void _create_from_data(int p_width, int p_height, bool p_use_mipmaps, Format p_format, const PoolVector<uint8_t> &p_data) { 165 create(p_width, p_height, p_use_mipmaps, p_format, p_data); 166 } 167 168 Format format; 169 PoolVector<uint8_t> data; 170 int width, height; 171 bool mipmaps; 172 _copy_internals_from(const Image & p_image)173 void _copy_internals_from(const Image &p_image) { 174 format = p_image.format; 175 width = p_image.width; 176 height = p_image.height; 177 mipmaps = p_image.mipmaps; 178 data = p_image.data; 179 } 180 181 _FORCE_INLINE_ void _get_mipmap_offset_and_size(int p_mipmap, int &r_offset, int &r_width, int &r_height) const; //get where the mipmap begins in data 182 183 static int _get_dst_image_size(int p_width, int p_height, Format p_format, int &r_mipmaps, int p_mipmaps = -1); 184 bool _can_modify(Format p_format) const; 185 186 _FORCE_INLINE_ void _put_pixelb(int p_x, int p_y, uint32_t p_pixelsize, uint8_t *p_data, const uint8_t *p_pixel); 187 _FORCE_INLINE_ void _get_pixelb(int p_x, int p_y, uint32_t p_pixelsize, const uint8_t *p_data, uint8_t *p_pixel); 188 189 void _set_data(const Dictionary &p_data); 190 Dictionary _get_data() const; 191 192 Error _load_from_buffer(const PoolVector<uint8_t> &p_array, ImageMemLoadFunc p_loader); 193 194 static void average_4_uint8(uint8_t &p_out, const uint8_t &p_a, const uint8_t &p_b, const uint8_t &p_c, const uint8_t &p_d); 195 static void average_4_float(float &p_out, const float &p_a, const float &p_b, const float &p_c, const float &p_d); 196 static void average_4_half(uint16_t &p_out, const uint16_t &p_a, const uint16_t &p_b, const uint16_t &p_c, const uint16_t &p_d); 197 static void average_4_rgbe9995(uint32_t &p_out, const uint32_t &p_a, const uint32_t &p_b, const uint32_t &p_c, const uint32_t &p_d); 198 static void renormalize_uint8(uint8_t *p_rgb); 199 static void renormalize_float(float *p_rgb); 200 static void renormalize_half(uint16_t *p_rgb); 201 static void renormalize_rgbe9995(uint32_t *p_rgb); 202 203 public: 204 int get_width() const; ///< Get image width 205 int get_height() const; ///< Get image height 206 Vector2 get_size() const; 207 bool has_mipmaps() const; 208 int get_mipmap_count() const; 209 210 /** 211 * Convert the image to another format, conversion only to raw byte format 212 */ 213 void convert(Format p_new_format); 214 215 /** 216 * Get the current image format. 217 */ 218 Format get_format() const; 219 220 int get_mipmap_offset(int p_mipmap) const; //get where the mipmap begins in data 221 void get_mipmap_offset_and_size(int p_mipmap, int &r_ofs, int &r_size) const; //get where the mipmap begins in data 222 void get_mipmap_offset_size_and_dimensions(int p_mipmap, int &r_ofs, int &r_size, int &w, int &h) const; //get where the mipmap begins in data 223 224 /** 225 * Resize the image, using the preferred interpolation method. 226 */ 227 void resize_to_po2(bool p_square = false); 228 void resize(int p_width, int p_height, Interpolation p_interpolation = INTERPOLATE_BILINEAR); 229 void shrink_x2(); 230 void expand_x2_hq2x(); 231 bool is_size_po2() const; 232 /** 233 * Crop the image to a specific size, if larger, then the image is filled by black 234 */ 235 void crop_from_point(int p_x, int p_y, int p_width, int p_height); 236 void crop(int p_width, int p_height); 237 238 void flip_x(); 239 void flip_y(); 240 241 /** 242 * Generate a mipmap to an image (creates an image 1/4 the size, with averaging of 4->1) 243 */ 244 Error generate_mipmaps(bool p_renormalize = false); 245 246 void clear_mipmaps(); 247 void normalize(); //for normal maps 248 249 /** 250 * Create a new image of a given size and format. Current image will be lost 251 */ 252 void create(int p_width, int p_height, bool p_use_mipmaps, Format p_format); 253 void create(int p_width, int p_height, bool p_use_mipmaps, Format p_format, const PoolVector<uint8_t> &p_data); 254 255 void create(const char **p_xpm); 256 /** 257 * returns true when the image is empty (0,0) in size 258 */ 259 bool empty() const; 260 261 PoolVector<uint8_t> get_data() const; 262 263 Error load(const String &p_path); 264 Error save_png(const String &p_path) const; 265 PoolVector<uint8_t> save_png_to_buffer() const; 266 Error save_exr(const String &p_path, bool p_grayscale) const; 267 268 /** 269 * create an empty image 270 */ 271 Image(); 272 /** 273 * create an empty image of a specific size and format 274 */ 275 Image(int p_width, int p_height, bool p_use_mipmaps, Format p_format); 276 /** 277 * import an image of a specific size and format from a pointer 278 */ 279 Image(int p_width, int p_height, bool p_mipmaps, Format p_format, const PoolVector<uint8_t> &p_data); 280 281 enum AlphaMode { 282 ALPHA_NONE, 283 ALPHA_BIT, 284 ALPHA_BLEND 285 }; 286 287 AlphaMode detect_alpha() const; 288 bool is_invisible() const; 289 290 static int get_format_pixel_size(Format p_format); 291 static int get_format_pixel_rshift(Format p_format); 292 static int get_format_block_size(Format p_format); 293 static void get_format_min_pixel_size(Format p_format, int &r_w, int &r_h); 294 295 static int get_image_data_size(int p_width, int p_height, Format p_format, bool p_mipmaps = false); 296 static int get_image_required_mipmaps(int p_width, int p_height, Format p_format); 297 static int get_image_mipmap_offset(int p_width, int p_height, Format p_format, int p_mipmap); 298 299 enum CompressMode { 300 COMPRESS_S3TC, 301 COMPRESS_PVRTC2, 302 COMPRESS_PVRTC4, 303 COMPRESS_ETC, 304 COMPRESS_ETC2, 305 COMPRESS_BPTC 306 }; 307 308 Error compress(CompressMode p_mode = COMPRESS_S3TC, CompressSource p_source = COMPRESS_SOURCE_GENERIC, float p_lossy_quality = 0.7); 309 Error decompress(); 310 bool is_compressed() const; 311 312 void fix_alpha_edges(); 313 void premultiply_alpha(); 314 void srgb_to_linear(); 315 void normalmap_to_xy(); 316 Ref<Image> rgbe_to_srgb(); 317 void bumpmap_to_normalmap(float bump_scale = 1.0); 318 319 void blit_rect(const Ref<Image> &p_src, const Rect2 &p_src_rect, const Point2 &p_dest); 320 void blit_rect_mask(const Ref<Image> &p_src, const Ref<Image> &p_mask, const Rect2 &p_src_rect, const Point2 &p_dest); 321 void blend_rect(const Ref<Image> &p_src, const Rect2 &p_src_rect, const Point2 &p_dest); 322 void blend_rect_mask(const Ref<Image> &p_src, const Ref<Image> &p_mask, const Rect2 &p_src_rect, const Point2 &p_dest); 323 void fill(const Color &c); 324 325 Rect2 get_used_rect() const; 326 Ref<Image> get_rect(const Rect2 &p_area) const; 327 328 static void set_compress_bc_func(void (*p_compress_func)(Image *, float, CompressSource)); 329 static void set_compress_bptc_func(void (*p_compress_func)(Image *, float, CompressSource)); 330 static String get_format_name(Format p_format); 331 332 Error load_png_from_buffer(const PoolVector<uint8_t> &p_array); 333 Error load_jpg_from_buffer(const PoolVector<uint8_t> &p_array); 334 Error load_webp_from_buffer(const PoolVector<uint8_t> &p_array); 335 Error load_tga_from_buffer(const PoolVector<uint8_t> &p_array); 336 337 Image(const uint8_t *p_mem_png_jpg, int p_len = -1); 338 Image(const char **p_xpm); 339 340 virtual Ref<Resource> duplicate(bool p_subresources = false) const; 341 342 void lock(); 343 void unlock(); 344 345 //this is used for compression 346 enum DetectChannels { 347 DETECTED_L, 348 DETECTED_LA, 349 DETECTED_R, 350 DETECTED_RG, 351 DETECTED_RGB, 352 DETECTED_RGBA, 353 }; 354 355 DetectChannels get_detected_channels(); 356 void optimize_channels(); 357 358 Color get_pixelv(const Point2 &p_src) const; 359 Color get_pixel(int p_x, int p_y) const; 360 void set_pixelv(const Point2 &p_dst, const Color &p_color); 361 void set_pixel(int p_x, int p_y, const Color &p_color); 362 copy_internals_from(const Ref<Image> & p_image)363 void copy_internals_from(const Ref<Image> &p_image) { 364 ERR_FAIL_COND_MSG(p_image.is_null(), "It's not a reference to a valid Image object."); 365 format = p_image->format; 366 width = p_image->width; 367 height = p_image->height; 368 mipmaps = p_image->mipmaps; 369 data = p_image->data; 370 } 371 372 ~Image(); 373 }; 374 375 VARIANT_ENUM_CAST(Image::Format) 376 VARIANT_ENUM_CAST(Image::Interpolation) 377 VARIANT_ENUM_CAST(Image::CompressMode) 378 VARIANT_ENUM_CAST(Image::CompressSource) 379 VARIANT_ENUM_CAST(Image::AlphaMode) 380 381 #endif 382