This is the current Transor API in early state.
You can also download the original Header file to work on it and send it back to me (robUx4).
An example of XML dialog file can be found in HTML source form or as an XML file. It is just an early draft but the strcuture should remain the same.
- /*!
* \file transor.h
* this API is intended only for codecs input, output, configuration
*/
- #if !defined(_TRANSOR_API_H)
#define _TRANSOR_API_H
- namespace Transor {
- /*!
* \class CodecOption
* store private or public options in binary form
*/
- class CodecOption {
public:
binary * data;
uint32 size;
};
- /*!
* \class CodecFormat
* a codec information is simply holding information about a Codec input/output type
* ie Format String and codec specific data
*
* \note there should be a few standard types already defined (PCM, some sort of YUV, RGB, etc)
*
* \todo add some configuration here
*/
- class CodecFormat {
public:
- enum CodecType {
CODEC_AUDIO = 0, ///< "audio/"
CODEC_VIDEO, ///< "video/"
CODEC_SUBTITLE, ///< "subtitle/"
CODEC_TITLE, ///< "title/" , MCF specific ?
CODEC_CONTROL, ///< "control/" , MCF specific
CODEC_MIDI, ///< "midi/" , everyone knows MIDI (Music Instrument Digital Interface ?)
CODEC_COMPLEX, ///< "complex/" , contain more than one "simple" data type (audio+video f.e.)
CODEC_CAPTURE, ///< "capture/" , not stored in container, only output data produced, not usable as output
CODEC_RENDER, ///< "render/" , not stored in container, no output data produced, not usable as input
CODEC_UNDEFINED ///< might be a problem with the format string
};
CodecFormat(const CodecType dataType, const std::string & formatString, const binary * _options = NULL, uint32 _optionSize = 0)
: codecType(dataType)
, formatSubString(format)
, optionSize(_optionSize)
- {
options = NULL;
- if (optionSize != 0) {
options = new binary[optionSize];
if (options != NULL)
memcpy(options, _options, optionSize);
}
}
~CodecFormat()
- {
if (options != NULL)
delete options;
}
/// the type of codec, based on the string
inline operator CodecType() const {return codecType;}
/// the whole format string, MCF compatible
const std::string & FormatString() const;
/// String without the audio/ video/ suffix
inline const std::string & SubString() const {return formatSubString;}
- /*! return the option buffer for the format
* \note only other codec that deal with the same string can understand the content
*/
const CodecOption & GeneralOption() const;
- /*!
* \return the type specific option buffer for the format
*/
virtual const CodecOption & TypeOption() const;
/// \return wether the Format is valid ("audio/xxx" is audio for ex)
virtual bool Valid() const = 0;
- /*!
* \return wether the format could be transformed to another, not just rendered
*
* \note used for DRM
*/
virtual bool TranscodingAllowed() const = 0;
- /*!
* Retrieve the configuration for the combination
*/
const std::string & GetConfig() const;
- /*!
* Set new configuration for the combination
* \return true if config was successfully applied
*/
bool SetConfig(const std::string & xmlConfig);
- /*!
* Retrieve the statistics for the combination
*/
const std::string & GetStats() const;
protected:
CodecType codecType;
std::string formatSubString;
CodecOption generalOptions;
};
- /*!
* \class AudioCodecFormat
* Audio specific format, to handle the audio specific options
*
* \see http://mcf.sourceforge.net/trackt.htm#0x02
*
* \todo we could have some methods to return the VfW/DirectShow compatible parameter for this format
* \todo we could have some methods to return the Quicktime compatible parameter for this format
*/
- class AudioCodecFormat : public CodecFormat {
public:
virtual const CodecOption & TypeOption() const;
/*! \return true if the string starts with "audio/" */
bool Valid() const;
protected:
uint32 sampligFrequency; ///< in milliHertz
uint32 channelBits; ///< a bit for each channel (front left, front right, LFE, etc)
};
/// Audio Channel bits
const uint32 SPEAKER_FRONT_LEFT = 0x00001;
const uint32 SPEAKER_FRONT_RIGHT = 0x00002;
const uint32 SPEAKER_FRONT_CENTER = 0x00004;
const uint32 SPEAKER_LOW_FREQUENCY = 0x00008;
const uint32 SPEAKER_BACK_LEFT = 0x00010;
const uint32 SPEAKER_BACK_RIGHT = 0x00020;
const uint32 SPEAKER_FRONT_LEFT_OF_CENTER = 0x00040;
const uint32 SPEAKER_FRONT_RIGHT_OF_CENTER = 0x00080;
const uint32 SPEAKER_BACK_CENTER = 0x00100;
const uint32 SPEAKER_SIDE_LEFT = 0x00200;
const uint32 SPEAKER_SIDE_RIGHT = 0x00400;
const uint32 SPEAKER_TOP_CENTER = 0x00800;
const uint32 SPEAKER_TOP_FRONT_LEFT = 0x01000;
const uint32 SPEAKER_TOP_FRONT_CENTER = 0x02000;
const uint32 SPEAKER_TOP_FRONT_RIGHT = 0x04000;
const uint32 SPEAKER_TOP_BACK_LEFT = 0x08000;
const uint32 SPEAKER_TOP_BACK_CENTER = 0x10000;
const uint32 SPEAKER_TOP_BACK_RIGHT = 0x20000;
- /*!
* \class VideoCodecFormat
* Video specific format, to handle the video specific options
*
* \see http://mcf.sourceforge.net/trackt.htm#0x01
*
* \todo we could have some methods to return the VfW/DirectShow compatible parameter for this format
* \todo we could have some methods to return the Quicktime compatible parameter for this format
*/
- class VideoCodecFormat : public CodecFormat {
public:
- enum EyePosition {
EYE_MONO = 0, ///< usual video mode
EYE_RIGHT,
EYE_LEFT,
EYE_BOTH
}; ///< Video Channel bits
virtual const CodecOption & TypeOption() const;
/*! \return true if the string starts with "video/" */
bool Valid() const;
protected:
uint16 width;
uint16 height;
uint16 aspectRatio;
// X:1000 = width of the video-window if the height is 1000 units.
// * 4:3 = 1.333:1 -> 1333
// * 16:9 = 1.778:1 -> 1778
// * 2.35:1 = 2.350:1 -> 2350
// This can range from 1 (0.001:1) to 65535 (65.535:1)
bool interlaced;
uint8 gammaValue;
EyePosition channelEye;
};
- /*!
* \class CodecBuffer
* handles a data buffer
*/
- class CodecBuffer {
public:
binary *buffer;
uint32 bufferSize;
uint64 timestamp; ///< in microseconds
uint64 duration; ///< of the data stored in the buffer
CodecFormat & format;
};
- /*!
* \class CodecInOut
* this class handles a codec In/Out combination
*
* \note all decoders should support at list CodecRawEncoded->another format
* \note all encoders should support at list another format->CodecRawEncoded
*
* \todo add some configuration here
*/
- class CodecInOut {
public:
/// the input type supported
const CodecFormat & Input() const;
/// the output type supported
const CodecFormat & Output() const;
/// the performance rating of the combination 0.0 (bad speed) to 1.0 (best speed)
float Performance() const;
/// the latency of the combination in microseconds, 0 when unknown
uint32 Latency() const;
/// indicate wether this combination can be used or not
bool Available() const;
- /*!
* friendly name used to differentiate many different same combination (for subtracks for example)
* \note only makes sense when the codec has been initialized with custom data for input/output
*/
const std::string & FriendlyName() const;
- /*!
* Prepare the transcoding process
*
* \todo add some init buffer ? options for input and output CodecFormat ?
*/
int Init();
- /*!
* End the transcoding
* \note some decoders still output data even after the stream is finished
*/
int Release(Buffer & outputBuffer);
- /*!
* Transcoding process
*
* \see GetTranscodedFrame()
*
* \note all input data should be used
* \note no verification is done on input format, otherwise the performance would be much worse
* \note might only be called on valid boundaries form frames (formats like MPEG Audio wouldn't care about that)
* \note it must use the remaining data of previous incomplete data frame on consecutive calls
* \note when calling again, the codec knows wether there is a break in input timecode
*/
int SetInputBuffer(const CodecBuffer & inputBuffer);
- /*!
* Transcoding process
* Output data on Frame boundaries
*
* \return 0 when a frame was successfully written to output buffer
*
* \see SetInputBuffer()
*
* \note formats without frames like PCM can return the whole encoded buffer
* \note the output timestamp and duration should be treated accordingly (based on input)
* \note no verification is done on output format, otherwise the performance would be much worse
*/
int GetTranscodedFrame(CodecBuffer & outputBuffer);
- /*!
* Retrieve the configuration for the combination
*/
const std::string & GetConfig() const;
- /*!
* Set new configuration for the combination
* \return true if config was successfully applied
*/
bool SetConfig(const std::string & xmlConfig);
- /*!
* Retrieve the statistics for the combination
*/
const std::string & GetStats() const;
protected:
CodecFormat & inputType;
CodecFormat & outputType;
uint32 latency; ///< in microsecond
std::string friendlyName;
};
- /*!
* \class CodecFactory
* this class can contain as many input/output combination as it wants
* this is the entry class that outside code will see
*
* \note a Transor is actually a CodecFactory
* \note you can use only one codec combination (in/out) by class instance
*
* \todo add some configuration here (allow/disallow some combination for ex)
* \todo add some "About" "dailog" about the whole factory (may be in the config communication)
*/
- class CodecFactory {
public :
/// The number of available this Transor can provide with the current configuration
uint32 PossibleCombinations() const;
- /*!
* retrieve the specifiec combination (starting from 1 to PossibleCombinations())
* \note configuration IDs should remain the same even after configuration changes
*/
CodecInOut & GetCombination(uint32 CombinationID);
/// Check for all inputs that support ouput of outputType
uint32 PossibleInputCombinations(const CodecFormat & outputType) const;
CodecInOut & GetInputCombination(uint32 CombinationID, const CodecFormat & outputType);
/// Check for all outputs that support input of inputType
uint32 PossibleOutputCombinations(const CodecFormat & inputType) const;
CodecInOut & GetOutputCombination(uint32 CombinationID, const CodecFormat & inputType);
- /*!
* Retrieve the configuration for the transor
* \note can be used to set default values to all combinations
*/
const std::string & GetConfig() const;
- /*!
* Set new configuration for the transor
* \return true if config was successfully applied
*/
bool SetConfig(const std::string & xmlConfig);
- /*!
* Retrieve the statistics for the transor
*/
const std::string & GetStats() const;
};
} // namespace
#endif // _TRANSOR_API_H