Tide 0.1.0
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes

tide::Segment Class Reference

The Segment element. More...

#include <tide/segment.h>

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

List of all members.

Public Member Functions

 Segment (std::streamsize pad_size=4096)
 Create a new segment element.
std::streamsize pad_size () const
 Get the padding size.
void pad_size (std::streamsize pad_size)
 Set the padding size.
std::streamsize size () const
 Get the total size of the element.
std::streamsize finalise (std::iostream &stream)
 Finalise writing of the segment.
std::streamsize to_segment_offset (std::streamsize stream_offset)
 Calculate an offset within the segment.
std::streamsize to_stream_offset (std::streamsize seg_offset)
 Calculate the offset in a stream of a position in the segment.

Public Attributes

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

Protected Member Functions

std::streamsize body_size () const
 Get the size of the body of this element.
std::streamsize write_size (std::ostream &output)
 Element size writing.
std::streamsize write_body (std::ostream &output)
 Element body writing.
std::streamsize read_body (std::istream &input, std::streamsize size)
 Element body loading.

Protected Attributes

std::streamsize pad_size_
 The size of the padding to place at the start of the file.
std::streamsize size_
 The size of the segment, as read from the file.
bool writing_
 If the segment is currently being written.

Detailed Description

The Segment element.

A segment makes up the body of a Tide document. It is the only top-level element, excluding the EBMLHeader. All other Tide elements are contained within it. Usually, a Tide 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 68 of file segment.h.


Constructor & Destructor Documentation

tide::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

std::streamsize tide::Segment::body_size ( ) const [inline, protected, virtual]

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 Tide document or it is finalised in a Tide document.

Implements tide::Element.

Definition at line 164 of file segment.h.

std::streamsize tide::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 tide::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 91 of file segment.h.

void tide::Segment::pad_size ( std::streamsize  pad_size) [inline]

Set the padding size.

Definition at line 93 of file segment.h.

std::streamsize tide::Segment::read_body ( std::istream &  input,
std::streamsize  size 
) [protected, virtual]

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 tide::Element.

std::streamsize tide::Segment::size ( ) const [virtual]

Get the total size of the element.

Reimplemented from tide::Element.

std::streamsize tide::Segment::to_segment_offset ( std::streamsize  stream_offset)

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 tide::Segment::to_stream_offset ( std::streamsize  seg_offset)

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 tide::Segment::write_body ( std::ostream &  output) [protected, virtual]

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 tide::Element.

std::streamsize tide::Segment::write_size ( std::ostream &  output) [protected, virtual]

Element size writing.

Reimplemented from tide::Element.


Member Data Documentation

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 126 of file segment.h.

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 133 of file segment.h.

std::streamsize tide::Segment::pad_size_ [protected]

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

Definition at line 152 of file segment.h.

std::streamsize tide::Segment::size_ [protected]

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

Definition at line 154 of file segment.h.

bool tide::Segment::writing_ [protected]

If the segment is currently being written.

Definition at line 156 of file segment.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines