Codec Toolkit references

  • NB: Document concerns OpenViBE 1.0.0 (doc updated 07.May.2015).

This reference page is divided in the following sections :

The superclass :

And its subclasses for the two subtypes of codec :

And their subclasses for each stream codec :

Introduction

Before starting to use the codec toolkit, every developer should understand how the streams are organized in OpenViBE. See the dedicated page for more information about the stream hierarchy.

In essence, codecs are convenience tools to insert and retrieve data from the OpenViBE streams. The codecs are typically used in box code to make this interfacing more simple than it would be working with the streams directly.

To properly create the required algorithm for handling its stream type, every codec needs the execution context, i.e. the box in which the codec works. That is why every codec class is templated with the class T, where T should be replaced by the actual class name of the box using the codec.

All codecs share the same behaviour when it comes to construction and destruction. Be sure to always initialize a codec before use, and never leave an uninitialized codec at stop. Note that each coder must be associated with a box stream input (decoders) or output (encoders) connector. The connector index must be specified during initialization of the codec. The requirement for the connector index was introduced in OpenViBE 1.0 to prevent misuse of the codecs (as they only work correctly for a single input).

Here is what you can expect when manipulating codec objects :

  • Default constructor : the codec is declared, but not initialized.
  • Constructor with (T& rBoxAlgorithm, OpenViBE::uint32 ui32ConnectorIndex) arguments : the codec is declared and initialized.
  • Destructor : uninitializes the codec properly.
  • initialize(T& rBoxAlgorithm, OpenViBE::uint32 ui32ConnectorIndex) : manually initializes the codec. Does nothing if already initialized.
  • uninitialize() : manually uninitializes the codec. Does nothing if already uninitialized.

You can retrieve the input and output parameters of the codecs (e.g. the sampling frequency in a signal stream, or the matrix of a streamed matrix) with dedicated functions. Each time you will get a c++ reference to the object, meaning you can modify it directly.

TCodec

The TCodec < T > class implements the behavior common to all encoders and decoders. The template class T refers to the class of the box in which the codec will work.

Protected Members

  • The BoxAlgorithm T
    T* m_pBoxAlgorithm;
  • The codec algorithm

    OpenViBE::Kernel::IAlgorithmProxy* m_pCodec;

Public Methods

  • Initialize : sets the reference to the T instance and calls the initialize()method, specific to each codec.
    OpenViBE::boolean initialize(T& rBoxAlgorithm, OpenViBE::uint32 l_ui32ConnectorIndex)
  • Uninitialize: method overwritten specifically by each codec.
    OpenViBE::boolean uninitialize(void)

TDecoder

The TDecoder < T > class inherits from TCodec and implements the behavior common to all decoders. The template class T refers to the class of the box in which the codec will work.

Protected Members

Public Methods

  • Decode method: decode the input chunk on given indexes. Basically, it just sets the input memory buffer, calls process() on the decoder algorithm, and mark the input chunk as deprecated if asked (if nothing specified, by default the chunk is marked).
    OpenViBE::boolean decode(OpenViBE::uint32 ui32ChunkIndex,
                            OpenViBE::boolean bMarkInputAsDeprecated = true)
  • Checkmethods: tells which type of memory buffer was just decoded. These methods are implemented by all decoders with respect to their own triggers.
    OpenViBE::boolean isHeaderReceived(void)
    OpenViBE::boolean isBufferReceived(void)
    OpenViBE::boolean isEndReceived(void)

TEncoder

The TEncoder < T > class inherits from TCodec and implements the behavior common to all encoders. The template class T refers to the class of the box in which the codec will work.

Protected Members

Public Methods

  • Encode : encode the input memory buffer. Basically, it just sets the output memory buffer, calls encodeXXX(). The encodeXXX() methods are specified by each encoder, with respect to their own triggers. The developer has to mark the output as ready to send manually afterward, in order to have accurate timing of the chunks.
    OpenViBE::boolean encodeHeader(void)
    OpenViBE::boolean encodeBuffer(void)
    OpenViBE::boolean encodeEnd(void)

TStreamedMatrixDecoder

The Streamed Matrix Decoder is able to process a IMatrix from a Streamed Matrix input chunk. Be aware that you get a reference on the TParameterHandler.

TSignalDecoder

The Signal Decoder inherits from the Streamed Matrix Decoder. It is able to process a IMatrix and a Sampling Frequency from a Signal input chunk. Be aware that you get references on the TParameterHandlers.

// From TStreamedMatrixDecoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getOutputMatrix()
// Signal-specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >& getOutputSamplingRate()

TFeatureVectorDecoder

The Feature Vector Decoder inherits from the Streamed Matrix Decoder. It is able to process a IMatrix with dimension 2 from a Feature Vector input chunk. Be aware that you get a reference on the TParameterHandler.

// From TStreamedMatrixDecoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getOutputMatrix()

TSpectrumDecoder

The Spectrum Decoder inherits from the Streamed Matrix Decoder. It is able to process 2 IMatrix objects (spectrum & Min-Max frequency bands) from a Spectrum input chunk. Be aware that you get references on the TParameterHandlers.

// From TStreamedMatrixDecoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getOutputMatrix()
// Spectrum-specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getOutputMinMaxFrequencyBands()

TChannelLocalisationDecoder

The Channel Localisation Decoder inherits from the Streamed Matrix Decoder. It is able to process a IMatrix (Localisation Matrix) and a boolean (Dynamic or not) from a Channel Localisation input chunk. Be aware that you get references on the TParameterHandlers.

// From TStreamedMatrixDecoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getOutputMatrix()
// Channel localisation specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::boolean >& getOutputDynamic()

TChannelUnitsDecoder

The Channel Units Decoder inherits from the Streamed Matrix Decoder. It is able to process a IMatrix (Units Matrix) and a boolean (Dynamic or not) from a Channel Units input chunk. Be aware that you get references on the TParameterHandlers.

// From TStreamedMatrixDecoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getOutputMatrix()
// Channel units specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::boolean >& getOutputDynamic()

TStimulationDecoder

The Stimulations Decoder is able to process a IStimulationSet from a Stimulations input chunk. Be aware that you get a reference on the TParameterHandler.

TExperimentInformationDecoder

The Experiment Information Decoder is able to process various elements from an Experiment Information input chunk. Be aware that you get references on the TParameterHandlers.

OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getOutputExperimentIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getOutputExperimentDate()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getOutputSubjectIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getOutputSubjectName()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getOutputSubjectAge()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getOutputSubjectGender()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getOutputLaboratoryIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getOutputLaboratoryName()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getOutputTechnicianIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getOutputTechnicianName()

TStreamedMatrixEncoder

The Streamed Matrix Encoder needs a IMatrix in order to process to encoding. As you get a reference you can modify the input directly.

TSignalEncoder

The Signal Encoder inherits from the Streamed Matrix Encoder. It needs a IMatrix and a Sampling Frequency in order to process to encoding. As you get a reference you can modify the input directly.

// From TStreamedMatrixEncoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getInputMatrix()
// Signal-specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >& getInputSamplingRate()

TFeatureVectorEncoder

The Feature Vector Encoder inherits from the Streamed Matrix Encoder. It needs a IMatrix (2 dimensions) in order to process to encoding. As you get a reference you can modify the input directly.

// From TStreamedMatrixEncoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getInputMatrix()

TSpectrumEncoder

The Spectrum Encoder inherits from the Streamed Matrix Encoder. It needs 2 IMatrix (spectrum & Min-Max frequency bands) in order to process to encoding. As you get a reference you can modify the input directly.

// From TStreamedMatrixEncoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getInputMatrix()
// Spectrum-specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getInputMinMaxFrequencyBands()

TChannelLocalisationEncoder

The Channel Localisation Encoder inherits from the Streamed Matrix Encoder. It needs a IMatrix (Localisation Matrix) and a boolean (Dynamic or not) in order to process to encoding. As you get a reference you can modify the input directly.

// From TStreamedMatrixEncoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getInputMatrix()
// Channel Localisation specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::boolean >& getInputDynamic()

TChannelUnitsEncoder

The Channel Units Encoder inherits from the Streamed Matrix Encoder. It needs a IMatrix ([n x 2] matrix of channel measurement units) and a boolean (Dynamic or not) in order to process to encoding. As you get a reference you can modify the input directly.

// From TStreamedMatrixEncoder <T> :
OpenViBE::Kernel::TParameterHandler < OpenViBE::IMatrix* >& getInputMatrix()
// Channel Units specific :
OpenViBE::Kernel::TParameterHandler < OpenViBE::boolean >& getInputDynamic()

TStimulationEncoder

The Stimulations Encoder needs a IStimulationSet in order to process to encoding. As you get a reference you can modify the input directly.

TExperimentInformationEncoder

The Experiment Information Encoder needs various elements in order to process to encoding. As you get a reference you can modify the input directly.

OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getInputExperimentIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getInputExperimentDate()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getInputSubjectIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getInputSubjectName()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getInputSubjectAge()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getInputSubjectGender()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getInputLaboratoryIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getInputLaboratoryName()
OpenViBE::Kernel::TParameterHandler < OpenViBE::uint64 >&   getInputTechnicianIdentifier()
OpenViBE::Kernel::TParameterHandler < OpenViBE::CString* >& getInputTechnicianName()
This entry was posted in Developer tools and tagged , . Bookmark the permalink.