Panda3D
Classes | Public Member Functions | Static Public Member Functions | Public Attributes | Friends | List of all members
BamWriter Class Reference

This is the fundamental interface for writing binary objects to a Bam file, to be extracted later by a BamReader. More...

#include "bamWriter.h"

Inheritance diagram for BamWriter:
BamEnums

Public Member Functions

 BamWriter (DatagramSink *target=nullptr)
 
void consider_update (const TypedWritable *obj)
 Should be called from TypedWritable::update_bam_nested() to recursively check the entire hiererachy of writable objects for needed updates. More...
 
void flush ()
 Ensures that all data written thus far is manifested on the output stream. More...
 
BamEndian get_file_endian () const
 
int get_file_major_ver () const
 Returns the major version number of the Bam file currently being written. More...
 
int get_file_minor_ver () const
 Returns the minor version number of the Bam file currently being written. More...
 
bool get_file_stdfloat_double () const
 
BamTextureMode get_file_texture_mode () const
 
const Filenameget_filename () const
 
TypedWritableget_root_node () const
 
DatagramSinkget_target ()
 
bool has_object (const TypedWritable *obj) const
 Returns true if the object has previously been written (or at least requested to be written) to the bam file, or false if we've never heard of it before. More...
 
bool init ()
 Initializes the BamWriter prior to writing any objects to its output stream. More...
 
bool register_pta (Datagram &packet, const void *ptr)
 Prepares to write a PointerToArray to the Bam file, unifying references to the same pointer across the Bam file. More...
 
void set_file_minor_ver (int minor_ver)
 Changes the minor .bam version to write. More...
 
void set_file_texture_mode (BamTextureMode file_texture_mode)
 Changes the BamTextureMode preference for the Bam file currently being written. More...
 
void set_root_node (TypedWritable *root_node)
 
void set_target (DatagramSink *target)
 
void write_cdata (Datagram &packet, const PipelineCyclerBase &cycler)
 Writes out the indicated CycleData object. More...
 
void write_cdata (Datagram &packet, const PipelineCyclerBase &cycler, void *extra_data)
 This version of write_cdata allows passing an additional parameter to cdata->write_datagram(). More...
 
void write_file_data (SubfileInfo &result, const Filename &filename)
 Writes a block of auxiliary file data from the indicated file (within the vfs). More...
 
void write_file_data (SubfileInfo &result, const SubfileInfo &source)
 Writes a block of auxiliary file data from the indicated file (outside of the vfs). More...
 
void write_handle (Datagram &packet, TypeHandle type)
 Writes a TypeHandle to the file in such a way that the BamReader can read the same TypeHandle later via read_handle(). More...
 
bool write_object (const TypedWritable *obj)
 Writes a single object to the Bam file, so that the BamReader::read_object() can later correctly restore the object and all its pointers. More...
 
void write_pointer (Datagram &packet, const TypedWritable *dest)
 The interface for writing a pointer to another object to a Bam file. More...
 

Static Public Member Functions

static std::string get_obsolete_type_name (TypeHandle type, int major, int minor)
 Returns the name that the given type had in an older .bam version. More...
 
static void record_obsolete_type_name (TypeHandle type, std::string name, int before_major, int before_minor)
 Registers the given type as having an older name in .bam files *before* the indicated version. More...
 

Public Attributes

 get_file_endian
 Returns the endian preference indicated by the Bam file currently being written. More...
 
 get_file_stdfloat_double
 Returns true if the file will store all "standard" floats as 64-bit doubles, or false if they are 32-bit floats. More...
 
 get_file_texture_mode
 Returns the BamTextureMode preference indicated by the Bam file currently being written. More...
 
 get_filename
 If a BAM is a file, then the BamWriter should contain the name of the file. More...
 
 get_root_node
 Returns the root node of the part of the scene graph we are currently writing out. More...
 
 get_target
 Returns the current target of the BamWriter as set by set_target() or the constructor. More...
 
 set_root_node
 Sets the root node of the part of the scene graph we are currently writing out. More...
 
 set_target
 Changes the destination of future datagrams written by the BamWriter. More...
 

Friends

class TypedWritable
 

Additional Inherited Members

- Public Types inherited from BamEnums
enum  BamEndian { BE_bigendian = 0, BE_littleendian = 1, BE_native = 1 }
 
enum  BamObjectCode {
  BOC_push, BOC_pop, BOC_adjunct, BOC_remove,
  BOC_file_data
}
 
enum  BamTextureMode {
  BTM_unchanged, BTM_fullpath, BTM_relative, BTM_basename,
  BTM_rawdata
}
 

Detailed Description

This is the fundamental interface for writing binary objects to a Bam file, to be extracted later by a BamReader.

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; the BamWriter automatically manages these (with help from code within each class) and writes all referenced objects to the file in such a way that the pointers may be correctly restored later.

This is the abstract interface and does not specifically deal with disk files, but rather with a DatagramSink of some kind, which simply accepts a linear stream of Datagrams. It is probably written to a disk file, but it might conceivably be streamed directly to 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 63 of file bamWriter.h.

Member Function Documentation

◆ consider_update()

void BamWriter::consider_update ( const TypedWritable object)

Should be called from TypedWritable::update_bam_nested() to recursively check the entire hiererachy of writable objects for needed updates.

This tests the indicated TypedWritable object and writes it to the bam stream if it has recently been modified, then recurses through update_bam_nested.

Definition at line 279 of file bamWriter.cxx.

References TypedWritable::get_bam_modified().

◆ flush()

void BamWriter::flush ( void  )

Ensures that all data written thus far is manifested on the output stream.

Definition at line 267 of file bamWriter.cxx.

◆ get_file_major_ver()

int BamWriter::get_file_major_ver ( ) const
inline

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

Definition at line 41 of file bamWriter.I.

◆ get_file_minor_ver()

int BamWriter::get_file_minor_ver ( ) const
inline

◆ get_obsolete_type_name()

std::string BamWriter::get_obsolete_type_name ( TypeHandle  type,
int  major,
int  minor 
)
static

Returns the name that the given type had in an older .bam version.

Definition at line 551 of file bamWriter.cxx.

◆ has_object()

bool BamWriter::has_object ( const TypedWritable obj) const

Returns true if the object has previously been written (or at least requested to be written) to the bam file, or false if we've never heard of it before.

Definition at line 258 of file bamWriter.cxx.

◆ init()

bool BamWriter::init ( )

Initializes the BamWriter prior to writing any objects to its output stream.

This includes writing out the Bam header.

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

Definition at line 147 of file bamWriter.cxx.

◆ record_obsolete_type_name()

void BamWriter::record_obsolete_type_name ( TypeHandle  type,
std::string  name,
int  before_major,
int  before_minor 
)
static

Registers the given type as having an older name in .bam files *before* the indicated version.

You can call this multiple times for the same type in order to establish a history of renames for this type.

Definition at line 574 of file bamWriter.cxx.

References TypeRegistry::ptr(), and TypeRegistry::record_alternate_name().

Referenced by init_libcollide().

◆ register_pta()

bool BamWriter::register_pta ( Datagram packet,
const void *  ptr 
)

Prepares to write a PointerToArray to the Bam file, unifying references to the same pointer across the Bam file.

The writing object should call this prior to writing out a PointerToArray. It will return true if the same pointer has been written previously, in which case the writing object need do nothing further; or it will return false if this particular pointer has not yet been written, in which case the writing object must then write out the contents of the array.

Also see the WRITE_PTA() macro, which consolidates the work that must be done to write a PTA.

Definition at line 457 of file bamWriter.cxx.

◆ set_file_minor_ver()

void BamWriter::set_file_minor_ver ( int  minor_ver)
inline

Changes the minor .bam version to write.

This should be called before init(). Each Panda version has only a fairly narrow range of versions it is able to write; consult the .bam documentation for more information.

Definition at line 51 of file bamWriter.I.

◆ set_file_texture_mode()

void BamWriter::set_file_texture_mode ( BamTextureMode  file_texture_mode)
inline

Changes the BamTextureMode preference for the Bam file currently being written.

Texture objects written to this Bam file will be encoded according to the specified mode.

Definition at line 101 of file bamWriter.I.

◆ write_cdata() [1/2]

void BamWriter::write_cdata ( Datagram packet,
const PipelineCyclerBase cycler 
)

◆ write_cdata() [2/2]

void BamWriter::write_cdata ( Datagram packet,
const PipelineCyclerBase cycler,
void *  extra_data 
)

This version of write_cdata allows passing an additional parameter to cdata->write_datagram().

Definition at line 436 of file bamWriter.cxx.

References PipelineCyclerTrivialImpl::read(), PipelineCyclerTrivialImpl::release_read(), and CycleData::write_datagram().

◆ write_file_data() [1/2]

void BamWriter::write_file_data ( SubfileInfo result,
const Filename filename 
)

Writes a block of auxiliary file data from the indicated file (within the vfs).

This can be a block of arbitrary size, and it is assumed it may be quite large. This must be balanced by a matching call to read_file_data() on restore.

Definition at line 363 of file bamWriter.cxx.

References Datagram::add_uint8(), and DatagramSink::copy_datagram().

Referenced by MovieVideo::write_datagram().

◆ write_file_data() [2/2]

void BamWriter::write_file_data ( SubfileInfo result,
const SubfileInfo source 
)

Writes a block of auxiliary file data from the indicated file (outside of the vfs).

This can be a block of arbitrary size, and it is assumed it may be quite large. This must be balanced by a matching call to read_file_data() on restore.

Definition at line 394 of file bamWriter.cxx.

References Datagram::add_uint8(), and DatagramSink::copy_datagram().

◆ write_handle()

void BamWriter::write_handle ( Datagram packet,
TypeHandle  type 
)

Writes a TypeHandle to the file in such a way that the BamReader can read the same TypeHandle later via read_handle().

Definition at line 504 of file bamWriter.cxx.

References TypeHandle::get_index.

Referenced by RecorderTable::write_datagram().

◆ write_object()

bool BamWriter::write_object ( const TypedWritable object)

Writes a single object to the Bam file, so that the BamReader::read_object() can later correctly restore the object and all its pointers.

This implicitly also writes any additional objects this object references (if they haven't already been written), so that pointers may be fully resolved.

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

Returns true if the object is successfully written, false otherwise.

Definition at line 204 of file bamWriter.cxx.

Referenced by BamFile::write_object().

◆ write_pointer()

void BamWriter::write_pointer ( Datagram packet,
const TypedWritable object 
)

The interface for writing a pointer to another object to a Bam file.

This is intended to be called by the various objects that write themselves to the Bam file, within the write_datagram() method.

This writes the pointer out in such a way that the BamReader will be able to restore the pointer later. If the pointer is to an object that has not yet itself been written to the Bam file, that object will automatically be written.

Definition at line 317 of file bamWriter.cxx.

References TypedWritable::get_bam_modified().

Referenced by ParamNodePath::write_datagram(), CharacterVertexSlider::write_datagram(), ParamTextureSampler::write_datagram(), AnimBundleNode::write_datagram(), RecorderFrame::write_datagram(), SourceTextureImage::write_datagram(), JointVertexTransform::write_datagram(), DataNodeTransmit::write_datagram(), FogAttrib::write_datagram(), BamCacheIndex::write_datagram(), MaterialAttrib::write_datagram(), BulletTriangleMeshShape::write_datagram(), BulletMinkowskiSumShape::write_datagram(), PalettePage::write_datagram(), CharacterJointEffect::write_datagram(), OccluderEffect::write_datagram(), AnimChannelScalarDynamic::write_datagram(), PartBundleNode::write_datagram(), PaletteGroups::write_datagram(), LensNode::write_datagram(), AnimChannelMatrixDynamic::write_datagram(), CharacterJoint::write_datagram(), TextureProperties::write_datagram(), GeomVertexColumn::write_datagram(), TransformTable::write_datagram(), MovingPartBase::write_datagram(), EggFile::write_datagram(), TexMatrixAttrib::write_datagram(), SliderTable::write_datagram(), TextureReference::write_datagram(), PaletteGroup::write_datagram(), TexturePlacement::write_datagram(), ParamTextureImage::write_datagram(), TexGenAttrib::write_datagram(), MovieVideoCursor::write_datagram(), TransformBlend::write_datagram(), Camera::write_datagram(), ClipPlaneAttrib::write_datagram(), Palettizer::write_datagram(), LightAttrib::write_datagram(), TextureAttrib::write_datagram(), GeomVertexArrayData::write_datagram(), PartBundle::write_datagram(), TextureStage::write_datagram(), GeomVertexFormat::write_datagram(), and NodePath::write_datagram().

Member Data Documentation

◆ get_file_endian

BamWriter::BamEndian BamWriter::get_file_endian
inline

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

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 93 of file bamWriter.h.

◆ get_file_stdfloat_double

bool BamWriter::get_file_stdfloat_double
inline

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

This isn't runtime settable; it's based on the compilation flags of the version of Panda that generated this file.

Definition at line 94 of file bamWriter.h.

◆ get_file_texture_mode

BamWriter::BamTextureMode BamWriter::get_file_texture_mode
inline

Returns the BamTextureMode preference indicated by the Bam file currently being written.

Texture objects written to this Bam file will be encoded according to the specified mode.

Definition at line 95 of file bamWriter.h.

◆ get_filename

const Filename & BamWriter::get_filename
inline

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

This enables the writer to convert pathnames in the BAM to relative to the directory containing the BAM.

Definition at line 92 of file bamWriter.h.

◆ get_root_node

TypedWritable * BamWriter::get_root_node
inline

Returns the root node of the part of the scene graph we are currently writing out.

This is used for determining what to make NodePaths relative to.

Definition at line 96 of file bamWriter.h.

◆ get_target

DatagramSink * BamWriter::get_target
inline

Returns the current target of the BamWriter as set by set_target() or the constructor.

Definition at line 91 of file bamWriter.h.

◆ set_root_node

void BamWriter::set_root_node
inline

Sets the root node of the part of the scene graph we are currently writing out.

NodePaths written to this bam file will be relative to this node.

Definition at line 96 of file bamWriter.h.

◆ set_target

void BamWriter::set_target

Changes the destination of future datagrams written by the BamWriter.

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

Definition at line 91 of file bamWriter.h.


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