Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File 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>

List of all members.

Public Types

typedef Factory< TypedWritable > WritableFactory
typedef TypedWritable *(* ChangeThisFunc )(TypedWritable *object, BamReader *manager)

Public Member Functions

 BamReader (DatagramGenerator *generator)
 ~BamReader ()
bool init ()
 Initializes the BamReader prior to reading any objects from its source.

TypedWritable * read_object ()
 Reads a single object from the Bam file.

bool is_eof () const
 Returns true if the reader has reached end-of-file, false otherwise.

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

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.

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.

void 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 skip_pointer (DatagramIterator &scan)
 Reads and discards a pointer value from the Bam file.

void read_cdata (DatagramIterator &scan, PipelineCyclerBase &cycler)
 Reads in the indicated CycleData object.

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_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 finalize_now (TypedWritable *whom)
 Forces the finalization of a particular object.

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.

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.

TypeHandle read_handle (DatagramIterator &scan)
 Reads a TypeHandle out of the Datagram.


Static Public Member Functions

WritableFactory * get_factory ()
 Returns the global WritableFactory for generating TypedWritable objects.


Static Public Attributes

BamReader *const Null = (BamReader*)0L
WritableFactory *const NullFactory = (WritableFactory*)0L

Private Types

typedef pmap< int, TypeHandle > IndexMap
typedef pmap< int, CreatedObj > CreatedObjs
typedef pmap< int, vector_int > ObjectPointers
typedef pmap< PipelineCyclerBase *,
vector_int > 		CyclerPointers
typedef pset< TypedWritable * > Finalize
typedef pmap< int, void * > PTAMap
typedef pset< TypeHandle > NewTypes

Private Member Functions

int p_read_object ()
 The private implementation of read_object(), this reads an object from the file and returns its object ID.

bool resolve_object_pointers (TypedWritable *object, const vector_int &pointer_ids)
 Checks whether all of the pointers a particular object is waiting for have been filled in yet.

bool resolve_cycler_pointers (PipelineCyclerBase *cycler, const vector_int &pointer_ids)
 Checks whether all of the pointers a particular PipelineCycler is waiting for have been filled in yet.

void finalize ()
 Should be called after all objects have been read, this will finalize all the objects that registered themselves for the finalize callback.


Static Private Member Functions

void create_factory ()
 Creates a new WritableFactory for generating TypedWritable objects.


Private Attributes

DatagramGenerator * _source
IndexMap _index_map
CreatedObjs _created_objs
CreatedObjs::iterator _now_creating
PipelineCyclerBase * _reading_cycler
ObjectPointers _object_pointers
CyclerPointers _cycler_pointers
int _num_extra_objects
Finalize _finalize_list
PTAMap _pta_map
int _pta_id
int _file_major
int _file_minor

Static Private Attributes

WritableFactory * _factory = (WritableFactory*)0L
NewTypes _new_types
const int _cur_major = _bam_major_ver
const int _cur_minor = _bam_minor_ver

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 124 of file bamReader.h.

Member Typedef Documentation

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

Definition at line 157 of file bamReader.h.

typedef pmap<int, CreatedObj> BamReader::CreatedObjs [private]
 

Definition at line 196 of file bamReader.h.

typedef pmap<PipelineCyclerBase *, vector_int> BamReader::CyclerPointers [private]
 

Definition at line 215 of file bamReader.h.

typedef pset<TypedWritable *> BamReader::Finalize [private]
 

Definition at line 225 of file bamReader.h.

typedef pmap<int, TypeHandle> BamReader::IndexMap [private]
 

Definition at line 186 of file bamReader.h.

typedef pset<TypeHandle> BamReader::NewTypes [private]
 

Definition at line 238 of file bamReader.h.

typedef pmap<int, vector_int> BamReader::ObjectPointers [private]
 

Definition at line 211 of file bamReader.h.

typedef pmap<int, void *> BamReader::PTAMap [private]
 

Definition at line 230 of file bamReader.h.

typedef Factory<TypedWritable> BamReader::WritableFactory
 

Definition at line 126 of file bamReader.h.

Constructor & Destructor Documentation

BamReader::BamReader (  DatagramGenerator *  generator  ) 
 

Definition at line 49 of file bamReader.cxx.

References _pta_id, _reading_cycler, and NULL.

BamReader::~BamReader (   ) 
 

Definition at line 67 of file bamReader.cxx.

References _source, DatagramGenerator::get_datagram(), and DatagramGenerator::is_error().

Member Function Documentation

void BamReader::create_factory (   )  [inline, static, private]
 

Creates a new WritableFactory for generating TypedWritable objects.

Definition at line 136 of file bamReader.I.

Referenced by get_current_major_ver().

void BamReader::finalize (  void   )  [private]
 

Should be called after all objects have been read, this will finalize all the objects that registered themselves for the finalize callback.

Definition at line 1098 of file bamReader.cxx.

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 695 of file bamReader.cxx.

References BamReader::CreatedObj::_change_this, _created_objs, _factory, _now_creating, _object_pointers, BamReader::CreatedObj::_ptr, FactoryParams::add_param(), Factory< TypedWritable >::make_instance_more_general(), nassertr, and NULL.

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 85 of file bamReader.I.

References _factory, create_factory(), INLINE, and NullFactory.

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 104 of file bamReader.I.

References DCAST, BamReaderParam::get_iterator(), FactoryParams::get_param(), and INLINE.

WritableFactory * BamReader::get_factory (  void   )  [inline, static]
 

Returns the global WritableFactory for generating TypedWritable objects.

Definition at line 119 of file bamReader.I.

Referenced by TransparencyAttrib::compare_to_impl(), TextureAttrib::compare_to_impl(), TextureApplyAttrib::compare_to_impl(), ShowBoundsEffect::compare_to_impl(), MaterialAttrib::compare_to_impl(), FogAttrib::compare_to_impl(), DepthWriteAttrib::compare_to_impl(), DepthTestAttrib::compare_to_impl(), CullBinAttrib::compare_to_impl(), ColorWriteAttrib::compare_to_impl(), ColorBlendAttrib::compare_to_impl(), BillboardEffect::compare_to_impl(), AlphaTestAttrib::compare_to_impl(), TexMatrixAttrib::compose_impl(), DepthOffsetAttrib::compose_impl(), CullFaceAttrib::compose_impl(), CollisionRay::fill_viz_geom(), CharacterJointBundle::make_CharacterJointBundle(), CharacterSlider::make_CharacterSlider(), ModelRoot::make_copy(), GeomPolygon::make_GeomPolygon(), GeomSphere::make_GeomSphere(), MovingPartMatrix::make_MovingPartMatrix(), MovingPartScalar::make_MovingPartScalar(), PNMFileTypeJPG2000::matches_magic_number(), PNMFileTypeJPG::matches_magic_number(), PNMFileTypeBMP::matches_magic_number(), LensNode::output(), AnimBundleNode::safe_to_flatten(), ModelNode::safe_to_modify_transform(), PNMFileTypeIMG::Writer::supports_write_row(), AmbientLight::write(), GeomNode::write_geoms(), PointLight::xform(), PlaneNode::xform(), and DirectionalLight::xform().

int BamReader::get_file_major_ver (   )  const [inline]
 

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

Definition at line 51 of file bamReader.I.

References _file_minor.

int BamReader::get_file_minor_ver (   )  const [inline]
 

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

Definition at line 66 of file bamReader.I.

References _cur_minor, and INLINE.

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 746 of file bamReader.cxx.

References NULL.

bool BamReader::init (  void   ) 
 

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 89 of file bamReader.cxx.

References _file_major, and _file_minor.

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 36 of file bamReader.I.

References _file_major, and INLINE.

int BamReader::p_read_object (   )  [private]
 

The private implementation of read_object(), this reads an object from the file and returns its object ID.

Definition at line 818 of file bamReader.cxx.

References NULL.

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 582 of file bamReader.cxx.

References _pta_id, _pta_map, DatagramIterator::get_uint16(), nassertr, and NULL.

Referenced by SequenceNode::has_single_child_visibility(), GeomNode::output(), PointLight::register_with_read_factory(), PlaneNode::register_with_read_factory(), DirectionalLight::register_with_read_factory(), and PandaNode::reparent().

TypeHandle BamReader::read_handle (  DatagramIterator &  scan  ) 
 

Reads a TypeHandle out of the Datagram.

Definition at line 379 of file bamReader.cxx.

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

Definition at line 189 of file bamReader.cxx.

References TypedWritable::get_type(), and NULL.

void 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 time read_pointer() was called. It is then the calling object's responsibilty to store these pointers in the object properly.

Definition at line 500 of file bamReader.cxx.

References _finalize_list, and TypedWritable::Null.

Referenced by GeomNode::CData::complete_pointers(), PiecewiseCurve::find_curve(), CharacterJoint::has_local_transform(), TextureAttrib::write_datagram(), MaterialAttrib::write_datagram(), FogAttrib::write_datagram(), and AnimGroup::write_descendants().

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 540 of file bamReader.cxx.

References BamReader::CreatedObj::_ptr, and NULL.

void BamReader::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.

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 661 of file bamReader.cxx.

References _source.

Referenced by RenderEffects::register_with_read_factory().

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 (like Characters) that need to do any additional finalization work after all of their related pointers are guaranteed to be filled in.

Definition at line 618 of file bamReader.cxx.

Referenced by TransformState::calc_components(), RenderEffects::determine_compass(), and CharacterJointBundle::make_copy().

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 795 of file bamReader.cxx.

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 get_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 276 of file bamReader.cxx.

References _cycler_pointers.

Referenced by BamFile::read_object().

bool BamReader::resolve_cycler_pointers (  PipelineCyclerBase *  cycler,
const vector_int &  pointer_ids
)  [private]
 

Checks whether all of the pointers a particular PipelineCycler is waiting for have been filled in yet.

If they have, calls complete_pointers() on the cycler and returns true; otherwise, returns false.

Definition at line 1029 of file bamReader.cxx.

bool BamReader::resolve_object_pointers (  TypedWritable *  object,
const vector_int &  pointer_ids
)  [private]
 

Checks whether all of the pointers a particular object is waiting for have been filled in yet.

If they have, calls complete_pointers() on the object and returns true; otherwise, returns false.

Definition at line 961 of file bamReader.cxx.

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 561 of file bamReader.cxx.

References _finalize_list, TypedWritable::finalize(), nassertv, and NULL.

Member Data Documentation

CreatedObjs BamReader::_created_objs [private]
 

Definition at line 197 of file bamReader.h.

Referenced by finalize_now().

const int BamReader::_cur_major = _bam_major_ver [static, private]
 

Definition at line 37 of file bamReader.cxx.

const int BamReader::_cur_minor = _bam_minor_ver [static, private]
 

Definition at line 38 of file bamReader.cxx.

Referenced by get_file_minor_ver().

CyclerPointers BamReader::_cycler_pointers [private]
 

Definition at line 216 of file bamReader.h.

Referenced by resolve().

WritableFactory * BamReader::_factory = (WritableFactory*)0L [static, private]
 

Definition at line 31 of file bamReader.cxx.

Referenced by finalize_now(), and get_current_major_ver().

int BamReader::_file_major [private]
 

Definition at line 241 of file bamReader.h.

Referenced by init(), and is_eof().

int BamReader::_file_minor [private]
 

Definition at line 241 of file bamReader.h.

Referenced by get_file_major_ver(), and init().

Finalize BamReader::_finalize_list [private]
 

Definition at line 226 of file bamReader.h.

Referenced by read_pointer(), and skip_pointer().

IndexMap BamReader::_index_map [private]
 

Definition at line 187 of file bamReader.h.

BamReader::NewTypes BamReader::_new_types [static, private]
 

Definition at line 35 of file bamReader.cxx.

CreatedObjs::iterator BamReader::_now_creating [private]
 

Definition at line 202 of file bamReader.h.

Referenced by finalize_now().

int BamReader::_num_extra_objects [private]
 

Definition at line 221 of file bamReader.h.

ObjectPointers BamReader::_object_pointers [private]
 

Definition at line 212 of file bamReader.h.

Referenced by finalize_now().

int BamReader::_pta_id [private]
 

Definition at line 232 of file bamReader.h.

Referenced by BamReader(), and read_cdata().

PTAMap BamReader::_pta_map [private]
 

Definition at line 231 of file bamReader.h.

Referenced by read_cdata().

PipelineCyclerBase* BamReader::_reading_cycler [private]
 

Definition at line 205 of file bamReader.h.

Referenced by BamReader().

DatagramGenerator* BamReader::_source [private]
 

Definition at line 182 of file bamReader.h.

Referenced by register_change_this(), and ~BamReader().

BamReader *const BamReader::Null = (BamReader*)0L [static]
 

Definition at line 32 of file bamReader.cxx.

WritableFactory *const BamReader::NullFactory = (WritableFactory*)0L [static]
 

Definition at line 33 of file bamReader.cxx.

Referenced by get_current_major_ver().

The documentation for this class was generated from the following files:
Generated on Fri May 2 00:47:32 2003 for Panda by doxygen1.3