Panda3D

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
BamReader Class Reference

This is the fundamental interface for extracting binary objects from a Bam file, as generated by a BamWriter. More...

`#include "bamReader.h"`

Inheritance diagram for BamReader:

## Classes
class | AuxData

## Public Types
typedef TypedWritable *(* | ChangeThisFunc) (TypedWritable *object, BamReader *manager)
typedef PT TypedWritableReferenceCount(* | ChangeThisRefFunc) (TypedWritableReferenceCount *object, BamReader *manager)
typedef Factory< TypedWritable > | WritableFactory
Public Types inherited from BamEnums
enum | BamEndian { BE_bigendian = 0 , BE_littleendian = 1 , BE_native = 1 }
| This defines an enumerated type used to represent the endianness of certain numeric values stored in a Bam file. More...
enum | BamObjectCode { BOC_push , BOC_pop , BOC_adjunct , BOC_remove , BOC_file_data }
| This is the code written along with each object. More...
enum | BamTextureMode { BTM_unchanged , BTM_fullpath , BTM_relative , BTM_basename , BTM_rawdata }

## Public Member Functions
| BamReader (DatagramGenerator *source=nullptr)
bool | change_pointer (const TypedWritable *orig_pointer, const TypedWritable *new_pointer)
| Indicates that an object recently read from the bam stream should be replaced with a new object.
void | finalize_now (TypedWritable *whom)
| Forces the finalization of a particular object.
AuxData * | get_aux_data (TypedWritable *obj, const std::string &name) const
| Returns the pointer previously associated with the bam reader by a previous call to set_aux_data(), or NULL if data with the indicated key has not been set.
BamReaderAuxData * | get_aux_tag (const std::string &tag) const
| Returns the value previously set via set_aux_tag().
int | get_current_major_ver () const
| Returns the major version number of Bam files supported by the current code base.
int | get_current_minor_ver () const
| Returns the minor version number of Bam files supported by the current code base.
const FileReference * | get_file ()
| Returns the FileReference that provides the source for these datagrams, if any, or NULL if the datagrams do not originate from a file on disk.
BamEndian | get_file_endian () const
int | get_file_major_ver () const
| Returns the major version number of the Bam file currently being read.
int | get_file_minor_ver () const
| Returns the minor version number of the Bam file currently being read.
std::streampos | get_file_pos ()
| Returns the current file position within the data stream, if any, or 0 if the file position is not meaningful or cannot be determined.
bool | get_file_stdfloat_double () const
const Filename & | get_filename () const
int | get_int_tag (const std::string &tag) const
| Returns the value previously set via set_int_tag().
const LoaderOptions & | get_loader_options () const
void * | get_pta (DatagramIterator &scan)
| This function works in conjection with register_pta(), below, to read a PointerToArray (PTA) from the Bam file, and unify references to the same PTA.
DatagramGenerator * | get_source ()
VirtualFile * | get_vfile ()
| Returns the VirtualFile that provides the source for these datagrams, if any, or NULL if the datagrams do not originate from a VirtualFile.
bool | init ()
| Initializes the BamReader prior to reading any objects from its source.
bool | is_eof () const
| Returns true if the reader has reached end-of-file, false otherwise.
void | read_cdata (DatagramIterator &scan, PipelineCyclerBase &cycler)
| Reads in the indicated CycleData object.
void | read_cdata (DatagramIterator &scan, PipelineCyclerBase &cycler, void *extra_data)
| This flavor of read_cdata allows passing an additional parameter to cdata->fillin().
void | read_file_data (SubfileInfo &info)
| Reads a block of auxiliary file data from the Bam file.
TypeHandle | read_handle (DatagramIterator &scan)
| Reads a TypeHandle out of the Datagram.
TypedWritable * | read_object ()
| Reads a single object from the Bam file.
bool | read_object (TypedWritable *&ptr, ReferenceCount *&ref_ptr)
| Reads a single object from the Bam file.
bool | read_pointer (DatagramIterator &scan)
| The interface for reading a pointer to another object from a Bam file.
void | read_pointers (DatagramIterator &scan, int count)
| A convenience function to read a contiguous list of pointers.
void | register_change_this (ChangeThisFunc func, TypedWritable *whom)
| Called by an object reading itself from the bam file to indicate that the object pointer that will be returned is temporary, and will eventually need to be replaced with another pointer.
void | register_change_this (ChangeThisRefFunc func, TypedWritableReferenceCount *whom)
| Called by an object reading itself from the bam file to indicate that the object pointer that will be returned is temporary, and will eventually need to be replaced with another pointer.
void | register_finalize (TypedWritable *whom)
| Should be called by an object reading itself from the Bam file to indicate that this particular object would like to receive the finalize() callback when all the objects and pointers in the Bam file are completely read.
void | register_pta (void *ptr)
| The second part of read_pta(), this should be called with the pointer to the array that was read in after read_pta() returned NULL.
bool | resolve ()
| This may be called at any time during processing of the Bam file to resolve all the known pointers so far.
void | set_aux_data (TypedWritable *obj, const std::string &name, AuxData *data)
| Associates an arbitrary block of data with the indicated object (or NULL), and the indicated name.
void | set_aux_tag (const std::string &tag, BamReaderAuxData *value)
| Allows the creating object to store a temporary data value on the BamReader.
void | set_int_tag (const std::string &tag, int value)
| Allows the creating object to store a temporary data value on the BamReader.
void | set_loader_options (const LoaderOptions &options)
void | set_source (DatagramGenerator *source)
void | skip_pointer (DatagramIterator &scan)
| Reads and discards a pointer value from the Bam file.

## Static Public Member Functions
static WritableFactory * | get_factory ()
| Returns the global WritableFactory for generating TypedWritable objects.
static void | register_factory (TypeHandle type, WritableFactory::CreateFunc *func, void *user_data=nullptr)
| Registers a factory function that is called when an object of the given type is encountered within the .bam stream.

## Public Attributes
| get_file_endian
| Returns the endian preference indicated by the Bam file currently being read.
| get_file_stdfloat_double
| Returns true if the file stores all "standard" floats as 64-bit doubles, or false if they are 32-bit floats.
| get_file_version
| get_filename
| If a BAM is a file, then the BamReader should contain the name of the file.
| get_loader_options
| Returns the LoaderOptions passed to the loader when the model was requested, if any.
| get_source
| Returns the current source of the BamReader as set by set_source() or the constructor.
| set_loader_options
| Specifies the LoaderOptions for this BamReader.
| set_source
| Changes the source of future datagrams for this BamReader.

## Static Public Attributes
static BamReader *const | Null = nullptr
static WritableFactory *const | NullFactory = nullptr

## Detailed Description

This is the fundamental interface for extracting binary objects from a Bam file, as generated by a BamWriter.

A Bam file can be thought of as a linear collection of objects. Each object is an instance of a class that inherits, directly or indirectly, from TypedWritable. The objects may include pointers to other objects within the Bam file; the BamReader automatically manages these (with help from code within each class) and restores the pointers correctly.

This is the abstract interface and does not specifically deal with disk files, but rather with a DatagramGenerator of some kind, which is simply a linear source of Datagrams. It is probably from a disk file, but it might conceivably be streamed directly from a network or some such nonsense.

Bam files are most often used to store scene graphs or subgraphs, and by convention they are given filenames ending in the extension ".bam" when they are used for this purpose. However, a Bam file may store any arbitrary list of TypedWritable objects; in this more general usage, they are given filenames ending in ".boo" to differentiate them from the more common scene graph files.

See also BamFile, which defines a higher-level interface to read and write Bam files on disk.

Definition at line 110 of file bamReader.h.

## Member Typedef Documentation

## ◆ ChangeThisFunc

typedef TypedWritable *(* BamReader::ChangeThisFunc) (TypedWritable *object, BamReader *manager)

Definition at line 183 of file bamReader.h.

## ◆ ChangeThisRefFunc

typedef PT TypedWritableReferenceCount(* BamReader::ChangeThisRefFunc) (TypedWritableReferenceCount *object, BamReader *manager)

Definition at line 184 of file bamReader.h.

## ◆ WritableFactory

typedef Factory<TypedWritable> BamReader::WritableFactory

Definition at line 112 of file bamReader.h.

## Constructor & Destructor Documentation

## ◆ BamReader()

BamReader::BamReader | ( | DatagramGenerator * | source = nullptr | ) |
| explicit

Definition at line 40 of file bamReader.cxx.

## ◆ ~BamReader()

BamReader::~BamReader | ( |  | ) |

Definition at line 58 of file bamReader.cxx.

## Member Function Documentation

## ◆ change_pointer()

bool BamReader::change_pointer | ( | const TypedWritable * | orig_pointer,
|  | const TypedWritable * | new_pointer )

Indicates that an object recently read from the bam stream should be replaced with a new object.

Any future occurrences of the original object in the stream will henceforth return the new object instead.

The return value is true if the replacement was successfully made, or false if the object was not read from the stream (or if change_pointer had already been called on it).

Definition at line 463 of file bamReader.cxx.

References TypedWritable::as_reference_count().

Referenced by GeomVertexArrayData::finalize(), and GeomVertexData::finalize().

## ◆ finalize_now()

void BamReader::finalize_now | ( | TypedWritable * | whom | ) |

Forces the finalization of a particular object.

This may be called by any of the objects during finalization, to guarantee finalization ordering where it is important.

Definition at line 896 of file bamReader.cxx.

References TypedWritable::finalize().

Referenced by GeomNode::finalize().

## ◆ get_aux_data()

BamReader::AuxData * BamReader::get_aux_data | ( | TypedWritable * | obj,
|  | const std::string & | name ) const

Returns the pointer previously associated with the bam reader by a previous call to set_aux_data(), or NULL if data with the indicated key has not been set.

Definition at line 188 of file bamReader.cxx.

Referenced by ClipPlaneAttrib::complete_pointers(), LightAttrib::complete_pointers(), ClipPlaneAttrib::finalize(), GeomVertexArrayData::finalize(), and LightAttrib::finalize().

## ◆ get_aux_tag()

BamReaderAuxData * BamReader::get_aux_tag | ( | const std::string & | tag | ) | const

Returns the value previously set via set_aux_tag().

It is an error if no value has been set.

Definition at line 784 of file bamReader.cxx.

## ◆ get_current_major_ver()

int BamReader::get_current_major_ver | ( |  | ) | const
| inline

Returns the major version number of Bam files supported by the current code base.

This must match get_file_major_ver() in order to successfully read a file.

Definition at line 113 of file bamReader.I.

## ◆ get_current_minor_ver()

int BamReader::get_current_minor_ver | ( |  | ) | const
| inline

Returns the minor version number of Bam files supported by the current code base.

This must match or exceed get_file_minor_ver() in order to successfully read a file.

Definition at line 123 of file bamReader.I.

## ◆ get_factory()

WritableFactory * BamReader::get_factory | ( |  | ) |
| inline static

Returns the global WritableFactory for generating TypedWritable objects.

Definition at line 176 of file bamReader.I.

Referenced by register_factory(), AlphaTestAttrib::register_with_read_factory(), AmbientLight::register_with_read_factory(), AnimBundle::register_with_read_factory(), AnimBundleNode::register_with_read_factory(), AnimChannelMatrixDynamic::register_with_read_factory(), AnimChannelMatrixFixed::register_with_read_factory(), AnimChannelMatrixXfmTable::register_with_read_factory(), AnimChannelScalarDynamic::register_with_read_factory(), AnimChannelScalarTable::register_with_read_factory(), AnimGroup::register_with_read_factory(), AnimPreloadTable::register_with_read_factory(), AntialiasAttrib::register_with_read_factory(), AudioVolumeAttrib::register_with_read_factory(), AuxBitplaneAttrib::register_with_read_factory(), BamCacheIndex::register_with_read_factory(), BamCacheRecord::register_with_read_factory(), BillboardEffect::register_with_read_factory(), BulletBoxShape::register_with_read_factory(), BulletCapsuleShape::register_with_read_factory(), BulletConeShape::register_with_read_factory(), BulletConvexHullShape::register_with_read_factory(), BulletConvexPointCloudShape::register_with_read_factory(), BulletCylinderShape::register_with_read_factory(), BulletDebugNode::register_with_read_factory(), BulletGhostNode::register_with_read_factory(), BulletHeightfieldShape::register_with_read_factory(), BulletMinkowskiSumShape::register_with_read_factory(), BulletMultiSphereShape::register_with_read_factory(), BulletPlaneShape::register_with_read_factory(), BulletRigidBodyNode::register_with_read_factory(), BulletSphereShape::register_with_read_factory(), BulletTriangleMesh::register_with_read_factory(), BulletTriangleMeshShape::register_with_read_factory(), ButtonEventList::register_with_read_factory(), CallbackNode::register_with_read_factory(), Camera::register_with_read_factory(), Character::register_with_read_factory(), CharacterJoint::register_with_read_factory(), CharacterJointBundle::register_with_read_factory(), CharacterJointEffect::register_with_read_factory(), CharacterSlider::register_with_read_factory(), CharacterVertexSlider::register_with_read_factory(), ClipPlaneAttrib::register_with_read_factory(), CollisionBox::register_with_read_factory(), CollisionCapsule::register_with_read_factory(), CollisionFloorMesh::register_with_read_factory(), CollisionInvSphere::register_with_read_factory(), CollisionLine::register_with_read_factory(), CollisionNode::register_with_read_factory(), CollisionParabola::register_with_read_factory(), CollisionPlane::register_with_read_factory(), CollisionPolygon::register_with_read_factory(), CollisionRay::register_with_read_factory(), CollisionSegment::register_with_read_factory(), CollisionSphere::register_with_read_factory(), ColorAttrib::register_with_read_factory(), ColorBlendAttrib::register_with_read_factory(), ColorScaleAttrib::register_with_read_factory(), ColorWriteAttrib::register_with_read_factory(), CompassEffect::register_with_read_factory(), ComputeNode::register_with_read_factory(), CubicCurveseg::register_with_read_factory(), CullBinAttrib::register_with_read_factory(), CullFaceAttrib::register_with_read_factory(), DataNodeTransmit::register_with_read_factory(), DecalEffect::register_with_read_factory(), DepthOffsetAttrib::register_with_read_factory(), DepthTestAttrib::register_with_read_factory(), DepthWriteAttrib::register_with_read_factory(), DestTextureImage::register_with_read_factory(), DirectionalLight::register_with_read_factory(), EggFile::register_with_read_factory(), FadeLODNode::register_with_read_factory(), FfmpegVideo::register_with_read_factory(), FfmpegVideoCursor::register_with_read_factory(), Fog::register_with_read_factory(), FogAttrib::register_with_read_factory(), Geom::register_with_read_factory(), GeomLines::register_with_read_factory(), GeomLinesAdjacency::register_with_read_factory(), GeomLinestrips::register_with_read_factory(), GeomLinestripsAdjacency::register_with_read_factory(), GeomNode::register_with_read_factory(), GeomPatches::register_with_read_factory(), GeomPoints::register_with_read_factory(), GeomTextGlyph::register_with_read_factory(), GeomTriangles::register_with_read_factory(), GeomTrianglesAdjacency::register_with_read_factory(), GeomTrifans::register_with_read_factory(), GeomTristrips::register_with_read_factory(), GeomTristripsAdjacency::register_with_read_factory(), GeomVertexArrayData::register_with_read_factory(), GeomVertexArrayFormat::register_with_read_factory(), GeomVertexData::register_with_read_factory(), GeomVertexFormat::register_with_read_factory(), HermiteCurve::register_with_read_factory(), InternalName::register_with_read_factory(), JointVertexTransform::register_with_read_factory(), LensNode::register_with_read_factory(), LightAttrib::register_with_read_factory(), LightRampAttrib::register_with_read_factory(), LODNode::register_with_read_factory(), LogicOpAttrib::register_with_read_factory(), Material::register_with_read_factory(), MaterialAttrib::register_with_read_factory(), MatrixLens::register_with_read_factory(), ModelNode::register_with_read_factory(), ModelRoot::register_with_read_factory(), MouseRecorder::register_with_read_factory(), MovingPartMatrix::register_with_read_factory(), MovingPartScalar::register_with_read_factory(), NurbsCurve::register_with_read_factory(), OccluderEffect::register_with_read_factory(), OccluderNode::register_with_read_factory(), OrthographicLens::register_with_read_factory(), PaletteGroup::register_with_read_factory(), PaletteGroups::register_with_read_factory(), PaletteImage::register_with_read_factory(), PalettePage::register_with_read_factory(), Palettizer::register_with_read_factory(), PandaNode::register_with_read_factory(), ParamNodePath::register_with_read_factory(), ParamTextureImage::register_with_read_factory(), ParamTextureSampler::register_with_read_factory(), ParamValue< Type >::register_with_read_factory(), PartBundle::register_with_read_factory(), PartGroup::register_with_read_factory(), PerspectiveLens::register_with_read_factory(), PlaneNode::register_with_read_factory(), PNMFileTypePfm::register_with_read_factory(), PointLight::register_with_read_factory(), PolylightNode::register_with_read_factory(), PortalNode::register_with_read_factory(), RecorderFrame::register_with_read_factory(), RecorderHeader::register_with_read_factory(), RecorderTable::register_with_read_factory(), RectangleLight::register_with_read_factory(), RenderEffects::register_with_read_factory(), RenderModeAttrib::register_with_read_factory(), RenderState::register_with_read_factory(), RescaleNormalAttrib::register_with_read_factory(), RopeNode::register_with_read_factory(), ScissorAttrib::register_with_read_factory(), ScissorEffect::register_with_read_factory(), SequenceNode::register_with_read_factory(), ShadeModelAttrib::register_with_read_factory(), Shader::register_with_read_factory(), ShaderBuffer::register_with_read_factory(), SheetNode::register_with_read_factory(), ShowBoundsEffect::register_with_read_factory(), SliderTable::register_with_read_factory(), SourceTextureImage::register_with_read_factory(), SpeedTreeNode::register_with_read_factory(), SphereLight::register_with_read_factory(), Spotlight::register_with_read_factory(), StencilAttrib::register_with_read_factory(), SwitchNode::register_with_read_factory(), TexGenAttrib::register_with_read_factory(), TexMatrixAttrib::register_with_read_factory(), TexProjectorEffect::register_with_read_factory(), Texture::register_with_read_factory(), TextureAttrib::register_with_read_factory(), TextureImage::register_with_read_factory(), TexturePlacement::register_with_read_factory(), TexturePosition::register_with_read_factory(), TextureProperties::register_with_read_factory(), TextureReference::register_with_read_factory(), TextureStage::register_with_read_factory(), TransformBlendTable::register_with_read_factory(), TransformState::register_with_read_factory(), TransformTable::register_with_read_factory(), TransparencyAttrib::register_with_read_factory(), UserVertexSlider::register_with_read_factory(), UserVertexTransform::register_with_read_factory(), and UvScrollNode::register_with_read_factory().

## ◆ get_file()

const FileReference * BamReader::get_file | ( |  | ) |
| inline

Returns the FileReference that provides the source for these datagrams, if any, or NULL if the datagrams do not originate from a file on disk.

Definition at line 132 of file bamReader.I.

## ◆ get_file_major_ver()

int BamReader::get_file_major_ver | ( |  | ) | const
| inline

Returns the major version number of the Bam file currently being read.

Definition at line 74 of file bamReader.I.

## ◆ get_file_minor_ver()

int BamReader::get_file_minor_ver | ( |  | ) | const
| inline

Returns the minor version number of the Bam file currently being read.

Definition at line 82 of file bamReader.I.

Referenced by BillboardEffect::complete_pointers(), Camera::complete_pointers(), CharacterJoint::complete_pointers(), ClipPlaneAttrib::complete_pointers(), CompassEffect::complete_pointers(), GeomVertexColumn::complete_pointers(), LightAttrib::complete_pointers(), MovingPartBase::complete_pointers(), OccluderEffect::complete_pointers(), ParamNodePath::complete_pointers(), PartBundle::complete_pointers(), GeomVertexColumn::fillin(), ClipPlaneAttrib::finalize(), GeomNode::finalize(), LightAttrib::finalize(), SamplerState::read_datagram(), and read_pointer().

## ◆ get_file_pos()

std::streampos BamReader::get_file_pos | ( |  | ) |
| inline

Returns the current file position within the data stream, if any, or 0 if the file position is not meaningful or cannot be determined.

For BamReaders that return a meaningful file position, this will be pointing to the first byte following the datagram returned after a call to get_datagram().

Definition at line 156 of file bamReader.I.

## ◆ get_int_tag()

int BamReader::get_int_tag | ( | const std::string & | tag | ) | const

Returns the value previously set via set_int_tag().

It is an error if no value has been set.

Definition at line 743 of file bamReader.cxx.

## ◆ get_pta()

void * BamReader::get_pta | ( | DatagramIterator & | scan | ) |

This function works in conjection with register_pta(), below, to read a PointerToArray (PTA) from the Bam file, and unify references to the same PTA.

The first time get_pta() encounters a particular PTA, it will return NULL. This is the indication that the caller should then read in the data associated with the PTA, and subsequently call register_pta() with the address of the filled-in array.

The next time (and all subsequent times) that get_pta() encounters this same PTA, it will return the pointer that was passed with register_pta().

Also see the READ_PTA() macro, which consolidates all the work that must be done to read a PTA.

Definition at line 930 of file bamReader.cxx.

## ◆ get_vfile()

VirtualFile * BamReader::get_vfile | ( |  | ) |
| inline

Returns the VirtualFile that provides the source for these datagrams, if any, or NULL if the datagrams do not originate from a VirtualFile.

Definition at line 142 of file bamReader.I.

## ◆ init()

bool BamReader::init | ( |  | ) |

Initializes the BamReader prior to reading any objects from its source.

This includes reading the Bam header.

This returns true if the BamReader successfully initialized, false otherwise.

Definition at line 84 of file bamReader.cxx.

References DatagramIterator::get_bool(), DatagramIterator::get_current_index(), Datagram::get_length(), DatagramIterator::get_uint16(), and DatagramIterator::get_uint8().

Referenced by TypedWritable::decode_raw_from_bam_stream().

## ◆ is_eof()

bool BamReader::is_eof | ( |  | ) | const
| inline

Returns true if the reader has reached end-of-file, false otherwise.

This call is only valid after a call to read_object().

Definition at line 65 of file bamReader.I.

## ◆ read_cdata() [1/2]

void BamReader::read_cdata | ( | DatagramIterator & | scan,
|  | PipelineCyclerBase & | cycler )

Reads in the indicated CycleData object.

This should be used by classes that store some or all of their data within a CycleData subclass, in support of pipelining. This will call the virtual CycleData::fillin() method to do the actual reading.

Definition at line 694 of file bamReader.cxx.

References CycleData::fillin(), Thread::get_current_thread, PipelineCyclerTrivialImpl::release_write(), and PipelineCyclerTrivialImpl::write().

## ◆ read_cdata() [2/2]

void BamReader::read_cdata | ( | DatagramIterator & | scan,
|  | PipelineCyclerBase & | cycler,
|  | void * | extra_data )

This flavor of read_cdata allows passing an additional parameter to cdata->fillin().

Definition at line 708 of file bamReader.cxx.

References CycleData::fillin(), Thread::get_current_thread, PipelineCyclerTrivialImpl::release_write(), and PipelineCyclerTrivialImpl::write().

## ◆ read_file_data()

void BamReader::read_file_data | ( | SubfileInfo & | info | ) |

Reads a block of auxiliary file data from the Bam file.

This can be a block of arbitrary size, and it is assumed it may be quite large. Rather than reading the entire block into memory, a file reference is returned to locate the block on disk. The data must have been written by a matching call to write_file_data().

Definition at line 676 of file bamReader.cxx.

## ◆ read_handle()

TypeHandle BamReader::read_handle | ( | DatagramIterator & | scan | ) |

Reads a TypeHandle out of the Datagram.

Definition at line 513 of file bamReader.cxx.

References TypeRegistry::find_type(), get_filename, TypeHandle::get_parent_towards(), DatagramIterator::get_string(), DatagramIterator::get_uint16(), DatagramIterator::get_uint8(), TypeRegistry::ptr(), read_handle(), TypeRegistry::record_derivation(), and TypeRegistry::register_dynamic_type().

Referenced by read_handle().

## ◆ read_object() [1/2]

TypedWritable * BamReader::read_object | ( |  | ) |

Reads a single object from the Bam file.

If the object type is known, a new object of the appropriate type is created and returned; otherwise, NULL is returned. NULL is also returned when the end of the file is reached. is_eof() may be called to differentiate between these two cases.

This may be called repeatedly to extract out all the objects in the Bam file, but typically (especially for scene graph files, indicated with the .bam extension), only one object is retrieved directly from the Bam file: the root of the scene graph. The remaining objects will all be retrieved recursively by the first object.

Note that the object returned may not yet be complete. In particular, some of its pointers may not be filled in; you must call resolve() to fill in all the available pointers before you can safely use any objects returned by read_object().

This flavor of read_object() requires the caller to know what type of object it has received in order to properly manage the reference counts.

Definition at line 223 of file bamReader.cxx.

References read_object().

Referenced by NodePath::decode_from_bam_stream(), TypedWritable::decode_raw_from_bam_stream(), and read_object().

## ◆ read_object() [2/2]

bool BamReader::read_object | ( | TypedWritable *& | ptr,
|  | ReferenceCount *& | ref_ptr )

Reads a single object from the Bam file.

This flavor of read_object() returns both a TypedWritable and a ReferenceCount pointer to the same object, so the reference count may be tracked reliably, without having to know precisely what type of object we have.

Returns
  true on success, or false on failure.

Definition at line 244 of file bamReader.cxx.

## ◆ read_pointer()

bool BamReader::read_pointer | ( | DatagramIterator & | scan | ) |

The interface for reading a pointer to another object from a Bam file.

Objects reading themselves from a Bam file should call this when they expect to read a pointer to some other object. This function reads whatever is stored in the bam file to represent the pointer, and advances the datagram iterator accordingly.

Rather than returning a pointer immediately, this function reads the internal pointer information from the datagram and queues up the request. The pointer itself may not be available until later (it may be a pointer to an object that appears later in the Bam file). Later, when all pointers are available, the complete_pointers() callback function will be called with an array of actual pointers, one for each time read_pointer() was called. It is then the calling object's responsibility to store these pointers in the object properly.

We don't know what the final pointer will be yet, but we do know whether it was NULL, so this method returns true if the pointer is non-NULL, false if NULL.

Definition at line 609 of file bamReader.cxx.

References Thread::consider_yield(), and get_file_minor_ver().

Referenced by AnimChannelMatrixDynamic::fillin(), AnimChannelScalarDynamic::fillin(), GeomVertexColumn::fillin(), NodePath::fillin(), TextureProperties::fillin(), TransformBlend::fillin(), and read_pointers().

## ◆ read_pointers()

void BamReader::read_pointers | ( | DatagramIterator & | scan,
|  | int | count )

A convenience function to read a contiguous list of pointers.

This is equivalent to calling read_pointer() count times.

Definition at line 652 of file bamReader.cxx.

References read_pointer().

Referenced by PaletteGroups::fillin().

## ◆ register_change_this() [1/2]

void BamReader::register_change_this | ( | ChangeThisFunc | func,
|  | TypedWritable * | object )

Called by an object reading itself from the bam file to indicate that the object pointer that will be returned is temporary, and will eventually need to be replaced with another pointer.

The supplied function pointer will later be called on the object, immediately after complete_pointers() is called; it should return the new and final pointer.

We use a static function pointer instead of a virtual function (as in finalize()), to allow the function to destruct the old pointer if necessary. (It is invalid to destruct the this pointer within a virtual function.)

Definition at line 834 of file bamReader.cxx.

References TypedWritable::as_reference_count().

## ◆ register_change_this() [2/2]

void BamReader::register_change_this | ( | ChangeThisRefFunc | func,
|  | TypedWritableReferenceCount * | object )

Called by an object reading itself from the bam file to indicate that the object pointer that will be returned is temporary, and will eventually need to be replaced with another pointer.

The supplied function pointer will later be called on the object, immediately after complete_pointers() is called; it should return the new and final pointer.

We use a static function pointer instead of a virtual function (as in finalize()), to allow the function to destruct the old pointer if necessary. (It is invalid to destruct the this pointer within a virtual function.)

Definition at line 869 of file bamReader.cxx.

## ◆ register_factory()

void BamReader::register_factory | ( | TypeHandle | handle,
|  | WritableFactory::CreateFunc * | func,
|  | void * | user_data = nullptr )
| inline static

Registers a factory function that is called when an object of the given type is encountered within the .bam stream.

Parameters

  user_data | an optional pointer to be passed along to the function.

Definition at line 168 of file bamReader.I.

References get_factory(), and Factory< Type >::register_factory().

## ◆ register_finalize()

void BamReader::register_finalize | ( | TypedWritable * | whom | ) |

Should be called by an object reading itself from the Bam file to indicate that this particular object would like to receive the finalize() callback when all the objects and pointers in the Bam file are completely read.

This provides a hook for objects that need to do any additional finalization work after all of their related pointers are guaranteed to be filled in.

Definition at line 807 of file bamReader.cxx.

Referenced by RenderAttrib::change_this(), RenderEffect::change_this(), RenderEffects::change_this(), RenderState::change_this(), and CharacterJointBundle::make_CharacterJointBundle().

## ◆ register_pta()

void BamReader::register_pta | ( | void * | ptr | ) |

The second part of read_pta(), this should be called with the pointer to the array that was read in after read_pta() returned NULL.

This associates the pointer with the ID that was previously read, so that future calls to read_pta() will return the same pointer.

Also see the READ_PTA() macro, which consolidates all the work that must be done to read a PTA.

Definition at line 963 of file bamReader.cxx.

## ◆ resolve()

bool BamReader::resolve | ( |  | ) |

This may be called at any time during processing of the Bam file to resolve all the known pointers so far.

It is usually called at the end of the processing, after all objects have been read, which is generally the best time to call it.

This must be called at least once after reading a particular object via read_object() in order to validate that object.

The return value is true if all objects have been resolved, or false if some objects are still outstanding (in which case you will need to call resolve() again later).

Definition at line 324 of file bamReader.cxx.

References TypedWritable::as_reference_count().

Referenced by NodePath::decode_from_bam_stream(), and TypedWritable::decode_raw_from_bam_stream().

## ◆ set_aux_data()

void BamReader::set_aux_data | ( | TypedWritable * | obj,
|  | const std::string & | name,
|  | BamReader::AuxData * | data )

Associates an arbitrary block of data with the indicated object (or NULL), and the indicated name.

This is intended to provide a place for temporary storage for objects reading themselves from the bam file. To use it, inherit from BamReader::AuxData and store whatever data you like there. Then associate your AuxData with the object as it is being read with set_aux_data(). You may later set the aux data to NULL to remove it; or it will automatically be removed (and deleted) after finalize() is called for the object in question.

If the TypedWritable pointer is NULL, the the aux data is stored globally for the BamReader in general. This pointer is available to any bam objects, and will not be automatically removed until the BamReader itself destructs.

In either case, the name is just an arbitrary user-defined key. If there is already a data pointer stored for the obj/name pair, that data pointer will be replaced (and deleted).

Definition at line 166 of file bamReader.cxx.

Referenced by GeomNode::finalize().

## ◆ set_aux_tag()

void BamReader::set_aux_tag | ( | const std::string & | tag,
|  | BamReaderAuxData * | value )

Allows the creating object to store a temporary data value on the BamReader.

This method may be called during an object's fillin() method; it will associate a newly-allocated BamReaderAuxData construct with an arbitrary string key (which is in turn associated with the calling object only). Later, in the complete_pointers() method, the same object may query this data again via get_aux_tag().

The BamReader will maintain the reference count on the BamReaderAuxData, and destruct it when it is cleaned up.

The tag string need not be unique between different objects, but it should be unique between an object and its CData object(s).

Definition at line 771 of file bamReader.cxx.

## ◆ set_int_tag()

void BamReader::set_int_tag | ( | const std::string & | tag,
|  | int | value )

Allows the creating object to store a temporary data value on the BamReader.

This method may be called during an object's fillin() method; it will associate an integer value with an arbitrary string key (which is in turn associated with the calling object only). Later, in the complete_pointers() method, the same object may query this data again via get_int_tag().

The tag string need not be unique between different objects, but it should be unique between an object and its CData object(s).

Definition at line 730 of file bamReader.cxx.

## ◆ skip_pointer()

void BamReader::skip_pointer | ( | DatagramIterator & | scan | ) |

Reads and discards a pointer value from the Bam file.

This pointer will not be counted among the pointers read for a given object, and will not be in the list of pointers passed to complete_pointers().

Definition at line 664 of file bamReader.cxx.

## Member Data Documentation

## ◆ get_file_endian

BamReader::BamEndian BamReader::get_file_endian
| inline

Returns the endian preference indicated by the Bam file currently being read.

This does not imply that every number is stored using the indicated convention, but individual objects may choose to respect this flag when recording data.

Definition at line 159 of file bamReader.h.

## ◆ get_file_stdfloat_double

bool BamReader::get_file_stdfloat_double
| inline

Returns true if the file stores all "standard" floats as 64-bit doubles, or false if they are 32-bit floats.

This is determined by the compilation flags of the version of Panda that generated this file.

Definition at line 160 of file bamReader.h.

## ◆ get_file_version

BamReader::get_file_version

Definition at line 158 of file bamReader.h.

## ◆ get_filename

const Filename & BamReader::get_filename
| inline

If a BAM is a file, then the BamReader should contain the name of the file.

This enables the reader to interpret pathnames in the BAM as relative to the directory containing the BAM.

Definition at line 155 of file bamReader.h.

Referenced by read_handle().

## ◆ get_loader_options

const LoaderOptions & BamReader::get_loader_options
| inline

Returns the LoaderOptions passed to the loader when the model was requested, if any.

Definition at line 156 of file bamReader.h.

## ◆ get_source

DatagramGenerator * BamReader::get_source
| inline

Returns the current source of the BamReader as set by set_source() or the constructor.

Definition at line 154 of file bamReader.h.

## ◆ Null

BamReader *const BamReader::Null = nullptr
| static

Definition at line 113 of file bamReader.h.

## ◆ NullFactory

WritableFactory *const BamReader::NullFactory = nullptr
| static

Definition at line 114 of file bamReader.h.

## ◆ set_loader_options

void BamReader::set_loader_options
| inline

Specifies the LoaderOptions for this BamReader.

Definition at line 156 of file bamReader.h.

## ◆ set_source

void BamReader::set_source

Changes the source of future datagrams for this BamReader.

This also implicitly calls init() if it has not already been called.

Definition at line 154 of file bamReader.h.

Referenced by NodePath::decode_from_bam_stream(), and TypedWritable::decode_raw_from_bam_stream().

The documentation for this class was generated from the following files:

- panda/src/putil/bamReader.h
- panda/src/putil/bamReader.cxx
- panda/src/putil/bamReader.I