API

Core API usable from modules

When writing a new module or generally using libyuri, you will most often get to use API of three important classes: BasicFrame, BasicPipe and BasicIOThread from namespace yuri::core. BasicIOThread is the base class for every module and BasicFrame is class encapsulating the data traveling between modules. BasicPipe is the type of queues transporting frames between modules and provides information about frame types.

yuri::io::BasicFrame

BasicFrame contains a single frame of raw video, par of bytestream for compressed video (not necessarily exactly a frame) or several audio samples. The main purpose are raw video frames and the whole interface is built around them.

The actual type used in libyuri is yuri::core::pBasicFrame, which is defined as:

  typedef shared_ptr<BasicFrame> pBasicFrame;

Note: When you receive a frame in the module, you must not modify it. The frame might be shared with some other module. IF you want to modify it in-place, create a copy (using get_copy() method).

Most often used methods:

Name Description
Getting info
size_t
get_size()
Returns size of current frame (the sum of sizes of all planes).
size_t
get_planes_count()
Returns size of current frame (the sum of sizes of all planes). Returns 1 for non-video frames.
usize_t
get_width()
Returns width of current frame. Value is not defined for non-video frames.
usize_t
get_height()
Returns width of current frame. Value is not defined for non-video frames.
format_t
get_format()
Returns format of current frame.
size_t
get_pts()
Returns presentation time stamp of current frame in nanoseconds. If no PTS was set, the method returns 0.
size_t
get_dts()
Returns decoding time stamp of current frame in nanoseconds. If no DTS was set, the method returns 0.
size_t
get_duration()
Returns duration of current frame in nanoseconds. If no PTS was set, the method returns 0.
usize_t
get_sample_count()
Returns number of audio samples in current frame. Returns 0 for non-audio frames.
usize_t
get_channel_count()
Returns number of audio channels in current frame. Returns 0 for non-audio frames.
Working with planes
plane_t&
get_plane
(size_t index)
Returns reference to a planes with index index.
plane_t&
operator[]
(size_t index)
Returns reference to a planes with index index.
void
set_plane
(size_t index,
const ubyte_t *data,
size_t size)
Sets the data for a plane with index from a memory location.
void
set_plane
(size_t index,
const plane_t& plane)
Sets the data for a plane with index as a copy of another plane.
void
set_plane
(size_t index,
plane_t& plane)
Sets the data for a plane with index from a another plane. This method swaps the data, so the original plane will NOT preserve the data after this call.

For accessing underlying plane data, it's strongly preferred to use these convenience macros:

Macro Description
PLANE_SIZE(frame,plane) Returns the size of a plane in the frame. Plane is specified as index
PLANE_DATA(frame,plane) Return reference to the plane_t object associated with a plane in the frame
PLANE_RAW_DATA(frame,plane) Return pointer to data of the plane_t object associated with a plane in the frame

yuri::core::BasicPipe

Name Description
Getting info
pBasicPipe
pop_frame()
Returns oldest frame from the pipe.
pBasicPipe
pop_latest()
Returns newest frame from the pipe, dropping all older.
bool
is_empty()
Returns true if there are no frames in the pipe, false otherwise.
std::string
get_format_string
(format_t type)
Returns string representation of the format provided. (e.g. “Planar RGB 24bit”)
std::string
get_simple_format_string
(format_t type)
Returns short string representation of the format. (e.g. “RGBp”)
size_t
get_bpp_from_format
(format_t type)
Returns bit depth of the format
FormatInfo_t
get_format_info
(format_t format)
Returns and instance of FormatInfo_t providing extended information about format.
format_t
get_format_from_string
(std::string format,
format_t group=YURI_FMT_NONE)
Converts string to a format_t. If the string doesn't correcpond to any known format, YURI_FMT_NONE is returned. The secod paramet optionally limit the lookup to only a specified type (e.g. YURI_FMT_VIDEO).
format_t
set_frame_from_mime
(pBasicFrame frame,
std::string mime)
Sets type of the frame from a mime type.

yuri::core::BasicIOThread

yuri::uvector

Basic data storage. Modeled after std::vector and provides compatible interface. The biggest difference is that uvector does not initialize the allocated memory. If you call resize() on std::vector, it will reallocate the memory AND initialize it. As we are usually filling the memory right after we create it, this can lead to significant speed loss.

The signature of yuri::uvector is:

  template<typename T, bool Realloc> class uvector;

The parameter T is the underlying type (most common usage is with yuri::ubyte_t aka uint8_t) and Realloc specifies whether resize()/reserve() operations should preserve the content of the uvector. Setting it to false leads to marginal speedup.

Most often used member methods:

  • uvector() - default constructor, doesn't allocate any memory.
  • uvector(size_type size) - Constructs uvector and allocates memory for size items.
  • uvector(size_type size, const T& value) - Constructs uvector, allocates size items and initializes them to value value.
  • reserve(size_type size) - Ensures that uvector has enough memory to hold at least size items of type T.
  • resize(size_type size) - Ensures that uvector has enough memory to hold at least size items of type T and sets occupied size to size.
  • size() const - returns current occupied size of the vector
  • operator[](size_type pos) - Return element at position pos. No range checking is done.
  • front()/back() - Returns iterator to first/last allocated item.
  • template<Iter> insert(iterator pos, Iter first, Iter, last) - Inserts range (first-last) before position pos.
  • template<Iter> assign(Iter first, Iter, last) - Inserts range (first-last) at beginning of the uvector ans sets size to size of the range. Effectively equivalent to:
  uvector.clear();
  uvector.insert(uvector.begin(),first,last);
  • clear() - Clears the vector. Does not deallocate or clean the memory. Effectively just sets size to 0.
 
yuri/design/module_api.txt · Last modified: 2013/02/23 09:33 by neneko
 
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki