Package com.avpkit.core

Class IRational

  • public class IRational
extends RefCounted
    This class wraps represents a Rational number for the AVPKit.


    Video formats often use rational numbers, and converting between
    them willy nilly can lead to rounding errors, and eventually, out
    of sync problems. Therefore we use IRational objects to pass
    around Rational Numbers and avoid conversion until the very last moment.


    Note: There are some static convenience methods
    in this class that start with s*. They start with s
    (as opposed to overloading methods (e.g. sAdd(...) vs. add(...)).

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  IRational.Rounding  

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected IRational​(long cPtr, boolean cMemoryOwn)
      Internal Only.
      protected IRational​(long cPtr, boolean cMemoryOwn, java.util.concurrent.atomic.AtomicLong ref)
      Internal Only.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      IRational add​(IRational arg)
      Adds arg to this rational
      int compareTo​(IRational other)
      Compare a rational to this rational
      IRational copy()
      Creates a new IRational object by copying (by value) this object.
      IRational copyReference()
      Create a new IRational object that is actually referring to the exact same underlying native object.
      IRational divide​(IRational arg)
      Divides this rational by arg.
      boolean equals​(java.lang.Object obj)
      Compares two values, returning true if the underlying objects in native code are the same object.
      static long getCPtr​(IRational obj)
      Internal Only.
      int getDenominator()
      Get the denominator for this rational.
      double getDouble()
      Rational to double conversion.
      long getMyCPtr()
      Internal Only.
      int getNumerator()
      Get the numerator for this rational.
      double getValue()
      An alias for {#getDouble()} but matching JavaBean
      conventions.
      int hashCode()
      Get a hashable value for this object.
      void init()
      Marks this object as finalized and immutable.
      boolean isFinalized()
      Returns true if {#init()} has been called and
      this object is now considered finalized and immutable.
      boolean isNegative()
      Is this number negative?
      boolean isPositive()
      Is this number positive?
      static IRational make()
      Get a new rational that will be set to 0/0.
      The rational will not have {#init()} called
      and hence will be modifiable by {#setValue(double)}
      until {#init()} is called.
      static IRational make​(double d)
      Converts a double precision floating point number to a rational.
      static IRational make​(int num, int den)
      Create a rational from a numerator and denominator.

      We will always reduce this to the lowest num/den pair
      we can, but never having den exceed what was passed in.
      static IRational make​(IRational src)
      Creates deep copy of a Rational from another Rational.
      IRational multiply​(IRational arg)
      Multiplies this number by arg
      static boolean negative​(IRational num)
      Is this number not null and negative.
      static boolean positive​(IRational num)
      Is this number not null and positive.
      int reduce​(long num, long den, long max)
      Reduce a fraction to it's lowest common denominators.
      This is useful for framerate calculations.
      static long rescale​(long srcValue, int dstNumerator, int dstDenominator, int srcNumerator, int srcDenominator, IRational.Rounding rounding)
      Rescales a long value to another long value.
      long rescale​(long origValue, IRational origBase)
      Takes a value scaled in increments of origBase and gives the
      equivalent value scaled in terms of this Rational.
      long rescale​(long origValue, IRational origBase, IRational.Rounding rounding)
      Takes a value scaled in increments of origBase and gives the
      equivalent value scaled in terms of this Rational.
      static IRational sAdd​(IRational a, IRational b)
      Adds a to b.
      static int sCompareTo​(IRational a, IRational b)
      Compare two rationals
      static IRational sDivide​(IRational a, IRational b)
      Divides a by b.
      void setDenominator​(int value)
      Sets the denominator on this object.
      void setNumerator​(int value)
      Sets the numerator on this object.
      void setValue​(double value)
      Sets the numerator and denominator on this object by
      reducing the double to the closest integer numerator
      and denominator.
      static IRational sMultiply​(IRational a, IRational b)
      Multiples a by b.
      static int sReduce​(IRational dst, long num, long den, long max)
      Reduce a fraction to it's lowest common denominators.
      This is useful for framerate calculations.
      static long sRescale​(long origValue, IRational origBase, IRational newBase)
      Takes a value scaled in increments of origBase and gives the
      equivalent value scaled in terms of this Rational.
      static long sRescale​(long origValue, IRational origBase, IRational newBase, IRational.Rounding rounding)
      Takes a value scaled in increments of origBase and gives the
      equivalent value scaled in terms of this Rational.
      static IRational sSubtract​(IRational a, IRational b)
      Subtracts a from b.
      IRational subtract​(IRational arg)
      Subtracts arg from this rational
      java.lang.String toString()
      Prints the contents of this object as a fraction.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • IRational

        protected IRational​(long cPtr,
                    boolean cMemoryOwn)
        Internal Only.

      • IRational

        protected IRational​(long cPtr,
                    boolean cMemoryOwn,
                    java.util.concurrent.atomic.AtomicLong ref)
        Internal Only.

    • Method Detail

      • getCPtr

        public static long getCPtr​(IRational obj)
        Internal Only. Not part of public API. Get the raw value of the native object that obj is proxying for.
        Parameters:
        obj - The java proxy object for a native object.
        Returns:
        The raw pointer obj is proxying for.

      • getMyCPtr

        public long getMyCPtr()
        Internal Only. Not part of public API. Get the raw value of the native object that we're proxying for.
        Overrides:
        getMyCPtr in class RefCounted
        Returns:
        The raw pointer we're proxying for.

      • copyReference

        public IRational copyReference()
        Create a new IRational object that is actually referring to the exact same underlying native object.
        Overrides:
        copyReference in class RefCounted
        Returns:
        the new Java object.

      • equals

        public boolean equals​(java.lang.Object obj)
        Compares two values, returning true if the underlying objects in native code are the same object. That means you can have two different Java objects, but when you do a comparison, you'll find out they are the EXACT same object.
        Overrides:
        equals in class java.lang.Object
        Returns:
        True if the underlying native object is the same. False otherwise.

      • hashCode

        public int hashCode()
        Get a hashable value for this object.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hashable value.

      • isPositive

        public boolean isPositive()
        Is this number positive?
        Returns:
        true if > 0; false if not.

      • positive

        public static boolean positive​(IRational num)
        Is this number not null and positive.
        Parameters:
        num - the number; may be null
        Returns:
        true if not-null and > 0; else false;

      • isNegative

        public boolean isNegative()
        Is this number negative?
        Returns:
        true if < 0; false if not.

      • negative

        public static boolean negative​(IRational num)
        Is this number not null and negative.
        Parameters:
        num - the number; may be null
        Returns:
        true if not-null and < 0; else false;

      • getNumerator

        public int getNumerator()
        Get the numerator for this rational.
        Returns:
        the numerator.

      • getDenominator

        public int getDenominator()
        Get the denominator for this rational.
        Returns:
        the denominator.

      • copy

        public IRational copy()
        Creates a new IRational object by copying (by value) this object.

        Returns:
        the new object

      • compareTo

        public int compareTo​(IRational other)
        Compare a rational to this rational
        Parameters:
        other - second rational
        Returns:
        0 if this==other, 1 if this>other and -1 if this<other.

      • sCompareTo

        public static int sCompareTo​(IRational a,
                             IRational b)
        Compare two rationals
        Parameters:
        a - the first rational
        b - the second rational
        Returns:
        0 if a==b, 1 if a>b and -1 if b<a.

      • getDouble

        public double getDouble()
        Rational to double conversion.

        Returns:
        (double) a

      • reduce

        public int reduce​(long num,
                  long den,
                  long max)
        Reduce a fraction to it's lowest common denominators.
        This is useful for framerate calculations.
        Parameters:
        num - the src numerator.
        den - the src denominator.
        max - the maximum allowed for nom & den in the reduced fraction.
        Returns:
        1 if exact, 0 otherwise

      • sReduce

        public static int sReduce​(IRational dst,
                          long num,
                          long den,
                          long max)
        Reduce a fraction to it's lowest common denominators.
        This is useful for framerate calculations.
        Parameters:
        dst - The destination rational
        num - the src numerator.
        den - the src denominator.
        max - the maximum allowed for nom & den in the reduced fraction.
        Returns:
        1 if exact, 0 otherwise

      • multiply

        public IRational multiply​(IRational arg)
        Multiplies this number by arg
        Parameters:
        arg - number to mulitply by.
        Returns:
        this*arg.

      • divide

        public IRational divide​(IRational arg)
        Divides this rational by arg.
        Parameters:
        arg - The divisor to use.
        Returns:
        this/arg.

      • subtract

        public IRational subtract​(IRational arg)
        Subtracts arg from this rational
        Parameters:
        arg - The amount to subtract from this.
        Returns:
        this-arg.

      • add

        public IRational add​(IRational arg)
        Adds arg to this rational
        Parameters:
        arg - The amount to add to this.
        Returns:
        this+arg.

      • rescale

        public long rescale​(long origValue,
                    IRational origBase)
        Takes a value scaled in increments of origBase and gives the
        equivalent value scaled in terms of this Rational.

        Parameters:
        origValue - The original int64_t value you care about.
        origBase - The original base Rational that origValue is scaled with.

        Returns:
        The new integer value, scaled in units of this IRational.

      • sRescale

        public static long sRescale​(long origValue,
                            IRational origBase,
                            IRational newBase)
        Takes a value scaled in increments of origBase and gives the
        equivalent value scaled in terms of this Rational.

        Parameters:
        origValue - The original int64_t value you care about.
        origBase - The original base Rational that origValue is scaled with.
        newBase - The rational you want to rescale origValue into.

        Returns:
        The new integer value, scaled in units of this IRational.

      • make

        public static IRational make()
        Get a new rational that will be set to 0/0.
        The rational will not have {#init()} called
        and hence will be modifiable by {#setValue(double)}
        until {#init()} is called.
        Returns:
        a rational number object

      • make

        public static IRational make​(double d)
        Converts a double precision floating point number to a rational.
        Parameters:
        d - double to convert
        Returns:
        A new Rational; caller must release() when done.

      • make

        public static IRational make​(IRational src)
        Creates deep copy of a Rational from another Rational.

        Parameters:
        src - The source Rational to copy.
        Returns:
        A new Rational; Returns null
        if src is null.

      • make

        public static IRational make​(int num,
                             int den)
        Create a rational from a numerator and denominator.

        We will always reduce this to the lowest num/den pair
        we can, but never having den exceed what was passed in.

        Parameters:
        num - The numerator of the resulting Rational
        den - The denominator of the resulting Rational

        Returns:
        A new Rational;

      • rescale

        public long rescale​(long origValue,
                    IRational origBase,
                    IRational.Rounding rounding)
        Takes a value scaled in increments of origBase and gives the
        equivalent value scaled in terms of this Rational.

        Parameters:
        origValue - The original int64_t value you care about.
        origBase - The original base Rational that origValue is scaled with.
        rounding - How you want rounding to occur
        Returns:
        The new integer value, scaled in units of this IRational.

      • sRescale

        public static long sRescale​(long origValue,
                            IRational origBase,
                            IRational newBase,
                            IRational.Rounding rounding)
        Takes a value scaled in increments of origBase and gives the
        equivalent value scaled in terms of this Rational.

        Parameters:
        origValue - The original int64_t value you care about.
        origBase - The original base Rational that origValue is scaled with.
        newBase - The rational you want to rescale origValue into.
        rounding - How you want rounding to occur

        Returns:
        The new integer value, scaled in units of this IRational.

      • rescale

        public static long rescale​(long srcValue,
                           int dstNumerator,
                           int dstDenominator,
                           int srcNumerator,
                           int srcDenominator,
                           IRational.Rounding rounding)
        Rescales a long value to another long value.


        This method doesn't use IRational values, but
        instead uses numerators and denominators
        passed in by the caller. It will not result
        in any memory allocations.



        Parameters:
        srcValue - The value to rescale.
        dstNumerator - The numerator of the units
        you want to scale to. Must be non-zero.
        dstDenominator - The denominator of the units
        you want to scale to. Must be non-zero.
        srcNumerator - The numerator of the units
        srcValue is expressed in.
        Must be non-zero.
        srcDenominator - The denominator of the units
        srcValue is expressed in.
        Must be non-zero.
        rounding - How you want rounding to occur

        Returns:
        The new integer value, scaled in units of
        dstNumerator/dstNumerator, or 0 if there
        is a parameter error.

      • setNumerator

        public void setNumerator​(int value)
        Sets the numerator on this object.


        If {#isFinalized} is true, then this method is ignored.



        Since:
        3.2

      • setDenominator

        public void setDenominator​(int value)
        Sets the denominator on this object.


        If {#isFinalized} is true, then this method is ignored.



        Since:
        3.2

      • setValue

        public void setValue​(double value)
        Sets the numerator and denominator on this object by
        reducing the double to the closest integer numerator
        and denominator.


        If {#isFinalized} is true, then this method is ignored.



        Since:
        3.2

      • getValue

        public double getValue()
        An alias for {#getDouble()} but matching JavaBean
        conventions.
        Since:
        3.2

      • isFinalized

        public boolean isFinalized()
        Returns true if {#init()} has been called and
        this object is now considered finalized and immutable.

        Since:
        3.2

      • init

        public void init()
        Marks this object as finalized and immutable. Any
        setters called after the first {#init()} call
        will be ignored.


        Most make methods will call this method
        automatically, with the exception of the blank factory
        method {#make()}.


        Since:
        3.2