Texture

from panda3d.core import Texture

class Texture

Bases:

Bases: TypedWritableReferenceCount, Namable

Represents a texture object, which is typically a single 2-d image but may also represent a 1-d or 3-d texture image, or the six 2-d faces of a cube map texture.

A texture’s image data might be stored in system RAM (see getRamImage()) or its image may be represented in texture memory on one or more GraphicsStateGuardians (see prepare()), or both. The typical usage pattern is that a texture is loaded from an image file on disk, which copies its image data into system RAM; then the first time the texture is rendered its image data is copied to texture memory (actually, to the graphics API), and the system RAM image is automatically freed.

Inheritance diagram

enum ComponentType

enumerator T_unsigned_byte = 0

enumerator T_unsigned_short = 1

enumerator T_float = 2

enumerator T_unsigned_int_24_8 = 3

Packed

enumerator T_int = 4

enumerator T_byte = 5

enumerator T_short = 6

enumerator T_half_float = 7

enumerator T_unsigned_int = 8

enum CompressionMode

enumerator CM_default = 0

on or off, according to compressed-textures

enumerator CM_off = 1

uncompressed image

enumerator CM_on = 2

whatever compression the driver supports

enumerator CM_fxt1 = 3

Specific compression modes. Use only when you really want to use a particular compression algorithm. Use with caution; not all drivers support all compression modes. You can use GSG::get_supports_compressed_texture_format() to query the available compression modes for a particular GSG.

enumerator CM_dxt1 = 4

BC1: RGB with optional binary alpha.

enumerator CM_dxt2 = 5

Like DXT3, but assumes premultiplied alpha

enumerator CM_dxt3 = 6

BC2: RGB with uncompressed 4-bit alpha.

enumerator CM_dxt4 = 7

Like DXT5, but assumes premultiplied alpha

enumerator CM_dxt5 = 8

BC3: RGB with separately compressed 8-bit alpha.

enumerator CM_pvr1_2bpp = 9

enumerator CM_pvr1_4bpp = 10

enumerator CM_rgtc = 11

BC4/BC5: 1 or 2 channels, individually compressed.

enumerator CM_etc1 = 12

enumerator CM_etc2 = 13

enumerator CM_eac = 14

EAC: 1 or 2 channels.

enum DeprecatedFilterType

Deprecated. See SamplerState.FilterType.

enumerator FT_nearest = 0

enumerator FT_linear = 1

enumerator FT_nearest_mipmap_nearest = 2

enumerator FT_linear_mipmap_nearest = 3

enumerator FT_nearest_mipmap_linear = 4

enumerator FT_linear_mipmap_linear = 5

enumerator FT_shadow = 6

enumerator FT_default = 7

enumerator FT_invalid = 8

enum DeprecatedWrapMode

Deprecated. See SamplerState.WrapMode.

enumerator WM_clamp = 0

enumerator WM_repeat = 1

enumerator WM_mirror = 2

enumerator WM_mirror_once = 3

enumerator WM_border_color = 4

enumerator WM_invalid = 5

enum Format

enumerator F_depth_stencil = 1

enumerator F_color_index = 2

enumerator F_red = 3

enumerator F_green = 4

enumerator F_blue = 5

enumerator F_alpha = 6

enumerator F_rgb = 7

any suitable RGB mode, whatever the hardware prefers

enumerator F_rgb5 = 8

5 bits per R,G,B channel

enumerator F_rgb8 = 9

8 bits per R,G,B channel

enumerator F_rgb12 = 10

12 bits per R,G,B channel

enumerator F_rgb332 = 11

3 bits per R & G, 2 bits for B

enumerator F_rgba = 12

any suitable RGBA mode, whatever the hardware prefers

enumerator F_rgbm = 13

as above, but only requires 1 bit for alpha (i.e. mask)

enumerator F_rgba4 = 14

4 bits per R,G,B,A channel

enumerator F_rgba5 = 15

5 bits per R,G,B channel, 1 bit alpha

enumerator F_rgba8 = 16

8 bits per R,G,B,A channel

enumerator F_rgba12 = 17

12 bits per R,G,B,A channel

enumerator F_luminance = 18

enumerator F_luminance_alpha = 19

8 bits luminance, 8 bits alpha

enumerator F_luminance_alphamask = 20

8 bits luminance, only needs 1 bit of alpha

enumerator F_rgba16 = 21

16 bits per R,G,B,A channel

enumerator F_rgba32 = 22

32 bits per R,G,B,A channel

enumerator F_depth_component = 23

enumerator F_depth_component16 = 24

enumerator F_depth_component24 = 25

enumerator F_depth_component32 = 26

enumerator F_r16 = 27

enumerator F_rg16 = 28

enumerator F_rgb16 = 29

enumerator F_srgb = 30

These formats are in the sRGB color space. RGB is 2.2 gamma corrected, alpha is always linear.

enumerator F_srgb_alpha = 31

enumerator F_sluminance = 32

enumerator F_sluminance_alpha = 33

enumerator F_r32i = 34

32-bit integer, used for atomic access

enumerator F_r32 = 35

enumerator F_rg32 = 36

enumerator F_rgb32 = 37

enumerator F_r8i = 38

8 integer bits per R channel

enumerator F_rg8i = 39

8 integer bits per R,G channel

enumerator F_rgb8i = 40

8 integer bits per R,G,B channel

enumerator F_rgba8i = 41

8 integer bits per R,G,B,A channel

enumerator F_r11_g11_b10 = 42

unsigned floating-point, 11 Red, 11 Green, 10 Blue Bits

enumerator F_rgb9_e5 = 43

enumerator F_rgb10_a2 = 44

enumerator F_rg = 45

enumerator F_r16i = 46

enumerator F_rg16i = 47

enumerator F_rgb16i = 48

not recommended

enumerator F_rgba16i = 49

enumerator F_rg32i = 50

enumerator F_rgb32i = 51

enumerator F_rgba32i = 52

enum QualityLevel

enumerator QL_default = 0

according to texture-quality-level

enumerator QL_fastest = 1

enumerator QL_normal = 2

enumerator QL_best = 3

enum TextureType

enumerator TT_1d_texture = 0

enumerator TT_2d_texture = 1

enumerator TT_3d_texture = 2

enumerator TT_2d_texture_array = 3

enumerator TT_cube_map = 4

enumerator TT_buffer_texture = 5

enumerator TT_cube_map_array = 6

enumerator TT_1d_texture_array = 7

__deepcopy__(memo: object) → Texture

__init__(name: str)

Constructs an empty texture. The default is to set up the texture as an empty 2-d texture; follow up with one of the variants of setupTexture() if this is not what you want.

property alpha_filename → Filename

Getter

Returns the alpha_filename that has been set. If this is set, it represents the name of the alpha component, which is stored in a separate file. See also getFilename(), and getAlphaFullpath().

Setter

Sets the name of the file that contains the image’s alpha channel contents. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

The Texture’s getFilename() function returns the name of the image file that was loaded into the buffer. In the case where a texture specified two separate files to load, a 1- or 3-channel color image and a 1-channel alpha image, the alpha_filename is updated to contain the name of the image file that was loaded into the buffer’s alpha channel.

property alpha_fullpath → Filename

Getter

Returns the alpha_fullpath that has been set. This is the full path to the alpha part of the image file as it was found along the texture search path.

Setter

Sets the full pathname to the file that contains the image’s alpha channel contents, as found along the search path. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

property anisotropic_degree → int

Getter

Returns the degree of anisotropic filtering that should be applied to the texture. This value may return 0, indicating the default value; see also getEffectiveAnisotropicDegree().

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

Setter

Specifies the level of anisotropic filtering to apply to the texture. Set this 0 to indicate the default value, which is specified in the texture- anisotropic-degree config variable.

To explicitly disable anisotropic filtering, set this value to 1. To explicitly enable anisotropic filtering, set it to a value higher than 1; larger numbers indicate greater degrees of filtering.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

property auto_texture_scale → AutoTextureScale

Returns/Specifies the power-of-2 texture-scaling mode that will be applied to this particular texture when it is next loaded from disk. See setTexturesPower2().

property aux_data → TypedReferenceCount

Getter

Returns a record previously recorded via setAuxData(). Returns NULL if there was no record associated with the indicated key.

Setter

Records an arbitrary object in the Texture, associated with a specified key. The object may later be retrieved by calling getAuxData() with the same key.

These data objects are not recorded to a bam or txo file.

property border_color → LColor

Returns/Specifies the solid color of the texture’s border. Some OpenGL implementations use a border for tiling textures; in Panda, it is only used for specifying the clamp color.

This returns/sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

property cacheable → bool

Returns true if there is enough information in this Texture object to write it to the bam cache successfully, false otherwise. For most textures, this is the same as hasRamImage().

clear()

Reinitializes the texture to its default, empty state (except for the name).

clearAlphaFilename()

Removes the alpha filename, if it was previously set. See setAlphaFilename().

clearAlphaFullpath()

Removes the alpha fullpath, if it was previously set. See setAlphaFullpath().

clearAuxData(key: str)

Removes a record previously recorded via setAuxData().

clearClearColor()

The opposite of setClearColor(). If the image is cleared after setting this, its contents may be undefined (or may in fact not be cleared at all).

clearFilename()

Removes the filename, if it was previously set. See setFilename().

clearFullpath()

Removes the fullpath, if it was previously set. See setFullpath().

clearImage()

Clears the texture data without changing its format or resolution. The texture is cleared on both the graphics hardware and from RAM, unlike clearRamImage(), which only removes the data from RAM.

If a clear color has been specified using setClearColor(), the texture will be cleared using a solid color.

The texture data will be cleared the first time in which the texture is used after this method is called.

clearRamImage()

Discards the current system-RAM image.

clearRamMipmapImage(n: int)

Discards the current system-RAM image for the nth mipmap level.

clearRamMipmapImages()

Discards the current system-RAM image for all mipmap levels, except level 0 (the base image).

clearSimpleRamImage()

Discards the current “simple” image.

property clear_color → LColor

Getter

Returns the color that was previously set using setClearColor().

Setter

Sets the color that will be used to fill the texture image in absence of any image data. It is used when any of the setupTexture() functions or clearImage() is called and image data is not provided using read() or modifyRamImage().

This does not affect a texture that has already been cleared; call clearImage() to clear it again.

property component_type → ComponentType

Getter

Returns the numeric interpretation of each component of the texture.

Setter

Changes the data value for the texture components. This implicitly sets component_width as well.

property component_width → int

Returns the number of bytes stored for each color component of a texel. Typically this is 1, but it may be 2 for 16-bit texels.

compressRamImage(compression: CompressionMode, quality_level: QualityLevel, gsg: GraphicsStateGuardianBase) → bool

Attempts to compress the texture’s RAM image internally, to a format supported by the indicated GSG. In order for this to work, the squish library must have been compiled into Panda.

If compression is CM_on, then an appropriate compression method that is supported by the indicated GSG is automatically chosen. If the GSG pointer is NULL, any of the standard DXT1/3/5 compression methods will be used, regardless of whether it is supported.

If compression is any specific compression method, that method is used regardless of whether the GSG supports it.

quality_level determines the speed/quality tradeoff of the compression. If it is QL_default, the texture’s own quality_level parameter is used.

Returns true if successful, false otherwise.

property compression → CompressionMode

Could maybe use hasCompression() here, too

Getter

Returns the compression mode requested for this particular texture, or CM_off if the texture is not to be compressed.

If a value other than CM_off is returned, this is not a guarantee that the texture is actually successfully compressed on the GSG. It may be that the GSG does not support the requested compression mode, in which case the texture may actually be stored uncompressed in texture memory.

Setter

Requests that this particular Texture be compressed when it is loaded into texture memory.

This refers to the internal compression of the texture image within texture memory; it is not related to jpeg or png compression, which are disk file compression formats. The actual disk file that generated this texture may be stored in a compressed or uncompressed format supported by Panda; it will be decompressed on load, and then recompressed by the graphics API if this parameter is not CM_off.

If the GSG does not support this texture compression mode, the texture will silently be loaded uncompressed.

considerRescale(pnmimage: PNMImage)

Asks the PNMImage to change its scale when it reads the image, according to the whims of the Config.prc file.

For most efficient results, this method should be called after pnmimage.read_header() has been called, but before pnmimage.read(). This method may also be called after pnmimage.read(), i.e. when the pnmimage is already loaded; in this case it will rescale the image on the spot. Also see rescaleTexture().

considerRescale(pnmimage: PNMImage, name: str, auto_texture_scale: AutoTextureScale)

Asks the PNMImage to change its scale when it reads the image, according to the whims of the Config.prc file.

For most efficient results, this method should be called after pnmimage.read_header() has been called, but before pnmimage.read(). This method may also be called after pnmimage.read(), i.e. when the pnmimage is already loaded; in this case it will rescale the image on the spot. Also see rescaleTexture().

property default_sampler → SamplerState

Getter

This returns the default sampler state for this texture, containing the wrap and filter properties specified on the texture level; it may still be overridden by a sampler state specified at a higher level.

Setter

This sets the default sampler state for this texture, containing the wrap and filter properties specified on the texture level; it may still be overridden by a sampler state specified at a higher level. This encompasses the settings for getWrapU(), getMinfilter(), getAnisotropicDegree(), etc.

This makes a copy of the SamplerState object, so future modifications of the same SamplerState will have no effect on this texture unless you call setDefaultSampler() again.

static downToPower2(value: int) → int

Returns the largest power of 2 less than or equal to value.

property effective_anisotropic_degree → int

Returns the degree of anisotropic filtering that should be applied to the texture. This value will normally not return 0, unless there is an error in the config file.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

property effective_magfilter → FilterType

Returns the filter mode of the texture for magnification, with special treatment for FT_default. This will normally not return FT_default, unless there is an error in the config file.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

property effective_minfilter → FilterType

Returns the filter mode of the texture for minification, with special treatment for FT_default. This will normally not return FT_default, unless there is an error in the config file.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

property effective_quality_level → QualityLevel

Returns the current quality_level hint, or the global default quality_level if this texture doesn’t specify a quality level. This value will not normally return QL_default (unless there is an error in the config file)

estimateTextureMemory() → int

Estimates the amount of texture memory that will be consumed by loading this texture. This returns a value that is not specific to any particular graphics card or driver; it tries to make a reasonable assumption about how a driver will load the texture. It does not account for texture compression or anything fancy. This is mainly useful for debugging and reporting purposes.

Returns a value in bytes.

property expected_num_mipmap_levels → int

Returns the number of mipmap levels that should be defined for this texture, given the texture’s size.

Note that this returns a number appropriate for mipmapping, even if the texture does not currently have mipmapping enabled.

property expected_ram_image_size → int

Returns the number of bytes that ought to be used by the in-memory image, based on the texture parameters.

property expected_ram_page_size → int

Returns the number of bytes that should be used per each Z page of the 3-d texture. For a 2-d or 1-d texture, this is the same as getExpectedRamImageSize().

property filename → Filename

Getter

Returns the filename that has been set. This is the name of the file as it was requested. Also see getFullpath().

Setter

Sets the name of the file that contains the image’s contents. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

The Texture’s getName() function used to return the filename, but now returns just the basename (without the extension), which is a more useful name for identifying an image in show code.

property format → Format

Getter

Returns the format of the texture, which represents both the semantic meaning of the texels and, to some extent, their storage information.

Setter

Changes the format value for the texture components. This implicitly sets num_components as well.

static formatComponentType(ct: ComponentType) → str

Returns the indicated ComponentType converted to a string word.

static formatCompressionMode(cm: CompressionMode) → str

Returns the indicated CompressionMode converted to a string word.

static formatFormat(f: Format) → str

Returns the indicated Format converted to a string word.

static formatQualityLevel(tql: QualityLevel) → str

Returns the indicated QualityLevel converted to a string word.

static formatTextureType(tt: TextureType) → str

Returns the indicated TextureType converted to a string word.

property fullpath → Filename

Getter

Returns the fullpath that has been set. This is the full path to the file as it was found along the texture search path.

Setter

Sets the full pathname to the file that contains the image’s contents, as found along the search path. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

generateAlphaScaleMap()

Generates a special 256x1 1-d texture that can be used to apply an arbitrary alpha scale to objects by judicious use of texture matrix. The texture is a gradient, with an alpha of 0 on the left (U = 0), and 255 on the right (U = 1).

generateNormalizationCubeMap(size: int)

Generates a special cube map image in the texture that can be used to apply bump mapping effects: for each texel in the cube map that is indexed by the 3-d texture coordinates (x, y, z), the resulting value is the normalized vector (x, y, z) (compressed from -1..1 into 0..1).

generateRamMipmapImages()

Automatically fills in the n mipmap levels of the Texture, based on the texture’s source image. This requires the texture’s uncompressed ram image to be available in system memory. If it is not already, it will be fetched if possible.

This call is not normally necessary, since the mipmap levels will be generated automatically if needed. But there may be certain cases in which you would like to call this explicitly.

generateSimpleRamImage()

Computes the “simple” ram image by loading the main RAM image, if it is not already available, and reducing it to 16x16 or smaller. This may be an expensive operation.

getActive(prepared_objects: PreparedGraphicsObjects) → bool

Returns true if this Texture was rendered in the most recent frame within the indicated GSG.

getAlphaFilename() → Filename

Returns the alpha_filename that has been set. If this is set, it represents the name of the alpha component, which is stored in a separate file. See also getFilename(), and getAlphaFullpath().

getAlphaFullpath() → Filename

Returns the alpha_fullpath that has been set. This is the full path to the alpha part of the image file as it was found along the texture search path.

getAnisotropicDegree() → int

Returns the degree of anisotropic filtering that should be applied to the texture. This value may return 0, indicating the default value; see also getEffectiveAnisotropicDegree().

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getAutoTextureScale() → AutoTextureScale

Returns the power-of-2 texture-scaling mode that will be applied to this particular texture when it is next loaded from disk. See setTexturesPower2().

getAuxData(key: str) → TypedReferenceCount

Returns a record previously recorded via setAuxData(). Returns NULL if there was no record associated with the indicated key.

getBorderColor() → LColor

Returns the solid color of the texture’s border. Some OpenGL implementations use a border for tiling textures; in Panda, it is only used for specifying the clamp color.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

static getClassType() → TypeHandle

getClearColor() → LColor

Returns the color that was previously set using setClearColor().

getClearData() → bytes

Returns the raw image data for a single pixel if it were set to the clear color.

getComponentType() → ComponentType

Returns the numeric interpretation of each component of the texture.

getComponentWidth() → int

Returns the number of bytes stored for each color component of a texel. Typically this is 1, but it may be 2 for 16-bit texels.

getCompression() → CompressionMode

Returns the compression mode requested for this particular texture, or CM_off if the texture is not to be compressed.

If a value other than CM_off is returned, this is not a guarantee that the texture is actually successfully compressed on the GSG. It may be that the GSG does not support the requested compression mode, in which case the texture may actually be stored uncompressed in texture memory.

getDataSizeBytes(prepared_objects: PreparedGraphicsObjects) → int

Returns the number of bytes which the texture is reported to consume within graphics memory, for the indicated GSG. This may return a nonzero value even if the texture is not currently resident; you should also check getResident() if you want to know how much space the texture is actually consuming right now.

getDefaultSampler() → SamplerState

This returns the default sampler state for this texture, containing the wrap and filter properties specified on the texture level; it may still be overridden by a sampler state specified at a higher level.

getEffectiveAnisotropicDegree() → int

Returns the degree of anisotropic filtering that should be applied to the texture. This value will normally not return 0, unless there is an error in the config file.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getEffectiveMagfilter() → FilterType

Returns the filter mode of the texture for magnification, with special treatment for FT_default. This will normally not return FT_default, unless there is an error in the config file.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getEffectiveMinfilter() → FilterType

Returns the filter mode of the texture for minification, with special treatment for FT_default. This will normally not return FT_default, unless there is an error in the config file.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getEffectiveQualityLevel() → QualityLevel

Returns the current quality_level hint, or the global default quality_level if this texture doesn’t specify a quality level. This value will not normally return QL_default (unless there is an error in the config file)

getExpectedMipmapNumPages(n: int) → int

Returns the total number of pages that the nth mipmap level should have, based on the texture’s size. This is usually the same as getExpectedMipmapZSize(), except for a multiview texture, in which case it is getExpectedMipmapZSize() * getNumViews().

getExpectedMipmapXSize(n: int) → int

Returns the x_size that the nth mipmap level should have, based on the texture’s size.

getExpectedMipmapYSize(n: int) → int

Returns the y_size that the nth mipmap level should have, based on the texture’s size.

getExpectedMipmapZSize(n: int) → int

Returns the z_size that the nth mipmap level should have, based on the texture’s size.

getExpectedNumMipmapLevels() → int

Returns the number of mipmap levels that should be defined for this texture, given the texture’s size.

Note that this returns a number appropriate for mipmapping, even if the texture does not currently have mipmapping enabled.

getExpectedRamImageSize() → int

Returns the number of bytes that ought to be used by the in-memory image, based on the texture parameters.

getExpectedRamMipmapImageSize(n: int) → int

Returns the number of bytes that ought to be used by the in-memory image for mipmap level n, based on the texture parameters.

getExpectedRamMipmapPageSize(n: int) → int

Returns the number of bytes that should be used per each Z page of the 3-d texture, for mipmap level n. For a 2-d or 1-d texture, this is the same as get_expected_ram_mipmap_view_size(n).

getExpectedRamMipmapViewSize(n: int) → int

Returns the number of bytes that ought to be used by each view of the in- memory image for mipmap level n, based on the texture parameters. For a normal, non-multiview texture, this is the same as get_expected_ram_mipmap_image_size(n).

getExpectedRamPageSize() → int

Returns the number of bytes that should be used per each Z page of the 3-d texture. For a 2-d or 1-d texture, this is the same as getExpectedRamImageSize().

getFilename() → Filename

Returns the filename that has been set. This is the name of the file as it was requested. Also see getFullpath().

getFormat() → Format

Returns the format of the texture, which represents both the semantic meaning of the texels and, to some extent, their storage information.

getFullpath() → Filename

Returns the fullpath that has been set. This is the full path to the file as it was found along the texture search path.

getImageModified() → UpdateSeq

Returns a sequence number which is guaranteed to change at least every time the texture image data (including mipmap levels) are modified.

getKeepRamImage() → bool

Returns the flag that indicates whether this Texture is eligible to have its main RAM copy of the texture memory dumped when the texture is prepared for rendering. See setKeepRamImage().

getLoadedFromImage() → bool

Returns the flag that indicates the texture has been loaded from a disk file or PNMImage. See setLoadedFromImage().

getLoadedFromTxo() → bool

Returns the flag that indicates the texture has been loaded from a txo file.

getMagfilter() → FilterType

Returns the filter mode of the texture for magnification. The mipmap constants are invalid here. This may return FT_default; see also getEffectiveMinfilter().

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getMatchFramebufferFormat() → bool

Returns true if the special flag was set that indicates to the GSG that the Texture’s format should be chosen to exactly match the framebuffer’s format, presumably because the application intends to copy image data from the framebuffer into the Texture (or vice-versa).

getMinfilter() → FilterType

Returns the filter mode of the texture for minification. If this is one of the mipmap constants, then the texture requires mipmaps. This may return FT_default; see also getEffectiveMinfilter().

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getNumComponents() → int

Returns the number of color components for each texel of the texture image. This is 3 for an rgb texture or 4 for an rgba texture; it may also be 1 or 2 for a grayscale texture.

getNumLoadableRamMipmapImages() → int

Returns the number of contiguous mipmap levels that exist in RAM, up until the first gap in the sequence. It is guaranteed that at least mipmap levels [0, getNumRamMipmapImages()) exist.

The number returned will never exceed the number of required mipmap images based on the size of the texture and its filter mode.

This method is different from getNumRamMipmapImages() in that it returns only the number of mipmap levels that can actually be usefully loaded, regardless of the actual number that may be stored.

getNumPages() → int

Returns the total number of pages in the texture. Each “page” is a 2-d texture image within the larger image–a face of a cube map, or a level of a 3-d texture. Normally, getNumPages() is the same as getZSize(). However, in a multiview texture, this returns getZSize() * getNumViews().

getNumRamMipmapImages() → int

Returns the maximum number of mipmap level images available in system memory. The actual number may be less than this (that is, there might be gaps in the sequence); use hasRamMipmapImage() to verify each level.

Also see getNumLoadableRamMipmapImages().

getNumViews() → int

Returns the number of “views” in the texture. A view is a completely separate image stored within the Texture object. Most textures have only one view, but a stereo texture, for instance, may have two views, a left and a right image. Other uses for multiple views are not yet defined.

If this value is greater than one, the additional views are accessed as additional pages beyond getZSize().

getOrigFileXSize() → int

Returns the X size of the original disk image that this Texture was loaded from (if it came from a disk file), before any automatic rescaling by Panda.

getOrigFileYSize() → int

Returns the Y size of the original disk image that this Texture was loaded from (if it came from a disk file), before any automatic rescaling by Panda.

getOrigFileZSize() → int

Returns the Z size of the original disk image that this Texture was loaded from (if it came from a disk file), before any automatic rescaling by Panda.

getPadXSize() → int

Returns size of the pad region. See setPadSize().

getPadYSize() → int

Returns size of the pad region. See setPadSize().

getPadZSize() → int

Returns size of the pad region. See setPadSize().

getPostLoadStoreCache() → bool

Returns the setting of the post_load_store_cache flag. See setPostLoadStoreCache().

getPropertiesModified() → UpdateSeq

Returns a sequence number which is guaranteed to change at least every time the texture properties (unrelated to the image) are modified.

getQualityLevel() → QualityLevel

Returns the current quality_level hint. See setQualityLevel(). This value may return QL_default; see getEffectiveQualityLevel().

getRamImage() → CPTA_uchar

Returns the system-RAM image data associated with the texture. If the texture does not currently have an associated RAM image, and the texture was generated by loading an image from a disk file (the most common case), this forces the reload of the same texture. This can happen if keep_texture_ram is configured to false, and we have previously prepared this texture with a GSG.

Note that it is not correct to call hasRamImage() first to test whether this function will fail. A false return value from hasRamImage() indicates only that getRamImage() may need to reload the texture from disk, which it will do automatically. However, you can call mightHaveRamImage(), which will return true if the ram image exists, or there is a reasonable reason to believe it can be loaded.

On the other hand, it is possible that the texture cannot be found on disk or is otherwise unavailable. If that happens, this function will return NULL. There is no way to predict with 100% accuracy whether getRamImage() will return NULL without calling it first; mightHaveRamImage() is the closest.

getRamImageAs(requested_format: str) → CPTA_uchar

Returns the uncompressed system-RAM image data associated with the texture. Rather than just returning a pointer to the data, like getUncompressedRamImage(), this function first processes the data and reorders the components using the specified format string, and places these into a new char array.

The ‘format’ argument should specify in which order the components of the texture must be. For example, valid format strings are “RGBA”, “GA”, “ABRG” or “AAA”. A component can also be written as “0” or “1”, which means an empty/black or a full/white channel, respectively.

This function is particularly useful to copy an image in-memory to a different library (for example, PIL or wxWidgets) that require a different component order than Panda’s internal format, BGRA. Note, however, that this conversion can still be too slow if you want to do it every frame, and should thus be avoided for that purpose.

The only requirement for the reordering is that an uncompressed image must be available. If the RAM image is compressed, it will attempt to re-load the texture from disk, if it doesn’t find an uncompressed image there, it will return NULL.

getRamImageCompression() → CompressionMode

Returns the compression mode in which the ram image is already stored pre- compressed. If this is other than CM_off, you cannot rely on the contents of the ram image to be anything predicatable (it will not be an array of x by y pixels, and it probably won’t have the same length as getExpectedRamImageSize()).

getRamImageSize() → int

Returns the total number of bytes used by the in-memory image, across all pages and views, or 0 if there is no in-memory image.

getRamMipmapImage(n: int) → CPTA_uchar

Returns the system-RAM image data associated with the nth mipmap level, if present. Returns NULL if the nth mipmap level is not present.

getRamMipmapImageSize(n: int) → int

Returns the number of bytes used by the in-memory image for mipmap level n, or 0 if there is no in-memory image for this mipmap level.

getRamMipmapPageSize(n: int) → int

Returns the number of bytes used by the in-memory image per page for mipmap level n, or 0 if there is no in-memory image for this mipmap level.

For a non-compressed texture, this is the same as getExpectedRamMipmapPageSize(). For a compressed texture, this may be a smaller value. (We do assume that all pages will be the same size on a compressed texture).

getRamMipmapPointer(n: int)

Similiar to getRamMipmapImage(), however, in this case the void pointer for the given ram image is returned. This will be NULL unless it has been explicitly set.

getRamMipmapViewSize(n: int) → int

Returns the number of bytes used by the in-memory image per view for mipmap level n, or 0 if there is no in-memory image for this mipmap level.

A “view” is a collection of z_size pages for each mipmap level. Most textures have only one view, except for multiview or stereo textures.

For a non-compressed texture, this is the same as getExpectedRamMipmapViewSize(). For a compressed texture, this may be a smaller value. (We do assume that all pages will be the same size on a compressed texture).

getRamPageSize() → int

Returns the number of bytes used by the in-memory image per page, or 0 if there is no in-memory image.

For a non-compressed texture, this is the same as getExpectedRamPageSize(). For a compressed texture, this may be a smaller value. (We do assume that all pages will be the same size on a compressed texture).

getRamViewSize() → int

Returns the number of bytes used by the in-memory image per view, or 0 if there is no in-memory image. Since each view is a stack of z_size pages, this is getZSize() * getRamPageSize().

getRenderToTexture() → bool

Returns a flag on the texture that indicates whether the texture is intended to be used as a direct-render target, by binding a framebuffer to a texture and rendering directly into the texture.

Normally, a user should not need to set this flag directly; it is set automatically by the low-level display code when a texture is bound to a framebuffer.

getResident(prepared_objects: PreparedGraphicsObjects) → bool

Returns true if this Texture is reported to be resident within graphics memory for the indicated GSG.

getSimpleImageModified() → UpdateSeq

Returns a sequence number which is guaranteed to change at least every time the texture’s “simple” image data is modified.

getSimpleRamImage() → CPTA_uchar

Returns the image data associated with the “simple” texture image. This is provided for some textures as an option to display while the main texture image is being loaded from disk.

Unlike getRamImage(), this function will always return immediately. Either the simple image is available, or it is not.

The “simple” image is always 4 components, 1 byte each, regardless of the parameters of the full texture. The simple image is only supported for ordinary 2-d textures.

getSimpleRamImageSize() → int

Returns the number of bytes used by the “simple” image, or 0 if there is no simple image.

getSimpleXSize() → int

Returns the width of the “simple” image in texels.

getSimpleYSize() → int

Returns the height of the “simple” image in texels.

getTexScale() → LVecBase2

Returns a scale pair that is suitable for applying to geometry via NodePath.setTexScale(), which will convert texture coordinates on the geometry from the range 0..1 into the appropriate range to render the video part of the texture.

This is necessary only if a padding size has been set via setPadSize() (or implicitly via something like “textures-power-2 pad” in the config.prc file). In this case, this is a convenient way to generate UV’s that reflect the built-in padding size.

getTextureType() → TextureType

Returns the overall interpretation of the texture.

static getTexturesPower2() → AutoTextureScale

This flag returns ATS_none, ATS_up, or ATS_down and controls the scaling of textures in general. It is initialized from the config variable of the same name, but it can be subsequently adjusted. See also getAutoTextureScale().

getUncompressedRamImage() → CPTA_uchar

Returns the system-RAM image associated with the texture, in an uncompressed form if at all possible.

If getRamImageCompression() is CM_off, then the system-RAM image is already uncompressed, and this returns the same thing as getRamImage().

If getRamImageCompression() is anything else, then the system-RAM image is compressed. In this case, the image will be reloaded from the original file (not from the cache), in the hopes that an uncompressed image will be found there.

If an uncompressed image cannot be found, returns NULL.

getUsageHint() → UsageHint

Returns the usage hint specified for buffer textures, or UH_unspecified for all other texture types.

getWrapU() → WrapMode

Returns the wrap mode of the texture in the U direction.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getWrapV() → WrapMode

Returns the wrap mode of the texture in the V direction.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getWrapW() → WrapMode

Returns the wrap mode of the texture in the W direction. This is the depth direction of 3-d textures.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

getXSize() → int

Returns the width of the texture image in texels.

getYSize() → int

Returns the height of the texture image in texels. For a 1-d texture, this will be 1.

getZSize() → int

Returns the depth of the texture image in texels. For a 1-d texture or 2-d texture, this will be 1. For a cube map texture, this will be 6.

hasAllRamMipmapImages() → bool

Returns true if all expected mipmap levels have been defined and exist in the system RAM, or false if even one mipmap level is missing.

hasAlphaFilename() → bool

Returns true if the alpha_filename has been set and is available. See setAlphaFilename().

hasAlphaFullpath() → bool

Returns true if the alpha_fullpath has been set and is available. See setAlphaFullpath().

hasAutoTextureScale() → bool

Returns true if setAutoTextureScale() has been set to something other than ATS_unspecified for this particular texture.

hasClearColor() → bool

Returns true if a color was previously set using setClearColor().

hasCompression() → bool

Returns true if the texture indicates it wants to be compressed, either with CM_on or higher, or CM_default and compressed-textures is true.

If true returned, this is not a guarantee that the texture is actually successfully compressed on the GSG. It may be that the GSG does not support the requested compression mode, in which case the texture may actually be stored uncompressed in texture memory.

hasFilename() → bool

Returns true if the filename has been set and is available. See setFilename().

hasFullpath() → bool

Returns true if the fullpath has been set and is available. See setFullpath().

hasRamImage() → bool

Returns true if the Texture has its image contents available in main RAM, false if it exists only in texture memory or in the prepared GSG context.

Note that this has nothing to do with whether getRamImage() will fail or not. Even if hasRamImage() returns false, getRamImage() may still return a valid RAM image, because getRamImage() will automatically load the texture from disk if necessary. The only thing hasRamImage() tells you is whether the texture is available right now without hitting the disk first.

Note also that if an application uses only one GSG, it may appear that hasRamImage() returns true if the texture has not yet been loaded by the GSG, but this correlation is not true in general and should not be depended on. Specifically, if an application ever uses multiple GSG’s in its lifetime (for instance, by opening more than one window, or by closing its window and opening another one later), then hasRamImage() may well return false on textures that have never been loaded on the current GSG.

hasRamMipmapImage(n: int) → bool

Returns true if the Texture has the nth mipmap level available in system memory, false otherwise. If the texture’s minfilter mode requires mipmapping (see usesMipmaps()), and all the texture’s mipmap levels are not available when the texture is rendered, they will be generated automatically.

hasSimpleRamImage() → bool

Returns true if the Texture has a “simple” image available in main RAM.

static hasTexturesPower2() → bool

If true, then getTexturesPower2() has been set using setTexturesPower2(). If false, then getTexturesPower2() simply returns the config variable of the same name.

hasUncompressedRamImage() → bool

Returns true if the Texture has its image contents available in main RAM and is uncompressed, false otherwise. See hasRamImage().

property image_modified → UpdateSeq

Returns a sequence number which is guaranteed to change at least every time the texture image data (including mipmap levels) are modified.

isCacheable() → bool

Returns true if there is enough information in this Texture object to write it to the bam cache successfully, false otherwise. For most textures, this is the same as hasRamImage().

isPrepared(prepared_objects: PreparedGraphicsObjects) → bool

Returns true if the texture has already been prepared or enqueued for preparation on the indicated GSG, false otherwise.

property keep_ram_image → bool

Getter

Returns the flag that indicates whether this Texture is eligible to have its main RAM copy of the texture memory dumped when the texture is prepared for rendering. See setKeepRamImage().

Setter

Sets the flag that indicates whether this Texture is eligible to have its main RAM copy of the texture memory dumped when the texture is prepared for rendering.

This will be false for most textures, which can reload their images if needed by rereading the input file. However, textures that were generated dynamically and cannot be easily reloaded will want to set this flag to true, so that the texture will always keep its image copy around.

load(pnmimage: PNMImage, options: LoaderOptions) → bool

Replaces the texture with the indicated image.

load(pnmimage: PNMImage, z: int, n: int, options: LoaderOptions) → bool

Stores the indicated image in the given page and mipmap level. See read().

load(pfm: PfmFile, options: LoaderOptions) → bool

Replaces the texture with the indicated image.

load(pfm: PfmFile, z: int, n: int, options: LoaderOptions) → bool

Stores the indicated image in the given page and mipmap level. See read().

loadRelated(suffix: InternalName) → Texture

Loads a texture whose filename is derived by concatenating a suffix to the filename of this texture. May return NULL, for example, if this texture doesn’t have a filename.

loadSubImage(pnmimage: PNMImage, x: int, y: int, z: int, n: int) → bool

Stores the indicated image in a region of the texture. The texture properties remain unchanged. This can be more efficient than updating an entire texture, but has a few restrictions: for one, you must ensure that the texture is still in RAM (eg. using setKeepRamImage()) and it may not be compressed.

property loaded_from_image → bool

Getter

Returns the flag that indicates the texture has been loaded from a disk file or PNMImage. See setLoadedFromImage().

Setter

Sets the flag that indicates the texture has been loaded from a disk file or PNMImage. You should also ensure the filename has been set correctly. When this flag is true, the texture may be automatically reloaded when its ram image needs to be replaced.

property loaded_from_txo → bool

Getter

Returns the flag that indicates the texture has been loaded from a txo file.

Setter

Sets the flag that indicates the texture has been loaded from a txo file. You probably shouldn’t be setting this directly; it is set automatically when a Texture is loaded.

property magfilter → FilterType

Getter

Returns the filter mode of the texture for magnification. The mipmap constants are invalid here. This may return FT_default; see also getEffectiveMinfilter().

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

Setter

Sets the filtering method that should be used when viewing the texture up close.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

makeCopy() → Texture

Returns a new copy of the same Texture. This copy, if applied to geometry, will be copied into texture as a separate texture from the original, so it will be duplicated in texture memory (and may be independently modified if desired).

If the Texture is a VideoTexture, the resulting duplicate may be animated independently of the original.

static makeFromTxo(in: istream, filename: str) → Texture

Constructs a new Texture object from the txo file. This is similar to Texture.readTxo(), but it constructs and returns a new object, which allows it to return a subclass of Texture (for instance, a movie texture).

Pass a real filename if it is available, or empty string if it is not.

makeRamImage() → PTA_uchar

Discards the current system-RAM image for the texture, if any, and allocates a new buffer of the appropriate size. Returns the new buffer.

This does not affect keep_ram_image.

makeRamMipmapImage(n: int) → PTA_uchar

Discards the current system-RAM image for the nth mipmap level, if any, and allocates a new buffer of the appropriate size. Returns the new buffer.

This does not affect keep_ram_image.

property match_framebuffer_format → bool

Getter

Returns true if the special flag was set that indicates to the GSG that the Texture’s format should be chosen to exactly match the framebuffer’s format, presumably because the application intends to copy image data from the framebuffer into the Texture (or vice-versa).

Setter

Sets the special flag that, if true, indicates to the GSG that the Texture’s format should be chosen to exactly match the framebuffer’s format, presumably because the application intends to copy image data from the framebuffer into the Texture (or vice-versa).

This sets only the graphics card’s idea of the texture format; it is not related to the system-memory format.

mightHaveRamImage() → bool

Returns true if the texture’s image contents are currently available in main RAM, or there is reason to believe it can be loaded on demand. That is, this function returns a “best guess” as to whether getRamImage() will succeed without actually calling it first.

property minfilter → FilterType

Getter

Returns the filter mode of the texture for minification. If this is one of the mipmap constants, then the texture requires mipmaps. This may return FT_default; see also getEffectiveMinfilter().

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

Setter

Sets the filtering method that should be used when viewing the texture from a distance.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

modifyRamImage() → PTA_uchar

Returns a modifiable pointer to the system-RAM image. This assumes the RAM image should be uncompressed. If the RAM image has been dumped, or is stored compressed, creates a new one.

This does not affect keep_ram_image.

modifyRamMipmapImage(n: int) → PTA_uchar

Returns a modifiable pointer to the system-RAM image for the nth mipmap level. This assumes the RAM image is uncompressed; if this is not the case, raises an assertion.

This does not affect keep_ram_image.

modifySimpleRamImage() → PTA_uchar

Returns a modifiable pointer to the internal “simple” texture image. See setSimpleRamImage().

newSimpleRamImage(x_size: int, y_size: int) → PTA_uchar

Creates an empty array for the simple ram image of the indicated size, and returns a modifiable pointer to the new array. See setSimpleRamImage().

property num_components → int

Returns the number of color components for each texel of the texture image. This is 3 for an rgb texture or 4 for an rgba texture; it may also be 1 or 2 for a grayscale texture.

property num_loadable_ram_mipmap_images → int

Returns the number of contiguous mipmap levels that exist in RAM, up until the first gap in the sequence. It is guaranteed that at least mipmap levels [0, getNumRamMipmapImages()) exist.

The number returned will never exceed the number of required mipmap images based on the size of the texture and its filter mode.

This method is different from getNumRamMipmapImages() in that it returns only the number of mipmap levels that can actually be usefully loaded, regardless of the actual number that may be stored.

property num_pages → int

Returns the total number of pages in the texture. Each “page” is a 2-d texture image within the larger image–a face of a cube map, or a level of a 3-d texture. Normally, getNumPages() is the same as getZSize(). However, in a multiview texture, this returns getZSize() * getNumViews().

property num_ram_mipmap_images → int

Returns the maximum number of mipmap level images available in system memory. The actual number may be less than this (that is, there might be gaps in the sequence); use hasRamMipmapImage() to verify each level.

Also see getNumLoadableRamMipmapImages().

property num_views → int

Getter

Returns the number of “views” in the texture. A view is a completely separate image stored within the Texture object. Most textures have only one view, but a stereo texture, for instance, may have two views, a left and a right image. Other uses for multiple views are not yet defined.

If this value is greater than one, the additional views are accessed as additional pages beyond getZSize().

Setter

Sets the number of “views” within a texture. A view is a completely separate image stored within the Texture object. Most textures have only one view, but a stereo texture, for instance, may have two views, a left and a right image. Other uses for multiple views are not yet defined.

If this value is greater than one, the additional views are accessed as additional pages beyond getZSize().

This also implicitly unloads the texture if it has already been loaded.

property orig_file_x_size → int

Returns the X size of the original disk image that this Texture was loaded from (if it came from a disk file), before any automatic rescaling by Panda.

property orig_file_y_size → int

Returns the Y size of the original disk image that this Texture was loaded from (if it came from a disk file), before any automatic rescaling by Panda.

property orig_file_z_size → int

Returns the Z size of the original disk image that this Texture was loaded from (if it came from a disk file), before any automatic rescaling by Panda.

peek() → TexturePeeker

Returns a TexturePeeker object that can be used to examine the individual texels stored within this Texture by (u, v) coordinate.

If the texture has a ram image resident, that image is used. If it does not have a full ram image but does have a simple_ram_image resident, that image is used instead. If neither image is resident the full image is reloaded.

Returns NULL if the texture cannot find an image to load, or the texture format is incompatible.

property post_load_store_cache → bool

Getter

Returns the setting of the post_load_store_cache flag. See setPostLoadStoreCache().

Setter

Sets the post_load_store_cache flag. When this is set, the next time the texture is loaded on a GSG, it will automatically extract its RAM image from the GSG and save it to the global BamCache.

This is used to store compressed RAM images in the BamCache. This flag should not be set explicitly; it is set automatically by the TexturePool when model-cache-compressed-textures is set true.

prepare(prepared_objects: PreparedGraphicsObjects) → AsyncFuture

Indicates that the texture should be enqueued to be prepared in the indicated prepared_objects at the beginning of the next frame. This will ensure the texture is already loaded into texture memory if it is expected to be rendered soon.

Use this function instead of prepareNow() to preload textures from a user interface standpoint.

prepareNow(view: int, prepared_objects: PreparedGraphicsObjects, gsg: GraphicsStateGuardianBase) → TextureContext

Creates a context for the texture on the particular GSG, if it does not already exist. Returns the new (or old) TextureContext. This assumes that the GraphicsStateGuardian is the currently active rendering context and that it is ready to accept new textures. If this is not necessarily the case, you should use prepare() instead.

Normally, this is not called directly except by the GraphicsStateGuardian; a texture does not need to be explicitly prepared by the user before it may be rendered.

property properties_modified → UpdateSeq

Returns a sequence number which is guaranteed to change at least every time the texture properties (unrelated to the image) are modified.

property quality_level → QualityLevel

Getter

Returns the current quality_level hint. See setQualityLevel(). This value may return QL_default; see getEffectiveQualityLevel().

Setter

Sets a hint to the renderer about the desired performance / quality tradeoff for this particular texture. This is most useful for the tinydisplay software renderer; for normal, hardware-accelerated renderers, this may have little or no effect.

property ram_image_compression → CompressionMode

Returns the compression mode in which the ram image is already stored pre- compressed. If this is other than CM_off, you cannot rely on the contents of the ram image to be anything predicatable (it will not be an array of x by y pixels, and it probably won’t have the same length as getExpectedRamImageSize()).

property ram_image_size → int

Returns the total number of bytes used by the in-memory image, across all pages and views, or 0 if there is no in-memory image.

property ram_page_size → int

Returns the number of bytes used by the in-memory image per page, or 0 if there is no in-memory image.

For a non-compressed texture, this is the same as getExpectedRamPageSize(). For a compressed texture, this may be a smaller value. (We do assume that all pages will be the same size on a compressed texture).

property ram_view_size → int

Returns the number of bytes used by the in-memory image per view, or 0 if there is no in-memory image. Since each view is a stack of z_size pages, this is getZSize() * getRamPageSize().

read(fullpath: Filename, alpha_fullpath: Filename, primary_file_num_channels: int, alpha_file_channel: int, options: LoaderOptions) → bool

Combine a 3-component image with a grayscale image to get a 4-component image.

See the description of the full-parameter read() method for the meaning of the primary_file_num_channels and alpha_file_channel parameters.

read(fullpath: Filename, alpha_fullpath: Filename, primary_file_num_channels: int, alpha_file_channel: int, z: int, n: int, read_pages: bool, read_mipmaps: bool, record: BamCacheRecord, options: LoaderOptions) → bool

Reads the texture from the indicated filename. If primary_file_num_channels is not 0, it specifies the number of components to downgrade the image to if it is greater than this number.

If the filename has the extension .txo, this implicitly reads a texture object instead of a filename (which replaces all of the texture properties). In this case, all the rest of the parameters are ignored, and the filename should not contain any hash marks; just the one named file will be read, since a single .txo file can contain all pages and mipmaps necessary to define a texture.

If alpha_fullpath is not empty, it specifies the name of a file from which to retrieve the alpha. In this case, alpha_file_channel represents the numeric channel of this image file to use as the resulting texture’s alpha channel; usually, this is 0 to indicate the grayscale combination of r, g, b; or it may be a one-based channel number, e.g. 1 for the red channel, 2 for the green channel, and so on.

If read pages is false, then z indicates the page number into which this image will be assigned. Normally this is 0 for the first (or only) page of the texture. 3-D textures have one page for each level of depth, and cube map textures always have six pages.

If read_pages is true, multiple images will be read at once, one for each page of a cube map or a 3-D texture. In this case, the filename should contain a sequence of one or more hash marks (“#”) which will be filled in with the z value of each page, zero-based. In this case, the z parameter indicates the maximum z value that will be loaded, or 0 to load all filenames that exist.

If read_mipmaps is false, then n indicates the mipmap level to which this image will be assigned. Normally this is 0 for the base texture image, but it is possible to load custom mipmap levels into the later images. After the base texture image is loaded (thus defining the size of the texture), you can call getExpectedNumMipmapLevels() to determine the maximum sensible value for n.

If read_mipmaps is true, multiple images will be read as above, but this time the images represent the different mipmap levels of the texture image. In this case, the n parameter indicates the maximum n value that will be loaded, or 0 to load all filenames that exist (up to the expected number of mipmap levels).

If both read_pages and read_mipmaps is true, then both sequences will be read; the filename should contain two sequences of hash marks, separated by some character such as a hyphen, underscore, or dot. The first hash mark sequence will be filled in with the mipmap level, while the second hash mark sequence will be the page index.

This method implicitly sets keep_ram_image to false.

read(fullpath: Filename, options: LoaderOptions) → bool

Reads the named filename into the texture.

read(fullpath: Filename, z: int, n: int, read_pages: bool, read_mipmaps: bool, options: LoaderOptions) → bool

Reads a single file into a single page or mipmap level, or automatically reads a series of files into a series of pages and/or mipmap levels.

See the description of the full-parameter read() method for the meaning of the various parameters.

readDds(in: istream, filename: str, header_only: bool) → bool

Reads the texture from a DDS file object. This is a Microsoft-defined file format; it is similar in principle to a txo object, in that it is designed to contain the texture image in a form as similar as possible to its runtime image, and it can contain mipmaps, pre-compressed textures, and so on.

As with readTxo(), the filename is just for reference.

readKtx(in: istream, filename: str, header_only: bool) → bool

Reads the texture from a KTX file object. This is a Khronos-defined file format; it is similar in principle to a dds object, in that it is designed to contain the texture image in a form as similar as possible to its runtime image, and it can contain mipmaps, pre-compressed textures, and so on.

As with readDds(), the filename is just for reference.

readTxo(in: istream, filename: str) → bool

Reads the texture from a Panda texture object. This defines the complete Texture specification, including the image data as well as all texture properties. This only works if the txo file contains a static Texture image, as opposed to a subclass of Texture such as a movie texture.

Pass a real filename if it is available, or empty string if it is not.

release(prepared_objects: PreparedGraphicsObjects) → bool

Frees the texture context only on the indicated object, if it exists there. Returns true if it was released, false if it had not been prepared.

releaseAll() → int

Frees the context allocated on all objects for which the texture has been declared. Returns the number of contexts which have been freed.

reload() → bool

Re-reads the Texture from its disk file. Useful when you know the image on disk has recently changed, and you want to update the Texture image.

Returns true on success, false on failure (in which case, the Texture may or may not still be valid).

property render_to_texture → bool

Getter

Returns a flag on the texture that indicates whether the texture is intended to be used as a direct-render target, by binding a framebuffer to a texture and rendering directly into the texture.

Normally, a user should not need to set this flag directly; it is set automatically by the low-level display code when a texture is bound to a framebuffer.

Setter

Sets a flag on the texture that indicates whether the texture is intended to be used as a direct-render target, by binding a framebuffer to a texture and rendering directly into the texture.

This controls some low-level choices made about the texture object itself. For instance, compressed textures are disallowed when this flag is set true.

Normally, a user should not need to set this flag directly; it is set automatically by the low-level display code when a texture is bound to a framebuffer.

rescaleTexture() → bool

This method is similar to considerRescale(), but instead of scaling a separate PNMImage, it will ask the Texture to rescale its own internal image to a power of 2, according to the config file requirements. This may be useful after loading a Texture image by hand, instead of reading it from a disk file. Returns true if the texture is changed, false if it was not.

setAlphaFilename(alpha_filename: Filename)

Sets the name of the file that contains the image’s alpha channel contents. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

The Texture’s getFilename() function returns the name of the image file that was loaded into the buffer. In the case where a texture specified two separate files to load, a 1- or 3-channel color image and a 1-channel alpha image, the alpha_filename is updated to contain the name of the image file that was loaded into the buffer’s alpha channel.

setAlphaFullpath(alpha_fullpath: Filename)

Sets the full pathname to the file that contains the image’s alpha channel contents, as found along the search path. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

setAnisotropicDegree(anisotropic_degree: int)

Specifies the level of anisotropic filtering to apply to the texture. Set this 0 to indicate the default value, which is specified in the texture- anisotropic-degree config variable.

To explicitly disable anisotropic filtering, set this value to 1. To explicitly enable anisotropic filtering, set it to a value higher than 1; larger numbers indicate greater degrees of filtering.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

setAutoTextureScale(scale: AutoTextureScale)

Specifies the power-of-2 texture-scaling mode that will be applied to this particular texture when it is next loaded from disk. See setTexturesPower2().

setAuxData(key: str, aux_data: TypedReferenceCount)

Records an arbitrary object in the Texture, associated with a specified key. The object may later be retrieved by calling getAuxData() with the same key.

These data objects are not recorded to a bam or txo file.

setBorderColor(color: LColor)

Specifies the solid color of the texture’s border. Some OpenGL implementations use a border for tiling textures; in Panda, it is only used for specifying the clamp color.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

setClearColor(color: LColor)

Sets the color that will be used to fill the texture image in absence of any image data. It is used when any of the setupTexture() functions or clearImage() is called and image data is not provided using read() or modifyRamImage().

This does not affect a texture that has already been cleared; call clearImage() to clear it again.

setComponentType(component_type: ComponentType)

Changes the data value for the texture components. This implicitly sets component_width as well.

setCompression(compression: CompressionMode)

Requests that this particular Texture be compressed when it is loaded into texture memory.

This refers to the internal compression of the texture image within texture memory; it is not related to jpeg or png compression, which are disk file compression formats. The actual disk file that generated this texture may be stored in a compressed or uncompressed format supported by Panda; it will be decompressed on load, and then recompressed by the graphics API if this parameter is not CM_off.

If the GSG does not support this texture compression mode, the texture will silently be loaded uncompressed.

setDefaultSampler(sampler: SamplerState)

This sets the default sampler state for this texture, containing the wrap and filter properties specified on the texture level; it may still be overridden by a sampler state specified at a higher level. This encompasses the settings for getWrapU(), getMinfilter(), getAnisotropicDegree(), etc.

This makes a copy of the SamplerState object, so future modifications of the same SamplerState will have no effect on this texture unless you call setDefaultSampler() again.

setFilename(filename: Filename)

Sets the name of the file that contains the image’s contents. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

The Texture’s getName() function used to return the filename, but now returns just the basename (without the extension), which is a more useful name for identifying an image in show code.

setFormat(format: Format)

Changes the format value for the texture components. This implicitly sets num_components as well.

setFullpath(fullpath: Filename)

Sets the full pathname to the file that contains the image’s contents, as found along the search path. Normally, this is set automatically when the image is loaded, for instance via Texture.read().

setKeepRamImage(keep_ram_image: bool)

Sets the flag that indicates whether this Texture is eligible to have its main RAM copy of the texture memory dumped when the texture is prepared for rendering.

This will be false for most textures, which can reload their images if needed by rereading the input file. However, textures that were generated dynamically and cannot be easily reloaded will want to set this flag to true, so that the texture will always keep its image copy around.

setLoadedFromImage(flag: bool)

Sets the flag that indicates the texture has been loaded from a disk file or PNMImage. You should also ensure the filename has been set correctly. When this flag is true, the texture may be automatically reloaded when its ram image needs to be replaced.

setLoadedFromTxo(flag: bool)

Sets the flag that indicates the texture has been loaded from a txo file. You probably shouldn’t be setting this directly; it is set automatically when a Texture is loaded.

setMagfilter(filter: FilterType)

setMatchFramebufferFormat(flag: bool)

Sets the special flag that, if true, indicates to the GSG that the Texture’s format should be chosen to exactly match the framebuffer’s format, presumably because the application intends to copy image data from the framebuffer into the Texture (or vice-versa).

This sets only the graphics card’s idea of the texture format; it is not related to the system-memory format.

setMinfilter(filter: FilterType)

setNumViews(num_views: int)

Sets the number of “views” within a texture. A view is a completely separate image stored within the Texture object. Most textures have only one view, but a stereo texture, for instance, may have two views, a left and a right image. Other uses for multiple views are not yet defined.

If this value is greater than one, the additional views are accessed as additional pages beyond getZSize().

This also implicitly unloads the texture if it has already been loaded.

setOrigFileSize(x: int, y: int, z: int)

Specifies the size of the texture as it exists in its original disk file, before any Panda scaling.

setPadSize(x: int, y: int, z: int)

Sets the size of the pad region.

Sometimes, when a video card demands power-of-two textures, it is necessary to create a big texture and then only use a portion of it. The pad region indicates which portion of the texture is not really in use. All operations use the texture as a whole, including the pad region, unless they explicitly state that they use only the non-pad region.

Changing the texture’s size clears the pad region.

setPostLoadStoreCache(flag: bool)

Sets the post_load_store_cache flag. When this is set, the next time the texture is loaded on a GSG, it will automatically extract its RAM image from the GSG and save it to the global BamCache.

This is used to store compressed RAM images in the BamCache. This flag should not be set explicitly; it is set automatically by the TexturePool when model-cache-compressed-textures is set true.

setQualityLevel(quality_level: QualityLevel)

Sets a hint to the renderer about the desired performance / quality tradeoff for this particular texture. This is most useful for the tinydisplay software renderer; for normal, hardware-accelerated renderers, this may have little or no effect.

setRamImage(image: object, compression: CompressionMode, page_size: int)

setRamImageAs(image: object, provided_format: str)

setRamMipmapImage(n: int, image: CPTA_uchar, page_size: int)

Replaces the current system-RAM image for the indicated mipmap level with the new data. If compression is not CM_off, it indicates that the new data is already pre-compressed in the indicated format.

This does not affect keep_ram_image.

setRamMipmapPointerFromInt(pointer: int, n: int, page_size: int)

Accepts a raw pointer cast as an int, which is then passed to setRamMipmapPointer(); see the documentation for that method.

This variant is particularly useful to set an external pointer from a language like Python, which doesn’t support void pointers directly.

setRenderToTexture(render_to_texture: bool)

Sets a flag on the texture that indicates whether the texture is intended to be used as a direct-render target, by binding a framebuffer to a texture and rendering directly into the texture.

This controls some low-level choices made about the texture object itself. For instance, compressed textures are disallowed when this flag is set true.

Normally, a user should not need to set this flag directly; it is set automatically by the low-level display code when a texture is bound to a framebuffer.

setSimpleRamImage(image: CPTA_uchar, x_size: int, y_size: int)

Replaces the internal “simple” texture image. This can be used as an option to display while the main texture image is being loaded from disk. It is normally a very small image, 16x16 or smaller (and maybe even 1x1), that is designed to give just enough sense of color to serve as a placeholder until the full texture is available.

The “simple” image is always 4 components, 1 byte each, regardless of the parameters of the full texture. The simple image is only supported for ordinary 2-d textures.

Also see generateSimpleRamImage(), modifySimpleRamImage(), and newSimpleRamImage().

setSizePadded(x: int, y: int, z: int)

Changes the size of the texture, padding if necessary, and setting the pad region as well.

static setTexturesPower2(scale: AutoTextureScale)

Set this flag to ATS_none, ATS_up, ATS_down, or ATS_pad to control the scaling of textures in general, if a particular texture does not override this. See also setAutoTextureScale() for the per-texture override.

setWrapU(wrap: WrapMode)

setWrapV(wrap: WrapMode)

setWrapW(wrap: WrapMode)

setXSize(x_size: int)

Changes the x size indicated for the texture. This also implicitly unloads the texture if it has already been loaded.

setYSize(y_size: int)

Changes the y size indicated for the texture. This also implicitly unloads the texture if it has already been loaded.

setZSize(z_size: int)

Changes the z size indicated for the texture. This also implicitly unloads the texture if it has already been loaded.

setup1dTexture()

Sets the texture as an empty 1-d texture with no dimensions. Follow up with read() or load() to fill the texture properties and image data, or use setClearColor() to let the texture be cleared to a solid color.

setup1dTexture(x_size: int, component_type: ComponentType, format: Format)

Sets the texture as an empty 1-d texture with the specified dimensions and properties. Follow up with setRamImage() or modifyRamImage() to fill the image data, or use setClearColor() to let the texture be cleared to a solid color.

setup2dTexture()

Sets the texture as an empty 2-d texture with no dimensions. Follow up with read() or load() to fill the texture properties and image data, or use setClearColor() to let the texture be cleared to a solid color.

setup2dTexture(x_size: int, y_size: int, component_type: ComponentType, format: Format)

Sets the texture as an empty 2-d texture with the specified dimensions and properties. Follow up with setRamImage() or modifyRamImage() to fill the image data, or use setClearColor() to let the texture be cleared to a solid color.

setup2dTextureArray(z_size: int)

Sets the texture as an empty 2-d texture array with no dimensions (though if you know the depth ahead of time, it saves a bit of reallocation later). Follow up with read() or load() to fill the texture properties and image data, or use setClearColor() to let the texture be cleared to a solid color.

setup2dTextureArray(x_size: int, y_size: int, z_size: int, component_type: ComponentType, format: Format)

Sets the texture as an empty 2-d texture array with the specified dimensions and properties. Follow up with setRamImage() or modifyRamImage() to fill the image data, or use setClearColor() to let the texture be cleared to a solid color.

setup3dTexture(z_size: int)

Sets the texture as an empty 3-d texture with no dimensions (though if you know the depth ahead of time, it saves a bit of reallocation later). Follow up with read() or load() to fill the texture properties and image data, or use setClearColor() to let the texture be cleared to a solid color.

setup3dTexture(x_size: int, y_size: int, z_size: int, component_type: ComponentType, format: Format)

Sets the texture as an empty 3-d texture with the specified dimensions and properties. Follow up with setRamImage() or modifyRamImage() to fill the image data.

setupBufferTexture(size: int, component_type: ComponentType, format: Format, usage: UsageHint)

Sets the texture as an empty buffer texture with the specified size and properties. Follow up with setRamImage() or modifyRamImage() to fill the image data, or use setClearColor() to let the texture be cleared to a solid color.

Note that a buffer texture’s format needs to match the component type.

setupCubeMap()

Sets the texture as an empty cube map texture with no dimensions. Follow up with read() or load() to fill the texture properties and image data, or use setClearColor() to let the texture be cleared to a solid color.

setupCubeMap(size: int, component_type: ComponentType, format: Format)

Sets the texture as an empty cube map texture with the specified dimensions and properties. Follow up with setRamImage() or modifyRamImage() to fill the image data, or use setClearColor() to let the texture be cleared to a solid color.

Note that a cube map should always consist of six square images, so x_size and y_size will be the same, and z_size is always 6.

setupCubeMapArray(num_cube_maps: int)

Sets the texture as cube map array with N cube maps. Note that this number is not the same as the z_size. Follow up with read() or load() to fill the texture properties and image data, or use setClearColor() to let the texture be cleared to a solid color.

New in version 1.10.0.

setupCubeMapArray(size: int, num_cube_maps: int, component_type: ComponentType, format: Format)

Sets the texture as cube map array with N cube maps with the specified dimensions and format. Follow up with setRamImage() or modifyRamImage() to fill the image data, or use setClearColor() to let the texture be cleared to a solid color.

The num_cube_maps given here is multiplied by six to become the z_size of the image.

New in version 1.10.0.

setupTexture(texture_type: TextureType, x_size: int, y_size: int, z_size: int, component_type: ComponentType, format: Format)

Sets the texture to the indicated type and dimensions, presumably in preparation for calling read() or load(), or setRamImage() or modifyRamImage(), or use setClearColor() to let the texture be cleared to a solid color.

property simple_image_modified → UpdateSeq

Returns a sequence number which is guaranteed to change at least every time the texture’s “simple” image data is modified.

property simple_ram_image → CPTA_uchar

Returns the image data associated with the “simple” texture image. This is provided for some textures as an option to display while the main texture image is being loaded from disk.

Unlike getRamImage(), this function will always return immediately. Either the simple image is available, or it is not.

The “simple” image is always 4 components, 1 byte each, regardless of the parameters of the full texture. The simple image is only supported for ordinary 2-d textures.

property simple_x_size → int

Returns the width of the “simple” image in texels.

property simple_y_size → int

Returns the height of the “simple” image in texels.

store(pnmimage: PNMImage) → bool

Saves the texture to the indicated PNMImage, but does not write it to disk.

store(pnmimage: PNMImage, z: int, n: int) → bool

Saves the indicated page and mipmap level of the texture to the PNMImage.

store(pfm: PfmFile) → bool

Saves the texture to the indicated PfmFile, but does not write it to disk.

store(pfm: PfmFile, z: int, n: int) → bool

Saves the indicated page and mipmap level of the texture to the PfmFile.

static stringComponentType(str: str) → ComponentType

Returns the ComponentType corresponding to the indicated string word.

static stringCompressionMode(str: str) → CompressionMode

Returns the CompressionMode value associated with the given string representation.

static stringFormat(str: str) → Format

Returns the Format corresponding to the indicated string word.

static stringQualityLevel(str: str) → QualityLevel

Returns the QualityLevel value associated with the given string representation.

static stringTextureType(str: str) → TextureType

Returns the TextureType corresponding to the indicated string word.

property texture_type → TextureType

Returns the overall interpretation of the texture.

uncompressRamImage() → bool

Attempts to uncompress the texture’s RAM image internally. In order for this to work, the squish library must have been compiled into Panda, and the ram image must be compressed in a format supported by squish.

Returns true if successful, false otherwise.

static upToPower2(value: int) → int

Returns the smallest power of 2 greater than or equal to value.

property usage_hint → UsageHint

Returns the usage hint specified for buffer textures, or UH_unspecified for all other texture types.

usesMipmaps() → bool

Returns true if the minfilter settings on this texture indicate the use of mipmapping, false otherwise.

wasImageModified(prepared_objects: PreparedGraphicsObjects) → bool

Returns true if the texture needs to be re-loaded onto the indicated GSG, either because its image data is out-of-date, or because it’s not fully prepared now.

property wrap_u → WrapMode

Getter

Returns the wrap mode of the texture in the U direction.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

Setter

This setting determines what happens when the texture is sampled with a U value outside the range 0.0-1.0. The default is WM_repeat, which indicates that the texture should repeat indefinitely.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

property wrap_v → WrapMode

Getter

Returns the wrap mode of the texture in the V direction.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

Setter

This setting determines what happens when the texture is sampled with a V value outside the range 0.0-1.0. The default is WM_repeat, which indicates that the texture should repeat indefinitely.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

property wrap_w → WrapMode

Getter

Returns the wrap mode of the texture in the W direction. This is the depth direction of 3-d textures.

This returns the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

Setter

The W wrap direction is only used for 3-d textures.

This sets the default sampler state for this texture; it may still be overridden by a sampler state specified at a higher level.

write(fullpath: Filename) → bool

Writes the texture to the named filename.

write(fullpath: Filename, z: int, n: int, write_pages: bool, write_mipmaps: bool) → bool

Writes a single page or mipmap level to a single file, or automatically writes a series of pages and/or mipmap levels to a numbered series of files.

If the filename ends in the extension .txo, this implicitly writes a Panda texture object (.txo) instead of an image file. In this case, the remaining parameters are ignored, and only one file is written, which will contain all of the pages and resident mipmap levels in the texture.

If write_pages is false, then z indicates the page number to write. 3-D textures have one page number for each level of depth; cube maps have six pages number 0 through 5. Other kinds of textures have only one page, numbered 0. If there are multiple views, the range of z is increased; the total range is [0, getNumPages()).

If write_pages is true, then all pages of the texture will be written. In this case z is ignored, and the filename should contain a sequence of hash marks (“#”) which will be filled in with the page index number.

If write_mipmaps is false, then n indicates the mipmap level number to write. Normally, this is 0, for the base texture image. Normally, the mipmap levels of a texture are not available in RAM (they are generated automatically by the graphics card). However, if you have the mipmap levels available, for instance because you called generateRamMipmapImages() to generate them internally, or you called GraphicsEngine.extractTextureData() to retrieve them from the graphics card, then you may write out each mipmap level with this parameter.

If write_mipmaps is true, then all mipmap levels of the texture will be written. In this case n is ignored, and the filename should contain a sequence of hash marks (“#”) which will be filled in with the mipmap level number.

If both write_pages and write_mipmaps is true, then all pages and all mipmap levels will be written. In this case, the filename should contain two different sequences of hash marks, separated by a character such as a hyphen, underscore, or dot. The first hash mark sequence will be filled in with the mipmap level, while the second hash mark sequence will be the page index.

write(out: ostream, indent_level: int)

Not to be confused with write(Filename), this method simply describes the texture properties.

writeTxo(out: ostream, filename: str) → bool

Writes the texture to a Panda texture object. This defines the complete Texture specification, including the image data as well as all texture properties.

The filename is just for reference.

property x_size → int

Getter

Returns the width of the texture image in texels.

Setter

Changes the x size indicated for the texture. This also implicitly unloads the texture if it has already been loaded.

property y_size → int

Getter

Returns the height of the texture image in texels. For a 1-d texture, this will be 1.

Setter

Changes the y size indicated for the texture. This also implicitly unloads the texture if it has already been loaded.

property z_size → int

Getter

Returns the depth of the texture image in texels. For a 1-d texture or 2-d texture, this will be 1. For a cube map texture, this will be 6.

Setter

Changes the z size indicated for the texture. This also implicitly unloads the texture if it has already been loaded.