diff --git a/src/error.rs b/src/error.rs index 4863305..85ed387 100644 --- a/src/error.rs +++ b/src/error.rs @@ -103,11 +103,11 @@ impl InternalError { } } -/// FFMS2 error types +/// All error types. #[derive(Debug, Error)] pub enum Error { - /// An FFMS2 API error. - #[error("FFSM2 API error.")] + /// A `ffms2` API error. + #[error("ffms2 API error.")] FFMS2(borrow::Cow<'static, str>), /// The path is not a file. #[error("The path is not a file.")] @@ -139,13 +139,13 @@ pub enum Error { /// Wrong timestamp. #[error("Wrong timestamp.")] WrongTimestamp, - /// Failure in converting an operating system string into a str. + /// Failure in converting an operating system string into a [`&str`]. #[error("str convervion error.")] StrConversion, - /// Failure in creating a CString. + /// Failure in creating a [`CString`](std::ffi::CString). #[error("Failed to create a CString")] CString(#[from] std::ffi::NulError), - /// Failure in converting a CString into a String. + /// Failure in converting a [`CString`](std::ffi::CString) into a [`String`]. #[error("Failed to convert a CString into a String")] StringConversion(#[from] std::ffi::IntoStringError), } @@ -162,5 +162,5 @@ impl From for Error { } } -/// A specialized `Result` type. +/// A specialized [`Result`] type. pub type Result = ::std::result::Result; diff --git a/src/frame.rs b/src/frame.rs index efc1558..a54e767 100644 --- a/src/frame.rs +++ b/src/frame.rs @@ -73,6 +73,7 @@ impl Resizers { /// overlapped to the right scheme, but this is not possible due to /// text limitations. /// +/// ```text /// a b c d /// v v v v /// ______ ______ @@ -80,23 +81,22 @@ impl Resizers { /// | |1 2 /// 2nd luma line > |X X ... |5 6 X ... /// -/// *X*: _luma samples_ +/// ``` /// -/// # Chroma locations +/// # Symbols Description +/// - **X**: luma samples +/// - **a** = 1st horizontal luma sample location +/// - **b** = 2nd horizontal luma sample location +/// - **c** = 1st top-left chroma sample location +/// - **d** = 2nd horizontal luma sample location /// -/// - *1* = _Left_ -/// - *2* = _Center_ -/// - *3* = _Top-left_ -/// - *4* = _Top_ -/// - *5* = _Bottom-left_ -/// - *6* = _Bottom_ -/// -/// # Samples descriptions -/// -/// - *a* = _1st horizontal luma sample location_ -/// - *b* = _2nd horizontal luma sample location_ -/// - *c* = _1st top-left chroma sample location_ -/// - *d* = _2nd horizontal luma sample location_ +/// # Chroma Locations +/// - **1** = Left +/// - **2** = Center +/// - **3** = Top-left +/// - **4** = Top +/// - **5** = Bottom-left +/// - **6** = Bottom #[derive(Clone, Copy, Debug, Default)] pub enum ChromaLocation { /// Unspecified location. @@ -112,7 +112,7 @@ pub enum ChromaLocation { Center, /// Top-left. /// - /// ITU-R 601, SMPTE 274M 296M S314M(DV 4:1:1), mpeg2 4:2:2. + /// ITU-R 601, SMPTE 274M 296M S314M(DV 4:1:1), MPEG-2 4:2:2. TopLeft, /// Top. Top, @@ -143,18 +143,19 @@ impl ChromaLocation { pub struct FrameInfo { /// The decoding timestamp of a frame. /// - /// To convert this to a timestamp in clock milliseconds, use: + /// To convert this timestamp into one expressed in `clock milliseconds`, + /// use the following formula: /// - /// (`[FrameInfo.pts]` * `[TrackTimebase.numerator]`) / `[TrackTimebase.denominator]`. + /// (`pts` * [`TrackTimebase.numerator`](crate::track::TrackTimebase::numerator)) + /// / [`TrackTimebase.denominator`](crate::track::TrackTimebase::denominator) pub pts: u64, - /// Repeat First Field (RFF) flag for a MPEG frame. + /// **Repeat First Field (RFF)** flag for a _MPEG_ frame. /// - /// A frame must be displayed for `1 + repeat_picture` time units, - /// where the time units are expressed in the special - /// `[VideoSource.RFFTimebase]`. + /// A frame must be displayed on screen for `1 + repeat_picture` time units + /// which are expressed in [`RFFTimebase`](crate::video::RFFTimebase). /// - /// Usual timestamps must be ignored since since they are fundamentally - /// incompatible with RFF data. + /// Usual timestamps **must** be ignored because they are fundamentally + /// incompatible with the **RFF** timestamps. pub repeat_picture: usize, /// Whether a frame is a keyframe. pub keyframe: bool, @@ -164,7 +165,7 @@ pub struct FrameInfo { /// behavior might break some kind of video sources. /// /// This field should be used when a video source presents discontinuous - /// timestamps such as Variable Frame Rate (VFR) formats. + /// timestamps such as **Variable Frame Rate (VFR)** formats. pub original_pts: usize, } @@ -188,15 +189,15 @@ pub struct FrameResolution { pub height: usize, } +/// Video frame data. #[derive(Debug)] pub struct Frame { /// The length in bytes of each frame plane scan line. The number of scan - /// lines is equal to the number of frame planes, thus `PLANES_COUNT`. + /// lines is equal to the number of frame planes, thus [`PLANES_COUNT`]. /// - /// The total size in bytes of a frame plane is obtained with the following - /// computation: + /// The total size in bytes of the i-th frame plane is obtained in this way: /// - /// `linesize[i]` * `[VideoProperties.height]` + /// `linesize[i]` * [`FrameResolution.height`](FrameResolution::height) /// /// Some pixel formats though, most notably `YV12`, have vertical chroma /// subsampling, and then the U/V planes may be of a different height than @@ -229,36 +230,35 @@ pub struct Frame { pub converted_pixel_format: PixelFormat, /// Whether a frame is a keyframe. pub keyframe: usize, - /// Repeat First Field (RFF) flag for a MPEG frame. + /// **Repeat First Field (RFF)** flag for a _MPEG_ frame. /// - /// A frame must be displayed for `1 + repeat_picture` time units, - /// where the time units are expressed in the special - /// `[VideoSource.RFFTimebase]`. + /// A frame must be displayed on screen for `1 + repeat_picture` time units + /// which are expressed in [`RFFTimebase`](crate::video::RFFTimebase). /// - /// Usual timestamps must be ignored since since they are fundamentally - /// incompatible with RFF data. + /// Usual timestamps **must** be ignored because they are fundamentally + /// incompatible with the **RFF** timestamps. pub repeat_picture: usize, /// Whether a frame has been coded as interlaced. pub interlaced_frame: bool, /// Whether a frame has the top field first, otherwise it has the bottom /// field first. /// - /// Only relevant when [`interlaced_frame`] is `true`. + /// Only relevant when [`interlaced_frame`](Self::interlaced_frame) is [`true`]. pub top_field_first: bool, /// Compressed frame coding type. /// - /// - I: Intra - /// - P: Predicted - /// - B: Bi-dir predicted - /// - S: S(GMC)-VOP MPEG4 - /// - i: Switching Intra - /// - p: Switching Predicted - /// - b: FF_BI_TYPE - /// - ?: Unknown + /// - **I**: Intra + /// - **P**: Predicted + /// - **B**: Bi-dir predicted + /// - **S**: S(GMC)-VOP MPEG4 + /// - **i**: Switching Intra + /// - **p**: Switching Predicted + /// - **b**: FF_BI_TYPE + /// - **?**: Unknown pub picture_type: char, - /// YUV color space. + /// `YUV` color space. pub color_space: PixelFormat, - /// Valid range of luma values for a YUV video source. + /// Valid range of luma values for a `YUV` video source. pub color_range: ColorRange, /// Frame color primaries. pub color_primaries: usize, @@ -289,10 +289,10 @@ pub struct Frame { /// source content are accessible. pub has_mastering_display_luminance: bool, /// Minimum luminance of the display used to master a video - /// source content in cd/m^2. + /// source content in `cd/m^2`. pub mastering_display_min_luminance: f64, /// Maximum luminance of the display used to master a video - /// source content in cd/m^2. + /// source content in `cd/m^2`. pub mastering_display_max_luminance: f64, /// Whether a video source content has maximum and average light levels. /// Both of these values are measured over the duration of the content. @@ -300,9 +300,9 @@ pub struct Frame { /// A receiver can use this information to adjust the content light /// levels so that they match the capability of the current display. pub has_content_light_level: bool, - /// Maximum light level of a video source content in cd/m^2. + /// Maximum light level of a video source content in `cd/m^2`. pub content_light_level_max: usize, - /// Average light level of a video source content in cd/m^2. + /// Average light level of a video source content in `cd/m^2`. pub content_light_level_average: usize, frame: FFMS_Frame, } diff --git a/src/track.rs b/src/track.rs index 13dd638..b6be966 100644 --- a/src/track.rs +++ b/src/track.rs @@ -24,15 +24,15 @@ pub enum TrackType { Audio, /// A stream of bytes. /// - /// Not supported by ffms2. + /// Not supported by `ffms2`. Data, /// A subtitle stream. /// - /// Not supported by ffms2, + /// Not supported by `ffms2`. Subtitle, /// Attachment stream. /// - /// Not supported by ffms2. + /// Not supported by `ffms2`. Attachment, } @@ -72,10 +72,10 @@ impl TrackType { /// This information are only meaningful for video tracks. /// /// The rational number obtained dividing the `numerator` and `denominator` -/// fields of this structure might occasionally be equal to`1/framerate` -/// for some CFR video tracks. -/// However, this similarity has no relation whatsoever with the video framerate -/// and it is not related at all with any framerate concept. +/// fields of this structure might occasionally be equal to `1/framerate` +/// for some **Constant Frame Rate (CFR)** video tracks. +/// However, this similarity has no relation whatsoever with the video frame +/// rate and it is not related at all with any frame rate concept. pub struct TrackTimebase { /// Timebase numerator. pub numerator: usize, @@ -91,7 +91,7 @@ pub struct Track(*mut ffms2_sys::FFMS_Track, usize); unsafe impl Send for Track {} impl Track { - /// Builds a `[Track]` from the given `[Index]` and track number. + /// Builds a [`Track`] from the given [`Index`] and track number. pub fn from_index(index: &Index, track_number: usize) -> Result { if track_number > index.tracks_count() - 1 { return Err(Error::WrongTrack); @@ -106,9 +106,9 @@ impl Track { Self::evaluate_track(track) } - /// Builds a new `[Track]` from a video source. + /// Builds a new [`Track`] from a video source. /// - /// The `[TrackType]` is `Video`. + /// The [`TrackType`] is `Video`. pub fn from_video(video_source: &mut VideoSource) -> Result { let track = unsafe { ffms2_sys::FFMS_GetTrackFromVideo(video_source.as_mut_ptr()) @@ -116,9 +116,9 @@ impl Track { Self::evaluate_track(track) } - /// Builds a new `[Track]` from an audio source. + /// Builds a new [`Track`] from an audio source. /// - /// The `[TrackType]` is `Audio`. + /// The [`TrackType`] is `Audio`. pub fn from_audio(audio_source: &mut AudioSource) -> Result { let track = unsafe { ffms2_sys::FFMS_GetTrackFromAudio(audio_source.as_mut_ptr()) @@ -126,7 +126,7 @@ impl Track { Self::evaluate_track(track) } - /// Writes `Matroska` v2 timecodes for the track in a file. + /// Writes **Matroska v2** timecodes for the track in a file. /// /// Only meaningful for video tracks. pub fn write_timecodes(&self, timecode_file: &Path) -> Result<()> { diff --git a/src/video.rs b/src/video.rs index 1d78e72..3c7784a 100644 --- a/src/video.rs +++ b/src/video.rs @@ -33,7 +33,7 @@ pub enum SeekMode { Linear, /// Safe normal mode. /// - /// Seeking decisions are based on the keyframe positions. + /// Seeking decisions are based on the key frame positions. Normal, /// Unsafe normal mode. /// @@ -42,10 +42,10 @@ pub enum SeekMode { Unsafe, /// Aggressive mode. /// - /// It seeks in the forward direction even if no closer keyframe is known + /// It seeks in the forward direction even if no closer key frame is known /// to exist. /// - /// Only useful for testing purposes and those containers whose keyframes + /// Only useful for testing purposes and those containers whose key frames /// are not reported properly. Aggressive, }