Struct UnevenCore

pub struct UnevenCore<T> {
    pub times: Vec<f32>,
    pub samples: Vec<T>,
}

Available on crate feature curve only.

The data core of a curve defined by unevenly-spaced samples or keyframes. The intention is to use this in concert with implicitly or explicitly-defined interpolation in user-space in order to implement the curve interface using domain and sample_with.

The internals are made transparent to give curve authors freedom, but the provided constructor enforces the required invariants, and the methods maintain those invariants.

Example

// Let's make a curve formed by interpolating rotations.
// We'll support two common modes of interpolation:
// - Normalized linear: First do linear interpolation, then normalize to get a valid rotation.
// - Spherical linear: Interpolate through valid rotations with constant angular velocity.
enum InterpolationMode {
    NormalizedLinear,
    SphericalLinear,
}

// Our interpolation modes will be driven by traits.
trait NormalizedLinearInterpolate {
    fn nlerp(&self, other: &Self, t: f32) -> Self;
}

trait SphericalLinearInterpolate {
    fn slerp(&self, other: &Self, t: f32) -> Self;
}

// Omitted: These traits would be implemented for `Rot2`, `Quat`, and other rotation representations.

// The curve itself just needs to use the curve core for keyframes, `UnevenCore`, which handles
// everything except for the explicit interpolation used.
struct RotationCurve<T> {
    core: UnevenCore<T>,
    interpolation_mode: InterpolationMode,
}

impl<T> Curve<T> for RotationCurve<T>
where
    T: NormalizedLinearInterpolate + SphericalLinearInterpolate + Clone,
{
    fn domain(&self) -> Interval {
        self.core.domain()
    }
     
    fn sample_unchecked(&self, t: f32) -> T {
        // To sample the curve, we just look at the interpolation mode and
        // dispatch accordingly.
        match self.interpolation_mode {
            InterpolationMode::NormalizedLinear =>
                self.core.sample_with(t, <T as NormalizedLinearInterpolate>::nlerp),
            InterpolationMode::SphericalLinear =>
                self.core.sample_with(t, <T as SphericalLinearInterpolate>::slerp),
        }
    }
}

Fields

times: Vec<f32>

The times for the samples of this curve.

Invariants

This must always have a length of at least 2, be sorted, and have no duplicated or non-finite times.

samples: Vec<T>

The samples corresponding to the times for this curve.

Invariants

This must always have the same length as times.

Implementations

impl<T> UnevenCore<T>

pub fn new( timed_samples: impl IntoIterator<Item = (f32, T)>, ) -> Result<Self, UnevenCoreError>

Create a new UnevenCore. The given samples are filtered to finite times and sorted internally; if there are not at least 2 valid timed samples, an error will be returned.

pub fn domain(&self) -> Interval

The domain of the curve derived from this core.

Panics

This method may panic if the type’s invariants aren’t satisfied.

pub fn sample_with<I>(&self, t: f32, interpolation: I) -> T

where T: Clone, I: Fn(&T, &T, f32) -> T,

Obtain a value from the held samples using the given interpolation to interpolate between adjacent samples.

The interpolation takes two values by reference together with a scalar parameter and produces an owned value. The expectation is that interpolation(&x, &y, 0.0) and interpolation(&x, &y, 1.0) are equivalent to x and y respectively.

pub fn sample_interp(&self, t: f32) -> InterpolationDatum<&T>

Given a time t, obtain a InterpolationDatum which governs how interpolation might recover a sample at time t. For example, when a Between value is returned, its contents can be used to interpolate between the two contained values with the given parameter. The other variants give additional context about where the value is relative to the family of samples.

pub fn sample_interp_timed(&self, t: f32) -> InterpolationDatum<(f32, &T)>

Like sample_interp, but the returned values include the sample times. This can be useful when sample interpolation is not scale-invariant.

pub fn map_sample_times(self, f: impl Fn(f32) -> f32) -> UnevenCore<T>

This core, but with the sample times moved by the map f. In principle, when f is monotone, this is equivalent to Curve::reparametrize, but the function inputs to each are inverses of one another.

The samples are re-sorted by time after mapping and deduplicated by output time, so the function f should generally be injective over the set of sample times, otherwise data will be deleted.

Trait Implementations

impl<T: Clone> Clone for UnevenCore<T>

fn clone(&self) -> UnevenCore<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for UnevenCore<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for UnevenCore<T>

where T: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> FromReflect for UnevenCore<T>

where UnevenCore<T>: Any + Send + Sync, T: TypePath, Vec<f32>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Vec<T>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl<T> GetTypeRegistration for UnevenCore<T>

where UnevenCore<T>: Any + Send + Sync, T: TypePath, Vec<f32>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Vec<T>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl<T> PartialReflect for UnevenCore<T>

where UnevenCore<T>: Any + Send + Sync, T: TypePath, Vec<f32>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Vec<T>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn clone_value(&self) -> Box<dyn PartialReflect>

Clones the value as a Reflect trait object.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<T> Reflect for UnevenCore<T>

where UnevenCore<T>: Any + Send + Sync, T: TypePath, Vec<f32>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Vec<T>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl<T> Serialize for UnevenCore<T>

where T: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> Struct for UnevenCore<T>

where UnevenCore<T>: Any + Send + Sync, T: TypePath, Vec<f32>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Vec<T>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, name: &str) -> Option<&dyn PartialReflect>

Returns a reference to the value of the field named name as a &dyn PartialReflect.

fn field_mut(&mut self, name: &str) -> Option<&mut dyn PartialReflect>

Returns a mutable reference to the value of the field named name as a &mut dyn PartialReflect.

fn field_at(&self, index: usize) -> Option<&dyn PartialReflect>

Returns a reference to the value of the field with index index as a &dyn PartialReflect.

fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn PartialReflect>

Returns a mutable reference to the value of the field with index index as a &mut dyn PartialReflect.

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

fn iter_fields(&self) -> FieldIter<'_>

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

fn get_represented_struct_info(&self) -> Option<&'static StructInfo>

Will return None if TypeInfo is not available.

impl<T> TypePath for UnevenCore<T>

where UnevenCore<T>: Any + Send + Sync, T: TypePath,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl<T> Typed for UnevenCore<T>

where UnevenCore<T>: Any + Send + Sync, T: TypePath, Vec<f32>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, Vec<T>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.