Panda3D

texture.I
Go to the documentation of this file.
1 /**
2 * PANDA 3D SOFTWARE
3 * Copyright (c) Carnegie Mellon University. All rights reserved.
4 *
5 * All use of this software is subject to the terms of the revised BSD
6 * license. You should have received a copy of this license along
7 * with this source code in a file named "LICENSE."
8 *
9 * @file texture.I
10 * @author drose
11 * @date 1999-02-05
12 * @author fperazzi, PandaSE
13 * @date 2010-04-29
14 */
15
16 /**
17 * Returns a new copy of the same Texture. This copy, if applied to geometry,
18 * will be copied into texture as a separate texture from the original, so it
19 * will be duplicated in texture memory (and may be independently modified if
20 * desired).
21 *
22 * If the Texture is a VideoTexture, the resulting duplicate may be animated
23 * independently of the original.
24 */
25 INLINE PT(Texture) Texture::
26 make_copy() const {
27 PT(Texture) tex = make_copy_impl();
28 CDWriter cdata_tex(tex->_cycler, true);
29 cdata_tex->inc_properties_modified();
30 cdata_tex->inc_image_modified();
31 cdata_tex->inc_simple_image_modified();
32 return tex;
33 }
34
35 /**
36 * Reinitializes the texture to its default, empty state (except for the
37 * name).
38 */
39 INLINE void Texture::
40 clear() {
41 CDWriter cdata(_cycler, true);
42 do_clear(cdata);
43 }
44
45 /**
46 * Sets the texture to the indicated type and dimensions, presumably in
47 * preparation for calling read() or load(), or set_ram_image() or
48 * modify_ram_image(), or use set_clear_color to let the texture be cleared to
49 * a solid color.
50 */
51 INLINE void Texture::
52 setup_texture(Texture::TextureType texture_type, int x_size, int y_size,
53 int z_size, Texture::ComponentType component_type,
54 Texture::Format format) {
55 CDWriter cdata(_cycler, true);
56 do_setup_texture(cdata, texture_type, x_size, y_size, z_size,
57 component_type, format);
58 }
59
60 /**
61 * Sets the texture as an empty 1-d texture with no dimensions. Follow up
62 * with read() or load() to fill the texture properties and image data, or use
63 * set_clear_color to let the texture be cleared to a solid color.
64 */
65 INLINE void Texture::
66 setup_1d_texture() {
67 setup_1d_texture(0, T_unsigned_byte, F_rgb);
68 }
69
70 /**
71 * Sets the texture as an empty 1-d texture with the specified dimensions and
72 * properties. Follow up with set_ram_image() or modify_ram_image() to fill
73 * the image data, or use set_clear_color to let the texture be cleared to a
74 * solid color.
75 */
76 INLINE void Texture::
77 setup_1d_texture(int x_size, ComponentType component_type, Format format) {
78 setup_texture(TT_1d_texture, x_size, 1, 1, component_type, format);
79 }
80
81 /**
82 * Sets the texture as an empty 2-d texture with no dimensions. Follow up
83 * with read() or load() to fill the texture properties and image data, or use
84 * set_clear_color to let the texture be cleared to a solid color.
85 */
86 INLINE void Texture::
87 setup_2d_texture() {
88 setup_2d_texture(0, 1, T_unsigned_byte, F_rgb);
89 }
90
91 /**
92 * Sets the texture as an empty 2-d texture with the specified dimensions and
93 * properties. Follow up with set_ram_image() or modify_ram_image() to fill
94 * the image data, or use set_clear_color to let the texture be cleared to a
95 * solid color.
96 */
97 INLINE void Texture::
98 setup_2d_texture(int x_size, int y_size, ComponentType component_type,
99 Format format) {
100 setup_texture(TT_2d_texture, x_size, y_size, 1, component_type, format);
101 }
102
103 /**
104 * Sets the texture as an empty 3-d texture with no dimensions (though if you
105 * know the depth ahead of time, it saves a bit of reallocation later). Follow
106 * up with read() or load() to fill the texture properties and image data, or
107 * use set_clear_color to let the texture be cleared to a solid color.
108 */
109 INLINE void Texture::
110 setup_3d_texture(int z_size) {
111 setup_3d_texture(0, 1, z_size, T_unsigned_byte, F_rgb);
112 }
113
114 /**
115 * Sets the texture as an empty 3-d texture with the specified dimensions and
116 * properties. Follow up with set_ram_image() or modify_ram_image() to fill
117 * the image data.
118 */
119 INLINE void Texture::
120 setup_3d_texture(int x_size, int y_size, int z_size,
121 ComponentType component_type, Format format) {
122 setup_texture(TT_3d_texture, x_size, y_size, z_size, component_type, format);
123 }
124
125 /**
126 * Sets the texture as an empty 2-d texture array with no dimensions (though
127 * if you know the depth ahead of time, it saves a bit of reallocation later).
128 * Follow up with read() or load() to fill the texture properties and image
129 * data, or use set_clear_color to let the texture be cleared to a solid
130 * color.
131 */
132 INLINE void Texture::
133 setup_2d_texture_array(int z_size) {
134 setup_2d_texture_array(0, 1, z_size, T_unsigned_byte, F_rgb);
135 }
136
137 /**
138 * Sets the texture as an empty 2-d texture array with the specified
139 * dimensions and properties. Follow up with set_ram_image() or
140 * modify_ram_image() to fill the image data, or use set_clear_color to let
141 * the texture be cleared to a solid color.
142 */
143 INLINE void Texture::
144 setup_2d_texture_array(int x_size, int y_size, int z_size,
145 ComponentType component_type, Format format) {
146 setup_texture(TT_2d_texture_array, x_size, y_size, z_size, component_type, format);
147 }
148
149 /**
150 * Sets the texture as an empty cube map texture with no dimensions. Follow
151 * up with read() or load() to fill the texture properties and image data, or
152 * use set_clear_color to let the texture be cleared to a solid color.
153 */
154 INLINE void Texture::
155 setup_cube_map() {
156 setup_cube_map(0, T_unsigned_byte, F_rgb);
157 }
158
159 /**
160 * Sets the texture as an empty cube map texture with the specified dimensions
161 * and properties. Follow up with set_ram_image() or modify_ram_image() to
162 * fill the image data, or use set_clear_color to let the texture be cleared
163 * to a solid color.
164 *
165 * Note that a cube map should always consist of six square images, so x_size
166 * and y_size will be the same, and z_size is always 6.
167 */
168 INLINE void Texture::
169 setup_cube_map(int size, ComponentType component_type, Format format) {
170 setup_texture(TT_cube_map, size, size, 6, component_type, format);
171 }
172
173 /**
174 * Sets the texture as cube map array with N cube maps. Note that this number
175 * is not the same as the z_size. Follow up with read() or load() to fill the
176 * texture properties and image data, or use set_clear_color to let the
177 * texture be cleared to a solid color.
178 *
179 * @since 1.10.0
180 */
181 INLINE void Texture::
182 setup_cube_map_array(int num_cube_maps) {
183 setup_cube_map_array(0, num_cube_maps, T_unsigned_byte, F_rgb);
184 }
185
186 /**
187 * Sets the texture as cube map array with N cube maps with the specified
188 * dimensions and format. Follow up with set_ram_image() or
189 * modify_ram_image() to fill the image data, or use set_clear_color to let
190 * the texture be cleared to a solid color.
191 *
192 * The num_cube_maps given here is multiplied by six to become the z_size of
193 * the image.
194 *
195 * @since 1.10.0
196 */
197 INLINE void Texture::
198 setup_cube_map_array(int size, int num_cube_maps, ComponentType component_type, Format format) {
199 setup_texture(TT_cube_map_array, size, size, num_cube_maps * 6, component_type, format);
200 }
201
202 /**
203 * Sets the texture as an empty buffer texture with the specified size and
204 * properties. Follow up with set_ram_image() or modify_ram_image() to fill
205 * the image data, or use set_clear_color to let the texture be cleared to a
206 * solid color.
207 *
208 * Note that a buffer texture's format needs to match the component type.
209 */
210 INLINE void Texture::
211 setup_buffer_texture(int size, ComponentType component_type, Format format,
212 GeomEnums::UsageHint usage) {
213 setup_texture(TT_buffer_texture, size, 1, 1, component_type, format);
214 CDWriter cdata(_cycler);
215 cdata->_usage_hint = usage;
216 }
217
218 /**
219 * Clears the texture data without changing its format or resolution. The
220 * texture is cleared on both the graphics hardware and from RAM, unlike
221 * clear_ram_image, which only removes the data from RAM.
222 *
223 * If a clear color has been specified using set_clear_color, the texture will
224 * be cleared using a solid color.
225 *
226 * The texture data will be cleared the first time in which the texture is
227 * used after this method is called.
228 */
229 INLINE void Texture::
230 clear_image() {
231 CDWriter cdata(_cycler, true);
232 do_clear_ram_image(cdata);
233 do_clear_simple_ram_image(cdata);
234 cdata->inc_image_modified();
235 cdata->inc_simple_image_modified();
236 }
237
238 /**
239 * Returns true if a color was previously set using set_clear_color.
240 */
241 INLINE bool Texture::
242 has_clear_color() const {
243 CDReader cdata(_cycler);
244 return cdata->_has_clear_color;
245 }
246
247 /**
248 * Returns the color that was previously set using set_clear_color.
249 */
250 INLINE LColor Texture::
251 get_clear_color() const {
252 CDReader cdata(_cycler);
253 return cdata->_clear_color;
254 }
255
256 /**
257 * Sets the color that will be used to fill the texture image in absence of
258 * any image data. It is used when any of the setup_texture functions or
259 * clear_image is called and image data is not provided using read() or
260 * modify_ram_image().
261 *
262 * This does not affect a texture that has already been cleared; call
263 * clear_image to clear it again.
264 */
265 INLINE void Texture::
266 set_clear_color(const LColor &color) {
267 CDWriter cdata(_cycler, true);
268 cdata->_clear_color = color;
269 cdata->_has_clear_color = true;
270 }
271
272 /**
273 * The opposite of set_clear_color. If the image is cleared after setting
274 * this, its contents may be undefined (or may in fact not be cleared at all).
275 */
276 INLINE void Texture::
277 clear_clear_color() {
278 CDWriter cdata(_cycler, true);
279 cdata->_has_clear_color = true;
280 }
281
282 /**
283 * Returns the raw image data for a single pixel if it were set to the clear
284 * color.
285 */
286 INLINE vector_uchar Texture::
287 get_clear_data() const {
288 CDReader cdata(_cycler);
289 vector_uchar data(16);
290 data.resize(do_get_clear_data(cdata, &data[0]));
291 return data;
292 }
293
294 /**
295 * Writes the texture to the named filename.
296 */
297 INLINE bool Texture::
298 write(const Filename &fullpath) {
299 CDWriter cdata(_cycler);
300
301 // do_write() is non-const, because it might have to reload the ram image.
302 return do_write(cdata, fullpath, 0, 0, false, false);
303 }
304
305 /**
306 * Writes a single page or mipmap level to a single file, or automatically
307 * writes a series of pages and/or mipmap levels to a numbered series of
308 * files.
309 *
310 * If the filename ends in the extension .txo, this implicitly writes a Panda
311 * texture object (.txo) instead of an image file. In this case, the
312 * remaining parameters are ignored, and only one file is written, which will
313 * contain all of the pages and resident mipmap levels in the texture.
314 *
315 * If write_pages is false, then z indicates the page number to write. 3-D
316 * textures have one page number for each level of depth; cube maps have six
317 * pages number 0 through 5. Other kinds of textures have only one page,
318 * numbered 0. If there are multiple views, the range of z is increased; the
319 * total range is [0, get_num_pages()).
320 *
321 * If write_pages is true, then all pages of the texture will be written. In
322 * this case z is ignored, and the filename should contain a sequence of hash
323 * marks ("#") which will be filled in with the page index number.
324 *
325 * If write_mipmaps is false, then n indicates the mipmap level number to
326 * write. Normally, this is 0, for the base texture image. Normally, the
327 * mipmap levels of a texture are not available in RAM (they are generated
328 * automatically by the graphics card). However, if you have the mipmap levels
329 * available, for instance because you called generate_ram_mipmap_images() to
330 * generate them internally, or you called
331 * GraphicsEngine::extract_texture_data() to retrieve them from the graphics
332 * card, then you may write out each mipmap level with this parameter.
333 *
334 * If write_mipmaps is true, then all mipmap levels of the texture will be
335 * written. In this case n is ignored, and the filename should contain a
336 * sequence of hash marks ("#") which will be filled in with the mipmap level
337 * number.
338 *
339 * If both write_pages and write_mipmaps is true, then all pages and all
340 * mipmap levels will be written. In this case, the filename should contain
341 * two different sequences of hash marks, separated by a character such as a
342 * hyphen, underscore, or dot. The first hash mark sequence will be filled in
343 * with the mipmap level, while the second hash mark sequence will be the page
344 * index.
345 */
346 INLINE bool Texture::
347 write(const Filename &fullpath, int z, int n,
348 bool write_pages, bool write_mipmaps) {
349 CDWriter cdata(_cycler, false);
350 return do_write(cdata, fullpath, z, n, write_pages, write_mipmaps);
351 }
352
353 /**
354 * Replaces the texture with the indicated image.
355 */
356 INLINE bool Texture::
357 load(const PNMImage &pnmimage, const LoaderOptions &options) {
358 CDWriter cdata(_cycler, true);
359 do_clear(cdata);
360 cdata->inc_properties_modified();
361 cdata->inc_image_modified();
362 if (do_load_one(cdata, pnmimage, get_name(), 0, 0, options)) {
363 bool generate_mipmaps = ((options.get_texture_flags() & LoaderOptions::TF_generate_mipmaps) != 0);
364 consider_auto_process_ram_image(generate_mipmaps || uses_mipmaps(), true);
365 return true;
366 }
367 return false;
368 }
369
370 /**
371 * Stores the indicated image in the given page and mipmap level. See read().
372 */
373 INLINE bool Texture::
374 load(const PNMImage &pnmimage, int z, int n, const LoaderOptions &options) {
375 CDWriter cdata(_cycler, true);
376 cdata->inc_properties_modified();
377 cdata->inc_image_modified();
378 if (do_load_one(cdata, pnmimage, get_name(), z, n, options)) {
379 return true;
380 }
381 return false;
382 }
383
384 /**
385 * Replaces the texture with the indicated image.
386 */
387 INLINE bool Texture::
388 load(const PfmFile &pfm, const LoaderOptions &options) {
389 CDWriter cdata(_cycler, true);
390 do_clear(cdata);
391 cdata->inc_properties_modified();
392 cdata->inc_image_modified();
393 if (do_load_one(cdata, pfm, get_name(), 0, 0, options)) {
394 bool generate_mipmaps = ((options.get_texture_flags() & LoaderOptions::TF_generate_mipmaps) != 0);
395 consider_auto_process_ram_image(generate_mipmaps || uses_mipmaps(), true);
396 return true;
397 }
398 return false;
399 }
400
401 /**
402 * Stores the indicated image in the given page and mipmap level. See read().
403 */
404 INLINE bool Texture::
405 load(const PfmFile &pfm, int z, int n, const LoaderOptions &options) {
406 CDWriter cdata(_cycler, true);
407 cdata->inc_properties_modified();
408 cdata->inc_image_modified();
409 if (do_load_one(cdata, pfm, get_name(), z, n, options)) {
410 return true;
411 }
412 return false;
413 }
414
415 /**
416 * Stores the indicated image in a region of the texture. The texture
417 * properties remain unchanged. This can be more efficient than updating an
418 * entire texture, but has a few restrictions: for one, you must ensure that
419 * the texture is still in RAM (eg. using set_keep_ram_image) and it may not
420 * be compressed.
421 */
422 INLINE bool Texture::
423 load_sub_image(const PNMImage &image, int x, int y, int z, int n) {
424 CDWriter cdata(_cycler, true);
425 return do_load_sub_image(cdata, image, x, y, z, n);
426 }
427
428 /**
429 * Saves the texture to the indicated PNMImage, but does not write it to disk.
430 */
431 INLINE bool Texture::
432 store(PNMImage &pnmimage) const {
433 CDWriter cdata(((Texture *)this)->_cycler, false);
434 return ((Texture *)this)->do_store_one(cdata, pnmimage, 0, 0);
435 }
436
437 /**
438 * Saves the indicated page and mipmap level of the texture to the PNMImage.
439 */
440 INLINE bool Texture::
441 store(PNMImage &pnmimage, int z, int n) const {
442 CDWriter cdata(((Texture *)this)->_cycler, false);
443 return ((Texture *)this)->do_store_one(cdata, pnmimage, z, n);
444 }
445
446 /**
447 * Saves the texture to the indicated PfmFile, but does not write it to disk.
448 */
449 INLINE bool Texture::
450 store(PfmFile &pfm) const {
451 CDWriter cdata(((Texture *)this)->_cycler, false);
452 return ((Texture *)this)->do_store_one(cdata, pfm, 0, 0);
453 }
454
455 /**
456 * Saves the indicated page and mipmap level of the texture to the PfmFile.
457 */
458 INLINE bool Texture::
459 store(PfmFile &pfm, int z, int n) const {
460 CDWriter cdata(((Texture *)this)->_cycler, false);
461 return ((Texture *)this)->do_store_one(cdata, pfm, z, n);
462 }
463
464 /**
465 * Re-reads the Texture from its disk file. Useful when you know the image on
466 * disk has recently changed, and you want to update the Texture image.
467 *
468 * Returns true on success, false on failure (in which case, the Texture may
469 * or may not still be valid).
470 */
471 bool Texture::
472 reload() {
473 CDWriter cdata(_cycler, true);
474 return do_reload(cdata);
475 }
476
477 /**
478 * Returns true if the filename has been set and is available. See
479 * set_filename().
480 */
481 INLINE bool Texture::
482 has_filename() const {
483 CDReader cdata(_cycler);
484 return !cdata->_filename.empty();
485 }
486
487 /**
488 * Returns the filename that has been set. This is the name of the file as it
489 * was requested. Also see get_fullpath().
490 */
491 INLINE const Filename &Texture::
492 get_filename() const {
493 CDReader cdata(_cycler);
494 return cdata->_filename;
495 }
496
497 /**
498 * Returns true if the alpha_filename has been set and is available. See
499 * set_alpha_filename().
500 */
501 INLINE bool Texture::
502 has_alpha_filename() const {
503 CDReader cdata(_cycler);
504 return !cdata->_alpha_filename.empty();
505 }
506
507 /**
508 * Returns the alpha_filename that has been set. If this is set, it
509 * represents the name of the alpha component, which is stored in a separate
510 * file. See also get_filename(), and get_alpha_fullpath().
511 */
512 INLINE const Filename &Texture::
513 get_alpha_filename() const {
514 CDReader cdata(_cycler);
515 return cdata->_alpha_filename;
516 }
517
518 /**
519 * Returns true if the fullpath has been set and is available. See
520 * set_fullpath().
521 */
522 INLINE bool Texture::
523 has_fullpath() const {
524 CDReader cdata(_cycler);
525 return !cdata->_fullpath.empty();
526 }
527
528 /**
529 * Returns the fullpath that has been set. This is the full path to the file
530 * as it was found along the texture search path.
531 */
532 INLINE const Filename &Texture::
533 get_fullpath() const {
534 CDReader cdata(_cycler);
535 return cdata->_fullpath;
536 }
537
538 /**
539 * Returns true if the alpha_fullpath has been set and is available. See
540 * set_alpha_fullpath().
541 */
542 INLINE bool Texture::
543 has_alpha_fullpath() const {
544 CDReader cdata(_cycler);
545 return !cdata->_alpha_fullpath.empty();
546 }
547
548 /**
549 *
550 * Returns the alpha_fullpath that has been set. This is the full path to the
551 * alpha part of the image file as it was found along the texture search path.
552 */
553 INLINE const Filename &Texture::
554 get_alpha_fullpath() const {
555 CDReader cdata(_cycler);
556 return cdata->_alpha_fullpath;
557 }
558
559
560 /**
561 * Returns the width of the texture image in texels.
562 */
563 INLINE int Texture::
564 get_x_size() const {
565 CDReader cdata(_cycler);
566 return cdata->_x_size;
567 }
568
569 /**
570 * Returns the height of the texture image in texels. For a 1-d texture, this
571 * will be 1.
572 */
573 INLINE int Texture::
574 get_y_size() const {
575 CDReader cdata(_cycler);
576 return cdata->_y_size;
577 }
578
579 /**
580 * Returns the depth of the texture image in texels. For a 1-d texture or 2-d
581 * texture, this will be 1. For a cube map texture, this will be 6.
582 */
583 INLINE int Texture::
584 get_z_size() const {
585 CDReader cdata(_cycler);
586 return cdata->_z_size;
587 }
588
589 /**
590 * Returns the number of "views" in the texture. A view is a completely
591 * separate image stored within the Texture object. Most textures have only
592 * one view, but a stereo texture, for instance, may have two views, a left
593 * and a right image. Other uses for multiple views are not yet defined.
594 *
595 * If this value is greater than one, the additional views are accessed as
596 * additional pages beyond get_z_size().
597 */
598 INLINE int Texture::
599 get_num_views() const {
600 CDReader cdata(_cycler);
601 return cdata->_num_views;
602 }
603
604 /**
605 * Returns the total number of pages in the texture. Each "page" is a 2-d
606 * texture image within the larger image--a face of a cube map, or a level of
607 * a 3-d texture. Normally, get_num_pages() is the same as get_z_size().
608 * However, in a multiview texture, this returns get_z_size() *
609 * get_num_views().
610 */
611 INLINE int Texture::
612 get_num_pages() const {
613 return get_z_size() * get_num_views();
614 }
615
616 /**
617 * Returns size of the pad region. See set_pad_size.
618 */
619 INLINE int Texture::
620 get_pad_x_size() const {
621 CDReader cdata(_cycler);
622 return cdata->_pad_x_size;
623 }
624
625 /**
626 * Returns size of the pad region. See set_pad_size.
627 */
628 INLINE int Texture::
629 get_pad_y_size() const {
630 CDReader cdata(_cycler);
631 return cdata->_pad_y_size;
632 }
633
634 /**
635 * Returns size of the pad region. See set_pad_size.
636 */
637 INLINE int Texture::
638 get_pad_z_size() const {
639 CDReader cdata(_cycler);
640 return cdata->_pad_z_size;
641 }
642
643 /**
644 * Returns a scale pair that is suitable for applying to geometry via
645 * NodePath::set_tex_scale(), which will convert texture coordinates on the
646 * geometry from the range 0..1 into the appropriate range to render the video
647 * part of the texture.
648 *
649 * This is necessary only if a padding size has been set via set_pad_size()
650 * (or implicitly via something like "textures-power-2 pad" in the config.prc
651 * file). In this case, this is a convenient way to generate UV's that
652 * reflect the built-in padding size.
653 */
654 INLINE LVecBase2 Texture::
655 get_tex_scale() const {
656 CDReader cdata(_cycler);
657 if (cdata->_pad_x_size == 0 || cdata->_pad_y_size == 0 ||
658 cdata->_x_size == 0 || cdata->_y_size == 0) {
659 LVecBase2(1.0f, 1.0f);
660 }
661 return LVecBase2((PN_stdfloat)(cdata->_x_size - cdata->_pad_x_size) / (PN_stdfloat)cdata->_x_size,
662 (PN_stdfloat)(cdata->_y_size - cdata->_pad_y_size) / (PN_stdfloat)cdata->_y_size);
663 }
664
665 /**
666 * Sets the size of the pad region.
667 *
668 * Sometimes, when a video card demands power-of-two textures, it is necessary
669 * to create a big texture and then only use a portion of it. The pad region
670 * indicates which portion of the texture is not really in use. All
671 * operations use the texture as a whole, including the pad region, unless
672 * they explicitly state that they use only the non-pad region.
673 *
674 * Changing the texture's size clears the pad region.
675 */
676 INLINE void Texture::
677 set_pad_size(int x, int y, int z) {
678 CDWriter cdata(_cycler, true);
679 do_set_pad_size(cdata, x, y, z);
680 }
681
682 /**
683 * Returns the X size of the original disk image that this Texture was loaded
684 * from (if it came from a disk file), before any automatic rescaling by
685 * Panda.
686 */
687 INLINE int Texture::
688 get_orig_file_x_size() const {
689 CDReader cdata(_cycler);
690 return cdata->_orig_file_x_size;
691 }
692
693 /**
694 * Returns the Y size of the original disk image that this Texture was loaded
695 * from (if it came from a disk file), before any automatic rescaling by
696 * Panda.
697 */
698 INLINE int Texture::
699 get_orig_file_y_size() const {
700 CDReader cdata(_cycler);
701 return cdata->_orig_file_y_size;
702 }
703
704 /**
705 * Returns the Z size of the original disk image that this Texture was loaded
706 * from (if it came from a disk file), before any automatic rescaling by
707 * Panda.
708 */
709 INLINE int Texture::
710 get_orig_file_z_size() const {
711 // At the moment, we perform no automatic adjustment of Z size. So we can
712 // just return the current value, since it would be the same thing.
713 CDReader cdata(_cycler);
714 return cdata->_z_size;
715 }
716
717 /**
718 * Returns the number of color components for each texel of the texture image.
719 * This is 3 for an rgb texture or 4 for an rgba texture; it may also be 1 or
720 * 2 for a grayscale texture.
721 */
722 INLINE int Texture::
723 get_num_components() const {
724 CDReader cdata(_cycler);
725 return cdata->_num_components;
726 }
727
728 /**
729 * Returns the number of bytes stored for each color component of a texel.
730 * Typically this is 1, but it may be 2 for 16-bit texels.
731 */
732 INLINE int Texture::
733 get_component_width() const {
734 CDReader cdata(_cycler);
735 return cdata->_component_width;
736 }
737
738 /**
739 * Returns the overall interpretation of the texture.
740 */
741 INLINE Texture::TextureType Texture::
742 get_texture_type() const {
743 CDReader cdata(_cycler);
744 return cdata->_texture_type;
745 }
746
747 /**
748 * Returns the format of the texture, which represents both the semantic
749 * meaning of the texels and, to some extent, their storage information.
750 */
751 INLINE Texture::Format Texture::
752 get_format() const {
753 CDReader cdata(_cycler);
754 return cdata->_format;
755 }
756
757 /**
758 * Returns the numeric interpretation of each component of the texture.
759 */
760 INLINE Texture::ComponentType Texture::
761 get_component_type() const {
762 CDReader cdata(_cycler);
763 return cdata->_component_type;
764 }
765
766 /**
767 * Returns the usage hint specified for buffer textures, or UH_unspecified for
768 * all other texture types.
769 */
770 INLINE GeomEnums::UsageHint Texture::
771 get_usage_hint() const {
772 CDReader cdata(_cycler);
773 return cdata->_usage_hint;
774 }
775
776 /**
777 * This setting determines what happens when the texture is sampled with a U
778 * value outside the range 0.0-1.0. The default is WM_repeat, which indicates
779 * that the texture should repeat indefinitely.
780 *
781 * This sets the default sampler state for this texture; it may still be
782 * overridden by a sampler state specified at a higher level.
783 */
784 INLINE void Texture::
785 set_wrap_u(SamplerState::WrapMode wrap) {
786 CDWriter cdata(_cycler, true);
787 do_set_wrap_u(cdata, wrap);
788 }
789
790 /**
791 * This setting determines what happens when the texture is sampled with a V
792 * value outside the range 0.0-1.0. The default is WM_repeat, which indicates
793 * that the texture should repeat indefinitely.
794 *
795 * This sets the default sampler state for this texture; it may still be
796 * overridden by a sampler state specified at a higher level.
797 */
798 INLINE void Texture::
799 set_wrap_v(SamplerState::WrapMode wrap) {
800 CDWriter cdata(_cycler, true);
801 do_set_wrap_v(cdata, wrap);
802 }
803
804 /**
805 * The W wrap direction is only used for 3-d textures.
806 *
807 * This sets the default sampler state for this texture; it may still be
808 * overridden by a sampler state specified at a higher level.
809 */
810 INLINE void Texture::
811 set_wrap_w(SamplerState::WrapMode wrap) {
812 CDWriter cdata(_cycler, true);
813 do_set_wrap_w(cdata, wrap);
814 }
815
816 /**
817 * Sets the filtering method that should be used when viewing the texture from
818 * a distance.
819 *
820 * This sets the default sampler state for this texture; it may still be
821 * overridden by a sampler state specified at a higher level.
822 */
823 INLINE void Texture::
824 set_minfilter(SamplerState::FilterType filter) {
825 CDWriter cdata(_cycler, true);
826 do_set_minfilter(cdata, filter);
827 }
828
829 /**
830 * Sets the filtering method that should be used when viewing the texture up
831 * close.
832 *
833 * This sets the default sampler state for this texture; it may still be
834 * overridden by a sampler state specified at a higher level.
835 */
836 INLINE void Texture::
837 set_magfilter(SamplerState::FilterType filter) {
838 CDWriter cdata(_cycler, true);
839 do_set_magfilter(cdata, filter);
840 }
841
842 /**
843 * Specifies the level of anisotropic filtering to apply to the texture. Set
844 * this 0 to indicate the default value, which is specified in the texture-
845 * anisotropic-degree config variable.
846 *
847 * To explicitly disable anisotropic filtering, set this value to 1. To
848 * explicitly enable anisotropic filtering, set it to a value higher than 1;
849 * larger numbers indicate greater degrees of filtering.
850 *
851 * This sets the default sampler state for this texture; it may still be
852 * overridden by a sampler state specified at a higher level.
853 */
854 INLINE void Texture::
855 set_anisotropic_degree(int anisotropic_degree) {
856 CDWriter cdata(_cycler, true);
857 do_set_anisotropic_degree(cdata, anisotropic_degree);
858 }
859
860 /**
861 * Specifies the solid color of the texture's border. Some OpenGL
862 * implementations use a border for tiling textures; in Panda, it is only used
863 * for specifying the clamp color.
864 *
865 * This sets the default sampler state for this texture; it may still be
866 * overridden by a sampler state specified at a higher level.
867 */
868 INLINE void Texture::
869 set_border_color(const LColor &color) {
870 CDWriter cdata(_cycler, true);
871 do_set_border_color(cdata, color);
872 }
873
874 /**
875 * Requests that this particular Texture be compressed when it is loaded into
876 * texture memory.
877 *
878 * This refers to the internal compression of the texture image within texture
879 * memory; it is not related to jpeg or png compression, which are disk file
880 * compression formats. The actual disk file that generated this texture may
881 * be stored in a compressed or uncompressed format supported by Panda; it
882 * will be decompressed on load, and then recompressed by the graphics API if
883 * this parameter is not CM_off.
884 *
885 * If the GSG does not support this texture compression mode, the texture will
886 * silently be loaded uncompressed.
887 */
888 INLINE void Texture::
889 set_compression(Texture::CompressionMode compression) {
890 CDWriter cdata(_cycler, true);
891 do_set_compression(cdata, compression);
892 }
893
894 /**
895 * Sets a flag on the texture that indicates whether the texture is intended
896 * to be used as a direct-render target, by binding a framebuffer to a texture
897 * and rendering directly into the texture.
898 *
899 * This controls some low-level choices made about the texture object itself.
900 * For instance, compressed textures are disallowed when this flag is set
901 * true.
902 *
903 * Normally, a user should not need to set this flag directly; it is set
904 * automatically by the low-level display code when a texture is bound to a
905 * framebuffer.
906 */
907 INLINE void Texture::
908 set_render_to_texture(bool render_to_texture) {
909 CDWriter cdata(_cycler, false);
910 cdata->_render_to_texture = render_to_texture;
911 }
912
913 /**
914 * This returns the default sampler state for this texture, containing the
915 * wrap and filter properties specified on the texture level; it may still be
916 * overridden by a sampler state specified at a higher level.
917 */
918 INLINE const SamplerState &Texture::
919 get_default_sampler() const {
920 CDReader cdata(_cycler);
921 return cdata->_default_sampler;
922 }
923
924 /**
925 * This sets the default sampler state for this texture, containing the wrap
926 * and filter properties specified on the texture level; it may still be
927 * overridden by a sampler state specified at a higher level. This
928 * encompasses the settings for get_wrap_u, get_minfilter,
929 * get_anisotropic_degree, etc.
930 *
931 * This makes a copy of the SamplerState object, so future modifications of
932 * the same SamplerState will have no effect on this texture unless you call
933 * set_default_sampler again.
934 */
935 INLINE void Texture::
936 set_default_sampler(const SamplerState &sampler) {
937 CDWriter cdata(_cycler, true);
938 cdata->_default_sampler = sampler;
939 cdata->inc_properties_modified();
940 }
941
942 /**
943 * Returns the wrap mode of the texture in the U direction.
944 *
945 * This returns the default sampler state for this texture; it may still be
946 * overridden by a sampler state specified at a higher level.
947 */
948 INLINE SamplerState::WrapMode Texture::
949 get_wrap_u() const {
950 CDReader cdata(_cycler);
951 return cdata->_default_sampler.get_wrap_u();
952 }
953
954 /**
955 * Returns the wrap mode of the texture in the V direction.
956 *
957 * This returns the default sampler state for this texture; it may still be
958 * overridden by a sampler state specified at a higher level.
959 */
960 INLINE SamplerState::WrapMode Texture::
961 get_wrap_v() const {
962 CDReader cdata(_cycler);
963 return cdata->_default_sampler.get_wrap_v();
964 }
965
966 /**
967 * Returns the wrap mode of the texture in the W direction. This is the depth
968 * direction of 3-d textures.
969 *
970 * This returns the default sampler state for this texture; it may still be
971 * overridden by a sampler state specified at a higher level.
972 */
973 INLINE SamplerState::WrapMode Texture::
974 get_wrap_w() const {
975 CDReader cdata(_cycler);
976 return cdata->_default_sampler.get_wrap_w();
977 }
978
979 /**
980 * Returns the filter mode of the texture for minification. If this is one of
981 * the mipmap constants, then the texture requires mipmaps. This may return
982 * FT_default; see also get_effective_minfilter().
983 *
984 * This returns the default sampler state for this texture; it may still be
985 * overridden by a sampler state specified at a higher level.
986 */
987 INLINE SamplerState::FilterType Texture::
988 get_minfilter() const {
989 CDReader cdata(_cycler);
990 return cdata->_default_sampler.get_minfilter();
991 }
992
993 /**
994 * Returns the filter mode of the texture for magnification. The mipmap
995 * constants are invalid here. This may return FT_default; see also
996 * get_effective_minfilter().
997 *
998 * This returns the default sampler state for this texture; it may still be
999 * overridden by a sampler state specified at a higher level.
1000 */
1001 INLINE SamplerState::FilterType Texture::
1002 get_magfilter() const {
1003 CDReader cdata(_cycler);
1004 return cdata->_default_sampler.get_magfilter();
1005 }
1006
1007 /**
1008 * Returns the filter mode of the texture for minification, with special
1009 * treatment for FT_default. This will normally not return FT_default, unless
1010 * there is an error in the config file.
1011 *
1012 * This returns the default sampler state for this texture; it may still be
1013 * overridden by a sampler state specified at a higher level.
1014 */
1015 SamplerState::FilterType Texture::
1016 get_effective_minfilter() const {
1017 CDReader cdata(_cycler);
1018 return cdata->_default_sampler.get_effective_minfilter();
1019 }
1020
1021 /**
1022 * Returns the filter mode of the texture for magnification, with special
1023 * treatment for FT_default. This will normally not return FT_default, unless
1024 * there is an error in the config file.
1025 *
1026 * This returns the default sampler state for this texture; it may still be
1027 * overridden by a sampler state specified at a higher level.
1028 */
1029 SamplerState::FilterType Texture::
1030 get_effective_magfilter() const {
1031 CDReader cdata(_cycler);
1032 return cdata->_default_sampler.get_effective_magfilter();
1033 }
1034
1035 /**
1036 * Returns the degree of anisotropic filtering that should be applied to the
1037 * texture. This value may return 0, indicating the default value; see also
1038 * get_effective_anisotropic_degree.
1039 *
1040 * This returns the default sampler state for this texture; it may still be
1041 * overridden by a sampler state specified at a higher level.
1042 */
1043 INLINE int Texture::
1044 get_anisotropic_degree() const {
1045 CDReader cdata(_cycler);
1046 return cdata->_default_sampler.get_anisotropic_degree();
1047 }
1048
1049 /**
1050 * Returns the degree of anisotropic filtering that should be applied to the
1051 * texture. This value will normally not return 0, unless there is an error
1052 * in the config file.
1053 *
1054 * This returns the default sampler state for this texture; it may still be
1055 * overridden by a sampler state specified at a higher level.
1056 */
1057 INLINE int Texture::
1058 get_effective_anisotropic_degree() const {
1059 CDReader cdata(_cycler);
1060 return cdata->_default_sampler.get_effective_anisotropic_degree();
1061 }
1062
1063 /**
1064 * Returns the solid color of the texture's border. Some OpenGL
1065 * implementations use a border for tiling textures; in Panda, it is only used
1066 * for specifying the clamp color.
1067 *
1068 * This returns the default sampler state for this texture; it may still be
1069 * overridden by a sampler state specified at a higher level.
1070 */
1071 INLINE LColor Texture::
1072 get_border_color() const {
1073 CDReader cdata(_cycler);
1074 return cdata->_default_sampler.get_border_color();
1075 }
1076
1077 /**
1078 * Returns the compression mode requested for this particular texture, or
1079 * CM_off if the texture is not to be compressed.
1080 *
1081 * If a value other than CM_off is returned, this is not a guarantee that the
1082 * texture is actually successfully compressed on the GSG. It may be that the
1083 * GSG does not support the requested compression mode, in which case the
1084 * texture may actually be stored uncompressed in texture memory.
1085 */
1086 INLINE Texture::CompressionMode Texture::
1087 get_compression() const {
1088 CDReader cdata(_cycler);
1089 return cdata->_compression;
1090 }
1091
1092 /**
1093 * Returns true if the texture indicates it wants to be compressed, either
1094 * with CM_on or higher, or CM_default and compressed-textures is true.
1095 *
1096 * If true returned, this is not a guarantee that the texture is actually
1097 * successfully compressed on the GSG. It may be that the GSG does not
1098 * support the requested compression mode, in which case the texture may
1099 * actually be stored uncompressed in texture memory.
1100 */
1101 INLINE bool Texture::
1102 has_compression() const {
1103 CDReader cdata(_cycler);
1104 return do_has_compression(cdata);
1105 }
1106
1107 /**
1108 * Returns a flag on the texture that indicates whether the texture is
1109 * intended to be used as a direct-render target, by binding a framebuffer to
1110 * a texture and rendering directly into the texture.
1111 *
1112 * Normally, a user should not need to set this flag directly; it is set
1113 * automatically by the low-level display code when a texture is bound to a
1114 * framebuffer.
1115 */
1116 INLINE bool Texture::
1117 get_render_to_texture() const {
1118 CDReader cdata(_cycler);
1119 return cdata->_render_to_texture;
1120 }
1121
1122 /**
1123 * Returns true if the minfilter settings on this texture indicate the use of
1124 * mipmapping, false otherwise.
1125 */
1126 INLINE bool Texture::
1127 uses_mipmaps() const {
1128 return SamplerState::is_mipmap(get_effective_minfilter());
1129 }
1130
1131 /**
1132 * Sets a hint to the renderer about the desired performance / quality
1133 * tradeoff for this particular texture. This is most useful for the
1134 * tinydisplay software renderer; for normal, hardware-accelerated renderers,
1135 * this may have little or no effect.
1136 */
1137 INLINE void Texture::
1138 set_quality_level(Texture::QualityLevel quality_level) {
1139 CDWriter cdata(_cycler, true);
1140 do_set_quality_level(cdata, quality_level);
1141 }
1142
1143 /**
1144 * Returns the current quality_level hint. See set_quality_level(). This
1145 * value may return QL_default; see get_effective_quality_level().
1146 */
1147 INLINE Texture::QualityLevel Texture::
1148 get_quality_level() const {
1149 CDReader cdata(_cycler);
1150 return cdata->_quality_level;
1151 }
1152
1153 /**
1154 * Returns the current quality_level hint, or the global default quality_level
1155 * if this texture doesn't specify a quality level. This value will not
1156 * normally return QL_default (unless there is an error in the config file)
1157 */
1158 INLINE Texture::QualityLevel Texture::
1159 get_effective_quality_level() const {
1160 CDReader cdata(_cycler);
1161 if (cdata->_quality_level == QL_default) {
1162 return texture_quality_level;
1163 }
1164 return cdata->_quality_level;
1165 }
1166
1167 /**
1168 * Returns the number of mipmap levels that should be defined for this
1169 * texture, given the texture's size.
1170 *
1171 * Note that this returns a number appropriate for mipmapping, even if the
1172 * texture does not currently have mipmapping enabled.
1173 */
1174 INLINE int Texture::
1175 get_expected_num_mipmap_levels() const {
1176 CDReader cdata(_cycler);
1177 return do_get_expected_num_mipmap_levels(cdata);
1178 }
1179
1180 /**
1181 * Returns the x_size that the nth mipmap level should have, based on the
1182 * texture's size.
1183 */
1184 INLINE int Texture::
1185 get_expected_mipmap_x_size(int n) const {
1186 CDReader cdata(_cycler);
1187 return do_get_expected_mipmap_x_size(cdata, n);
1188 }
1189
1190 /**
1191 * Returns the y_size that the nth mipmap level should have, based on the
1192 * texture's size.
1193 */
1194 INLINE int Texture::
1195 get_expected_mipmap_y_size(int n) const {
1196 CDReader cdata(_cycler);
1197 return do_get_expected_mipmap_y_size(cdata, n);
1198 }
1199
1200 /**
1201 * Returns the z_size that the nth mipmap level should have, based on the
1202 * texture's size.
1203 */
1204 INLINE int Texture::
1205 get_expected_mipmap_z_size(int n) const {
1206 CDReader cdata(_cycler);
1207 return do_get_expected_mipmap_z_size(cdata, n);
1208 }
1209
1210 /**
1211 * Returns the total number of pages that the nth mipmap level should have,
1212 * based on the texture's size. This is usually the same as
1213 * get_expected_mipmap_z_size(), except for a multiview texture, in which case
1214 * it is get_expected_mipmap_z_size() * get_num_views().
1215 */
1216 INLINE int Texture::
1217 get_expected_mipmap_num_pages(int n) const {
1218 CDReader cdata(_cycler);
1219 return do_get_expected_mipmap_num_pages(cdata, n);
1220 }
1221
1222 /**
1223 * Returns true if the Texture has its image contents available in main RAM,
1224 * false if it exists only in texture memory or in the prepared GSG context.
1225 *
1226 * Note that this has nothing to do with whether get_ram_image() will fail or
1227 * not. Even if has_ram_image() returns false, get_ram_image() may still
1228 * return a valid RAM image, because get_ram_image() will automatically load
1229 * the texture from disk if necessary. The only thing has_ram_image() tells
1230 * you is whether the texture is available right now without hitting the disk
1231 * first.
1232 *
1233 * Note also that if an application uses only one GSG, it may appear that
1234 * has_ram_image() returns true if the texture has not yet been loaded by the
1235 * GSG, but this correlation is not true in general and should not be depended
1236 * on. Specifically, if an application ever uses multiple GSG's in its
1237 * lifetime (for instance, by opening more than one window, or by closing its
1238 * window and opening another one later), then has_ram_image() may well return
1239 * false on textures that have never been loaded on the current GSG.
1240 */
1241 INLINE bool Texture::
1242 has_ram_image() const {
1243 CDReader cdata(_cycler);
1244 return do_has_ram_image(cdata);
1245 }
1246
1247 /**
1248 * Returns true if the Texture has its image contents available in main RAM
1249 * and is uncompressed, false otherwise. See has_ram_image().
1250 */
1251 INLINE bool Texture::
1252 has_uncompressed_ram_image() const {
1253 CDReader cdata(_cycler);
1254 return do_has_uncompressed_ram_image(cdata);
1255 }
1256
1257 /**
1258 * Returns true if the texture's image contents are currently available in
1259 * main RAM, or there is reason to believe it can be loaded on demand. That
1260 * is, this function returns a "best guess" as to whether get_ram_image() will
1261 * succeed without actually calling it first.
1262 */
1263 INLINE bool Texture::
1264 might_have_ram_image() const {
1265 CDReader cdata(_cycler);
1266 return (do_has_ram_image(cdata) || !cdata->_fullpath.empty());
1267 }
1268
1269 /**
1270 * Returns the total number of bytes used by the in-memory image, across all
1271 * pages and views, or 0 if there is no in-memory image.
1272 */
1273 INLINE size_t Texture::
1274 get_ram_image_size() const {
1275 CDReader cdata(_cycler);
1276 return do_get_ram_image_size(cdata);
1277 }
1278
1279 /**
1280 * Returns the number of bytes used by the in-memory image per view, or 0 if
1281 * there is no in-memory image. Since each view is a stack of z_size pages,
1282 * this is get_z_size() * get_ram_page_size().
1283 */
1284 INLINE size_t Texture::
1285 get_ram_view_size() const {
1286 CDReader cdata(_cycler);
1287 if (cdata->_ram_image_compression == CM_off || cdata->_ram_images.empty()) {
1288 return do_get_expected_ram_view_size(cdata);
1289 } else {
1290 return cdata->_z_size * cdata->_ram_images[0]._page_size;
1291 }
1292 }
1293
1294 /**
1295 * Returns the number of bytes used by the in-memory image per page, or 0 if
1296 * there is no in-memory image.
1297 *
1298 * For a non-compressed texture, this is the same as
1299 * get_expected_ram_page_size(). For a compressed texture, this may be a
1300 * smaller value. (We do assume that all pages will be the same size on a
1301 * compressed texture).
1302 */
1303 INLINE size_t Texture::
1304 get_ram_page_size() const {
1305 CDReader cdata(_cycler);
1306 if (cdata->_ram_image_compression == CM_off || cdata->_ram_images.empty()) {
1307 return do_get_expected_ram_page_size(cdata);
1308 } else {
1309 return cdata->_ram_images[0]._page_size;
1310 }
1311 }
1312
1313 /**
1314 * Returns the number of bytes that *ought* to be used by the in-memory image,
1315 * based on the texture parameters.
1316 */
1317 INLINE size_t Texture::
1318 get_expected_ram_image_size() const {
1319 CDReader cdata(_cycler);
1320 return do_get_expected_ram_image_size(cdata);
1321 }
1322
1323 /**
1324 * Returns the number of bytes that should be used per each Z page of the 3-d
1325 * texture. For a 2-d or 1-d texture, this is the same as
1326 * get_expected_ram_image_size().
1327 */
1328 INLINE size_t Texture::
1329 get_expected_ram_page_size() const {
1330 CDReader cdata(_cycler);
1331 return do_get_expected_ram_page_size(cdata);
1332 }
1333
1334 /**
1335 * Returns the system-RAM image data associated with the texture. If the
1336 * texture does not currently have an associated RAM image, and the texture
1337 * was generated by loading an image from a disk file (the most common case),
1338 * this forces the reload of the same texture. This can happen if
1339 * keep_texture_ram is configured to false, and we have previously prepared
1340 * this texture with a GSG.
1341 *
1342 * Note that it is not correct to call has_ram_image() first to test whether
1343 * this function will fail. A false return value from has_ram_image()
1344 * indicates only that get_ram_image() may need to reload the texture from
1345 * disk, which it will do automatically. However, you can call
1346 * might_have_ram_image(), which will return true if the ram image exists, or
1347 * there is a reasonable reason to believe it can be loaded.
1348 *
1349 * On the other hand, it is possible that the texture cannot be found on disk
1350 * or is otherwise unavailable. If that happens, this function will return
1351 * NULL. There is no way to predict with 100% accuracy whether get_ram_image()
1352 * will return NULL without calling it first; might_have_ram_image() is the
1353 * closest.
1354 */
1355 INLINE CPTA_uchar Texture::
1356 get_ram_image() {
1357 CDWriter cdata(_cycler, unlocked_ensure_ram_image(true));
1358 return do_get_ram_image(cdata);
1359 }
1360
1361 /**
1362 * Returns the compression mode in which the ram image is already stored pre-
1363 * compressed. If this is other than CM_off, you cannot rely on the contents
1364 * of the ram image to be anything predicatable (it will not be an array of x
1365 * by y pixels, and it probably won't have the same length as
1366 * get_expected_ram_image_size()).
1367 */
1368 INLINE Texture::CompressionMode Texture::
1369 get_ram_image_compression() const {
1370 CDReader cdata(_cycler);
1371 return cdata->_ram_image_compression;
1372 }
1373
1374 /**
1375 * Returns a modifiable pointer to the system-RAM image. This assumes the RAM
1376 * image should be uncompressed. If the RAM image has been dumped, or is
1377 * stored compressed, creates a new one.
1378 *
1379 * This does *not* affect keep_ram_image.
1380 */
1381 INLINE PTA_uchar Texture::
1382 modify_ram_image() {
1383 CDWriter cdata(_cycler, true);
1384 cdata->inc_image_modified();
1385 return do_modify_ram_image(cdata);
1386 }
1387
1388 /**
1389 * Returns the system-RAM image associated with the texture, in an
1390 * uncompressed form if at all possible.
1391 *
1392 * If get_ram_image_compression() is CM_off, then the system-RAM image is
1393 * already uncompressed, and this returns the same thing as get_ram_image().
1394 *
1395 * If get_ram_image_compression() is anything else, then the system-RAM image
1396 * is compressed. In this case, the image will be reloaded from the
1397 * *original* file (not from the cache), in the hopes that an uncompressed
1398 * image will be found there.
1399 *
1400 * If an uncompressed image cannot be found, returns NULL.
1401 */
1402 INLINE CPTA_uchar Texture::
1403 get_uncompressed_ram_image() {
1404 CDWriter cdata(_cycler, false);
1405 return do_get_uncompressed_ram_image(cdata);
1406 }
1407
1408 /**
1409 * Discards the current system-RAM image for the texture, if any, and
1410 * allocates a new buffer of the appropriate size. Returns the new buffer.
1411 *
1412 * This does *not* affect keep_ram_image.
1413 */
1414 INLINE PTA_uchar Texture::
1415 make_ram_image() {
1416 CDWriter cdata(_cycler, true);
1417 cdata->inc_image_modified();
1418 return do_make_ram_image(cdata);
1419 }
1420
1421 /**
1422 * Replaces the current system-RAM image with the new data. If compression is
1423 * not CM_off, it indicates that the new data is already pre-compressed in the
1424 * indicated format.
1425 *
1426 * This does *not* affect keep_ram_image.
1427 */
1428 INLINE void Texture::
1429 set_ram_image(CPTA_uchar image, Texture::CompressionMode compression,
1430 size_t page_size) {
1431 CDWriter cdata(_cycler, true);
1432 do_set_ram_image(cdata, image, compression, page_size);
1433 }
1434
1435 /**
1436 * Discards the current system-RAM image.
1437 */
1438 INLINE void Texture::
1439 clear_ram_image() {
1440 CDWriter cdata(_cycler, false);
1441 do_clear_ram_image(cdata);
1442 }
1443
1444 /**
1445 * Sets the flag that indicates whether this Texture is eligible to have its
1446 * main RAM copy of the texture memory dumped when the texture is prepared for
1447 * rendering.
1448 *
1449 * This will be false for most textures, which can reload their images if
1450 * needed by rereading the input file. However, textures that were generated
1451 * dynamically and cannot be easily reloaded will want to set this flag to
1452 * true, so that the texture will always keep its image copy around.
1453 */
1454 INLINE void Texture::
1455 set_keep_ram_image(bool keep_ram_image) {
1456 CDWriter cdata(_cycler, true);
1457 cdata->_keep_ram_image = keep_ram_image;
1458 }
1459
1460 /**
1461 * Attempts to compress the texture's RAM image internally, to a format
1462 * supported by the indicated GSG. In order for this to work, the squish
1463 * library must have been compiled into Panda.
1464 *
1465 * If compression is CM_on, then an appropriate compression method that is
1466 * supported by the indicated GSG is automatically chosen. If the GSG pointer
1467 * is NULL, any of the standard DXT1/3/5 compression methods will be used,
1468 * regardless of whether it is supported.
1469 *
1470 * If compression is any specific compression method, that method is used
1471 * regardless of whether the GSG supports it.
1472 *
1473 * quality_level determines the speed/quality tradeoff of the compression. If
1474 * it is QL_default, the texture's own quality_level parameter is used.
1475 *
1476 * Returns true if successful, false otherwise.
1477 */
1478 INLINE bool Texture::
1479 compress_ram_image(Texture::CompressionMode compression,
1480 Texture::QualityLevel quality_level,
1481 GraphicsStateGuardianBase *gsg) {
1482 CDWriter cdata(_cycler, false);
1483 if (do_compress_ram_image(cdata, compression, quality_level, gsg)) {
1484 cdata->inc_image_modified();
1485 return true;
1486 }
1487 return false;
1488 }
1489
1490 /**
1491 * Attempts to uncompress the texture's RAM image internally. In order for
1492 * this to work, the squish library must have been compiled into Panda, and
1493 * the ram image must be compressed in a format supported by squish.
1494 *
1495 * Returns true if successful, false otherwise.
1496 */
1497 INLINE bool Texture::
1498 uncompress_ram_image() {
1499 CDWriter cdata(_cycler, false);
1500 if (do_uncompress_ram_image(cdata)) {
1501 cdata->inc_image_modified();
1502 return true;
1503 }
1504 return false;
1505 }
1506
1507 /**
1508 * Returns the maximum number of mipmap level images available in system
1509 * memory. The actual number may be less than this (that is, there might be
1510 * gaps in the sequence); use has_ram_mipmap_image() to verify each level.
1511 *
1512 * Also see get_num_loadable_ram_mipmap_images().
1513 */
1514 INLINE int Texture::
1515 get_num_ram_mipmap_images() const {
1516 CDReader cdata(_cycler);
1517 return cdata->_ram_images.size();
1518 }
1519
1520 /**
1521 * Returns true if the Texture has the nth mipmap level available in system
1522 * memory, false otherwise. If the texture's minfilter mode requires
1523 * mipmapping (see uses_mipmaps()), and all the texture's mipmap levels are
1524 * not available when the texture is rendered, they will be generated
1525 * automatically.
1526 */
1527 INLINE bool Texture::
1528 has_ram_mipmap_image(int n) const {
1529 CDReader cdata(_cycler);
1530 return do_has_ram_mipmap_image(cdata, n);
1531 }
1532
1533 /**
1534 * Returns true if all expected mipmap levels have been defined and exist in
1535 * the system RAM, or false if even one mipmap level is missing.
1536 */
1537 INLINE bool Texture::
1538 has_all_ram_mipmap_images() const {
1539 CDReader cdata(_cycler);
1540 return do_has_all_ram_mipmap_images(cdata);
1541 }
1542
1543 /**
1544 * Returns the number of bytes used by the in-memory image for mipmap level n,
1545 * or 0 if there is no in-memory image for this mipmap level.
1546 */
1547 INLINE size_t Texture::
1548 get_ram_mipmap_image_size(int n) const {
1549 CDReader cdata(_cycler);
1550 if (n >= 0 && n < (int)cdata->_ram_images.size()) {
1551 if (cdata->_ram_images[n]._pointer_image == nullptr) {
1552 return cdata->_ram_images[n]._image.size();
1553 } else {
1554 // Calculate it based on the given page size.
1555 return do_get_ram_mipmap_page_size(cdata, n) *
1556 do_get_expected_mipmap_z_size(cdata, n) *
1557 cdata->_num_views;
1558 }
1559 }
1560 return 0;
1561 }
1562
1563 /**
1564 * Returns the number of bytes used by the in-memory image per view for mipmap
1565 * level n, or 0 if there is no in-memory image for this mipmap level.
1566 *
1567 * A "view" is a collection of z_size pages for each mipmap level. Most
1568 * textures have only one view, except for multiview or stereo textures.
1569 *
1570 * For a non-compressed texture, this is the same as
1571 * get_expected_ram_mipmap_view_size(). For a compressed texture, this may be
1572 * a smaller value. (We do assume that all pages will be the same size on a
1573 * compressed texture).
1574 */
1575 INLINE size_t Texture::
1576 get_ram_mipmap_view_size(int n) const {
1577 CDReader cdata(_cycler);
1578 return do_get_ram_mipmap_page_size(cdata, n) * do_get_expected_mipmap_z_size(cdata, n);
1579 }
1580
1581 /**
1582 * Returns the number of bytes used by the in-memory image per page for mipmap
1583 * level n, or 0 if there is no in-memory image for this mipmap level.
1584 *
1585 * For a non-compressed texture, this is the same as
1586 * get_expected_ram_mipmap_page_size(). For a compressed texture, this may be
1587 * a smaller value. (We do assume that all pages will be the same size on a
1588 * compressed texture).
1589 */
1590 INLINE size_t Texture::
1591 get_ram_mipmap_page_size(int n) const {
1592 CDReader cdata(_cycler);
1593 return do_get_ram_mipmap_page_size(cdata, n);
1594 }
1595
1596 /**
1597 * Returns the number of bytes that *ought* to be used by the in-memory image
1598 * for mipmap level n, based on the texture parameters.
1599 */
1600 INLINE size_t Texture::
1601 get_expected_ram_mipmap_image_size(int n) const {
1602 CDReader cdata(_cycler);
1603 return do_get_expected_ram_mipmap_image_size(cdata, n);
1604 }
1605
1606 /**
1607 * Returns the number of bytes that *ought* to be used by each view of the in-
1608 * memory image for mipmap level n, based on the texture parameters. For a
1609 * normal, non-multiview texture, this is the same as
1610 * get_expected_ram_mipmap_image_size(n).
1611 */
1612 INLINE size_t Texture::
1613 get_expected_ram_mipmap_view_size(int n) const {
1614 CDReader cdata(_cycler);
1615 return do_get_expected_ram_mipmap_view_size(cdata, n);
1616 }
1617
1618 /**
1619 * Returns the number of bytes that should be used per each Z page of the 3-d
1620 * texture, for mipmap level n. For a 2-d or 1-d texture, this is the same as
1621 * get_expected_ram_mipmap_view_size(n).
1622 */
1623 INLINE size_t Texture::
1624 get_expected_ram_mipmap_page_size(int n) const {
1625 CDReader cdata(_cycler);
1626 return do_get_expected_ram_mipmap_page_size(cdata, n);
1627 }
1628
1629 /**
1630 * Returns a modifiable pointer to the system-RAM image for the nth mipmap
1631 * level. This assumes the RAM image is uncompressed; if this is not the
1632 * case, raises an assertion.
1633 *
1634 * This does *not* affect keep_ram_image.
1635 */
1636 INLINE PTA_uchar Texture::
1637 modify_ram_mipmap_image(int n) {
1638 CDWriter cdata(_cycler, false);
1639 cdata->inc_image_modified();
1640 return do_modify_ram_mipmap_image(cdata, n);
1641 }
1642
1643 /**
1644 * Discards the current system-RAM image for the nth mipmap level, if any, and
1645 * allocates a new buffer of the appropriate size. Returns the new buffer.
1646 *
1647 * This does *not* affect keep_ram_image.
1648 */
1649 INLINE PTA_uchar Texture::
1650 make_ram_mipmap_image(int n) {
1651 CDWriter cdata(_cycler, false);
1652 cdata->inc_image_modified();
1653 return do_make_ram_mipmap_image(cdata, n);
1654 }
1655
1656 /**
1657 * Replaces the current system-RAM image for the indicated mipmap level with
1658 * the new data. If compression is not CM_off, it indicates that the new data
1659 * is already pre-compressed in the indicated format.
1660 *
1661 * This does *not* affect keep_ram_image.
1662 */
1663 INLINE void Texture::
1664 set_ram_mipmap_image(int n, CPTA_uchar image, size_t page_size) {
1665 CDWriter cdata(_cycler, false);
1666 do_set_ram_mipmap_image(cdata, n, image, page_size);
1667 }
1668
1669 /**
1670 * Discards the current system-RAM image for all mipmap levels, except level 0
1671 * (the base image).
1672 */
1673 INLINE void Texture::
1674 clear_ram_mipmap_images() {
1675 CDWriter cdata(_cycler, false);
1676 cdata->inc_image_modified();
1677 do_clear_ram_mipmap_images(cdata);
1678 }
1679
1680 /**
1681 * Automatically fills in the n mipmap levels of the Texture, based on the
1682 * texture's source image. This requires the texture's uncompressed ram image
1683 * to be available in system memory. If it is not already, it will be fetched
1684 * if possible.
1685 *
1686 * This call is not normally necessary, since the mipmap levels will be
1687 * generated automatically if needed. But there may be certain cases in which
1688 * you would like to call this explicitly.
1689 */
1690 INLINE void Texture::
1691 generate_ram_mipmap_images() {
1692 // Don't use unlocked_ensure_ram_image here, because
1693 // do_generate_ram_mipmap_images will want to decompress and recompress the
1694 // image itself.
1695 CDWriter cdata(_cycler, false);
1696 cdata->inc_image_modified();
1697 do_generate_ram_mipmap_images(cdata, true);
1698 }
1699
1700 /**
1701 * Returns the width of the "simple" image in texels.
1702 */
1703 INLINE int Texture::
1704 get_simple_x_size() const {
1705 CDReader cdata(_cycler);
1706 return cdata->_simple_x_size;
1707 }
1708
1709 /**
1710 * Returns the height of the "simple" image in texels.
1711 */
1712 INLINE int Texture::
1713 get_simple_y_size() const {
1714 CDReader cdata(_cycler);
1715 return cdata->_simple_y_size;
1716 }
1717
1718 /**
1719 * Returns true if the Texture has a "simple" image available in main RAM.
1720 */
1721 INLINE bool Texture::
1722 has_simple_ram_image() const {
1723 CDReader cdata(_cycler);
1724 return !cdata->_simple_ram_image._image.empty();
1725 }
1726
1727 /**
1728 * Returns the number of bytes used by the "simple" image, or 0 if there is no
1729 * simple image.
1730 */
1731 INLINE size_t Texture::
1732 get_simple_ram_image_size() const {
1733 CDReader cdata(_cycler);
1734 return cdata->_simple_ram_image._image.size();
1735 }
1736
1737 /**
1738 * Returns the image data associated with the "simple" texture image. This is
1739 * provided for some textures as an option to display while the main texture
1740 * image is being loaded from disk.
1741 *
1742 * Unlike get_ram_image(), this function will always return immediately.
1743 * Either the simple image is available, or it is not.
1744 *
1745 * The "simple" image is always 4 components, 1 byte each, regardless of the
1746 * parameters of the full texture. The simple image is only supported for
1747 * ordinary 2-d textures.
1748 */
1749 INLINE CPTA_uchar Texture::
1750 get_simple_ram_image() const {
1751 CDReader cdata(_cycler);
1752 return cdata->_simple_ram_image._image;
1753 }
1754
1755 /**
1756 * Replaces the internal "simple" texture image. This can be used as an
1757 * option to display while the main texture image is being loaded from disk.
1758 * It is normally a very small image, 16x16 or smaller (and maybe even 1x1),
1759 * that is designed to give just enough sense of color to serve as a
1760 * placeholder until the full texture is available.
1761 *
1762 * The "simple" image is always 4 components, 1 byte each, regardless of the
1763 * parameters of the full texture. The simple image is only supported for
1764 * ordinary 2-d textures.
1765 *
1766 * Also see generate_simple_ram_image(), modify_simple_ram_image(), and
1767 * new_simple_ram_image().
1768 */
1769 INLINE void Texture::
1770 set_simple_ram_image(CPTA_uchar image, int x_size, int y_size) {
1771 CDWriter cdata(_cycler, true);
1772 do_set_simple_ram_image(cdata, image, x_size, y_size);
1773 }
1774
1775 /**
1776 * Discards the current "simple" image.
1777 */
1778 INLINE void Texture::
1779 clear_simple_ram_image() {
1780 CDWriter cdata(_cycler, true);
1781 do_clear_simple_ram_image(cdata);
1782 }
1783
1784 /**
1785 * Returns a sequence number which is guaranteed to change at least every time
1786 * the texture properties (unrelated to the image) are modified.
1787 */
1788 INLINE UpdateSeq Texture::
1789 get_properties_modified() const {
1790 CDReader cdata(_cycler);
1791 return cdata->_properties_modified;
1792 }
1793
1794 /**
1795 * Returns a sequence number which is guaranteed to change at least every time
1796 * the texture image data (including mipmap levels) are modified.
1797 */
1798 INLINE UpdateSeq Texture::
1799 get_image_modified() const {
1800 CDReader cdata(_cycler);
1801 return cdata->_image_modified;
1802 }
1803
1804 /**
1805 * Returns a sequence number which is guaranteed to change at least every time
1806 * the texture's "simple" image data is modified.
1807 */
1808 INLINE UpdateSeq Texture::
1809 get_simple_image_modified() const {
1810 CDReader cdata(_cycler);
1811 return cdata->_simple_image_modified;
1812 }
1813
1814 /**
1815 * Specifies the power-of-2 texture-scaling mode that will be applied to this
1816 * particular texture when it is next loaded from disk. See
1817 * set_textures_power_2().
1818 */
1819 INLINE void Texture::
1820 set_auto_texture_scale(AutoTextureScale scale) {
1821 CDWriter cdata(_cycler, true);
1822 cdata->_auto_texture_scale = scale;
1823 }
1824
1825 /**
1826 * Returns the power-of-2 texture-scaling mode that will be applied to this
1827 * particular texture when it is next loaded from disk. See
1828 * set_textures_power_2().
1829 */
1830 INLINE AutoTextureScale Texture::
1831 get_auto_texture_scale() const {
1832 CDReader cdata(_cycler);
1833 return do_get_auto_texture_scale(cdata);
1834 }
1835
1836 /**
1837 * Returns true if set_auto_texture_scale() has been set to something other
1838 * than ATS_unspecified for this particular texture.
1839 */
1840 INLINE bool Texture::
1841 has_auto_texture_scale() const {
1842 CDReader cdata(_cycler);
1843 return (cdata->_auto_texture_scale != ATS_unspecified);
1844 }
1845
1846 /**
1847 * Set this flag to ATS_none, ATS_up, ATS_down, or ATS_pad to control the
1848 * scaling of textures in general, if a particular texture does not override
1849 * this. See also set_auto_texture_scale() for the per-texture override.
1850 */
1851 INLINE void Texture::
1852 set_textures_power_2(AutoTextureScale scale) {
1853 _textures_power_2 = scale;
1854 }
1855
1856 /**
1857 * This flag returns ATS_none, ATS_up, or ATS_down and controls the scaling of
1858 * textures in general. It is initialized from the config variable of the
1859 * same name, but it can be subsequently adjusted. See also
1860 * get_auto_texture_scale().
1861 */
1862 INLINE AutoTextureScale Texture::
1863 get_textures_power_2() {
1864 if (_textures_power_2 == ATS_unspecified) {
1865 return textures_power_2;
1866 } else {
1867 return _textures_power_2;
1868 }
1869 }
1870
1871 /**
1872 * If true, then get_textures_power_2 has been set using set_textures_power_2.
1873 * If false, then get_textures_power_2 simply returns the config variable of
1874 * the same name.
1875 */
1876 INLINE bool Texture::
1877 has_textures_power_2() {
1878 return (_textures_power_2 != ATS_unspecified);
1879 }
1880
1881 /**
1882 * Sets the name of the file that contains the image's contents. Normally,
1883 * this is set automatically when the image is loaded, for instance via
1884 * Texture::read().
1885 *
1886 * The Texture's get_name() function used to return the filename, but now
1887 * returns just the basename (without the extension), which is a more useful
1888 * name for identifying an image in show code.
1889 */
1890 INLINE void Texture::
1891 set_filename(const Filename &filename) {
1892 CDWriter cdata(_cycler, true);
1893 cdata->_filename = filename;
1894 }
1895
1896 /**
1897 * Removes the alpha filename, if it was previously set. See set_filename().
1898 */
1899 INLINE void Texture::
1900 clear_filename() {
1901 CDWriter cdata(_cycler, true);
1902 cdata->_filename = Filename();
1903 }
1904
1905 /**
1906 * Sets the name of the file that contains the image's alpha channel contents.
1907 * Normally, this is set automatically when the image is loaded, for instance
1908 * via Texture::read().
1909 *
1910 * The Texture's get_filename() function returns the name of the image file
1911 * that was loaded into the buffer. In the case where a texture specified two
1912 * separate files to load, a 1- or 3-channel color image and a 1-channel alpha
1913 * image, this Filename is update to contain the name of the image file that
1914 * was loaded into the buffer's alpha channel.
1915 */
1916 INLINE void Texture::
1917 set_alpha_filename(const Filename &alpha_filename) {
1918 CDWriter cdata(_cycler, true);
1919 cdata->_alpha_filename = alpha_filename;
1920 }
1921
1922 /**
1923 * Removes the alpha filename, if it was previously set. See
1924 * set_alpha_filename().
1925 */
1926 INLINE void Texture::
1927 clear_alpha_filename() {
1928 CDWriter cdata(_cycler, true);
1929 cdata->_alpha_filename = Filename();
1930 }
1931
1932 /**
1933 * Sets the full pathname to the file that contains the image's contents, as
1934 * found along the search path. Normally, this is set automatically when the
1935 * image is loaded, for instance via Texture::read().
1936 */
1937 INLINE void Texture::
1938 set_fullpath(const Filename &fullpath) {
1939 CDWriter cdata(_cycler, true);
1940 cdata->_fullpath = fullpath;
1941 }
1942
1943 /**
1944 * Removes the alpha fullpath, if it was previously set. See set_fullpath().
1945 */
1946 INLINE void Texture::
1947 clear_fullpath() {
1948 CDWriter cdata(_cycler, true);
1949 cdata->_fullpath = Filename();
1950 }
1951
1952 /**
1953 * Sets the full pathname to the file that contains the image's alpha channel
1954 * contents, as found along the search path. Normally, this is set
1955 * automatically when the image is loaded, for instance via Texture::read().
1956 */
1957 INLINE void Texture::
1958 set_alpha_fullpath(const Filename &alpha_fullpath) {
1959 CDWriter cdata(_cycler, true);
1960 cdata->_alpha_fullpath = alpha_fullpath;
1961 }
1962
1963 /**
1964 * Removes the alpha fullpath, if it was previously set. See
1965 * set_alpha_fullpath().
1966 */
1967 INLINE void Texture::
1968 clear_alpha_fullpath() {
1969 CDWriter cdata(_cycler, true);
1970 cdata->_alpha_fullpath = Filename();
1971 }
1972
1973 /**
1974 * Changes the x size indicated for the texture. This also implicitly unloads
1975 * the texture if it has already been loaded.
1976 */
1977 INLINE void Texture::
1978 set_x_size(int x_size) {
1979 CDWriter cdata(_cycler, true);
1980 do_set_x_size(cdata, x_size);
1981 }
1982
1983 /**
1984 * Changes the y size indicated for the texture. This also implicitly unloads
1985 * the texture if it has already been loaded.
1986 */
1987 INLINE void Texture::
1988 set_y_size(int y_size) {
1989 CDWriter cdata(_cycler, true);
1990 do_set_y_size(cdata, y_size);
1991 }
1992
1993 /**
1994 * Changes the z size indicated for the texture. This also implicitly unloads
1995 * the texture if it has already been loaded.
1996 */
1997 INLINE void Texture::
1998 set_z_size(int z_size) {
1999 CDWriter cdata(_cycler, true);
2000 do_set_z_size(cdata, z_size);
2001 }
2002
2003 /**
2004 * Sets the number of "views" within a texture. A view is a completely
2005 * separate image stored within the Texture object. Most textures have only
2006 * one view, but a stereo texture, for instance, may have two views, a left
2007 * and a right image. Other uses for multiple views are not yet defined.
2008 *
2009 * If this value is greater than one, the additional views are accessed as
2010 * additional pages beyond get_z_size().
2011 *
2012 * This also implicitly unloads the texture if it has already been loaded.
2013 */
2014 INLINE void Texture::
2015 set_num_views(int num_views) {
2016 CDWriter cdata(_cycler, true);
2017 do_set_num_views(cdata, num_views);
2018 }
2019
2020 /**
2021 * Changes the format value for the texture components. This implicitly sets
2022 * num_components as well.
2023 */
2024 INLINE void Texture::
2025 set_format(Texture::Format format) {
2026 CDWriter cdata(_cycler, true);
2027 do_set_format(cdata, format);
2028 }
2029
2030 /**
2031 * Changes the data value for the texture components. This implicitly sets
2032 * component_width as well.
2033 */
2034 INLINE void Texture::
2035 set_component_type(Texture::ComponentType component_type) {
2036 CDWriter cdata(_cycler, true);
2037 do_set_component_type(cdata, component_type);
2038 }
2039
2040 /**
2041 * Sets the flag that indicates the texture has been loaded from a disk file
2042 * or PNMImage. You should also ensure the filename has been set correctly.
2043 * When this flag is true, the texture may be automatically reloaded when its
2044 * ram image needs to be replaced.
2045 */
2046 INLINE void Texture::
2047 set_loaded_from_image(bool flag) {
2048 CDWriter cdata(_cycler, false);
2049 cdata->_loaded_from_image = flag;
2050 }
2051
2052 /**
2053 * Returns the flag that indicates the texture has been loaded from a disk
2054 * file or PNMImage. See set_loaded_from_image().
2055 */
2056 INLINE bool Texture::
2057 get_loaded_from_image() const {
2058 CDReader cdata(_cycler);
2059 return cdata->_loaded_from_image;
2060 }
2061
2062 /**
2063 * Sets the flag that indicates the texture has been loaded from a txo file.
2064 * You probably shouldn't be setting this directly; it is set automatically
2065 * when a Texture is loaded.
2066 */
2067 INLINE void Texture::
2068 set_loaded_from_txo(bool flag) {
2069 CDWriter cdata(_cycler, false);
2070 cdata->_loaded_from_txo = flag;
2071 }
2072
2073 /**
2074 * Returns the flag that indicates the texture has been loaded from a txo
2075 * file.
2076 */
2077 INLINE bool Texture::
2078 get_loaded_from_txo() const {
2079 CDReader cdata(_cycler);
2080 return cdata->_loaded_from_txo;
2081 }
2082
2083 /**
2084 * Returns true if the special flag was set that indicates to the GSG that the
2085 * Texture's format should be chosen to exactly match the framebuffer's
2086 * format, presumably because the application intends to copy image data from
2087 * the framebuffer into the Texture (or vice-versa).
2088 */
2089 INLINE bool Texture::
2090 get_match_framebuffer_format() const {
2091 CDReader cdata(_cycler);
2092 return cdata->_match_framebuffer_format;
2093 }
2094
2095 /**
2096 * Sets the special flag that, if true, indicates to the GSG that the
2097 * Texture's format should be chosen to exactly match the framebuffer's
2098 * format, presumably because the application intends to copy image data from
2099 * the framebuffer into the Texture (or vice-versa).
2100 *
2101 * This sets only the graphics card's idea of the texture format; it is not
2102 * related to the system-memory format.
2103 */
2104 INLINE void Texture::
2105 set_match_framebuffer_format(bool flag) {
2106 CDWriter cdata(_cycler, true);
2107 cdata->_match_framebuffer_format = flag;
2108 }
2109
2110 /**
2111 * Returns the setting of the post_load_store_cache flag. See
2112 * set_post_load_store_cache().
2113 */
2114 INLINE bool Texture::
2115 get_post_load_store_cache() const {
2116 CDReader cdata(_cycler);
2117 return cdata->_post_load_store_cache;
2118 }
2119
2120 /**
2121 * Sets the post_load_store_cache flag. When this is set, the next time the
2122 * texture is loaded on a GSG, it will automatically extract its RAM image
2123 * from the GSG and save it to the global BamCache.
2124 *
2125 * This is used to store compressed RAM images in the BamCache. This flag
2126 * should not be set explicitly; it is set automatically by the TexturePool
2127 * when model-cache-compressed-textures is set true.
2128 */
2129 INLINE void Texture::
2130 set_post_load_store_cache(bool flag) {
2131 CDWriter cdata(_cycler, true);
2132 cdata->_post_load_store_cache = flag;
2133 }
2134
2135 /**
2136 * This method is similar to consider_rescale(), but instead of scaling a
2137 * separate PNMImage, it will ask the Texture to rescale its own internal
2138 * image to a power of 2, according to the config file requirements. This may
2139 * be useful after loading a Texture image by hand, instead of reading it from
2140 * a disk file. Returns true if the texture is changed, false if it was not.
2141 */
2142 INLINE bool Texture::
2143 rescale_texture() {
2144 CDWriter cdata(_cycler, true);
2145 return do_rescale_texture(cdata);
2146 }
2147
2148 /**
2149 * Works like adjust_size, but also considers the texture class. Movie
2150 * textures, for instance, always pad outwards, regardless of textures-
2151 * power-2.
2152 */
2153 INLINE bool Texture::
2154 adjust_this_size(int &x_size, int &y_size, const std::string &name,
2155 bool for_padding) const {
2156 CDReader cdata(_cycler);
2157 return do_adjust_this_size(cdata, x_size, y_size, name, for_padding);
2158 }
2159
2160 /**
2161 *
2162 */
2163 INLINE size_t Texture::
2164 do_get_ram_image_size(const CData *cdata) const {
2165 if (cdata->_ram_images.empty()) {
2166 return 0;
2167 }
2168 return cdata->_ram_images[0]._image.size();
2169 }
2170
2171 /**
2172 *
2173 */
2174 INLINE bool Texture::
2175 do_has_ram_mipmap_image(const CData *cdata, int n) const {
2176 return (n >= 0 && n < (int)cdata->_ram_images.size() &&
2177 !cdata->_ram_images[n]._image.empty());
2178 }
2179
2180 /**
2181 *
2182 */
2183 INLINE size_t Texture::
2184 do_get_expected_ram_image_size(const CData *cdata) const {
2185 return do_get_expected_ram_view_size(cdata) * (size_t)cdata->_num_views;
2186 }
2187
2188 /**
2189 *
2190 */
2191 INLINE size_t Texture::
2192 do_get_expected_ram_view_size(const CData *cdata) const {
2193 return do_get_expected_ram_page_size(cdata) * (size_t)cdata->_z_size;
2194 }
2195
2196 /**
2197 *
2198 */
2199 INLINE size_t Texture::
2200 do_get_expected_ram_page_size(const CData *cdata) const {
2201 return (size_t)(cdata->_x_size * cdata->_y_size * cdata->_num_components * cdata->_component_width);
2202 }
2203
2204 /**
2205 *
2206 */
2207 INLINE size_t Texture::
2208 do_get_expected_ram_mipmap_image_size(const CData *cdata, int n) const {
2209 return do_get_expected_ram_mipmap_view_size(cdata, n) * (size_t)cdata->_num_views;
2210 }
2211
2212 /**
2213 *
2214 */
2215 INLINE size_t Texture::
2216 do_get_expected_ram_mipmap_view_size(const CData *cdata, int n) const {
2217 return do_get_expected_ram_mipmap_page_size(cdata, n) * (size_t)do_get_expected_mipmap_z_size(cdata, n);
2218 }
2219
2220 /**
2221 *
2222 */
2223 INLINE size_t Texture::
2224 do_get_expected_ram_mipmap_page_size(const CData *cdata, int n) const {
2225 return (size_t)(do_get_expected_mipmap_x_size(cdata, n) * do_get_expected_mipmap_y_size(cdata, n) * cdata->_num_components * cdata->_component_width);
2226 }
2227
2228 /**
2229 *
2230 */
2231 INLINE int Texture::
2232 do_get_expected_mipmap_num_pages(const CData *cdata, int n) const {
2233 return do_get_expected_mipmap_z_size(cdata, n) * cdata->_num_views;
2234 }
2235
2236 /**
2237 *
2238 */
2239 INLINE void Texture::
2240 do_clear_ram_image(CData *cdata) {
2241 cdata->_ram_image_compression = CM_off;
2242 cdata->_ram_images.clear();
2243 }
2244
2245 /**
2246 *
2247 */
2248 INLINE AutoTextureScale Texture::
2249 do_get_auto_texture_scale(const CData *cdata) const {
2250 if (cdata->_auto_texture_scale == ATS_unspecified) {
2251 return get_textures_power_2();
2252 } else {
2253 return cdata->_auto_texture_scale;
2254 }
2255 }
2256
2257 /**
2258 * This is used by load() to store the next consecutive component value into
2259 * the indicated element of the array, which is taken to be an array of
2260 * unsigned bytes. The value is assumed to be in the range 0-255.
2261 */
2262 INLINE void Texture::
2263 store_unscaled_byte(unsigned char *&p, int value) {
2264 (*p++) = (uchar)value;
2265 }
2266
2267 /**
2268 * This is used by load() to store the next consecutive component value into
2269 * the indicated element of the array, which is taken to be an array of
2270 * unsigned shorts. The value is assumed to be in the range 0-65535.
2271 */
2272 INLINE void Texture::
2273 store_unscaled_short(unsigned char *&p, int value) {
2274 union {
2275 ushort us;
2276 uchar uc[2];
2277 } v;
2278 v.us = (ushort)value;
2279 (*p++) = v.uc[0];
2280 (*p++) = v.uc[1];
2281 }
2282
2283 /**
2284 * This is used by load() to store the next consecutive component value into
2285 * the indicated element of the array, which is taken to be an array of
2286 * unsigned bytes. The value will be scaled by the indicated factor before
2287 * storing it.
2288 */
2289 INLINE void Texture::
2290 store_scaled_byte(unsigned char *&p, int value, double scale) {
2291 store_unscaled_byte(p, (int)(value * scale));
2292 }
2293
2294 /**
2295 * This is used by load() to store the next consecutive component value into
2296 * the indicated element of the array, which is taken to be an array of
2297 * unsigned shorts. The value will be scaled by the indicated factor before
2298 * storing it.
2299 */
2300 INLINE void Texture::
2301 store_scaled_short(unsigned char *&p, int value, double scale) {
2302 store_unscaled_short(p, (int)(value * scale));
2303 }
2304
2305 /**
2306 * This is used by store() to retrieve the next consecutive component value
2307 * from the indicated element of the array, which is taken to be an array of
2308 * unsigned bytes.
2309 */
2310 INLINE double Texture::
2311 get_unsigned_byte(const unsigned char *&p) {
2312 return (double)(*p++) / 255.0;
2313 }
2314
2315 /**
2316 * This is used by store() to retrieve the next consecutive component value
2317 * from the indicated element of the array, which is taken to be an array of
2318 * unsigned shorts.
2319 */
2320 INLINE double Texture::
2321 get_unsigned_short(const unsigned char *&p) {
2322 union {
2323 ushort us;
2324 uchar uc[2];
2325 } v;
2326 v.uc[0] = (*p++);
2327 v.uc[1] = (*p++);
2328 return (double)v.us / 65535.0;
2329 }
2330
2331 /**
2332 * This is used by store() to retrieve the next consecutive component value
2333 * from the indicated element of the array, which is taken to be an array of
2334 * unsigned ints.
2335 */
2336 INLINE double Texture::
2337 get_unsigned_int(const unsigned char *&p) {
2338 union {
2339 unsigned int ui;
2340 uchar uc[4];
2341 } v;
2342 v.uc[0] = (*p++);
2343 v.uc[1] = (*p++);
2344 v.uc[2] = (*p++);
2345 v.uc[3] = (*p++);
2346 return (double)v.ui / 4294967295.0;
2347 }
2348
2349 /**
2350 * This is used by store() to retrieve the next consecutive component value
2351 * from the indicated element of the array, which is taken to be an array of
2352 * unsigned ints with the value packed in the 24 least significant bits.
2353 */
2354 INLINE double Texture::
2355 get_unsigned_int_24(const unsigned char *&p) {
2356 union {
2357 uint32_t ui;
2358 uint8_t uc[4];
2359 } v;
2360 v.uc[0] = (*p++);
2361 v.uc[1] = (*p++);
2362 v.uc[2] = (*p++);
2363 v.uc[3] = (*p++);
2364 return (double)(v.ui & 0xffffff) / (double)0xffffff;
2365 }
2366
2367 /**
2368 * This is used by store() to retrieve the next consecutive component value
2369 * from the indicated element of the array, which is taken to be an array of
2370 * floats.
2371 */
2372 INLINE double Texture::
2373 get_float(const unsigned char *&p) {
2374 double v = *((float *)p);
2375 p += 4;
2376 return v;
2377 }
2378
2379 /**
2380 * This is used by store() to retrieve the next consecutive component value
2381 * from the indicated element of the array, which is taken to be an array of
2382 * half-floats.
2383 */
2384 INLINE double Texture::
2385 get_half_float(const unsigned char *&p) {
2386 union {
2387 uint32_t ui;
2388 float uf;
2389 } v;
2390 uint16_t in = *(uint16_t *)p;
2391 p += 2;
2392 uint32_t t1 = in & 0x7fff; // Non-sign bits
2393 uint32_t t2 = in & 0x8000; // Sign bit
2394 uint32_t t3 = in & 0x7c00; // Exponent
2395 t1 <<= 13; // Align mantissa on MSB
2396 t2 <<= 16; // Shift sign bit into position
2397 if (t3 != 0x7c00) {
2398 t1 += 0x38000000; // Adjust bias
2399 t1 = (t3 == 0 ? 0 : t1); // Denormals-as-zero
2400 } else {
2401 // Infinity / NaN
2402 t1 |= 0x7f800000;
2403 }
2404 t1 |= t2; // Re-insert sign bit
2405 v.ui = t1;
2406 return v.uf;
2407 }
2408
2409 /**
2410 * Returns true if the indicated filename ends in .txo or .txo.pz or .txo.gz,
2411 * false otherwise.
2412 */
2413 INLINE bool Texture::
2414 is_txo_filename(const Filename &fullpath) {
2415 std::string extension = fullpath.get_extension();
2416 #ifdef HAVE_ZLIB
2417 if (extension == "pz" || extension == "gz") {
2418 extension = Filename(fullpath.get_basename_wo_extension()).get_extension();
2419 }
2420 #endif // HAVE_ZLIB
2421 return (extension == "txo");
2422 }
2423
2424 /**
2425 * Returns true if the indicated filename ends in .dds or .dds.pz or .dds.gz,
2426 * false otherwise.
2427 */
2428 INLINE bool Texture::
2429 is_dds_filename(const Filename &fullpath) {
2430 std::string extension = fullpath.get_extension();
2431 #ifdef HAVE_ZLIB
2432 if (extension == "pz" || extension == "gz") {
2433 extension = Filename(fullpath.get_basename_wo_extension()).get_extension();
2434 }
2435 #endif // HAVE_ZLIB
2436 return (downcase(extension) == "dds");
2437 }
2438
2439 /**
2440 * Returns true if the indicated filename ends in .ktx or .ktx.pz or .ktx.gz,
2441 * false otherwise.
2442 */
2443 INLINE bool Texture::
2444 is_ktx_filename(const Filename &fullpath) {
2445 std::string extension = fullpath.get_extension();
2446 #ifdef HAVE_ZLIB
2447 if (extension == "pz" || extension == "gz") {
2448 extension = Filename(fullpath.get_basename_wo_extension()).get_extension();
2449 }
2450 #endif // HAVE_ZLIB
2451 return (downcase(extension) == "ktx");
2452 }
2453
2454 /**
2455 *
2456 */
2457 INLINE void Texture::CData::
2458 inc_properties_modified() {
2459 ++_properties_modified;
2460 }
2461
2462 /**
2463 *
2464 */
2465 INLINE void Texture::CData::
2466 inc_image_modified() {
2467 ++_image_modified;
2468 }
2469
2470 /**
2471 *
2472 */
2473 INLINE void Texture::CData::
2474 inc_simple_image_modified() {
2475 ++_simple_image_modified;
2476 }
2477
2478 /**
2479 *
2480 */
2481 INLINE Texture::RamImage::
2482 RamImage() :
2483 _page_size(0),
2484 _pointer_image(nullptr)
2485 {
2486 }
ConstPointerToArray< unsigned char >
CycleDataReader
This template class calls PipelineCycler::read_unlocked(), and then provides a transparent read-only ...
Definition: cycleDataReader.h:35
CycleDataWriter
This template class calls PipelineCycler::write() in the constructor and PipelineCycler::release_writ...
Definition: cycleDataWriter.h:34
Filename
The name of a file, such as a texture file or an Egg file.
Definition: filename.h:39
Filename::get_extension
std::string get_extension() const
Returns the file extension.
Definition: filename.I:400
Filename::get_basename_wo_extension
std::string get_basename_wo_extension() const
Returns the basename part of the filename, without the file extension.
Definition: filename.I:386
GraphicsStateGuardianBase
This is a base class for the GraphicsStateGuardian class, which is itself a base class for the variou...
Definition: graphicsStateGuardianBase.h:110
LoaderOptions
Specifies parameters that may be passed to the loader.
Definition: loaderOptions.h:23
PNMImage
The name of this class derives from the fact that we originally implemented it as a layer on top of t...
Definition: pnmImage.h:58
PfmFile
Defines a pfm file, a 2-d table of floating-point numbers, either 3-component or 1-component,...
Definition: pfmFile.h:31
SamplerState
Represents a set of settings that indicate how a texture is sampled.
Definition: samplerState.h:36
SamplerState::is_mipmap
static bool is_mipmap(FilterType type)
Returns true if the indicated filter type requires the use of mipmaps, or false if it does not.
Definition: samplerState.I:257
Texture
Represents a texture object, which is typically a single 2-d image but may also represent a 1-d or 3-...
Definition: texture.h:71
Texture::get_ram_mipmap_image_size
size_t get_ram_mipmap_image_size(int n) const
Returns the number of bytes used by the in-memory image for mipmap level n, or 0 if there is no in-me...
Definition: texture.I:1548
Texture::setup_2d_texture
void setup_2d_texture()
Sets the texture as an empty 2-d texture with no dimensions.
Definition: texture.I:87
Texture::get_post_load_store_cache
get_post_load_store_cache
Returns the setting of the post_load_store_cache flag.
Definition: texture.h:594
Texture::set_compression
set_compression
Requests that this particular Texture be compressed when it is loaded into texture memory.
Definition: texture.h:413
Texture::set_alpha_fullpath
set_alpha_fullpath
Sets the full pathname to the file that contains the image's alpha channel contents,...
Definition: texture.h:338
Texture::get_uncompressed_ram_image
CPTA_uchar get_uncompressed_ram_image()
Returns the system-RAM image associated with the texture, in an uncompressed form if at all possible.
Definition: texture.I:1403
Texture::get_format
get_format
Returns the format of the texture, which represents both the semantic meaning of the texels and,...
Definition: texture.h:370
Texture::get_minfilter
get_minfilter
Returns the filter mode of the texture for minification.
Definition: texture.h:391
Texture::get_ram_image_size
get_ram_image_size
Returns the total number of bytes used by the in-memory image, across all pages and views,...
Definition: texture.h:445
Texture::get_expected_ram_mipmap_view_size
size_t get_expected_ram_mipmap_view_size(int n) const
Returns the number of bytes that *ought* to be used by each view of the in- memory image for mipmap l...
Definition: texture.I:1613
Texture::has_filename
has_filename
Returns true if the filename has been set and is available.
Definition: texture.h:320
Texture::generate_ram_mipmap_images
void generate_ram_mipmap_images()
Automatically fills in the n mipmap levels of the Texture, based on the texture's source image.
Definition: texture.I:1691
Texture::clear_ram_mipmap_images
void clear_ram_mipmap_images()
Discards the current system-RAM image for all mipmap levels, except level 0 (the base image).
Definition: texture.I:1674
Texture::set_match_framebuffer_format
set_match_framebuffer_format
Sets the special flag that, if true, indicates to the GSG that the Texture's format should be chosen ...
Definition: texture.h:589
Texture::clear_image
void clear_image()
Clears the texture data without changing its format or resolution.
Definition: texture.I:230
Texture::modify_ram_image
PTA_uchar modify_ram_image()
Returns a modifiable pointer to the system-RAM image.
Definition: texture.I:1382
Texture::setup_cube_map_array
void setup_cube_map_array(int num_cube_maps)
Sets the texture as cube map array with N cube maps.
Definition: texture.I:182
Texture::get_expected_ram_mipmap_image_size
size_t get_expected_ram_mipmap_image_size(int n) const
Returns the number of bytes that *ought* to be used by the in-memory image for mipmap level n,...
Definition: texture.I:1601
Texture::get_alpha_fullpath
get_alpha_fullpath
Returns the alpha_fullpath that has been set.
Definition: texture.h:338
Texture::has_auto_texture_scale
bool has_auto_texture_scale() const
Returns true if set_auto_texture_scale() has been set to something other than ATS_unspecified for thi...
Definition: texture.I:1841
Texture::set_wrap_u
set_wrap_u
This setting determines what happens when the texture is sampled with a U value outside the range 0....
Definition: texture.h:378
Texture::setup_2d_texture_array
void setup_2d_texture_array(int z_size=1)
Sets the texture as an empty 2-d texture array with no dimensions (though if you know the depth ahead...
Definition: texture.I:133
Texture::set_z_size
set_z_size
Changes the z size indicated for the texture.
Definition: texture.h:350
Texture::set_num_views
set_num_views
Sets the number of "views" within a texture.
Definition: texture.h:354
Texture::get_ram_page_size
get_ram_page_size
Returns the number of bytes used by the in-memory image per page, or 0 if there is no in-memory image...
Definition: texture.h:447
Texture::get_render_to_texture
get_render_to_texture
Returns a flag on the texture that indicates whether the texture is intended to be used as a direct-r...
Definition: texture.h:417
Texture::get_expected_mipmap_num_pages
int get_expected_mipmap_num_pages(int n) const
Returns the total number of pages that the nth mipmap level should have, based on the texture's size.
Definition: texture.I:1217
Texture::get_num_views
get_num_views
Returns the number of "views" in the texture.
Definition: texture.h:354
Texture::get_compression
get_compression
Returns the compression mode requested for this particular texture, or CM_off if the texture is not t...
Definition: texture.h:413
Texture::get_wrap_w
get_wrap_w
Returns the wrap mode of the texture in the W direction.
Definition: texture.h:386
Texture::has_ram_image
bool has_ram_image() const
Returns true if the Texture has its image contents available in main RAM, false if it exists only in ...
Definition: texture.I:1242
Texture::get_texture_type
get_texture_type
Returns the overall interpretation of the texture.
Definition: texture.h:365
Texture::write
bool write(const Filename &fullpath)
Writes the texture to the named filename.
Definition: texture.I:298
Texture::get_filename
get_filename
Returns the filename that has been set.
Definition: texture.h:320
Texture::get_default_sampler
get_default_sampler
This returns the default sampler state for this texture, containing the wrap and filter properties sp...
Definition: texture.h:421
Texture::get_pad_y_size
int get_pad_y_size() const
Returns size of the pad region.
Definition: texture.I:629
Texture::get_ram_image
CPTA_uchar get_ram_image()
Returns the system-RAM image data associated with the texture.
Definition: texture.I:1356
Texture::get_simple_ram_image
get_simple_ram_image
Returns the image data associated with the "simple" texture image.
Definition: texture.h:517
Texture::has_fullpath
has_fullpath
Returns true if the fullpath has been set and is available.
Definition: texture.h:332
Texture::get_ram_image_compression
get_ram_image_compression
Returns the compression mode in which the ram image is already stored pre- compressed.
Definition: texture.h:471
Texture::get_effective_anisotropic_degree
get_effective_anisotropic_degree
Returns the degree of anisotropic filtering that should be applied to the texture.
Definition: texture.h:404
Texture::set_format
set_format
Changes the format value for the texture components.
Definition: texture.h:370
Texture::get_orig_file_z_size
get_orig_file_z_size
Returns the Z size of the original disk image that this Texture was loaded from (if it came from a di...
Definition: texture.h:574
Texture::get_component_width
get_component_width
Returns the number of bytes stored for each color component of a texel.
Definition: texture.h:364
Texture::setup_texture
void setup_texture(TextureType texture_type, int x_size, int y_size, int z_size, ComponentType component_type, Format format)
Sets the texture to the indicated type and dimensions, presumably in preparation for calling read() o...
Definition: texture.I:52
Texture::get_alpha_filename
get_alpha_filename
Returns the alpha_filename that has been set.
Definition: texture.h:326
Texture::get_expected_mipmap_z_size
int get_expected_mipmap_z_size(int n) const
Returns the z_size that the nth mipmap level should have, based on the texture's size.
Definition: texture.I:1205
Texture::load
bool load(const PNMImage &pnmimage, const LoaderOptions &options=LoaderOptions())
Replaces the texture with the indicated image.
Definition: texture.I:357
Texture::clear_fullpath
clear_fullpath
Removes the alpha fullpath, if it was previously set.
Definition: texture.h:332
Texture::reload
bool reload()
Re-reads the Texture from its disk file.
Definition: texture.I:472
Texture::get_clear_data
vector_uchar get_clear_data() const
Returns the raw image data for a single pixel if it were set to the clear color.
Definition: texture.I:287
Texture::clear_simple_ram_image
void clear_simple_ram_image()
Discards the current "simple" image.
Definition: texture.I:1779
Texture::get_effective_minfilter
get_effective_minfilter
Returns the filter mode of the texture for minification, with special treatment for FT_default.
Definition: texture.h:392
Texture::rescale_texture
bool rescale_texture()
This method is similar to consider_rescale(), but instead of scaling a separate PNMImage,...
Definition: texture.I:2143
Texture::set_anisotropic_degree
set_anisotropic_degree
Specifies the level of anisotropic filtering to apply to the texture.
Definition: texture.h:403
Texture::set_render_to_texture
set_render_to_texture
Sets a flag on the texture that indicates whether the texture is intended to be used as a direct-rend...
Definition: texture.h:417
Texture::set_loaded_from_image
set_loaded_from_image
Sets the flag that indicates the texture has been loaded from a disk file or PNMImage.
Definition: texture.h:580
Texture::set_quality_level
set_quality_level
Sets a hint to the renderer about the desired performance / quality tradeoff for this particular text...
Definition: texture.h:427
Texture::set_clear_color
set_clear_color
Sets the color that will be used to fill the texture image in absence of any image data.
Definition: texture.h:278
Texture::get_expected_num_mipmap_levels
get_expected_num_mipmap_levels
Returns the number of mipmap levels that should be defined for this texture, given the texture's size...
Definition: texture.h:435
Texture::clear_alpha_fullpath
clear_alpha_fullpath
Removes the alpha fullpath, if it was previously set.
Definition: texture.h:338
Texture::setup_cube_map
void setup_cube_map()
Sets the texture as an empty cube map texture with no dimensions.
Definition: texture.I:155
Texture::get_anisotropic_degree
get_anisotropic_degree
Returns the degree of anisotropic filtering that should be applied to the texture.
Definition: texture.h:403
Texture::has_alpha_fullpath
has_alpha_fullpath
Returns true if the alpha_fullpath has been set and is available.
Definition: texture.h:338
Texture::get_match_framebuffer_format
get_match_framebuffer_format
Returns true if the special flag was set that indicates to the GSG that the Texture's format should b...
Definition: texture.h:589
Texture::modify_ram_mipmap_image
PTA_uchar modify_ram_mipmap_image(int n)
Returns a modifiable pointer to the system-RAM image for the nth mipmap level.
Definition: texture.I:1637
Texture::get_properties_modified
get_properties_modified
Returns a sequence number which is guaranteed to change at least every time the texture properties (u...
Definition: texture.h:524
Texture::clear_alpha_filename
clear_alpha_filename
Removes the alpha filename, if it was previously set.
Definition: texture.h:326
Texture::has_compression
bool has_compression() const
Returns true if the texture indicates it wants to be compressed, either with CM_on or higher,...
Definition: texture.I:1102
Texture::get_y_size
get_y_size
Returns the height of the texture image in texels.
Definition: texture.h:346
Texture::compress_ram_image
bool compress_ram_image(CompressionMode compression=CM_on, QualityLevel quality_level=QL_default, GraphicsStateGuardianBase *gsg=nullptr)
Attempts to compress the texture's RAM image internally, to a format supported by the indicated GSG.
Definition: texture.I:1479
Texture::load_sub_image
bool load_sub_image(const PNMImage &pnmimage, int x, int y, int z=0, int n=0)
Stores the indicated image in a region of the texture.
Definition: texture.I:423
Texture::get_ram_mipmap_view_size
size_t get_ram_mipmap_view_size(int n) const
Returns the number of bytes used by the in-memory image per view for mipmap level n,...
Definition: texture.I:1576
Texture::get_magfilter
get_magfilter
Returns the filter mode of the texture for magnification.
Definition: texture.h:397
Texture::get_tex_scale
LVecBase2 get_tex_scale() const
Returns a scale pair that is suitable for applying to geometry via NodePath::set_tex_scale(),...
Definition: texture.I:655
Texture::get_z_size
get_z_size
Returns the depth of the texture image in texels.
Definition: texture.h:350
Texture::get_pad_x_size
int get_pad_x_size() const
Returns size of the pad region.
Definition: texture.I:620
Texture::get_image_modified
get_image_modified
Returns a sequence number which is guaranteed to change at least every time the texture image data (i...
Definition: texture.h:525
Texture::set_x_size
set_x_size
Changes the x size indicated for the texture.
Definition: texture.h:342
Texture::get_quality_level
get_quality_level
Returns the current quality_level hint.
Definition: texture.h:427
Texture::get_simple_image_modified
get_simple_image_modified
Returns a sequence number which is guaranteed to change at least every time the texture's "simple" im...
Definition: texture.h:526
Texture::set_ram_mipmap_image
void set_ram_mipmap_image(int n, CPTA_uchar image, size_t page_size=0)
Replaces the current system-RAM image for the indicated mipmap level with the new data.
Definition: texture.I:1664
Texture::get_expected_ram_mipmap_page_size
size_t get_expected_ram_mipmap_page_size(int n) const
Returns the number of bytes that should be used per each Z page of the 3-d texture,...
Definition: texture.I:1624
Texture::setup_1d_texture
void setup_1d_texture()
Sets the texture as an empty 1-d texture with no dimensions.
Definition: texture.I:66
Texture::set_minfilter
set_minfilter
Sets the filtering method that should be used when viewing the texture from a distance.
Definition: texture.h:391
Texture::get_effective_magfilter
get_effective_magfilter
Returns the filter mode of the texture for magnification, with special treatment for FT_default.
Definition: texture.h:398
Texture::has_alpha_filename
has_alpha_filename
Returns true if the alpha_filename has been set and is available.
Definition: texture.h:326
Texture::set_magfilter
set_magfilter
Sets the filtering method that should be used when viewing the texture up close.
Definition: texture.h:397
Texture::might_have_ram_image
bool might_have_ram_image() const
Returns true if the texture's image contents are currently available in main RAM, or there is reason ...
Definition: texture.I:1264
Texture::make_ram_mipmap_image
PTA_uchar make_ram_mipmap_image(int n)
Discards the current system-RAM image for the nth mipmap level, if any, and allocates a new buffer of...
Definition: texture.I:1650
Texture::get_textures_power_2
static AutoTextureScale get_textures_power_2()
This flag returns ATS_none, ATS_up, or ATS_down and controls the scaling of textures in general.
Definition: texture.I:1863
Texture::get_pad_z_size
int get_pad_z_size() const
Returns size of the pad region.
Definition: texture.I:638
Texture::has_ram_mipmap_image
bool has_ram_mipmap_image(int n) const
Returns true if the Texture has the nth mipmap level available in system memory, false otherwise.
Definition: texture.I:1528
Texture::get_loaded_from_image
get_loaded_from_image
Returns the flag that indicates the texture has been loaded from a disk file or PNMImage.
Definition: texture.h:580
Texture::get_auto_texture_scale
get_auto_texture_scale
Returns the power-of-2 texture-scaling mode that will be applied to this particular texture when it i...
Definition: texture.h:532
Texture::setup_buffer_texture
void setup_buffer_texture(int size, ComponentType component_type, Format format, GeomEnums::UsageHint usage)
Sets the texture as an empty buffer texture with the specified size and properties.
Definition: texture.I:211
Texture::set_pad_size
void set_pad_size(int x=0, int y=0, int z=0)
Sets the size of the pad region.
Definition: texture.I:677
Texture::get_expected_mipmap_x_size
int get_expected_mipmap_x_size(int n) const
Returns the x_size that the nth mipmap level should have, based on the texture's size.
Definition: texture.I:1185
Texture::set_simple_ram_image
void set_simple_ram_image(CPTA_uchar image, int x_size, int y_size)
Replaces the internal "simple" texture image.
Definition: texture.I:1770
Texture::get_num_components
get_num_components
Returns the number of color components for each texel of the texture image.
Definition: texture.h:363
Texture::get_effective_quality_level
get_effective_quality_level
Returns the current quality_level hint, or the global default quality_level if this texture doesn't s...
Definition: texture.h:428
Texture::clear_ram_image
void clear_ram_image()
Discards the current system-RAM image.
Definition: texture.I:1439
Texture::uses_mipmaps
bool uses_mipmaps() const
Returns true if the minfilter settings on this texture indicate the use of mipmapping,...
Definition: texture.I:1127
Texture::get_fullpath
get_fullpath
Returns the fullpath that has been set.
Definition: texture.h:332
Texture::set_default_sampler
set_default_sampler
This sets the default sampler state for this texture, containing the wrap and filter properties speci...
Definition: texture.h:421
Texture::has_clear_color
has_clear_color
Returns true if a color was previously set using set_clear_color.
Definition: texture.h:278
Texture::get_wrap_u
get_wrap_u
Returns the wrap mode of the texture in the U direction.
Definition: texture.h:378
Texture::set_loaded_from_txo
set_loaded_from_txo
Sets the flag that indicates the texture has been loaded from a txo file.
Definition: texture.h:584
Texture::get_num_pages
get_num_pages
Returns the total number of pages in the texture.
Definition: texture.h:362
Texture::has_simple_ram_image
has_simple_ram_image
Returns true if the Texture has a "simple" image available in main RAM.
Definition: texture.h:517
Texture::set_auto_texture_scale
set_auto_texture_scale
Specifies the power-of-2 texture-scaling mode that will be applied to this particular texture when it...
Definition: texture.h:532
Texture::set_textures_power_2
static void set_textures_power_2(AutoTextureScale scale)
Set this flag to ATS_none, ATS_up, ATS_down, or ATS_pad to control the scaling of textures in general...
Definition: texture.I:1852
Texture::get_simple_ram_image_size
size_t get_simple_ram_image_size() const
Returns the number of bytes used by the "simple" image, or 0 if there is no simple image.
Definition: texture.I:1732
Texture::get_orig_file_x_size
get_orig_file_x_size
Returns the X size of the original disk image that this Texture was loaded from (if it came from a di...
Definition: texture.h:572
Texture::get_ram_mipmap_page_size
size_t get_ram_mipmap_page_size(int n) const
Returns the number of bytes used by the in-memory image per page for mipmap level n,...
Definition: texture.I:1591
Texture::get_x_size
get_x_size
Returns the width of the texture image in texels.
Definition: texture.h:342
Texture::has_uncompressed_ram_image
bool has_uncompressed_ram_image() const
Returns true if the Texture has its image contents available in main RAM and is uncompressed,...
Definition: texture.I:1252
Texture::has_all_ram_mipmap_images
bool has_all_ram_mipmap_images() const
Returns true if all expected mipmap levels have been defined and exist in the system RAM,...
Definition: texture.I:1538
Texture::clear_clear_color
clear_clear_color
The opposite of set_clear_color.
Definition: texture.h:278
Texture::get_simple_y_size
get_simple_y_size
Returns the height of the "simple" image in texels.
Definition: texture.h:516
Texture::get_expected_ram_page_size
get_expected_ram_page_size
Returns the number of bytes that should be used per each Z page of the 3-d texture.
Definition: texture.h:449
Texture::set_fullpath
set_fullpath
Sets the full pathname to the file that contains the image's contents, as found along the search path...
Definition: texture.h:332
Texture::get_expected_mipmap_y_size
int get_expected_mipmap_y_size(int n) const
Returns the y_size that the nth mipmap level should have, based on the texture's size.
Definition: texture.I:1195
Texture::uncompress_ram_image
bool uncompress_ram_image()
Attempts to uncompress the texture's RAM image internally.
Definition: texture.I:1498
Texture::set_y_size
set_y_size
Changes the y size indicated for the texture.
Definition: texture.h:346
Texture::get_expected_ram_image_size
get_expected_ram_image_size
Returns the number of bytes that *ought* to be used by the in-memory image, based on the texture para...
Definition: texture.h:448
Texture::set_post_load_store_cache
set_post_load_store_cache
Sets the post_load_store_cache flag.
Definition: texture.h:594
Texture::set_wrap_w
set_wrap_w
The W wrap direction is only used for 3-d textures.
Definition: texture.h:386
Texture::make_ram_image
PTA_uchar make_ram_image()
Discards the current system-RAM image for the texture, if any, and allocates a new buffer of the appr...
Definition: texture.I:1415
Texture::get_component_type
get_component_type
Returns the numeric interpretation of each component of the texture.
Definition: texture.h:374
Texture::set_ram_image
void set_ram_image(CPTA_uchar image, CompressionMode compression=CM_off, size_t page_size=0)
Replaces the current system-RAM image with the new data.
Definition: texture.I:1429
Texture::adjust_this_size
bool adjust_this_size(int &x_size, int &y_size, const std::string &name, bool for_padding) const
Works like adjust_size, but also considers the texture class.
Definition: texture.I:2154
Texture::get_simple_x_size
get_simple_x_size
Returns the width of the "simple" image in texels.
Definition: texture.h:515
Texture::get_loaded_from_txo
get_loaded_from_txo
Returns the flag that indicates the texture has been loaded from a txo file.
Definition: texture.h:584
Texture::get_wrap_v
get_wrap_v
Returns the wrap mode of the texture in the V direction.
Definition: texture.h:382
Texture::get_border_color
get_border_color
Returns the solid color of the texture's border.
Definition: texture.h:408
Texture::get_clear_color
get_clear_color
Returns the color that was previously set using set_clear_color.
Definition: texture.h:278
Texture::set_keep_ram_image
set_keep_ram_image
Sets the flag that indicates whether this Texture is eligible to have its main RAM copy of the textur...
Definition: texture.h:472
Texture::clear_filename
clear_filename
Removes the alpha filename, if it was previously set.
Definition: texture.h:320
Texture::set_border_color
set_border_color
Specifies the solid color of the texture's border.
Definition: texture.h:408
Texture::get_ram_view_size
get_ram_view_size
Returns the number of bytes used by the in-memory image per view, or 0 if there is no in-memory image...
Definition: texture.h:446
Texture::set_alpha_filename
set_alpha_filename
Sets the name of the file that contains the image's alpha channel contents.
Definition: texture.h:326
Texture::set_wrap_v
set_wrap_v
This setting determines what happens when the texture is sampled with a V value outside the range 0....
Definition: texture.h:382
Texture::set_filename
set_filename
Sets the name of the file that contains the image's contents.
Definition: texture.h:320
Texture::store
bool store(PNMImage &pnmimage) const
Saves the texture to the indicated PNMImage, but does not write it to disk.
Definition: texture.I:432
Texture::has_textures_power_2
static bool has_textures_power_2()
If true, then get_textures_power_2 has been set using set_textures_power_2.
Definition: texture.I:1877
Texture::set_component_type
set_component_type
Changes the data value for the texture components.
Definition: texture.h:374
Texture::get_orig_file_y_size
get_orig_file_y_size
Returns the Y size of the original disk image that this Texture was loaded from (if it came from a di...
Definition: texture.h:573
Texture::get_num_ram_mipmap_images
get_num_ram_mipmap_images
Returns the maximum number of mipmap level images available in system memory.
Definition: texture.h:501
Texture::setup_3d_texture
void setup_3d_texture(int z_size=1)
Sets the texture as an empty 3-d texture with no dimensions (though if you know the depth ahead of ti...
Definition: texture.I:110
Texture::get_usage_hint
get_usage_hint
Returns the usage hint specified for buffer textures, or UH_unspecified for all other texture types.
Definition: texture.h:366
UpdateSeq
This is a sequence number that increments monotonically.
Definition: updateSeq.h:37
downcase
string downcase(const string &s)
Returns the input string with all uppercase letters converted to lowercase.
Definition: string_utils.cxx:71
PT
PT(Texture) Texture
Returns a new copy of the same Texture.
Definition: texture.I:25