com.xuggle.xuggler
Class IRational

Package class diagram package IRational
java.lang.Object
  extended by com.xuggle.ferry.RefCounted
      extended by com.xuggle.xuggler.IRational

public class IRational
extends RefCounted

This class wraps represents a Rational number for the Xuggler.

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
static class IRational.Rounding
           
 
Field Summary
 
Fields inherited from class com.xuggle.ferry.RefCounted
swigCMemOwn
 
Constructor Summary
protected IRational(long cPtr, boolean cMemoryOwn)
          Internal Only.
protected IRational(long cPtr, boolean cMemoryOwn, AtomicLong ref)
          Internal Only.
 
Method Summary
 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(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.
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.
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.
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.
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
 String toString()
          Prints the contents of this object as a fraction.
 
Methods inherited from class com.xuggle.ferry.RefCounted
acquire, delete, getCPtr, getCurrentRefCount, getJavaRefCount, release
 
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,
                    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(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 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 Object
Returns:
the hashable value.

toString

public String toString()
Prints the contents of this object as a fraction.

Overrides:
toString in class Object
Returns:
"getNumerator()/getDenominator()"

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

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

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.

sMultiply

public static IRational sMultiply(IRational a,
                                  IRational b)
Multiples a by b.

Parameters:
a - the first number
b - the second number.
Returns:
a*b

divide

public IRational divide(IRational arg)
Divides this rational by arg.

Parameters:
arg - The divisor to use.
Returns:
this/arg.

sDivide

public static IRational sDivide(IRational a,
                                IRational b)
Divides a by b.

Parameters:
a - The first number. b The second number.
Returns:
a/b.

subtract

public IRational subtract(IRational arg)
Subtracts arg from this rational

Parameters:
arg - The amount to subtract from this.
Returns:
this-arg.

sSubtract

public static IRational sSubtract(IRational a,
                                  IRational b)
Subtracts a from b.

Parameters:
a - The first number. b The second number.
Returns:
a-b.

add

public IRational add(IRational arg)
Adds arg to this rational

Parameters:
arg - The amount to add to this.
Returns:
this+arg.

sAdd

public static IRational sAdd(IRational a,
                             IRational b)
Adds a to b.

Parameters:
a - The first number. b The second number.
Returns:
a+b.

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.
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.
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


Copyright © 2008, 2010 Xuggle