Panda3D
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Types | Protected Member Functions | Protected Attributes

Lens Class Reference

A base class for any number of different kinds of lenses, linear and otherwise. More...

#include "lens.h"

Inheritance diagram for Lens:
TypedWritableReferenceCount TypedWritable ReferenceCount TypedObject MemoryBase MemoryBase CylindricalLens FisheyeLens MatrixLens OrthographicLens PerspectiveLens PSphereLens

List of all members.

Public Types

enum  FromCorners {
  FC_roll = 0x0001, FC_camera_plane = 0x0002, FC_off_axis = 0x0004, FC_aspect_ratio = 0x0008,
  FC_shear = 0x0010, FC_keystone = 0x0020
}
enum  StereoChannel { SC_mono = 0x00, SC_left = 0x01, SC_right = 0x02, SC_stereo = 0x03 }

Public Member Functions

 Lens (const Lens &copy)
virtual ReferenceCountas_reference_count ()
 Returns the pointer cast to a ReferenceCount pointer, if it is in fact of that type.
TypedObjectas_typed_object ()
 Returns the object, upcast (if necessary) to a TypedObject pointer.
const TypedObjectas_typed_object () const
 Returns the object, upcast (if necessary) to a TypedObject pointer.
void clear ()
 Resets all lens parameters to their initial default settings.
void clear_keystone ()
 Disables the lens keystone correction.
void clear_view_mat ()
 Resets the lens transform to identity.
virtual int complete_pointers (TypedWritable **p_list, BamReader *manager)
 Receives an array of pointers, one for each time manager->read_pointer() was called in fillin().
bool encode_to_bam_stream (string &data, BamWriter *writer=NULL) const
 Converts the TypedWritable object into a single stream of data using a BamWriter, and stores that data in the indicated string.
string encode_to_bam_stream () const
 Converts the TypedWritable object into a single stream of data using a BamWriter, and returns that data as a string string.
bool extrude (const LPoint2f &point2d, LPoint3f &near_point, LPoint3f &far_point) const
 Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the corresponding vector in space that maps to this point, if such a vector can be determined.
bool extrude (const LPoint3f &point2d, LPoint3f &near_point, LPoint3f &far_point) const
 Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the corresponding vector in space that maps to this point, if such a vector can be determined.
bool extrude_vec (const LPoint3f &point2d, LVector3f &vec3d) const
 Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the vector that corresponds to the view direction.
bool extrude_vec (const LPoint2f &point2d, LVector3f &vec3d) const
 Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the vector that corresponds to the view direction.
virtual void finalize (BamReader *manager)
 Called by the BamReader to perform any final actions needed for setting up the object after all objects have been read and all pointers have been completed.
virtual TypeHandle force_init_type ()
float get_aspect_ratio () const
 Returns the aspect ratio of the Lens.
UpdateSeq get_bam_modified () const
 Returns the current bam_modified counter.
int get_best_parent_from_Set (const std::set< int > &) const
const string & get_change_event () const
 Returns the name of the event that will be generated whenever any properties of this particular Lens have changed.
float get_convergence_distance () const
 See set_convergence_distance().
CoordinateSystem get_coordinate_system () const
 Returns the coordinate system that all 3-d computations are performed within for this Lens.
float get_far () const
 Returns the position of the far plane (or cylinder, sphere, whatever).
const LMatrix4fget_film_mat () const
 Returns the matrix that transforms from a point behind the lens to a point on the film.
const LMatrix4fget_film_mat_inv () const
 Returns the matrix that transforms from a point on the film to a point behind the lens.
const LVector2fget_film_offset () const
 Returns the horizontal and vertical offset amounts of this Lens.
const LVecBase2fget_film_size () const
 Returns the horizontal and vertical film size of the virtual film.
float get_focal_length () const
 Returns the focal length of the lens.
const LVecBase2fget_fov () const
 Returns the horizontal and vertical film size of the virtual film.
float get_hfov () const
 Returns the horizontal component of fov only.
float get_interocular_distance () const
 See set_interocular_distance().
const LVecBase2fget_keystone () const
 Returns the keystone correction specified for the lens.
const UpdateSeqget_last_change () const
 Returns the UpdateSeq that is incremented whenever the lens properties are changed.
const LMatrix4fget_lens_mat () const
 Returns the matrix that transforms from a point in front of the lens to a point in space.
const LMatrix4fget_lens_mat_inv () const
 Returns the matrix that transforms from a point in space to a point in front of the lens.
float get_min_fov () const
 Returns the field of view of the narrowest dimension of the window.
float get_near () const
 Returns the position of the near plane (or cylinder, sphere, whatever).
LPoint3f get_nodal_point () const
 Returns the center point of the lens: the point from which the lens is viewing.
const LMatrix4fget_projection_mat (StereoChannel channel=SC_mono) const
 Returns the complete transformation matrix from a 3-d point in space to a point on the film, if such a matrix exists, or the identity matrix if the lens is nonlinear.
const LMatrix4fget_projection_mat_inv (StereoChannel channel=SC_mono) const
 Returns the matrix that transforms from a 2-d point on the film to a 3-d vector in space, if such a matrix exists.
int get_ref_count () const
 Returns the current reference count.
virtual TypeHandle get_type () const
int get_type_index () const
 Returns the internal index number associated with this object's TypeHandle, a unique number for each different type.
const LVector3fget_up_vector () const
 Returns the axis perpendicular to the camera's view vector that indicates the "up" direction.
float get_vfov () const
 Returns the vertical component of fov only.
const LVecBase3fget_view_hpr () const
 Returns the direction in which the lens is facing.
const LMatrix4fget_view_mat () const
 Returns the direction in which the lens is facing.
const LVector3fget_view_vector () const
 Returns the axis along which the lens is facing.
WeakReferenceListget_weak_list () const
 Returns the WeakReferenceList associated with this ReferenceCount object.
bool has_weak_list () const
 Returns true if this particular ReferenceCount object has a WeakReferenceList created, false otherwise.
bool is_exact_type (TypeHandle handle) const
 Returns true if the current object is the indicated type exactly.
virtual bool is_linear () const
 Returns true if the lens represents a linear projection (e.g.
bool is_of_type (TypeHandle handle) const
 Returns true if the current object is or derives from the indicated type.
virtual bool is_orthographic () const
 Returns true if the lens represents a orthographic projection (i.e.
virtual bool is_perspective () const
 Returns true if the lens represents a perspective projection (i.e.
void local_object ()
 This function should be called, once, immediately after creating a new instance of some ReferenceCount-derived object on the stack.
void mark_bam_modified ()
 Increments the bam_modified counter, so that this object will be invalidated and retransmitted on any open bam streams.
void operator delete (void *ptr, void *)
void operator delete (void *ptr)
void operator delete (void *ptr, void *)
void operator delete (void *ptr)
void operator delete[] (void *, void *)
void operator delete[] (void *ptr)
void operator delete[] (void *, void *)
void operator delete[] (void *ptr)
void * operator new (size_t size, void *ptr)
void * operator new (size_t size, void *ptr)
void * operator new (size_t size)
void * operator new (size_t size)
void * operator new[] (size_t size, void *ptr)
void * operator new[] (size_t size)
void * operator new[] (size_t size, void *ptr)
void * operator new[] (size_t size)
void operator= (const Lens &copy)
virtual void output (ostream &out) const
bool project (const LPoint3f &point3d, LPoint3f &point2d) const
 Given a 3-d point in space, determine the 2-d point this maps to, in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner.
bool project (const LPoint3f &point3d, LPoint2f &point2d) const
 Given a 3-d point in space, determine the 2-d point this maps to, in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner.
virtual PT (Lens) make_copy() const =0
virtual PT (BoundingVolume) make_bounds() const
virtual PT (Geom) make_geometry()
void recompute_all ()
 Forces all internal parameters of the Lens to be recomputed.
void ref () const
 Explicitly increments the reference count.
virtual bool require_fully_complete () const
 Some objects require all of their nested pointers to have been completed before the objects themselves can be completed.
void set_aspect_ratio (float aspect_ratio)
 Sets the aspect ratio of the lens.
void set_change_event (const string &event)
 Sets the name of the event that will be generated whenever any properties of the Lens have changed.
void set_convergence_distance (float convergence_distance)
 Sets the distance between between the camera plane and the point in the distance that the left and right eyes are both looking at.
void set_coordinate_system (CoordinateSystem cs)
 Specifies the coordinate system that all 3-d computations are performed within for this Lens.
void set_far (float far_distance)
 Defines the position of the far plane (or cylinder, sphere, whatever).
void set_film_offset (float x, float y)
 Sets the horizontal and vertical offset amounts of this Lens.
void set_film_offset (const LVecBase2f &film_offset)
 Sets the horizontal and vertical offset amounts of this Lens.
void set_film_size (float width, float height)
 Sets the size and shape of the "film" within the lens.
void set_film_size (const LVecBase2f &film_size)
 Sets the size and shape of the "film" within the lens.
void set_film_size (float width)
 Sets the horizontal size of the film without changing its shape.
void set_focal_length (float focal_length)
 Sets the focal length of the lens.
void set_fov (float hfov, float vfov)
 Sets the field of view of the lens in both dimensions.
void set_fov (const LVecBase2f &fov)
 Sets the field of view of the lens in both dimensions.
void set_fov (float fov)
 Sets the horizontal field of view of the lens without changing the aspect ratio.
void set_frustum_from_corners (const LVecBase3f &ul, const LVecBase3f &ur, const LVecBase3f &ll, const LVecBase3f &lr, int flags)
 Sets up the lens to use the frustum defined by the four indicated points.
void set_interocular_distance (float interocular_distance)
 Sets the distance between the left and right eyes of a stereo camera.
void set_keystone (const LVecBase2f &keystone)
 Indicates the ratio of keystone correction to perform on the lens, in each of three axes.
void set_min_fov (float min_fov)
 Sets the field of view of the smallest dimension of the window.
void set_near (float near_distance)
 Defines the position of the near plane (or cylinder, sphere, whatever).
void set_near_far (float near_distance, float far_distance)
 Simultaneously changes the near and far planes.
void set_view_hpr (const LVecBase3f &view_hpr)
 Sets the direction in which the lens is facing.
void set_view_hpr (float h, float p, float r)
 Sets the direction in which the lens is facing.
void set_view_mat (const LMatrix4f &view_mat)
 Sets an arbitrary transformation on the lens.
void set_view_vector (float x, float y, float z, float i, float j, float k)
 Specifies the direction in which the lens is facing by giving an axis to look along, and a perpendicular (or at least non-parallel) up axis.
void set_view_vector (const LVector3f &view_vector, const LVector3f &up_vector)
 Specifies the direction in which the lens is facing by giving an axis to look along, and a perpendicular (or at least non-parallel) up axis.
bool test_ref_count_integrity () const
 Does some easy checks to make sure that the reference count isn't completely bogus.
bool test_ref_count_nonzero () const
 Does some easy checks to make sure that the reference count isn't zero, or completely bogus.
virtual bool unref () const
 Explicitly decrements the reference count.
virtual void update_bam_nested (BamWriter *manager)
 Called by the BamWriter when this object has not itself been modified recently, but it should check its nested objects for updates.
void weak_ref (WeakPointerToVoid *ptv)
 Adds the indicated PointerToVoid as a weak reference to this object.
void weak_unref (WeakPointerToVoid *ptv)
 Removes the indicated PointerToVoid as a weak reference to this object.
virtual void write (ostream &out, int indent_level=0) const
virtual void write_datagram (BamWriter *manager, Datagram &dg)
 Writes the contents of this object to the datagram for shipping out to a Bam file.

Static Public Member Functions

static bool decode_raw_from_bam_stream (TypedWritable *&ptr, ReferenceCount *&ref_ptr, const string &data, BamReader *reader=NULL)
 Reads the string created by a previous call to encode_to_bam_stream(), and extracts the single object on that string.
static TypeHandle get_class_type ()
static float get_default_far ()
 Returns the default far plane distance that will be assigned to each newly-created lens.
static float get_default_near ()
 Returns the default near plane distance that will be assigned to each newly-created lens.
static void init_type ()
static PT (TypedWritableReferenceCount) decode_from_bam_stream(const string &data

Public Attributes

static BamReaderreader = NULL)

Static Public Attributes

static TypedWritable *const Null = (TypedWritable*)0L

Protected Types

enum  CompFlags {
  CF_film_mat = 0x0001, CF_film_mat_inv = 0x0002, CF_lens_mat = 0x0004, CF_lens_mat_inv = 0x0008,
  CF_projection_mat = 0x0010, CF_projection_mat_inv = 0x0020, CF_projection_mat_left_inv = 0x0040, CF_projection_mat_right_inv = 0x0080,
  CF_mat = 0x00ff, CF_film_size = 0x0100, CF_aspect_ratio = 0x0200, CF_view_hpr = 0x0400,
  CF_view_vector = 0x0800, CF_focal_length = 0x1000, CF_fov = 0x2000
}
enum  UserFlags {
  UF_film_width = 0x0001, UF_film_height = 0x0002, UF_focal_length = 0x0004, UF_hfov = 0x0008,
  UF_vfov = 0x0010, UF_aspect_ratio = 0x0020, UF_view_hpr = 0x0040, UF_view_vector = 0x0080,
  UF_interocular_distance = 0x0100, UF_convergence_distance = 0x0200, UF_view_mat = 0x0400, UF_keystone = 0x0800,
  UF_min_fov = 0x1000
}

Protected Member Functions

void adjust_comp_flags (int clear_flags, int set_flags)
 Clears from _comp_flags the bits in the first parameter, and sets the bits in the second parameter.
void adjust_user_flags (int clear_flags, int set_flags)
 Clears from _user_flags the bits in the first parameter, and sets the bits in the second parameter.
virtual void compute_aspect_ratio ()
 Computes the aspect ratio of the film rectangle, as a ratio of width to height.
virtual void compute_film_mat ()
 Computes the matrix that transforms from a point behind the lens to a point on the film.
virtual void compute_film_size ()
 Computes the size and shape of the film behind the camera, based on the aspect ratio and fov.
virtual void compute_focal_length ()
 Computes the focal length of the lens, based on the fov and film size.
virtual void compute_fov ()
 Computes the field of view of the lens, based on the film size and focal length.
virtual void compute_lens_mat ()
 Computes the matrix that transforms from a point in front of the lens to a point in space.
virtual void compute_projection_mat ()
 Computes the complete transformation matrix from 3-d point to 2-d point, if the lens is linear.
virtual void compute_view_hpr ()
 Computes the Euler angles representing the lens' rotation.
virtual void compute_view_vector ()
 Computes the view vector and up vector for the lens.
bool do_test_ref_count_integrity () const
 Does some easy checks to make sure that the reference count isn't completely bogus.
bool do_test_ref_count_nonzero () const
 Returns true if the reference count is nonzero, false otherwise.
virtual bool extrude_impl (const LPoint3f &point2d, LPoint3f &near_point, LPoint3f &far_point) const
 Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the corresponding vector in space that maps to this point, if such a vector can be determined.
virtual bool extrude_vec_impl (const LPoint3f &point2d, LVector3f &vec) const
 Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the vector that corresponds to the view direction.
void fillin (DatagramIterator &scan, BamReader *manager)
 This internal function is called by make_from_bam to read in all of the relevant data from the BamFile for the new Lens.
virtual float film_to_fov (float film_size, float focal_length, bool horiz) const
 Given a width (or height) on the film and a focal length, compute the field of view in degrees.
virtual float fov_to_film (float fov, float focal_length, bool horiz) const
 Given a field of view in degrees and a focal length, compute the corresponding width (or height) on the film.
virtual float fov_to_focal_length (float fov, float film_size, bool horiz) const
 Given a field of view in degrees and a width (or height) on the film, compute the focal length of the lens.
virtual bool project_impl (const LPoint3f &point3d, LPoint3f &point2d) const
 Given a 3-d point in space, determine the 2-d point this maps to, in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner.
 PT (GeomVertexData) _geom_data
void throw_change_event ()
 Throws the event associated with changing properties on this Lens, if any.

Protected Attributes

float _aspect_ratio
string _change_event
short _comp_flags
float _convergence_distance
CoordinateSystem _cs
float _far_distance
LMatrix4f _film_mat
LMatrix4f _film_mat_inv
LVector2f _film_offset
LVecBase2f _film_size
char _film_size_seq
float _focal_length
char _focal_length_seq
LVecBase2f _fov
char _fov_seq
float _interocular_distance
LVecBase2f _keystone
UpdateSeq _last_change
LMatrix4f _lens_mat
LMatrix4f _lens_mat_inv
float _min_fov
float _near_distance
LMatrix4f _projection_mat
LMatrix4f _projection_mat_inv
LMatrix4f _projection_mat_left
LMatrix4f _projection_mat_left_inv
LMatrix4f _projection_mat_right
LMatrix4f _projection_mat_right_inv
LVector3f _up_vector
short _user_flags
LVecBase3f _view_hpr
LVector3f _view_vector

Detailed Description

A base class for any number of different kinds of lenses, linear and otherwise.

Presently, this includes perspective and orthographic lenses.

A Lens object is the main part of a Camera node (defined in sgraph), which defines the fundamental interface to point-of-view for rendering. Lenses are also used in other contexts, however; for instance, a Spotlight is also defined using a lens.

Definition at line 41 of file lens.h.


Member Function Documentation

void Lens::adjust_comp_flags ( int  clear_flags,
int  set_flags 
) [inline, protected]
void Lens::adjust_user_flags ( int  clear_flags,
int  set_flags 
) [inline, protected]

Clears from _user_flags the bits in the first parameter, and sets the bits in the second parameter.

Definition at line 421 of file lens.I.

Referenced by clear_keystone(), clear_view_mat(), set_aspect_ratio(), set_convergence_distance(), set_film_size(), set_focal_length(), set_fov(), set_interocular_distance(), set_keystone(), set_min_fov(), set_view_hpr(), set_view_mat(), and set_view_vector().

ReferenceCount * TypedWritableReferenceCount::as_reference_count ( ) [virtual, inherited]

Returns the pointer cast to a ReferenceCount pointer, if it is in fact of that type.

Reimplemented from TypedWritable.

Definition at line 26 of file typedWritableReferenceCount.cxx.

TypedObject * TypedObject::as_typed_object ( ) [inline, inherited]

Returns the object, upcast (if necessary) to a TypedObject pointer.

Definition at line 99 of file typedObject.I.

const TypedObject * TypedObject::as_typed_object ( ) const [inline, inherited]

Returns the object, upcast (if necessary) to a TypedObject pointer.

Definition at line 110 of file typedObject.I.

void Lens::clear ( )

Resets all lens parameters to their initial default settings.

Definition at line 102 of file lens.cxx.

References ConfigVariableBase::has_value(), set_convergence_distance(), and set_interocular_distance().

void Lens::clear_keystone ( )

Disables the lens keystone correction.

Definition at line 766 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), and throw_change_event().

void Lens::clear_view_mat ( )

Resets the lens transform to identity.

Definition at line 722 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), LMatrix4f::ident_mat(), and throw_change_event().

int TypedWritable::complete_pointers ( TypedWritable **  p_list,
BamReader manager 
) [virtual, inherited]

Receives an array of pointers, one for each time manager->read_pointer() was called in fillin().

Returns the number of pointers processed.

This is the callback function that is made by the BamReader at some later point, after all of the required pointers have been filled in. It is necessary because there might be forward references in a bam file; when we call read_pointer() in fillin(), the object may not have been read from the file yet, so we do not have a pointer available at that time. Thus, instead of returning a pointer, read_pointer() simply reserves a later callback. This function provides that callback. The calling object is responsible for keeping track of the number of times it called read_pointer() and extracting the same number of pointers out of the supplied vector, and storing them appropriately within the object.

Reimplemented in CFDoCullCommand, AnimBundleNode, AnimChannelMatrixDynamic, AnimChannelScalarDynamic, AnimGroup, MovingPartBase, PartBundle, PartBundleNode, PartGroup, Character, CharacterJoint, CharacterJointEffect, CharacterVertexSlider, JointVertexTransform, CollisionNode, DataNodeTransmit, GeomVertexArrayData, GeomVertexArrayFormat, GeomVertexData, GeomVertexFormat, SliderTable, TextureStage, TransformBlendTable, TransformTable, PiecewiseCurve, ClipPlaneAttrib, FogAttrib, LensNode, LightAttrib, MaterialAttrib, PortalNode, RenderEffects, RenderState, TexGenAttrib, TexMatrixAttrib, TexProjectorEffect, TextureAttrib, BamCacheIndex, RecorderFrame, EggFile, ImageFile, PaletteGroup, PaletteGroups, PaletteImage, PalettePage, Palettizer, SourceTextureImage, TextureImage, TexturePlacement, TextureProperties, and TextureReference.

Definition at line 103 of file typedWritable.cxx.

void Lens::compute_aspect_ratio ( ) [protected, virtual]

Computes the aspect ratio of the film rectangle, as a ratio of width to height.

Definition at line 1620 of file lens.cxx.

References adjust_comp_flags(), and get_film_size().

Referenced by set_film_size(), set_fov(), and set_min_fov().

void Lens::compute_film_mat ( ) [protected, virtual]

Computes the matrix that transforms from a point behind the lens to a point on the film.

Definition at line 1689 of file lens.cxx.

References adjust_comp_flags(), get_film_offset(), and get_film_size().

void Lens::compute_film_size ( ) [protected, virtual]

Computes the size and shape of the film behind the camera, based on the aspect ratio and fov.

Definition at line 1462 of file lens.cxx.

References adjust_comp_flags(), fov_to_film(), and fov_to_focal_length().

void Lens::compute_focal_length ( ) [protected, virtual]

Computes the focal length of the lens, based on the fov and film size.

This is based on the horizontal dimension.

Definition at line 1525 of file lens.cxx.

References adjust_comp_flags(), fov_to_focal_length(), get_film_size(), and get_fov().

void Lens::compute_fov ( ) [protected, virtual]

Computes the field of view of the lens, based on the film size and focal length.

Definition at line 1542 of file lens.cxx.

References adjust_comp_flags(), film_to_fov(), fov_to_focal_length(), and get_film_size().

void Lens::compute_lens_mat ( ) [protected, virtual]

Computes the matrix that transforms from a point in front of the lens to a point in space.

Definition at line 1724 of file lens.cxx.

References adjust_comp_flags(), and LMatrix4f::ident_mat().

void Lens::compute_projection_mat ( ) [protected, virtual]

Computes the complete transformation matrix from 3-d point to 2-d point, if the lens is linear.

Reimplemented in MatrixLens, OrthographicLens, and PerspectiveLens.

Definition at line 1670 of file lens.cxx.

References adjust_comp_flags(), and LMatrix4f::ident_mat().

void Lens::compute_view_hpr ( ) [protected, virtual]

Computes the Euler angles representing the lens' rotation.

Definition at line 1639 of file lens.cxx.

References adjust_comp_flags(), and get_view_mat().

void Lens::compute_view_vector ( ) [protected, virtual]

Computes the view vector and up vector for the lens.

Definition at line 1654 of file lens.cxx.

References adjust_comp_flags(), LVector3f::forward(), get_view_mat(), and LVector3f::up().

bool TypedWritable::decode_raw_from_bam_stream ( TypedWritable *&  ptr,
ReferenceCount *&  ref_ptr,
const string &  data,
BamReader reader = NULL 
) [static, inherited]

Reads the string created by a previous call to encode_to_bam_stream(), and extracts the single object on that string.

Returns true on success, false on on error.

This variant sets the TypedWritable and ReferenceCount pointers separately; both are pointers to the same object. The reference count is not incremented; it is the caller's responsibility to manage the reference count.

Note that this method cannot be used to retrieve objects that do not inherit from ReferenceCount, because these objects cannot persist beyond the lifetime of the BamReader that reads them. To retrieve these objects from a bam stream, you must construct a BamReader directly.

If you happen to know that the particular object in question inherits from TypedWritableReferenceCount or PandaNode, consider calling the variant of decode_from_bam_stream() defined for those methods, which presents a simpler interface.

Definition at line 353 of file typedWritable.cxx.

References BamReader::init(), DatagramInputFile::open(), DatagramInputFile::read_header(), BamReader::read_object(), ReferenceCount::ref(), BamReader::resolve(), BamReader::set_source(), and ReferenceCount::unref().

bool ReferenceCount::do_test_ref_count_integrity ( ) const [protected, inherited]

Does some easy checks to make sure that the reference count isn't completely bogus.

Returns true if ok, false otherwise.

Reimplemented in NodeReferenceCount, CachedTypedWritableReferenceCount, and NodeCachedReferenceCount.

Definition at line 29 of file referenceCount.cxx.

Referenced by ReferenceCount::do_test_ref_count_nonzero(), and ReferenceCount::test_ref_count_integrity().

bool ReferenceCount::do_test_ref_count_nonzero ( ) const [protected, inherited]

Returns true if the reference count is nonzero, false otherwise.

Definition at line 56 of file referenceCount.cxx.

References ReferenceCount::do_test_ref_count_integrity().

Referenced by ReferenceCount::test_ref_count_nonzero().

string TypedWritable::encode_to_bam_stream ( ) const [inline, inherited]

Converts the TypedWritable object into a single stream of data using a BamWriter, and returns that data as a string string.

Returns empty string on failure.

This is a convenience method particularly useful for cases when you are only serializing a single object. If you have many objects to process, it is more efficient to use the same BamWriter to serialize all of them together.

Definition at line 86 of file typedWritable.I.

bool TypedWritable::encode_to_bam_stream ( string &  data,
BamWriter writer = NULL 
) const [inherited]

Converts the TypedWritable object into a single stream of data using a BamWriter, and stores that data in the indicated string.

Returns true on success, false on failure.

This is a convenience method particularly useful for cases when you are only serializing a single object. If you have many objects to process, it is more efficient to use the same BamWriter to serialize all of them together.

Definition at line 283 of file typedWritable.cxx.

References BamWriter::init(), DatagramOutputFile::open(), BamWriter::set_target(), DatagramOutputFile::write_header(), and BamWriter::write_object().

bool Lens::extrude ( const LPoint3f point2d,
LPoint3f near_point,
LPoint3f far_point 
) const [inline]

Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the corresponding vector in space that maps to this point, if such a vector can be determined.

The vector is returned by indicating the points on the near plane and far plane that both map to the indicated 2-d point.

The z coordinate of the 2-d point is ignored.

Returns true if the vector is defined, or false otherwise.

Definition at line 55 of file lens.I.

References extrude_impl().

bool Lens::extrude ( const LPoint2f point2d,
LPoint3f near_point,
LPoint3f far_point 
) const [inline]

Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the corresponding vector in space that maps to this point, if such a vector can be determined.

The vector is returned by indicating the points on the near plane and far plane that both map to the indicated 2-d point.

Returns true if the vector is defined, or false otherwise.

Definition at line 32 of file lens.I.

References extrude_impl().

Referenced by PortalClipper::prepare_portal(), CollisionSegment::set_from_lens(), and CollisionRay::set_from_lens().

bool Lens::extrude_impl ( const LPoint3f point2d,
LPoint3f near_point,
LPoint3f far_point 
) const [protected, virtual]

Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the corresponding vector in space that maps to this point, if such a vector can be determined.

The vector is returned by indicating the points on the near plane and far plane that both map to the indicated 2-d point.

The z coordinate of the 2-d point is ignored.

Returns true if the vector is defined, or false otherwise.

Reimplemented in CylindricalLens, FisheyeLens, and PSphereLens.

Definition at line 1357 of file lens.cxx.

References get_projection_mat_inv(), and LMatrix4f::xform().

Referenced by extrude().

bool Lens::extrude_vec ( const LPoint2f point2d,
LVector3f vec 
) const [inline]

Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the vector that corresponds to the view direction.

This will be parallel to the normal on the surface (the far plane) corresponding to the lens shape at this point.

See the comment block on Lens::extrude_vec_impl() for a more in-depth comment on the meaning of this vector.

Returns true if the vector is defined, or false otherwise.

Definition at line 78 of file lens.I.

References extrude_vec_impl().

bool Lens::extrude_vec ( const LPoint3f point2d,
LVector3f vec 
) const [inline]

Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the vector that corresponds to the view direction.

This will be parallel to the normal on the surface (the far plane) corresponding to the lens shape at this point.

See the comment block on Lens::extrude_vec_impl() for a more in-depth comment on the meaning of this vector.

The z coordinate of the 2-d point is ignored.

Returns true if the vector is defined, or false otherwise.

Definition at line 103 of file lens.I.

References extrude_vec_impl().

bool Lens::extrude_vec_impl ( const LPoint3f point2d,
LVector3f vec 
) const [protected, virtual]

Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner, compute the vector that corresponds to the view direction.

This will be parallel to the normal on the surface (the far plane) corresponding to the lens shape at this point.

Generally, for all rational lenses, the center of the film at (0,0) computes a vector that is in the same direction as the vector specified by set_view_vector().

For all linear lenses, including perspective and orthographic lenses, all points on the film compute this same vector (the far plane is a flat plane, so the normal is the same everywhere). For curved lenses like fisheye and cylindrical lenses, different points may compute different vectors (the far "plane" on these lenses is a curved surface).

The z coordinate of the 2-d point is ignored.

Returns true if the vector is defined, or false otherwise.

Reimplemented in CylindricalLens, and FisheyeLens.

Definition at line 1415 of file lens.cxx.

References LVector3f::forward(), and get_lens_mat().

Referenced by extrude_vec().

void Lens::fillin ( DatagramIterator scan,
BamReader manager 
) [protected, virtual]

This internal function is called by make_from_bam to read in all of the relevant data from the BamFile for the new Lens.

Reimplemented from TypedWritable.

Definition at line 2115 of file lens.cxx.

References DatagramIterator::get_float32(), DatagramIterator::get_string(), DatagramIterator::get_uint16(), DatagramIterator::get_uint8(), and LVecBase2f::read_datagram().

Referenced by PerspectiveLens::make_from_bam(), OrthographicLens::make_from_bam(), and MatrixLens::make_from_bam().

float Lens::film_to_fov ( float  film_size,
float  focal_length,
bool  horiz 
) const [protected, virtual]

Given a width (or height) on the film and a focal length, compute the field of view in degrees.

If horiz is true, this is in the horizontal direction; otherwise, it is in the vertical direction (some lenses behave differently in each direction).

Reimplemented in CylindricalLens, FisheyeLens, PSphereLens, and PerspectiveLens.

Definition at line 1782 of file lens.cxx.

Referenced by compute_fov().

void TypedWritable::finalize ( BamReader manager) [virtual, inherited]

Called by the BamReader to perform any final actions needed for setting up the object after all objects have been read and all pointers have been completed.

Reimplemented in PartBundle, Geom, GeomPrimitive, GeomVertexArrayData, GeomVertexArrayFormat, GeomVertexData, InternalName, GeomNode, LightAttrib, RenderAttrib, RenderEffect, RenderEffects, RenderState, PaletteGroup, and Palettizer.

Definition at line 145 of file typedWritable.cxx.

Referenced by BamReader::finalize_now().

float Lens::fov_to_film ( float  fov,
float  focal_length,
bool  horiz 
) const [protected, virtual]

Given a field of view in degrees and a focal length, compute the corresponding width (or height) on the film.

If horiz is true, this is in the horizontal direction; otherwise, it is in the vertical direction (some lenses behave differently in each direction).

Reimplemented in CylindricalLens, FisheyeLens, PSphereLens, and PerspectiveLens.

Definition at line 1754 of file lens.cxx.

Referenced by compute_film_size().

float Lens::fov_to_focal_length ( float  fov,
float  film_size,
bool  horiz 
) const [protected, virtual]

Given a field of view in degrees and a width (or height) on the film, compute the focal length of the lens.

If horiz is true, this is in the horizontal direction; otherwise, it is in the vertical direction (some lenses behave differently in each direction).

Reimplemented in CylindricalLens, FisheyeLens, PSphereLens, and PerspectiveLens.

Definition at line 1768 of file lens.cxx.

Referenced by compute_film_size(), compute_focal_length(), and compute_fov().

float Lens::get_aspect_ratio ( ) const

Returns the aspect ratio of the Lens.

This is determined based on the indicated film size; see set_film_size().

Definition at line 466 of file lens.cxx.

Referenced by set_film_size(), and set_frustum_from_corners().

UpdateSeq TypedWritable::get_bam_modified ( ) const [inline, inherited]

Returns the current bam_modified counter.

This counter is normally incremented automatically whenever the object is modified.

Definition at line 66 of file typedWritable.I.

Referenced by BamWriter::consider_update(), and BamWriter::write_pointer().

const string & Lens::get_change_event ( ) const [inline]

Returns the name of the event that will be generated whenever any properties of this particular Lens have changed.

Definition at line 177 of file lens.I.

float Lens::get_convergence_distance ( ) const

See set_convergence_distance().

Definition at line 671 of file lens.cxx.

CoordinateSystem Lens::get_coordinate_system ( ) const [inline]

Returns the coordinate system that all 3-d computations are performed within for this Lens.

Normally, this is CS_default.

Definition at line 189 of file lens.I.

Referenced by PortalClipper::prepare_portal().

float Lens::get_default_far ( ) [static]

Returns the default far plane distance that will be assigned to each newly-created lens.

This is read from the Configrc file.

Definition at line 493 of file lens.cxx.

Referenced by WindowFramework::center_trackball().

float Lens::get_default_near ( ) [static]

Returns the default near plane distance that will be assigned to each newly-created lens.

This is read from the Configrc file.

Definition at line 481 of file lens.cxx.

Referenced by WindowFramework::center_trackball().

float Lens::get_far ( ) const [inline]
const LMatrix4f & Lens::get_film_mat ( ) const
const LMatrix4f & Lens::get_film_mat_inv ( ) const

Returns the matrix that transforms from a point on the film to a point behind the lens.

Definition at line 1250 of file lens.cxx.

References adjust_comp_flags(), get_film_mat(), and LMatrix4f::invert_from().

Referenced by FisheyeLens::extrude_impl(), CylindricalLens::extrude_impl(), PSphereLens::extrude_impl(), and CylindricalLens::extrude_vec_impl().

const LVector2f & Lens::get_film_offset ( ) const [inline]

Returns the horizontal and vertical offset amounts of this Lens.

See set_film_offset().

Definition at line 256 of file lens.I.

Referenced by compute_film_mat().

const LVecBase2f & Lens::get_film_size ( ) const

Returns the horizontal and vertical film size of the virtual film.

See set_film_size().

Definition at line 224 of file lens.cxx.

Referenced by compute_aspect_ratio(), compute_film_mat(), compute_focal_length(), compute_fov(), and set_frustum_from_corners().

float Lens::get_focal_length ( ) const

Returns the focal length of the lens.

This may have been set explicitly by a previous call to set_focal_length(), or it may be computed based on the lens' fov and film_size. For certain kinds of lenses, the focal length has no meaning.

Definition at line 279 of file lens.cxx.

Referenced by PerspectiveLens::compute_projection_mat(), FisheyeLens::extrude_impl(), CylindricalLens::extrude_impl(), PSphereLens::extrude_impl(), CylindricalLens::extrude_vec_impl(), PSphereLens::project_impl(), CylindricalLens::project_impl(), and FisheyeLens::project_impl().

const LVecBase2f & Lens::get_fov ( ) const

Returns the horizontal and vertical film size of the virtual film.

See set_fov().

Definition at line 417 of file lens.cxx.

Referenced by WindowFramework::center_trackball(), compute_focal_length(), get_hfov(), and get_vfov().

float Lens::get_hfov ( ) const [inline]

Returns the horizontal component of fov only.

See get_fov().

Definition at line 284 of file lens.I.

References get_fov().

Referenced by TinyGraphicsStateGuardian::bind_light(), DXGraphicsStateGuardian9::bind_light(), and DXGraphicsStateGuardian8::bind_light().

float Lens::get_interocular_distance ( ) const

See set_interocular_distance().

Definition at line 625 of file lens.cxx.

const LVecBase2f & Lens::get_keystone ( ) const [inline]

Returns the keystone correction specified for the lens.

Definition at line 397 of file lens.I.

const UpdateSeq & Lens::get_last_change ( ) const [inline]

Returns the UpdateSeq that is incremented whenever the lens properties are changed.

As long as this number remains the same, you may assume the lens properties are unchanged.

Definition at line 410 of file lens.I.

const LMatrix4f & Lens::get_lens_mat ( ) const

Returns the matrix that transforms from a point in front of the lens to a point in space.

Definition at line 1267 of file lens.cxx.

Referenced by FisheyeLens::extrude_impl(), CylindricalLens::extrude_impl(), PSphereLens::extrude_impl(), extrude_vec_impl(), CylindricalLens::extrude_vec_impl(), and get_lens_mat_inv().

const LMatrix4f & Lens::get_lens_mat_inv ( ) const
float Lens::get_min_fov ( ) const

Returns the field of view of the narrowest dimension of the window.

See set_min_fov().

Definition at line 431 of file lens.cxx.

float Lens::get_near ( ) const [inline]
LPoint3f Lens::get_nodal_point ( ) const

Returns the center point of the lens: the point from which the lens is viewing.

Definition at line 586 of file lens.cxx.

References LMatrix4f::get_row3(), and get_view_mat().

Referenced by TinyGraphicsStateGuardian::bind_light(), DXGraphicsStateGuardian9::bind_light(), and DXGraphicsStateGuardian8::bind_light().

const LMatrix4f & Lens::get_projection_mat ( StereoChannel  channel = SC_mono) const

Returns the complete transformation matrix from a 3-d point in space to a point on the film, if such a matrix exists, or the identity matrix if the lens is nonlinear.

Definition at line 1165 of file lens.cxx.

Referenced by ScissorEffect::cull_callback(), get_projection_mat_inv(), and project_impl().

const LMatrix4f & Lens::get_projection_mat_inv ( StereoChannel  channel = SC_mono) const

Returns the matrix that transforms from a 2-d point on the film to a 3-d vector in space, if such a matrix exists.

Definition at line 1191 of file lens.cxx.

References adjust_comp_flags(), get_projection_mat(), and LMatrix4f::invert_from().

Referenced by extrude_impl().

int ReferenceCount::get_ref_count ( ) const [inline, inherited]
int TypedObject::get_type_index ( ) const [inline, inherited]

Returns the internal index number associated with this object's TypeHandle, a unique number for each different type.

This is equivalent to get_type().get_index().

Definition at line 52 of file typedObject.I.

References TypeHandle::get_index().

const LVector3f & Lens::get_up_vector ( ) const

Returns the axis perpendicular to the camera's view vector that indicates the "up" direction.

Definition at line 572 of file lens.cxx.

float Lens::get_vfov ( ) const [inline]

Returns the vertical component of fov only.

See get_fov().

Definition at line 295 of file lens.I.

References get_fov().

const LVecBase3f & Lens::get_view_hpr ( ) const

Returns the direction in which the lens is facing.

Definition at line 524 of file lens.cxx.

const LMatrix4f & Lens::get_view_mat ( ) const

Returns the direction in which the lens is facing.

Definition at line 709 of file lens.cxx.

Referenced by compute_view_hpr(), compute_view_vector(), and get_nodal_point().

const LVector3f & Lens::get_view_vector ( ) const

Returns the axis along which the lens is facing.

Definition at line 558 of file lens.cxx.

Referenced by TinyGraphicsStateGuardian::bind_light(), DXGraphicsStateGuardian9::bind_light(), and DXGraphicsStateGuardian8::bind_light().

WeakReferenceList * ReferenceCount::get_weak_list ( ) const [inline, inherited]

Returns the WeakReferenceList associated with this ReferenceCount object.

If there has never been a WeakReferenceList associated with this object, creates one now.

Definition at line 307 of file referenceCount.I.

Referenced by ReferenceCount::weak_ref().

bool ReferenceCount::has_weak_list ( ) const [inline, inherited]

Returns true if this particular ReferenceCount object has a WeakReferenceList created, false otherwise.

In general, this will be true if there was ever a WeakPointerTo created for this object (even if there is not any for it now).

Definition at line 294 of file referenceCount.I.

Referenced by ReferenceCount::weak_unref().

bool TypedObject::is_exact_type ( TypeHandle  handle) const [inline, inherited]
bool Lens::is_linear ( ) const [virtual]

Returns true if the lens represents a linear projection (e.g.

PerspectiveLens, OrthographicLens), and therefore there is a valid matrix returned by get_projection_mat(), or false otherwise.

Reimplemented in MatrixLens, OrthographicLens, and PerspectiveLens.

Definition at line 1004 of file lens.cxx.

bool TypedObject::is_of_type ( TypeHandle  handle) const [inline, inherited]

Returns true if the current object is or derives from the indicated type.

Definition at line 63 of file typedObject.I.

References TypeHandle::is_derived_from().

Referenced by EggSliderData::add_back_pointer(), EggJointData::add_back_pointer(), CIntervalManager::add_c_interval(), XFileNode::add_child(), CollisionTraverser::add_collider(), CollisionHandlerPhysical::add_collider(), EggXfmSAnim::add_data(), CharacterJointBundle::add_node(), NonlinearImager::add_screen(), EggGroupNode::apply_first_attribute(), EggGroupNode::apply_last_attribute(), DeferredNodeProperty::apply_to_node(), RecorderController::begin_playback(), NodePath::clear_clip_plane(), EggGroupNode::clear_connected_shading(), NodePath::clear_light(), EggBase::convert_paths(), NodePath::decode_from_bam_stream(), VrpnClient::disconnect_device(), PhysicsManager::do_physics(), GraphicsStateGuardian::fetch_specified_part(), EggRenderState::fill_state(), AnimBundleNode::find_anim_bundle(), EggGroupNode::find_coordsys_entry(), XFile::find_data_object(), Character::find_joint(), EggGroupNode::find_materials(), Character::find_slider(), XFile::find_template(), EggGroupNode::find_textures(), EggMaterialCollection::find_used_materials(), EggTextureCollection::find_used_textures(), EggGroupNode::force_filenames(), EggJointData::force_initial_rest_frame(), WindowFramework::get_aspect_2d(), EggPoolUniquifier::get_category(), EggGroupUniquifier::get_category(), EggGroupNode::get_connected_shading(), PandaFramework::get_mouse(), FactoryParams::get_param_of_type(), EggGroupNode::has_absolute_pathnames(), NodePath::has_clip_plane(), NodePath::has_clip_plane_off(), NodePath::has_light(), PandaFramework::hide_collision_solids(), x11GraphicsWindow::open_window(), eglGraphicsWindow::open_window(), EggNode::parse_egg(), CharacterMaker::part_to_node(), EggGroupNode::post_apply_flat_attribute(), EggBinner::prepare_node(), PortalClipper::prepare_portal(), NodePath::project_texture(), EggMatrixTablePointer::quantize_channels(), ParametricCurveCollection::r_add_curves(), SceneGraphReducer::r_collect_vertex_data(), EggGroupNode::r_load_externals(), EggGroupNode::rebuild_vertex_pools(), EggGroupNode::recompute_polygon_normals(), EggGroupNode::remove_invalid_primitives(), EggGroupNode::remove_unused_vertices(), EggLoader::reparent_decals(), EggMaterialCollection::replace_materials(), EggTextureCollection::replace_textures(), EggGroupNode::resolve_filenames(), EggGroupNode::reverse_vertex_ordering(), NodePath::set_clip_plane(), NodePath::set_clip_plane_off(), NodePath::set_light(), ProjectionScreen::set_projector(), NonlinearImager::set_source_camera(), EggXfmSAnim::set_value(), NonlinearImager::set_viewer_camera(), PandaFramework::show_collision_solids(), BamCache::store(), XFileToEggConverter::strip_nodes(), EggGroupNode::strip_normals(), DataGraphTraverser::traverse(), DataGraphTraverser::traverse_below(), EggGroupNode::triangulate_polygons(), EggGroupNode::unify_attributes(), EggNameUniquifier::uniquify(), NodeCullCallbackData::upcall(), PhysicsCollisionHandler::validate_target(), EggXfmSAnim::write(), EggGroup::write(), EggToDXFLayer::write_3d_face(), and EggToDXFLayer::write_entities().

bool Lens::is_orthographic ( ) const [virtual]

Returns true if the lens represents a orthographic projection (i.e.

it is a OrthographicLens), false otherwise.

Reimplemented in OrthographicLens.

Definition at line 1028 of file lens.cxx.

bool Lens::is_perspective ( ) const [virtual]

Returns true if the lens represents a perspective projection (i.e.

it is a PerspectiveLens), false otherwise.

Reimplemented in PerspectiveLens.

Definition at line 1016 of file lens.cxx.

void ReferenceCount::local_object ( ) [inline, inherited]

This function should be called, once, immediately after creating a new instance of some ReferenceCount-derived object on the stack.

This allows the object to be passed to functions that will increment and decrement the object's reference count temporarily, and it will prevent the object from being deleted (inappropriately), when the reference count returns to zero. It actually achieves this by setting a large positive value in the reference count field.

Definition at line 276 of file referenceCount.I.

Referenced by PGTop::cull_callback(), BoundingSphere::extend_by_hexahedron(), AsyncTaskManager::find_task(), AsyncTaskManager::find_tasks(), and AsyncTaskManager::find_tasks_matching().

void TypedWritable::mark_bam_modified ( ) [inline, inherited]
bool Lens::project ( const LPoint3f point3d,
LPoint3f point2d 
) const [inline]

Given a 3-d point in space, determine the 2-d point this maps to, in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner.

The z coordinate will also be set to a value in the range (-1, 1), where 1 represents a point on the near plane, and -1 represents a point on the far plane.

Returns true if the 3-d point is in front of the lens and within the viewing frustum (in which case point2d is filled in), or false otherwise (in which case point2d will be filled in with something, which may or may not be meaningful).

Definition at line 148 of file lens.I.

References project_impl().

Referenced by PortalClipper::prepare_portal().

bool Lens::project ( const LPoint3f point3d,
LPoint2f point2d 
) const [inline]

Given a 3-d point in space, determine the 2-d point this maps to, in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner.

Returns true if the 3-d point is in front of the lens and within the viewing frustum (in which case point2d is filled in), or false otherwise (in which case point2d will be filled in with something, which may or may not be meaningful).

Definition at line 122 of file lens.I.

References project_impl().

bool Lens::project_impl ( const LPoint3f point3d,
LPoint3f point2d 
) const [protected, virtual]

Given a 3-d point in space, determine the 2-d point this maps to, in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner.

The z coordinate will also be set to a value in the range (-1, 1), where 1 represents a point on the near plane, and -1 represents a point on the far plane.

Returns true if the 3-d point is in front of the lens and within the viewing frustum (in which case point2d is filled in), or false otherwise (in which case point2d will be filled in with something, which may or may not be meaningful).

Reimplemented in CylindricalLens, FisheyeLens, and PSphereLens.

Definition at line 1439 of file lens.cxx.

References get_projection_mat(), and LMatrix4f::xform().

Referenced by project().

void Lens::recompute_all ( )

Forces all internal parameters of the Lens to be recomputed.

Normally, this should never need to be called; it is provided only to assist in debugging.

Definition at line 991 of file lens.cxx.

void ReferenceCount::ref ( ) const [inline, inherited]

Explicitly increments the reference count.

User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically.

This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

Definition at line 179 of file referenceCount.I.

References ReferenceCount::test_ref_count_integrity().

Referenced by CachedTypedWritableReferenceCount::cache_ref(), TypedWritable::decode_raw_from_bam_stream(), NodeCachedReferenceCount::node_ref(), NodeReferenceCount::node_ref(), BamCacheRecord::set_data(), CullableObject::set_draw_callback(), and ModelRoot::set_reference().

bool TypedWritable::require_fully_complete ( ) const [virtual, inherited]

Some objects require all of their nested pointers to have been completed before the objects themselves can be completed.

If this is the case, override this method to return true, and be careful with circular references (which would make the object unreadable from a bam file).

Reimplemented in GeomVertexData, ClipPlaneAttrib, and RenderEffects.

Definition at line 118 of file typedWritable.cxx.

void Lens::set_aspect_ratio ( float  aspect_ratio)

Sets the aspect ratio of the lens.

This is the ratio of the height to the width of the generated image. Setting this overrides the two-parameter fov or film size setting.

Definition at line 448 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), and throw_change_event().

Referenced by WindowFramework::adjust_aspect_ratio(), WindowFramework::make_camera(), and set_frustum_from_corners().

void Lens::set_change_event ( const string &  event) [inline]

Sets the name of the event that will be generated whenever any properties of the Lens have changed.

If this is not set for a particular lens, no event will be generated.

The event is thrown with one parameter, the lens itself. This can be used to automatically track changes to camera fov, etc. in the application.

Definition at line 165 of file lens.I.

void Lens::set_convergence_distance ( float  convergence_distance)

Sets the distance between between the camera plane and the point in the distance that the left and right eyes are both looking at.

This distance is used to apply a stereo effect when the lens is rendered on a stereo display region. It only has an effect on a PerspectiveLens.

This parameter must be greater than 0, but may be as large as you like. It controls the amount to which the two eyes are directed inwards towards each other, which is a normal property of stereo vision. It is a distance, not an angle; normally this should be set to the distance from the camera to the area of interest in your scene. If you want to simulate parallel stereo, set this value to a very large number.

Also see set_interocular_distance(), which relates.

Definition at line 652 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), and throw_change_event().

Referenced by clear().

void Lens::set_coordinate_system ( CoordinateSystem  cs)

Specifies the coordinate system that all 3-d computations are performed within for this Lens.

Normally, this is CS_default.

Definition at line 90 of file lens.cxx.

References adjust_comp_flags().

void Lens::set_far ( float  far_distance) [inline]

Defines the position of the far plane (or cylinder, sphere, whatever).

Points farther from the lens than this may not be rendered.

Definition at line 332 of file lens.I.

References adjust_comp_flags(), and throw_change_event().

Referenced by WindowFramework::center_trackball().

void Lens::set_film_offset ( const LVecBase2f film_offset) [inline]

Sets the horizontal and vertical offset amounts of this Lens.

These are both in the same units specified in set_film_size().

This can be used to establish an off-axis lens.

Definition at line 243 of file lens.I.

References adjust_comp_flags(), and throw_change_event().

void Lens::set_film_offset ( float  x,
float  y 
) [inline]

Sets the horizontal and vertical offset amounts of this Lens.

These are both in the same units specified in set_film_size().

This can be used to establish an off-axis lens.

Definition at line 229 of file lens.I.

Referenced by set_frustum_from_corners().

void Lens::set_film_size ( const LVecBase2f film_size)

Sets the size and shape of the "film" within the lens.

This both establishes the units used by calls like set_focal_length(), and establishes the aspect ratio of the frame.

In a physical camera, the field of view of a lens is determined by the lens' focal length and by the size of the film area exposed by the lens. For instance, a 35mm camera exposes a rectangle on the film about 24mm x 36mm, which means a 50mm lens gives about a 40-degree horizontal field of view.

In the virtual camera, you may set the film size to any units here, and specify a focal length in the same units to simulate the same effect. Or, you may ignore this parameter, and specify the field of view and aspect ratio of the lens directly.

Definition at line 188 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), compute_aspect_ratio(), LVecBase2f::is_nan(), and throw_change_event().

void Lens::set_film_size ( float  width)

Sets the horizontal size of the film without changing its shape.

The aspect ratio remains unchanged; this computes the vertical size of the film to automatically maintain the aspect ratio.

Definition at line 143 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), get_aspect_ratio(), and throw_change_event().

Referenced by WindowFramework::adjust_aspect_ratio(), WindowFramework::get_render_2d(), set_film_size(), FrameRateMeter::setup_window(), and SceneGraphAnalyzerMeter::setup_window().

void Lens::set_film_size ( float  width,
float  height 
) [inline]

Sets the size and shape of the "film" within the lens.

This both establishes the units used by calls like set_focal_length(), and establishes the aspect ratio of the frame.

In a physical camera, the field of view of a lens is determined by the lens' focal length and by the size of the film area exposed by the lens. For instance, a 35mm camera exposes a rectangle on the film about 24mm x 36mm, which means a 50mm lens gives about a 40-degree horizontal field of view.

In the virtual camera, you may set the film size to any units here, and specify a focal length in the same units to simulate the same effect. Or, you may ignore this parameter, and specify the field of view and aspect ratio of the lens directly.

Definition at line 215 of file lens.I.

References set_film_size().

void Lens::set_focal_length ( float  focal_length)

Sets the focal length of the lens.

This may adjust the field-of-view correspondingly, and is an alternate way to specify field of view.

For certain kinds of lenses (e.g. OrthographicLens), the focal length has no meaning.

Definition at line 245 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), and throw_change_event().

void Lens::set_fov ( float  hfov,
float  vfov 
) [inline]

Sets the field of view of the lens in both dimensions.

This establishes both the field of view and the aspect ratio of the lens. This is one way to specify the field of view of a lens; set_focal_length() is another way.

For certain kinds of lenses (like OrthoLens), the field of view has no meaning.

Definition at line 273 of file lens.I.

References set_fov().

void Lens::set_fov ( const LVecBase2f fov)

Sets the field of view of the lens in both dimensions.

This establishes both the field of view and the aspect ratio of the lens. This is one way to specify the field of view of a lens; set_focal_length() is another way.

For certain kinds of lenses (like OrthographicLens), the field of view has no meaning.

Definition at line 381 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), compute_aspect_ratio(), LVecBase2f::is_nan(), and throw_change_event().

void Lens::set_fov ( float  hfov)

Sets the horizontal field of view of the lens without changing the aspect ratio.

The vertical field of view is adjusted to maintain the same aspect ratio.

Definition at line 339 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), compute_aspect_ratio(), and throw_change_event().

Referenced by GraphicsOutput::make_cube_map(), set_fov(), and set_frustum_from_corners().

void Lens::set_frustum_from_corners ( const LVecBase3f ul,
const LVecBase3f ur,
const LVecBase3f ll,
const LVecBase3f lr,
int  flags 
)

Sets up the lens to use the frustum defined by the four indicated points.

This is most useful for a PerspectiveLens, but it may be called for other kinds of lenses as well.

The frustum will be rooted at the origin (or by whatever translation might have been specified in a previous call to set_view_mat).

It is legal for the four points not to be arranged in a rectangle; if this is the case, the frustum will be fitted as tightly as possible to cover all four points.

The flags parameter contains the union of one or more of the following bits to control the behavior of this function:

FC_roll - If this is included, the camera may be rotated so that its up vector is perpendicular to the top line. Otherwise, the standard up vector is used.

FC_camera_plane - This allows the camera plane to be adjusted to be as nearly perpendicular to the center of the frustum as possible. Without this bit, the orientation camera plane is defined by position of the four points (which should all be coplanar). With this bit, the camera plane is arbitarary, and may be chosen so that the four points do not themselves lie in the camera plane (but the points will still be within the frustum).

FC_off_axis - This allows the resulting frustum to be off-axis to get the tightest possible fit. Without this bit, the viewing axis will be centered within the frustum, but there may be more wasted space along the edges.

FC_aspect_ratio - This allows the frustum to be scaled non-proportionately in the vertical and horizontal dimensions, if necessary, to get a tighter fit. Without this bit, the current aspect ratio will be preserved.

FC_shear - This allows the frustum to be sheared, if necessary, to get the tightest possible fit. This may result in a parallelogram-based frustum, which will give a slanted appearance to the rendered image. Without this bit, the frustum will be rectangle-based.

In general, if 0 is passed in as the value for flags, the generated frustum will be a loose fit but sane; if -1 is passed in, it will be a tighter fit and possibly screwy.

Definition at line 835 of file lens.cxx.

References get_aspect_ratio(), get_film_size(), get_lens_mat_inv(), LMatrix4f::ident_mat(), LMatrix4f::invert_affine_from(), LMatrix4f::invert_from(), LVecBase3f::is_nan(), LVecBase3f::length_squared(), set_aspect_ratio(), set_film_offset(), set_fov(), LMatrix4f::set_row(), set_view_mat(), LVector3f::up(), and LMatrix4f::xform_point().

void Lens::set_interocular_distance ( float  interocular_distance)

Sets the distance between the left and right eyes of a stereo camera.

This distance is used to apply a stereo effect when the lens is rendered on a stereo display region. It only has an effect on a PerspectiveLens.

The left eye and the right eye are each offset along the X axis by half of this distance, so that this parameter specifies the total distance between them.

Also see set_convergence_distance(), which relates.

Definition at line 606 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), and throw_change_event().

Referenced by clear().

void Lens::set_keystone ( const LVecBase2f keystone)

Indicates the ratio of keystone correction to perform on the lens, in each of three axes.

This will build a special non-affine scale factor into the projection matrix that will compensate for keystoning of a projected image; this can be used to compensate for a projector that for physical reasons cannot be aimed directly at its screen.

The default value is taken from the default-keystone Config variable. 0, 0 indicates no keystone correction; specify a small value (usually in the range -1 .. 1) in either the x or y position to generate a keystone correction in that axis.

Definition at line 750 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), LVecBase2f::is_nan(), and throw_change_event().

void Lens::set_min_fov ( float  min_fov)

Sets the field of view of the smallest dimension of the window.

If the window is wider than it is tall, this specifies the vertical field of view; if it is taller than it is wide, this specifies the horizontal field of view.

In many cases, this is preferable to setting either the horizontal or vertical field of view explicitly. Setting this parameter means that pulling the window wider will widen the field of view, which is usually what you expect to happen.

Definition at line 302 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), compute_aspect_ratio(), and throw_change_event().

void Lens::set_near ( float  near_distance) [inline]

Defines the position of the near plane (or cylinder, sphere, whatever).

Points closer to the lens than this may not be rendered.

Definition at line 307 of file lens.I.

References adjust_comp_flags(), and throw_change_event().

Referenced by WindowFramework::center_trackball().

void Lens::set_near_far ( float  near_distance,
float  far_distance 
) [inline]

Simultaneously changes the near and far planes.

Definition at line 355 of file lens.I.

References adjust_comp_flags(), and throw_change_event().

void Lens::set_view_hpr ( float  h,
float  p,
float  r 
) [inline]

Sets the direction in which the lens is facing.

Normally, this is down the forward axis (usually the Y axis), but it may be rotated. This is only one way of specifying the rotation; you may also specify an explicit vector in which to look, or you may give a complete transformation matrix.

Definition at line 373 of file lens.I.

void Lens::set_view_hpr ( const LVecBase3f view_hpr)

Sets the direction in which the lens is facing.

Normally, this is down the forward axis (usually the Y axis), but it may be rotated. This is only one way of specifying the rotation; you may also specify an explicit vector in which to look, or you may give a complete transformation matrix.

Definition at line 508 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), LVecBase3f::is_nan(), and throw_change_event().

void Lens::set_view_mat ( const LMatrix4f view_mat)

Sets an arbitrary transformation on the lens.

This replaces the individual transformation components like set_view_hpr().

Setting a transformation here will have a slightly different effect than putting one on the LensNode that contains this lens. In particular, lighting and other effects computations will still be performed on the lens in its untransformed (facing forward) position, but the actual projection matrix will be transformed by this matrix.

Definition at line 691 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), LMatrix4f::is_nan(), and throw_change_event().

Referenced by set_frustum_from_corners().

void Lens::set_view_vector ( float  x,
float  y,
float  z,
float  i,
float  j,
float  k 
) [inline]

Specifies the direction in which the lens is facing by giving an axis to look along, and a perpendicular (or at least non-parallel) up axis.

See also set_view_hpr().

Definition at line 386 of file lens.I.

Referenced by PointLight::PointLight().

void Lens::set_view_vector ( const LVector3f view_vector,
const LVector3f up_vector 
)

Specifies the direction in which the lens is facing by giving an axis to look along, and a perpendicular (or at least non-parallel) up axis.

See also set_view_hpr().

Definition at line 541 of file lens.cxx.

References adjust_comp_flags(), adjust_user_flags(), LVecBase3f::is_nan(), and throw_change_event().

bool ReferenceCount::test_ref_count_integrity ( ) const [inline, inherited]
bool ReferenceCount::test_ref_count_nonzero ( ) const [inline, inherited]

Does some easy checks to make sure that the reference count isn't zero, or completely bogus.

Returns true if ok, false otherwise.

Definition at line 252 of file referenceCount.I.

References ReferenceCount::do_test_ref_count_nonzero().

Referenced by CopyOnWritePointer::test_ref_count_nonzero().

void Lens::throw_change_event ( ) [protected]
bool ReferenceCount::unref ( ) const [inline, virtual, inherited]

Explicitly decrements the reference count.

Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic.) However, see the helper function unref_delete().

User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically.

This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

The return value is true if the new reference count is nonzero, false if it is zero.

Reimplemented in GeomVertexArrayFormat, GeomVertexFormat, InternalName, RenderAttrib, RenderEffects, RenderState, and TransformState.

Definition at line 214 of file referenceCount.I.

References ReferenceCount::test_ref_count_integrity().

Referenced by CachedTypedWritableReferenceCount::cache_unref(), TypedWritable::decode_raw_from_bam_stream(), RenderEffect::finalize(), NodeCachedReferenceCount::node_unref(), NodeReferenceCount::node_unref(), TransformState::unref(), RenderState::unref(), RenderEffects::unref(), RenderAttrib::unref(), InternalName::unref(), GeomVertexFormat::unref(), and GeomVertexArrayFormat::unref().

void TypedWritable::update_bam_nested ( BamWriter manager) [virtual, inherited]

Called by the BamWriter when this object has not itself been modified recently, but it should check its nested objects for updates.

Reimplemented in CFDoCullCommand, and PandaNode.

Definition at line 77 of file typedWritable.cxx.

void ReferenceCount::weak_ref ( WeakPointerToVoid ptv) [inline, inherited]

Adds the indicated PointerToVoid as a weak reference to this object.

Definition at line 321 of file referenceCount.I.

References WeakReferenceList::add_reference(), and ReferenceCount::get_weak_list().

void ReferenceCount::weak_unref ( WeakPointerToVoid ptv) [inline, inherited]

Removes the indicated PointerToVoid as a weak reference to this object.

It must have previously been added via a call to weak_ref().

Definition at line 334 of file referenceCount.I.

References WeakReferenceList::clear_reference(), and ReferenceCount::has_weak_list().

void Lens::write_datagram ( BamWriter manager,
Datagram dg 
) [virtual]

Writes the contents of this object to the datagram for shipping out to a Bam file.

Reimplemented from TypedWritable.

Definition at line 2092 of file lens.cxx.

References Datagram::add_float32(), Datagram::add_string(), Datagram::add_uint16(), Datagram::add_uint8(), and LVecBase2f::write_datagram().


The documentation for this class was generated from the following files:
 All Classes Functions Variables Enumerations