===== 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:
<code cpp>
  typedef shared_ptr<BasicFrame> pBasicFrame;
</code>

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:
<code cpp>
  template<typename T, bool Realloc> class uvector;
</code>
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:
<code cpp>
  uvector.clear();
  uvector.insert(uvector.begin(),first,last);
</code>
  * **clear()** - Clears the vector. Does not deallocate or clean the memory. Effectively just sets size to 0.