Refactor codec::Parameters (shssoichiro#88)

* Split codec::Parameters into owned, ref, mut variants

* Implement common functions via macro

* Immutable AVCodecParameters API

* Add `AsPtr` and `AsMutPtr` traits

* Add missing API to StreamMut

fn copy_parameters_from_context is more verbose but avoids an
allocation.

fn parameters_mut is necessary to ensure UB (before the refactor,
fn parameters(&self) allowed mutation via unsafe code).

* Add docs

Author: FreezyLemon

examples/remux.rs

@@ -35,7 +35,7 @@ fn main() {
         // issues when muxing into a different container format. Unfortunately
         // there's no high level API to do this (yet).
         unsafe {
-            (*ost.parameters().as_mut_ptr()).codec_tag = 0;
+            (*ost.parameters_mut().as_mut_ptr()).codec_tag = 0;
         }
     }
 

examples/transcode-audio.rs

@@ -135,7 +135,7 @@ fn transcoder<P: AsRef<Path>>(
     output.set_time_base((1, decoder.rate() as i32));
 
     let encoder = encoder.open_as(codec)?;
-    output.set_parameters(&encoder);
+    output.copy_parameters_from_context(&encoder);
 
     let filter = filter(filter_spec, &decoder, &encoder)?;
 

examples/transcode-x264.rs

@@ -70,7 +70,7 @@ impl Transcoder {
         encoder = codec::context::Context::from_parameters(ost.parameters())?
             .encoder()
             .video()?;
-        ost.set_parameters(&encoder);
+        ost.copy_parameters_from_context(&encoder);
         Ok(Self {
             ost_index,
             decoder,
@@ -224,7 +224,7 @@ fn main() {
             // issues when muxing into a different container format. Unfortunately
             // there's no high level API to do this (yet).
             unsafe {
-                (*ost.parameters().as_mut_ptr()).codec_tag = 0;
+                (*ost.parameters_mut().as_mut_ptr()).codec_tag = 0;
             }
         }
         ost_index += 1;

src/as_ptr.rs

@@ -0,0 +1,9 @@
+pub trait AsPtr<T> {
+    /// Returns a *const raw pointer to the underlying FFmpeg type.
+    fn as_ptr(&self) -> *const T;
+}
+
+pub trait AsMutPtr<T> {
+    /// Returns a *mut raw pointer to the underlying FFmpeg type.
+    fn as_mut_ptr(&mut self) -> *mut T;
+}

src/codec/context.rs

@@ -4,9 +4,10 @@ use std::rc::Rc;
 
 use super::decoder::Decoder;
 use super::encoder::Encoder;
-use super::{threading, Compliance, Debug, Flags, Id, Parameters};
+use super::{threading, Compliance, Debug, Flags, Id};
 use crate::ffi::*;
 use crate::media;
+use crate::AsPtr;
 use crate::{Codec, Error};
 use libc::c_int;
 
@@ -41,8 +42,7 @@ impl Context {
         }
     }
 
-    pub fn from_parameters<P: Into<Parameters>>(parameters: P) -> Result<Self, Error> {
-        let parameters = parameters.into();
+    pub fn from_parameters<P: AsPtr<AVCodecParameters>>(parameters: P) -> Result<Self, Error> {
         let mut context = Self::new();
 
         unsafe {
@@ -113,9 +113,10 @@ impl Context {
         }
     }
 
-    pub fn set_parameters<P: Into<Parameters>>(&mut self, parameters: P) -> Result<(), Error> {
-        let parameters = parameters.into();
-
+    pub fn set_parameters<P: AsPtr<AVCodecParameters>>(
+        &mut self,
+        parameters: P,
+    ) -> Result<(), Error> {
         unsafe {
             match avcodec_parameters_to_context(self.as_mut_ptr(), parameters.as_ptr()) {
                 e if e < 0 => Err(Error::from(e)),

src/codec/mod.rs

@@ -28,7 +28,7 @@ pub mod codec;
 pub use self::codec::{Audio, Codec, Video};
 
 pub mod parameters;
-pub use self::parameters::Parameters;
+pub use self::parameters::{Parameters, ParametersMut, ParametersRef};
 
 pub mod audio_service;
 pub mod field_order;

src/codec/parameters.rs

@@ -0,0 +1,38 @@
+use std::marker::PhantomData;
+use std::ptr::NonNull;
+
+use crate::ffi::*;
+use crate::AsPtr;
+
+pub struct ParametersRef<'p> {
+    ptr: NonNull<AVCodecParameters>,
+    _marker: PhantomData<&'p AVCodecParameters>,
+}
+
+impl<'p> ParametersRef<'p> {
+    /// # Safety
+    ///
+    /// Ensure that
+    /// - `ptr` is either null or valid,
+    /// - the shared borrow represented by `ptr` follows Rust borrow rules and
+    /// - the lifetime of the returned struct is correctly bounded.
+    pub unsafe fn from_raw(ptr: *const AVCodecParameters) -> Option<Self> {
+        NonNull::new(ptr as *mut _).map(|ptr| Self {
+            ptr,
+            _marker: PhantomData,
+        })
+    }
+
+    /// Exposes a pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
+    pub fn as_ptr(&self) -> *const AVCodecParameters {
+        self.ptr.as_ptr()
+    }
+}
+
+impl<'p> AsPtr<AVCodecParameters> for ParametersRef<'p> {
+    fn as_ptr(&self) -> *const AVCodecParameters {
+        self.ptr.as_ptr()
+    }
+}

src/codec/parameters/borrowed.rs

@@ -0,0 +1,51 @@
+use std::marker::PhantomData;
+use std::ptr::NonNull;
+
+use crate::ffi::*;
+use crate::{AsMutPtr, AsPtr};
+
+pub struct ParametersMut<'p> {
+    ptr: NonNull<AVCodecParameters>,
+    _marker: PhantomData<&'p mut AVCodecParameters>,
+}
+
+impl<'p> ParametersMut<'p> {
+    /// # Safety
+    ///
+    /// Ensure that
+    /// - `ptr` is either null or valid,
+    /// - the mutable borrow represented by `ptr` follows Rust borrow rules and
+    /// - the lifetime of the returned struct is correctly bounded.
+    pub unsafe fn from_raw(ptr: *mut AVCodecParameters) -> Option<Self> {
+        NonNull::new(ptr as *mut _).map(|ptr| Self {
+            ptr,
+            _marker: PhantomData,
+        })
+    }
+
+    /// Exposes a pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
+    pub fn as_ptr(&self) -> *const AVCodecParameters {
+        self.ptr.as_ptr()
+    }
+
+    /// Exposes a mutable pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
+    pub fn as_mut_ptr(&mut self) -> *mut AVCodecParameters {
+        self.ptr.as_ptr()
+    }
+}
+
+impl<'p> AsPtr<AVCodecParameters> for ParametersMut<'p> {
+    fn as_ptr(&self) -> *const AVCodecParameters {
+        self.as_ptr()
+    }
+}
+
+impl<'p> AsMutPtr<AVCodecParameters> for ParametersMut<'p> {
+    fn as_mut_ptr(&mut self) -> *mut AVCodecParameters {
+        self.as_mut_ptr()
+    }
+}