Panda3D
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
SamplerState Class Reference

Represents a set of settings that indicate how a texture is sampled. More...

Public Types

enum  FilterType {
  FT_nearest = 0, FT_linear = 1, FT_nearest_mipmap_nearest = 2, FT_linear_mipmap_nearest = 3,
  FT_nearest_mipmap_linear = 4, FT_linear_mipmap_linear = 5, FT_shadow = 6, FT_default = 7,
  FT_invalid = 8
}
 
enum  WrapMode {
  WM_clamp = 0, WM_repeat = 1, WM_mirror = 2, WM_mirror_once = 3,
  WM_border_color = 4, WM_invalid = 5
}
 

Public Member Functions

 __init__ ()
 Creates a new SamplerState initialized to the default values. More...
 
 __init__ (const SamplerState)
 
int getAnisotropicDegree ()
 Returns the degree of anisotropic filtering that should be applied to the texture. More...
 
const LColor getBorderColor ()
 Returns the solid color of the texture's border. More...
 
int getEffectiveAnisotropicDegree ()
 Returns the degree of anisotropic filtering that should be applied to the texture. More...
 
SamplerState::FilterType getEffectiveMagfilter ()
 Returns the filter mode of the texture for magnification, with special treatment for FT_default. More...
 
SamplerState::FilterType getEffectiveMinfilter ()
 Returns the filter mode of the texture for minification, with special treatment for FT_default. More...
 
float getLodBias ()
 Returns the bias that will be added to the texture level of detail when sampling this texture. More...
 
SamplerState::FilterType getMagfilter ()
 Returns the filter mode of the texture for magnification. More...
 
float getMaxLod ()
 Returns the maximum level of detail that will be observed when sampling this texture. More...
 
SamplerState::FilterType getMinfilter ()
 Returns the filter mode of the texture for minification. More...
 
float getMinLod ()
 Returns the minimum level of detail that will be observed when sampling this texture. More...
 
SamplerState::WrapMode getWrapU ()
 Returns the wrap mode of the texture in the U direction. More...
 
SamplerState::WrapMode getWrapV ()
 Returns the wrap mode of the texture in the V direction. More...
 
SamplerState::WrapMode getWrapW ()
 Returns the wrap mode of the texture in the W direction. More...
 
bool isPrepared (PreparedGraphicsObjects prepared_objects)
 Returns true if the sampler has already been prepared or enqueued for preparation on the indicated GSG, false otherwise. More...
 
bool operator != (const SamplerState other)
 
bool operator< (const SamplerState other)
 
bool operator== (const SamplerState other)
 
 prepare (PreparedGraphicsObjects prepared_objects)
 Indicates that the sampler should be enqueued to be prepared in the indicated prepared_objects at the beginning of the next frame. More...
 
SamplerContext prepareNow (PreparedGraphicsObjects prepared_objects, GraphicsStateGuardianBase gsg)
 Creates a context for the sampler on the particular GSG, if it does not already exist. More...
 
 release (PreparedGraphicsObjects prepared_objects)
 Frees the texture context only on the indicated object, if it exists there. More...
 
 setAnisotropicDegree (int anisotropic_degree)
 Specifies the level of anisotropic filtering to apply to the SamplerState. More...
 
 setBorderColor (const LColor color)
 Specifies the solid color of the SamplerState's border. More...
 
 setLodBias (float lod_bias)
 Sets the value that will be added to the level of detail when sampling the texture. More...
 
 setMagfilter (SamplerState::FilterType filter)
 Sets the filtering method that should be used when viewing the SamplerState up close. More...
 
 setMaxLod (float max_lod)
 Sets the maximum level of detail that will be used when sampling this texture. More...
 
 setMinfilter (SamplerState::FilterType filter)
 Sets the filtering method that should be used when viewing the SamplerState from a distance. More...
 
 setMinLod (float min_lod)
 Sets the minimum level of detail that will be used when sampling this texture. More...
 
 setWrapU (SamplerState::WrapMode wrap)
 This setting determines what happens when the SamplerState is sampled with a U value outside the range 0.0-1.0. More...
 
 setWrapV (SamplerState::WrapMode wrap)
 This setting determines what happens when the SamplerState is sampled with a V value outside the range 0.0-1.0. More...
 
 setWrapW (SamplerState::WrapMode wrap)
 The W wrap direction is only used for 3-d SamplerStates. More...
 
bool usesMipmaps ()
 Returns true if the minfilter settings on this sampler indicate the use of mipmapping, false otherwise. More...
 

Static Public Member Functions

static str formatFilterType (SamplerState::FilterType ft)
 Returns the indicated FilterType converted to a string word. More...
 
static str formatWrapMode (SamplerState::WrapMode wm)
 Returns the indicated WrapMode converted to a string word. More...
 
static TypeHandle getClassType ()
 
static const SamplerState getDefault ()
 Returns a reference to the global default immutable SamplerState object. More...
 
static bool isMipmap (SamplerState::FilterType type)
 Returns true if the indicated filter type requires the use of mipmaps, or false if it does not. More...
 
static SamplerState::FilterType stringFilterType (str str)
 Returns the FilterType value associated with the given string representation, or FT_invalid if the string does not match any known FilterType value. More...
 
static SamplerState::WrapMode stringWrapMode (str str)
 Returns the WrapMode value associated with the given string representation, or WM_invalid if the string does not match any known WrapMode value. More...
 

Public Attributes

int anisotropic_degree
 Returns the degree of anisotropic filtering that should be applied to the texture. More...
 
const LColor border_color
 Returns the solid color of the texture's border. More...
 
int effective_anisotropic_degree
 Returns the degree of anisotropic filtering that should be applied to the texture. More...
 
SamplerState::FilterType effective_magfilter
 Returns the filter mode of the texture for magnification, with special treatment for FT_default. More...
 
SamplerState::FilterType effective_minfilter
 Returns the filter mode of the texture for minification, with special treatment for FT_default. More...
 
float lod_bias
 Returns the bias that will be added to the texture level of detail when sampling this texture. More...
 
SamplerState::FilterType magfilter
 Returns the filter mode of the texture for magnification. More...
 
float max_lod
 Returns the maximum level of detail that will be observed when sampling this texture. More...
 
float min_lod
 Returns the minimum level of detail that will be observed when sampling this texture. More...
 
SamplerState::FilterType minfilter
 Returns the filter mode of the texture for minification. More...
 
SamplerState::WrapMode wrap_u
 Returns the wrap mode of the texture in the U direction. More...
 
SamplerState::WrapMode wrap_v
 Returns the wrap mode of the texture in the V direction. More...
 
SamplerState::WrapMode wrap_w
 Returns the wrap mode of the texture in the W direction. More...
 

Detailed Description

Represents a set of settings that indicate how a texture is sampled.

This can be used to sample the same texture using different settings in different places.

Member Enumeration Documentation

◆ FilterType

enum FilterType
Enumerator
FT_nearest 

Point sample the pixel.

FT_linear 

Bilinear filtering of four neighboring pixels.

FT_nearest_mipmap_nearest 

Point sample the pixel from the nearest mipmap level.

FT_linear_mipmap_nearest 

Bilinear filter the pixel from the nearest mipmap level.

FT_nearest_mipmap_linear 

Point sample the pixel from two mipmap levels, and linearly blend.

FT_linear_mipmap_linear 

A.k.a. trilinear filtering: Bilinear filter the pixel from two mipmap levels, and linearly blend the results.

FT_shadow 

The OpenGL ARB_shadow extension can be thought of as a kind of filtering.

FT_default 

Default is usually linear, but it depends on format. This was added at the end of the list to avoid bumping TXO version #.

FT_invalid 

Returned by string_filter_type() for an invalid match.

◆ WrapMode

enum WrapMode
Enumerator
WM_clamp 

coords that would be outside [0-1] are clamped to 0 or 1

WM_repeat 
WM_mirror 
WM_mirror_once 

mirror once, then clamp

WM_border_color 

coords outside [0-1] use explicit border color Returned by string_wrap_mode() for an invalid match.

WM_invalid 

coords outside [0-1] use explicit border color Returned by string_wrap_mode() for an invalid match.

Member Function Documentation

◆ __init__() [1/2]

__init__ ( )

Creates a new SamplerState initialized to the default values.

◆ __init__() [2/2]

__init__ ( const  SamplerState)

◆ formatFilterType()

static str formatFilterType ( SamplerState::FilterType  ft)
static

Returns the indicated FilterType converted to a string word.

◆ formatWrapMode()

static str formatWrapMode ( SamplerState::WrapMode  wm)
static

Returns the indicated WrapMode converted to a string word.

◆ getAnisotropicDegree()

int getAnisotropicDegree ( )

Returns the degree of anisotropic filtering that should be applied to the texture.

This value may return 0, indicating the default value; see also get_effective_anisotropic_degree.

◆ getBorderColor()

const LColor getBorderColor ( )

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.

◆ getClassType()

static TypeHandle getClassType ( )
static

◆ getDefault()

static const SamplerState getDefault ( )
static

Returns a reference to the global default immutable SamplerState object.

◆ getEffectiveAnisotropicDegree()

int getEffectiveAnisotropicDegree ( )

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.

◆ getEffectiveMagfilter()

SamplerState::FilterType getEffectiveMagfilter ( )

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.

◆ getEffectiveMinfilter()

SamplerState::FilterType getEffectiveMinfilter ( )

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.

◆ getLodBias()

float getLodBias ( )

Returns the bias that will be added to the texture level of detail when sampling this texture.

◆ getMagfilter()

SamplerState::FilterType getMagfilter ( )

Returns the filter mode of the texture for magnification.

The mipmap constants are invalid here. This may return FT_default; see also get_effective_minfilter().

◆ getMaxLod()

float getMaxLod ( )

Returns the maximum level of detail that will be observed when sampling this texture.

◆ getMinfilter()

SamplerState::FilterType getMinfilter ( )

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 get_effective_minfilter().

◆ getMinLod()

float getMinLod ( )

Returns the minimum level of detail that will be observed when sampling this texture.

◆ getWrapU()

SamplerState::WrapMode getWrapU ( )

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

◆ getWrapV()

SamplerState::WrapMode getWrapV ( )

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

◆ getWrapW()

SamplerState::WrapMode getWrapW ( )

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

This is the depth direction of 3-d textures.

◆ isMipmap()

static bool isMipmap ( SamplerState::FilterType  type)
static

Returns true if the indicated filter type requires the use of mipmaps, or false if it does not.

◆ isPrepared()

bool isPrepared ( PreparedGraphicsObjects  prepared_objects)

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

◆ operator !=()

bool operator != ( const SamplerState  other)

◆ operator<()

bool operator< ( const SamplerState  other)

◆ operator==()

bool operator== ( const SamplerState  other)

◆ prepare()

prepare ( PreparedGraphicsObjects  prepared_objects)

Indicates that the sampler should be enqueued to be prepared in the indicated prepared_objects at the beginning of the next frame.

Use this function instead of prepare_now() to preload samplers from a user interface standpoint.

◆ prepareNow()

SamplerContext prepareNow ( PreparedGraphicsObjects  prepared_objects,
GraphicsStateGuardianBase  gsg 
)

Creates a context for the sampler on the particular GSG, if it does not already exist.

Returns the new (or old) SamplerContext. 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 sampler does not need to be explicitly prepared by the user before it may be rendered.

◆ release()

release ( PreparedGraphicsObjects  prepared_objects)

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.

◆ setAnisotropicDegree()

setAnisotropicDegree ( int  anisotropic_degree)

Specifies the level of anisotropic filtering to apply to the SamplerState.

Set this 0 to indicate the default value, which is specified in the SamplerState-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.

◆ setBorderColor()

setBorderColor ( const LColor  color)

Specifies the solid color of the SamplerState's border.

Some OpenGL implementations use a border for tiling SamplerStates; in Panda, it is only used for specifying the clamp color.

◆ setLodBias()

setLodBias ( float  lod_bias)

Sets the value that will be added to the level of detail when sampling the texture.

This may be a negative value, although some graphics hardware may not support the use of negative LOD values.

◆ setMagfilter()

setMagfilter ( SamplerState::FilterType  filter)

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

◆ setMaxLod()

setMaxLod ( float  max_lod)

Sets the maximum level of detail that will be used when sampling this texture.

This may exceed the number of mipmap levels that the texture has.

◆ setMinfilter()

setMinfilter ( SamplerState::FilterType  filter)

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

◆ setMinLod()

setMinLod ( float  min_lod)

Sets the minimum level of detail that will be used when sampling this texture.

This may be a negative value.

◆ setWrapU()

setWrapU ( SamplerState::WrapMode  wrap)

This setting determines what happens when the SamplerState is sampled with a U value outside the range 0.0-1.0.

The default is WM_repeat, which indicates that the SamplerState should repeat indefinitely.

◆ setWrapV()

setWrapV ( SamplerState::WrapMode  wrap)

This setting determines what happens when the SamplerState is sampled with a V value outside the range 0.0-1.0.

The default is WM_repeat, which indicates that the SamplerState should repeat indefinitely.

◆ setWrapW()

setWrapW ( SamplerState::WrapMode  wrap)

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

◆ stringFilterType()

static SamplerState::FilterType stringFilterType ( str  str)
static

Returns the FilterType value associated with the given string representation, or FT_invalid if the string does not match any known FilterType value.

◆ stringWrapMode()

static SamplerState::WrapMode stringWrapMode ( str  str)
static

Returns the WrapMode value associated with the given string representation, or WM_invalid if the string does not match any known WrapMode value.

◆ usesMipmaps()

bool usesMipmaps ( )

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

Member Data Documentation

◆ anisotropic_degree

int anisotropic_degree

Returns the degree of anisotropic filtering that should be applied to the texture.

This value may return 0, indicating the default value; see also get_effective_anisotropic_degree.

◆ border_color

const LColor border_color

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.

◆ effective_anisotropic_degree

int effective_anisotropic_degree

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.

◆ effective_magfilter

SamplerState::FilterType effective_magfilter

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.

◆ effective_minfilter

SamplerState::FilterType effective_minfilter

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.

◆ lod_bias

float lod_bias

Returns the bias that will be added to the texture level of detail when sampling this texture.

◆ magfilter

Returns the filter mode of the texture for magnification.

The mipmap constants are invalid here. This may return FT_default; see also get_effective_minfilter().

◆ max_lod

float max_lod

Returns the maximum level of detail that will be observed when sampling this texture.

◆ min_lod

float min_lod

Returns the minimum level of detail that will be observed when sampling this texture.

◆ minfilter

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 get_effective_minfilter().

◆ wrap_u

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

◆ wrap_v

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

◆ wrap_w

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

This is the depth direction of 3-d textures.