Tawara  0.1.0
Classes | Public Types | Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
tawara::Segment Class Reference

The Segment element. More...

#include <tawara/segment.h>

Inheritance diagram for tawara::Segment:
Inheritance graph
[legend]
Collaboration diagram for tawara::Segment:
Collaboration graph
[legend]

Classes

class  BlockIteratorBase
 
class  ClusterIteratorBase
 

Public Types

typedef boost::shared_ptr
< Segment
Ptr
 Pointer to a segment. More...
 
typedef ClusterIteratorBase
< MemoryCluster
MemClusterIterator
 Memory-based cluster iterator interface. More...
 
typedef ClusterIteratorBase
< FileCluster
FileClusterIterator
 File-based cluster iterator interface. More...
 
typedef BlockIteratorBase
< MemClusterIterator,
MemoryCluster::Iterator
MemBlockIterator
 Memory-based block iterator interface. More...
 
typedef BlockIteratorBase
< FileClusterIterator,
FileCluster::Iterator
FileBlockIterator
 File-based block iterator interface. More...
 

Public Member Functions

 Segment (std::streamsize pad_size=4096)
 Create a new segment element. More...
 
MemClusterIterator clusters_begin_mem (std::istream &stream)
 Access the start of the clusters. More...
 
MemClusterIterator clusters_end_mem (std::istream &stream)
 Access the end of the clusters. More...
 
MemBlockIterator blocks_begin_mem (std::istream &stream)
 Access the start of the blocks. More...
 
MemBlockIterator blocks_end_mem (std::istream &stream)
 Access the end of the blocks. More...
 
FileClusterIterator clusters_begin_file (std::istream &stream)
 Access the start of the clusters. More...
 
FileClusterIterator clusters_end_file (std::istream &stream)
 Access the end of the clusters. More...
 
FileBlockIterator blocks_begin_file (std::istream &stream)
 Access the start of the blocks. More...
 
FileBlockIterator blocks_end_file (std::istream &stream)
 Access the end of the blocks. More...
 
std::streamsize pad_size () const
 Get the padding size. More...
 
void pad_size (std::streamsize pad_size)
 Set the padding size. More...
 
std::streamsize size () const
 Get the total size of the element. More...
 
std::streamsize finalise (std::iostream &stream)
 Finalise writing of the segment. More...
 
std::streamsize to_segment_offset (std::streamsize stream_offset) const
 Calculate an offset within the segment. More...
 
std::streamsize to_stream_offset (std::streamsize seg_offset) const
 Calculate the offset in a stream of a position in the segment. More...
 
- Public Member Functions inherited from tawara::MasterElement
 MasterElement (uint32_t id, bool crc=false)
 Create a new MasterElement. More...
 
virtual ~MasterElement ()
 Destructor. More...
 
- Public Member Functions inherited from tawara::Element
 Element (tawara::ids::ID id)
 Create a new Element. More...
 
virtual ~Element ()
 Destructor. More...
 
uint32_t id () const
 Get the element's ID. More...
 
std::streampos offset () const
 Get the element's offset in the byte stream. More...
 
virtual std::streamsize write (std::ostream &output)
 Element writing. More...
 
virtual std::streamsize read (std::istream &input)
 Element reading. More...
 

Public Attributes

SeekHead index
 The segment index. More...
 
SegmentInfo info
 The segment information. More...
 

Protected Member Functions

std::streamsize body_size () const
 Get the size of the body of this element. More...
 
std::streamsize write_size (std::ostream &output)
 Element size writing. More...
 
std::streamsize write_body (std::ostream &output)
 Element body writing. More...
 
std::streamsize read_body (std::istream &input, std::streamsize size)
 Element body loading. More...
 
- Protected Member Functions inherited from tawara::Element
std::streamsize write_id (std::ostream &output)
 Element ID writing. More...
 

Protected Attributes

std::streamsize pad_size_
 The size of the padding to place at the start of the file. More...
 
std::streamsize size_
 The size of the segment, as read from the file. More...
 
bool writing_
 If the segment is currently being written. More...
 
- Protected Attributes inherited from tawara::Element
tawara::ids::ID id_
 
std::streampos offset_
 

Detailed Description

The Segment element.

A segment makes up the body of a Tawara document. It is the only top-level element, excluding the EBMLHeader. All other Tawara elements are contained within it. Usually, a Tawara document contains a single segment.

The segment contains all the document's blocks (stored in clusters), and all relevant meta-data, such as document information, tags, attachments and cue points.

Because the body of a segment contains data that arrives at differing times, segments cannot be written in a single operation. Instead, a segment is opened for writing by calling write(), which provides it with its target output byte stream. This prepares the byte stream for the segment to be written. Once writing is complete, the segment is finalised by calling finalise(). Finalising a segment completes it, writing such things as the segment's final size into the output stream.

Likewise, segments are not read in a single operation. Trying to do so for any reasonably-sized file would require a significant quantity of memory and be inefficient. Instead, the segment is opened for reading by calling the read() method, which prepares the segment for reading by the meta-seek element (if present) and filling in the index table. The child elements are then read directly from the file as needed. The segment does not need to be closed once reading is complete.

Definition at line 81 of file segment.h.

Member Typedef Documentation

File-based block iterator interface.

This interface provides access to the blocks in the segment, stored across all the clusters.

Definition at line 398 of file segment.h.

File-based cluster iterator interface.

This interface provides access to the clusters in the segment, with each cluster loading its blocks on demand.

Definition at line 266 of file segment.h.

Memory-based block iterator interface.

This interface provides access to the blocks in the segment, stored across all the clusters.

Definition at line 390 of file segment.h.

Memory-based cluster iterator interface.

This interface provides access to the clusters in the segment, with each cluster read entirely into memory.

Definition at line 259 of file segment.h.

typedef boost::shared_ptr<Segment> tawara::Segment::Ptr

Pointer to a segment.

Definition at line 85 of file segment.h.

Constructor & Destructor Documentation

tawara::Segment::Segment ( std::streamsize  pad_size = 4096)

Create a new segment element.

Parameters
[in]pad_sizeThe size of the padding to place at the start of the segment when opening it for writing.

Member Function Documentation

FileBlockIterator tawara::Segment::blocks_begin_file ( std::istream &  stream)

Access the start of the blocks.

Gets an iterator pointing to the first block in the segment, using the file-based cluster implementation.

MemBlockIterator tawara::Segment::blocks_begin_mem ( std::istream &  stream)

Access the start of the blocks.

Gets an iterator pointing to the first block in the segment, using the memory-based cluster implementation.

FileBlockIterator tawara::Segment::blocks_end_file ( std::istream &  stream)

Access the end of the blocks.

Gets an iterator pointing to the last block in the segment, using the file-based cluster implementation.

MemBlockIterator tawara::Segment::blocks_end_mem ( std::istream &  stream)

Access the end of the blocks.

Gets an iterator pointing to the last block in the segment, using the memory-based cluster implementation.

std::streamsize tawara::Segment::body_size ( ) const
inlineprotectedvirtual

Get the size of the body of this element.

This function will not return the actual size of the segment until either the segment is read from a Tawara document or it is finalised in a Tawara document.

Implements tawara::Element.

Definition at line 549 of file segment.h.

FileClusterIterator tawara::Segment::clusters_begin_file ( std::istream &  stream)

Access the start of the clusters.

Gets an iterator pointing to the first cluster in the segment, using the file-based cluster implementation.

MemClusterIterator tawara::Segment::clusters_begin_mem ( std::istream &  stream)

Access the start of the clusters.

Gets an iterator pointing to the first cluster in the segment, using the memory-based cluster implementation.

FileClusterIterator tawara::Segment::clusters_end_file ( std::istream &  stream)

Access the end of the clusters.

Gets an iterator pointing to the last cluster in the segment, using the file-based cluster implementation.

MemClusterIterator tawara::Segment::clusters_end_mem ( std::istream &  stream)

Access the end of the clusters.

Gets an iterator pointing to the last cluster in the segment, using the memory-based cluster implementation.

std::streamsize tawara::Segment::finalise ( std::iostream &  stream)

Finalise writing of the segment.

Calculates the total size of the segment and writes it into the segment header, followed by writing in the SeekHead element as the first child of the Segment, thus finalising the segment.

The write pointer in stream must be positioned at the first byte after the last byte of the segment before this method is called.

Parameters
[in]streamThe byte stream to write the segment to.
Returns
The final size, in bytes, of the segment (including the element header).
Exceptions
NotWritingif the segment has not yet been opened for writing by calling write().
std::streamsize tawara::Segment::pad_size ( ) const
inline

Get the padding size.

When the segment is opened for writing, it places a certain quantity of padding at the start of the segment using a Void element. This padding is over-written during finalisation with the SeekHead and SegmentInfo elements. The length of the padding is controlled by this property. Setting it to a value that is too small for one or both of the SeekHead and SegmentInfo elements will result in those that don't fit being written at the end of the segment. In the case of the SeekHead, this can significantly degrade start-up performance when reading the segment.

Definition at line 476 of file segment.h.

void tawara::Segment::pad_size ( std::streamsize  pad_size)
inline

Set the padding size.

Definition at line 478 of file segment.h.

std::streamsize tawara::Segment::read_body ( std::istream &  input,
std::streamsize  size 
)
protectedvirtual

Element body loading.

This function does not actually read the body of the segment. Instead, it reads some of the level 1 elements and validates that the segment is usable:

  • Reads the meta-seek element (if present), filling in the segment's index.
  • Reads the SegmentInfo element. If not present, raises an error.
  • Checks for the existence of the Tracks element. Raises an error if not present. Checks for the existence of at least one Cluster element. Raises an error if not present.

When this function returns, the stream's read pointer will be placed at the end of the SegmentInformation element, unless the SeekHead element occurs after it, in which case it will be placed at the end of the SeekHead element.

Returns
The number of bytes read from the stream, excluding bytes read during element presence checks. In other words, this is the number of bytes into the segment that the read pointer has moved.
Exceptions
MultipleSeekHeadsif the segment has more than one index.
NoSegmentInfoif the SegmentInfo element is not found.
NoTracksif the Tracks element is not found.
NoClustersif at least one Cluster element is not found.

Implements tawara::Element.

std::streamsize tawara::Segment::size ( ) const
virtual

Get the total size of the element.

Reimplemented from tawara::Element.

std::streamsize tawara::Segment::to_segment_offset ( std::streamsize  stream_offset) const

Calculate an offset within the segment.

This function turns an offset in the output stream into an offset in this segment, which is necessary for the index.

std::streamsize tawara::Segment::to_stream_offset ( std::streamsize  seg_offset) const

Calculate the offset in a stream of a position in the segment.

This function turns an offset within the segment into an absolute position in a byte stream.

std::streamsize tawara::Segment::write_body ( std::ostream &  output)
protectedvirtual

Element body writing.

This function, which opens up a segment for writing, does not actually write any final content. Instead, it preserves a chunk of space at the beginning of the file using a Void element for the SeekHead and SegmentInfo elements to be written into by finalise().

The size of space reserved is controlled by pad_size().

Implements tawara::Element.

std::streamsize tawara::Segment::write_size ( std::ostream &  output)
protectedvirtual

Element size writing.

Reimplemented from tawara::Element.

Member Data Documentation

SeekHead tawara::Segment::index

The segment index.

All known level 1 elements are included in this index. It is a mapping from element ID (the key) to position, in bytes, in the segment (the value). The first level 1 element has a position of 0. An ID may occur multiple times.

There may be additional level 1 elements that are not mentioned in this index. Typically, all but the first cluster are not found in the index.

Definition at line 511 of file segment.h.

SegmentInfo tawara::Segment::info

The segment information.

This property stores all the segment's meta-data, such as the origin timecode of the segment and its timecode scale.

Definition at line 518 of file segment.h.

std::streamsize tawara::Segment::pad_size_
protected

The size of the padding to place at the start of the file.

Definition at line 537 of file segment.h.

std::streamsize tawara::Segment::size_
protected

The size of the segment, as read from the file.

Definition at line 539 of file segment.h.

bool tawara::Segment::writing_
protected

If the segment is currently being written.

Definition at line 541 of file segment.h.


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