sub_arctic.output
Class gradient

java.lang.Object
  |
  +--sub_arctic.output.gradient

Direct Known Subclasses:

linear_gradient, radial_gradient

public abstract class gradient

extends java.lang.Object

An abstract class representing a gradient object. Gradients encapsulate a 1D sequence of colors that make up the gradient, along with a mapping from 2D space onto the 1D gradient space, and operations for drawing the gradient within a rectangular area of an image.

See Also:

linear_gradient

Field Summary

protected int[]	_color_values The array of color values (stored as ints encoded aarrggbb) providing the colors we interpolate across.
static int	alpha_shift Shift constant to extract alpha value from color.
static int	blue_shift Shift constant to extract blue value from color.
static int	green_shift Shift constant to extract green value from color.
static int	MASK_A_EQ Constant for mask test MASK.alpha == reference (can be inverted for !=)
static int	MASK_A_GT Constant for mask test MASK.alpha > reference (can be inverted for <=)
static int	MASK_A_LT Constant for mask test MASK.alpha < reference (can be inverted for >=)
static int	MASK_B_EQ Constant for mask test MASK.blue == reference (can be inverted for !=)
static int	MASK_B_GT Constant for mask test MASK.blue > reference (can be inverted for <=)
static int	MASK_B_LT Constant for mask test MASK.blue < reference (can be inverted for >=)
static int	MASK_EQ Constant for mask test MASK == reference (can be inverted for !=)
static int	red_shift Shift constant to extract red value from color.

Constructor Summary

gradient(int[] colors)
Full constructor

Method Summary

int	average_of_range(float indx1, float indx2) Compute an averaged color value for the sequence of colors appearing between two indexes into the gradient color array.
int	color_for_pixel(int left, int top) Compute the anti-aliased gradient color for the pixel whose top-left position is given.
int[]	color_values() The array of color values (stored as ints encoded aarrggbb) providing the colors we interpolate across.
abstract float	map_point_to_index(int ptx, int pty) Map the given point (expressed in the coordinate system of the gradient) to an index within the linear gradient color value array.
loaded_image	render_image(int x, int y, int w, int h) Produce an in-memory loaded_image containing the drawn gradient.
loaded_image	render_image(int x, int y, int w, int h, loaded_image mask, int test_code, boolean invert, int ref_color, int outside_mask_color) Produce an in-memory loaded_image containing the gradient drawn through a mask.
int[]	render_to_data(int x, int y, int w, int h) Produce an in-memory data array (suitable for constructing an image) containing the drawn gradient.
int[]	render_to_data(int x, int y, int w, int h, loaded_image mask, int test_code, boolean invert, int ref_color, int outside_mask_color) Produce an in-memory data array (suitable for constructing an image) containing the gradient drawn through a mask.
void	set_color_values(int[] new_vals) Set the array of color values (stored as ints encoded aarrggbb) providing the colors we interpolate across.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_color_values

protected int[] _color_values

The array of color values (stored as ints encoded aarrggbb) providing the colors we interpolate across. This array must have at least two values.

alpha_shift

public static final int alpha_shift

Shift constant to extract alpha value from color. alpha = (color_val >> alpha_shift) & 0xff

red_shift

public static final int red_shift

Shift constant to extract red value from color. red = (color_val >> red_shift) & 0xff

green_shift

public static final int green_shift

Shift constant to extract green value from color. green = (color_val >> green_shift) & 0xff

blue_shift

public static final int blue_shift

Shift constant to extract blue value from color. blue = (color_val >> blue_shift) & 0xff

MASK_EQ

public static final int MASK_EQ

Constant for mask test MASK == reference (can be inverted for !=)

MASK_A_EQ

public static final int MASK_A_EQ

Constant for mask test MASK.alpha == reference (can be inverted for !=)

MASK_B_EQ

public static final int MASK_B_EQ

Constant for mask test MASK.blue == reference (can be inverted for !=)

MASK_A_LT

public static final int MASK_A_LT

Constant for mask test MASK.alpha < reference (can be inverted for >=)

MASK_B_LT

public static final int MASK_B_LT

Constant for mask test MASK.blue < reference (can be inverted for >=)

MASK_A_GT

public static final int MASK_A_GT

Constant for mask test MASK.alpha > reference (can be inverted for <=)

MASK_B_GT

public static final int MASK_B_GT

Constant for mask test MASK.blue > reference (can be inverted for <=)

Constructor Detail

gradient

public gradient(int[] colors)

Full constructor

Parameters:

int[] - colors array of color values encoded as integers using the standard aarrggbb encoding (i.e., alpha value in the high byte, red value in the next, etc.). This array must have at least 2 values or an error will be thrown.

Method Detail

color_values

public int[] color_values()

The array of color values (stored as ints encoded aarrggbb) providing the colors we interpolate across. This array must have at least two values.

Returns:

int[] the array of color values

set_color_values

public void set_color_values(int[] new_vals)

Set the array of color values (stored as ints encoded aarrggbb) providing the colors we interpolate across. This array must have at least two values (if not, an error will be thrown).

Parameters:

int[] - new_vals the new array of color values

average_of_range

public int average_of_range(float indx1,
                            float indx2)

Compute an averaged color value for the sequence of colors appearing between two indexes into the gradient color array. Indexes are given as real numbers so that positions between values can be given. (This is important for proper antialiased results, if for example, the gradient contains only two colors.) The indexes given must be in order (indx1 <= index2) and within the range of the color_values array when truncated back to integers (however, these properties are not verified by this method).

Parameters:

float - indx1 index of start of range in color sequence

float - indx2 index of end of range in color sequence

Returns:

int the resulting averaged color stored as aarrggbb

map_point_to_index

public abstract float map_point_to_index(int ptx,
                                         int pty)

Map the given point (expressed in the coordinate system of the gradient) to an index within the linear gradient color value array. This corresponds to a mapping from 2D drawing space into the 1D gradient space. Exactly what this mapping is, is dependent on the nature (shape) of the gradient. For example, a linear gradient finds the point on its orientation line with the closest perpendicular distance, then uses the percentage distance of that point along its orientation line to determine the position in the gradient space. A radial gradient would measure the angle between the point, its center point, and the y axis and use that to determine the position in gradient space.

Note that the index result here is a float because we are interested in exact mappings to the 1D gradient space for anti-aliasing purposes. This routine returns values in the interval [0..color_values().length), so fractional values beyond the last index are possible. These represent positions within the last color sample in the sequence.

Parameters:

int - ptx x coordinate of the point to be mapped

int - pty y coordinate of the point to be mapped

float - the index position (possibly fractional) that the point maps to.

color_for_pixel

public int color_for_pixel(int left,
                           int top)

Compute the anti-aliased gradient color for the pixel whose top-left position is given. This is currently done in a simplified fashion where we map each of the corners of the pixel into its corresponding point in the space of the gradient, find the min and max of that range and average across that. This is not accurate in that it will throw out some transformations of the pixel. For example, for linear gradients it will ignore the effects of rotation of the pixel box with respect to the gradient space and approximate the pixel box by its axis aligned bounding box in gradient space instead. However, this approximation is fast, and for now seems to be accurate enough (since we are not normally using sequences of related gradents that vary over time, or otherwise closely comaring related gradients).

Parameters:

int - left x coordinate of top-left of pixel in question

int - top y coordinate of top-left of pixel in question

Returns:

int averaged color (encoded as an int in standard aarrggbb form) for pixel.

render_to_data

public int[] render_to_data(int x,
                            int y,
                            int w,
                            int h)

Produce an in-memory data array (suitable for constructing an image) containing the drawn gradient. The image will cover the indicated rectangle of the resulting gradient. What the coordinates mean is dependent on the gradient subclass. For example, for a linear gradient, these values place the result rectangle with respect to the (previously defined) orientation line of the gradient.

Parameters:

int - x left of result rectangle

int - y top of result rectangle

int - w width of result rectangle

int - h height of result rectangle

Returns:

int[]

render_to_data

public int[] render_to_data(int x,
                            int y,
                            int w,
                            int h,
                            loaded_image mask,
                            int test_code,
                            boolean invert,
                            int ref_color,
                            int outside_mask_color)

Produce an in-memory data array (suitable for constructing an image) containing the gradient drawn through a mask. The image will cover the indicated rectangle of the resulting gradient. What the coordinates mean is dependent on the gradient subclass. For example, for a linear gradient, these values place the result rectangle with respect to the (previously defined) orientation line of the gradient. Only pixels meeting a specified test on the mask are drawn from the gradient, other pixels are given a value from the outside_mask_color parameter. Tests provided include equality comparisons (==) against a reference color, or the alpha (transparency) or blue components of a reference color (the blue test is typically used for greyscale masks -- blue is just the fastest to get at, since it doesn't require a shift). Relational tests (< and >) against the alpha or blue components of a reference color, are also provided. Finally, each of the seven test codes may be optionally inverted in sense to get the remaining tests (!=, <=, and >=).

Parameters:

int - x left of result rectangle

int - y top of result rectangle

int - w width of result rectangle

int - h height of result rectangle

loaded_image - mask the mask to draw through. This must be of size w, h, or an error will be thrown.

int - test_code test done on mask pixels. Must have one of the values MASK_EQ, MASK_A_{EQ,LT,GT}, or MASK_B_{EQ,LT,GT}.

boolean - invert indicating if we should invert sense of test

int - ref_color reference color for mask test

int - outside_mask_color color to draw pixels that fall outside the mask

Returns:

int[] data array holding result.

render_image

public loaded_image render_image(int x,
                                 int y,
                                 int w,
                                 int h)

Produce an in-memory loaded_image containing the drawn gradient. The image will cover the indicated rectangle of the resulting gradient. What the coordinates mean is dependent on the gradient subclass. For example, for a linear gradient, these values place the result rectangle with respect to the (previously defined) orientation line of the gradient.

Parameters:

int - x left of result rectangle

int - y top of result rectangle

int - w width of result rectangle

int - h height of result rectangle

Returns:

loaded_image

render_image

public loaded_image render_image(int x,
                                 int y,
                                 int w,
                                 int h,
                                 loaded_image mask,
                                 int test_code,
                                 boolean invert,
                                 int ref_color,
                                 int outside_mask_color)

Produce an in-memory loaded_image containing the gradient drawn through a mask. The image will cover the indicated rectangle of the resulting gradient. What the coordinates mean is dependent on the gradient subclass. For example, for a linear gradient, these values place the result rectangle with respect to the (previously defined) orientation line of the gradient. Only pixels meeting a specified test on the mask are drawn from the gradient, other pixels are given a value from the outside_mask_color parameter. Tests provided include equality comparisons (==) against a reference color, or the alpha (transparency) or blue components of a reference color (the blue test is typically used for greyscale masks -- blue is just the fastest to get at, since it doesn't require a shift). Relational tests (< and >) against the alpha or blue components of a reference color, are also provided. Finally, each of the seven test codes may be optionally inverted in sense to get the remaining tests (!=, <=, and >=).

Parameters:

int - x left of result rectangle

int - y top of result rectangle

int - w width of result rectangle

int - h height of result rectangle

loaded_image - mask the mask to draw through. This must be of size w, h, or an error will be thrown.

int - test_code test done on mask pixels. Must have one of the values MASK_EQ, MASK_A_{EQ,LT,GT}, or MASK_B_{EQ,LT,GT}.

boolean - invert indicating if we should invert sense of test

int - ref_color reference color for mask test

int - outside_mask_color color to draw pixels that fall outside the mask

Returns:

loaded_image the resulting image