It's important to note that a quantization value of 2 doesn't mean that a blend result will always be even (it could also be odd), since quantization determines the step increments from the first of the values being blended.

So, if the first value was 0, then a quantization of 2 would produce blend results like 0, 2, 4, etc. (i.e. even numbers). But if the first value was 1, then blend results like 1, 3, 5, etc. (i.e. odd numbers) would be produced.

Similarly, a quantization value of 1 doesn't guarantee that a blend result will always be an integer. If the first value was 1, then a quantization of 1 would produce blend results like 1, 2, 3, etc. (i.e. integers). However, if the first value was 1.5, then a quantization of 1 would produce blend results like 1.5, 2.5, 3.5, etc. (definitely not integers).

This is generally not an obstacle for applications that desire integer interpolated values, because in those cases both of the values being blended are almost certain to be integers, and a quantization value of 1 will have the desired effect under such conditions.

It is possible to specify a single quantization number that should apply to all components of a compound value (e.g. a color object with red, green, and blue properties).

EXAMPLE

var blendedColor = Uize.Math.Blend.blend (
  {red:255,green:128,blue:0},   // orange
  {red:179,green:136,blue:255}, // violet
  .5,
  1
);

In the above example, a new blended color is being created by blending between the colors orange and violet. The values to blend are specified using an object with red, green, and blue properties that specify the values for each of the three channels that constitute an RGB color. This approach leverages the Uize.Math.Blend.blend method's ability to interpolate arbitrarily complex, compound values. Now, the value for each of the red, green, and blue channels must be an integer - there is no meaning to floating point values for these channels.

So, if quantization is not specified when calling this method, then an RGB color with floating point channel values would be produced, and this might not be appropriate for the code that is being supplied the new blended color, or that code would have to do its own rounding. Specifying a value of 1 for the quantizationNUMorARRAYorOBJ parameter ensures that the values for all the channels of the blended color will be interpolated in steps of 1 and would, therefore, always be integers.

It is possible to specify a compound value for the quantizationNUMorARRAYorOBJ parameter, just as with the aNUMorARRAYorOBJ and bNUMorARRAYorOBJ parameters used to specify the two values being blended.

In fact, you can specify a quantization value that matches the structure of the values being blended and that specifies granular quantization for all components of a compound value blend.

EXAMPLE

var blendedColor = Uize.Math.Blend.blend (
  {red:255,green:128,blue:0},   // orange
  {red:179,green:136,blue:255}, // violet
  .5,
  {
    red:5,   // medium resolution
    green:1, // highest resolution
    blue:10  // low resolution
  }
);

In the above example, a value is being specified for the quantizationNUMorARRAYorOBJ parameter that matches the structure of the two values being blended, being an object with red, green, and blue properties just as with the RGB color tuple objects being blended.

This allows different quantization to be specified for the different subcomponents of the compound value that is produced from blending the two compound values. When performing blends using this compound quantization and different blend amounts, the value of the green channel would change with the highest resolution (while always being an integer), while the red channel value would change with less precision (in steps of 5) and the blue channel value would change with the least precision (steps of 10).

Given the above blend amount of .5, the statement would produce the result {red:215,green:132,blue:130}, whereas the same blend with a simple quantization of 1 would produce the result {red:217,green:132,blue:128}.

When specifying a compound quantization value, it is possible to omit quantization for certain components of the structured value, and the quantization for such components will be defaulted to 0.

EXAMPLE

var blendedColorAndOpacity = Uize.Math.Blend.blend (
  {
    color:{red:255,green:128,blue:0},  // orange
    opacity:0                          // completely transparent
  },
  {
    color:{red:179,green:136,blue:255}, // violet
    opacity:1                           // completely opaque
  },
  .5,
  {color:1}
);

In the above example, a blend of two structured values containing color and opacity information is being performed. Specifically, we are creating a halfway blend between fully transparent orange and fully opaque violet. This will produce the result {color:{red:217,green:132,blue:128},opacity:.5}

We are specifying a compound quantization value in this example. By specifying the value 1 for color, and not an entire subtree object with quantization values for red, green, and blue, the quantization of 1 applies to all three color channels. And by omitting a quantization value for opacity, the quantization for this component of the interpolated compound value defaults to 0 (i.e. no quantization / floating point precision).

So, a compound quantization value may have "terminations" and "omissions", both of which lead to defaulting behaviors. Omissions are essentially terminations with defaulting to 0. So, in effect, omitting a subtree is equivalent to "terminating" the subtree by specifying the simple value 0.

When specifying a compound value for quantization, it is possible to "terminate" the tree structure at any node of the tree by specifying a number in place of a subtree object/array.

This has the effect of imposing the quantization value specified for that node on all components of the subtree when interpolating the fade value. This is a convenience that allows defaulting at different levels of a compound quantization value.

EXAMPLE

var colorFade = Uize.Fade ({
  startValue:{
    colorA:{red:255,green:128,blue:0},   // orange
    colorB:{red:255,green:0,blue:0}      // pure red
  },
  endValue:{
    colorA:{red:179,green:136,blue:255}, // violet
    colorB:{red:0,green:0,blue:255}      // pure blue
  },
  quantization:{
    colorA:{
      red:5,   // medium resolution
      green:1, // highest resolution
      blue:10  // low resolution
    },
    colorB:1    // highest resolution
  },
  duration:2000
});

In the above example, a fade instance is created for fading two colors, colorA and colorB, where colorA is faded between orange and violet, and where colorB is faded between pure red and pure blue. A compound value is specified for quantization, where the structure mostly matches the structure of the start and end values, but with the key distinction that a simple number is specified for colorB, rather than an object with red, green, and blue properties as with colorA. This has the effect of defaulting the quantization for all components of the colorB subtree (i.e. red, green, and blue) in the interpolated compound value to 1.

There's nothing to say that values for the quantizationNUMorARRAYorOBJ parameter have to be integers.

You can just as well specify a floating point value for quantization. For example, a blend with a first value of 0 and with a quantization of .5 would produce the blend results like 0, .5, 1, 1.5, 2, 2.5, etc.

This could be useful in cases where a floating point blend result is acceptable, but where you wish to limit the number of value changes that occur for performance reasons when blends are repeatedly performed over a period of time (such as in an animation process). In such cases, setting a quantization to anything other than 0 would provide a throttling effect that would reduce the number of value updates that would occur.

EXAMPLE

var opacityFade = Uize.Fade ({
  startValue:0,
  endValue:1,
  quantization:.02,
  duration:2000
});

In the above example, a fade instance is created for fading an opacity value between 0 and 1. Opacity is a floating point value, where 0 represents completely transparent and 1 represents completely opaque. Setting a quantization of .02 for the fade ensures that there will be a maximum of 50 value updates (1 / .02) over the duration of the fade (there may be fewer, depending on CPU load).

In the simplest usage, a curve function can be specified when blending two number values.

EXAMPLE

function quadratic (value) {return value * value}

Uize.Math.Blend.blend (0,100,0,0,quadratic);   // returns 0
Uize.Math.Blend.blend (0,100,.1,0,quadratic);  // returns 1
Uize.Math.Blend.blend (0,100,.2,0,quadratic);  // returns 4
Uize.Math.Blend.blend (0,100,.3,0,quadratic);  // returns 9
Uize.Math.Blend.blend (0,100,.4,0,quadratic);  // returns 16
Uize.Math.Blend.blend (0,100,.5,0,quadratic);  // returns 25
Uize.Math.Blend.blend (0,100,.6,0,quadratic);  // returns 36
Uize.Math.Blend.blend (0,100,.7,0,quadratic);  // returns 49
Uize.Math.Blend.blend (0,100,.8,0,quadratic);  // returns 64
Uize.Math.Blend.blend (0,100,.9,0,quadratic);  // returns 81
Uize.Math.Blend.blend (0,100,1,0,quadratic);   // returns 100

In the above example, various blends are being created between the numbers 0 and 100, using a quadratic curve function. As you can tell from the results returned for the various blends, the blend result is not linear between 0 and 100 - instead, it follows a quadratic curve. For instance, the blend between 0 and 100 at the halfway point is not 50 (as it would be with a linear blend), but is instead 25.

When blending two compound (hierarchical) objects, a simple curve function can be specified for the curveFUNCorARRAYorOBJ parameter and this curve function will be applied when blending values for all nodes of the two hierarchical objects.

EXAMPLE

Uize.Math.Blend.blend (
  {red:210,green:105,blue:30},             // chocolate brown
  {red:139,green:69,blue:19},              // saddle brown
  .5,
  0,
  function (value) {return value * value}  // quadratic curve
);

RESULT

{red:174.5,green:87,blue:24.5}

In the above example, you will notice that the quadratic curve function has been applied when producing blended values for the red, green, and blue properties of the two color tuple objects being blended.

In the same way that one can specify a compound quantization value when blending two compound (hierarchical) objects, one can also specify a compound curve value in order to apply different curves to different parts of the structure of two hierarchical objects being blended.

EXAMPLE

Uize.Math.Blend.blend (
  {red:210,green:105,blue:30},                            // chocolate brown
  {red:139,green:69,blue:19},                             // saddle brown
  .5,
  0,
  {
    red:function (value) {return Math.pow (value,2)},    // quadratic curve
    green:function (value) {return Math.pow (value,3)},  // cubic curve
    blue:function (value) {return Math.pow (value,4)}    // quartic curve
  }
);

In the above example, two color tuple objects are being blended. To achieve different blend curves for the red, green, and blue components of the color, a compound curve value is specified.

By specifying a curve value that is an object with the same structure as the object values being blended, the curve functions specified for the properties of the compound curve value object are applied when creating blend values for each of the corresponding properties of the two object values being blended. So, the curve function specified for the red property of the curve value object is used when producing a blend value for the red property of the color tuples being blended.

RESULT

{red:192.25,green:100.5,blue:29.3125}

When a compound curve value is specified, its structure can be a subset of the structure of the two hierarchical objects being blended.

EXAMPLE

Uize.Math.Blend.blend (
  {red:210,green:105,blue:30},                           // chocolate brown
  {red:139,green:69,blue:19},                            // saddle brown
  .5,
  0,
  {
    red:function (value) {return Math.pow (value,2)},   // quadratic curve
    green:function (value) {return Math.pow (value,3)}  // cubic curve
  }
);

In the above example, two color tuple objects are being blended. Each tuple object contains red, green, and blue properties for the three channels of an RGB color value.

Now, in order to achieve non-linear blending for the red and green properties, we are specifying a compound curve value with curve functions specified for the red and green properties of the object. Because we are ok with the blend of the blue channel's value being linear, we can omit specifying a curve function for the blue property in the compound curve value - the blend will be defaulted to linear for this property.

RESULT

{red:192.25,green:100.5,blue:24.5}

When a compound curve value has no curve function explicitly specified for a property of the two hierarchical objects being blended, the curve function will be defaulted to the curve function of the parent node in the compound curve value.

EXAMPLE

Uize.Math.Blend.blend (
  {
    textColor:{red:255,green:222,blue:173},                  // navajo white
    bgColor:{red:210,green:105,blue:30}                      // chocolate brown
  },
  {
    textColor:{red:255,green:240,blue:230},                  // linen white
    bgColor:{red:139,green:69,blue:19}                       // saddle brown
  },
  .5,
  0,
  {
    textColor:function (value) {return Math.pow (value,2)},  // quadratic curve
    bgColor:function (value) {return Math.pow (value,3)}     // cubic curve
  }
);

In the above example, two sets of color values are being blended, each set containing two RGB color tuple objects.

Now, because we wish to blend the textColor and bgColor color values with different curves, we specify a compound curve value object containing textColor and bgColor properties. Because we want the curve for each of the colors to be applied to all three RGB color channels, we specify just a curve function for each of the textColor and bgColor properties.

Because no curve functions are specified explicitly for the red, green, and blue properties in the textColor and bgColor properties of the compound curve value, the curve functions are "inherited" for all the deeper nodes that exist in the corresponding spots in the structures of the hierarchical values being blended - in this case, the color channel properties.

RESULT

{
  textColor:{
    red:255,
    green:226.5,
    blue:187.25
  },
  bgColor:{
    red:201.125,
    green:100.5,
    blue:28.625
  }
}