UIZE JavaScript Framework

MODULES Uize.Curve.Mod

1. Introduction

The Uize.Curve.Mod module defines various curve function modifiers, to enable creation of new curve functions by combining existing curve functions.

DEVELOPERS: Chris van Rensburg

1.1. In A Nutshell

Curve function modifiers are curve function generators that accept curve functions as their primary inputs.

The Uize.Curve.Mod module provides a good selection of these curve function modifiers. Curve function modifiers operate on the curve functions they are provided in order to produce new, modified curve functions. You can consider them as operators that operate on curve functions to produce new curve functions. They could also be thought of as specialized parameterized curve function generators, where some - or all - of the parameters just happen to be curve functions. As an example, the Uize.Curve.Mod.blend static method blends the two specified curve functions to produce a new curve function, with blend parameters that let you specify the blend between the two curve functions.

"What does it mean to blend two functions?" you may ask. No, JavaScript doesn't support some crazy new math that allows us to add or multiply functions. Blending two curve functions is carried out by returning a new curve function that takes an input value, uses each of the two curve functions that are to be blended and obtains a remapped value from each, then blends between those two values to produce a new output value. This has the effect of blending the curves that would be produced by the two curve functions that are being blended - across their entire input value range. So, effectively, you are blending two curve functions to produce a new curve function.

EXAMPLE

// quickly to middle, hesitate, quickly to end

Uize.Curve.Mod.blend (
  Uize.Curve.easeInSweetPow (1/6),
  Uize.Curve.easeOutSweetPow (1/12),
  Uize.Curve.line (0,1)
)

In the above example, the curve function generated by the statement Uize.Curve.easeInSweetPow (1/6) is being blended with the curve function generated by the statement Uize.Curve.easeOutSweetPow (1/12), with the blend biased towards the first curve function at the lower input values, and biased towards the second curve function at the higher input values.

VISUALIZE IT

To better visualize how curve function modifiers work and how they affect motion, visit the interactive Curve Explorer tool.

BACKGROUND READING

For an in-depth discussion on animation in the UIZE JavaScript Framework, and for a discussion on how this module fits into the larger picture, consult the guide JavaScript Animation and Effects and read through the section Curves.

1.2. Examples

There are no dedicated showcase example pages for the Uize.Curve.Mod module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Curve.Mod module...

SEARCH

1.3. Implementation Info

The Uize.Curve.Mod module defines the Uize.Curve.Mod package under the Uize.Curve namespace.

1.3.1. Features Introduced in This Module

1.3.2. Features Overridden in This Module

No features have been overridden in this module.

1.3.3. Features Inherited From Other Modules

This module has no inherited features.

1.3.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.3.5. Unit Tests

There is no dedicated unit tests module for the Uize.Curve.Mod module.

2. Static Methods

2.1. Uize.Curve.Mod.band

Returns a curve function, that is the specified source curve function compressed into the specified horizontal and vertical band.

SYNTAX

curveFUNC = Uize.Curve.Mod.band (
  curveFUNCorFLOAT,sizeX0to1FLOAT,alignX0to1FLOAT,sizeY0to1FLOAT,alignY0to1FLOAT
);

2.1.1. Parameters

2.1.1.1. curveFUNCorFLOAT

A function reference for a curve function, or a numerical value that will be resolved to a power curve function using the Uize.Curve.resolve method, specifying the source curve function that should be compressed into the specified band.

For a linear curve, the value 1 can be specified for this parameter.

2.1.1.2. sizeX0to1FLOAT

A floating point number in the range of 0 to 1, specifying the width of the horizontal band.

2.1.1.3. alignX0to1FLOAT

A floating point number in the range of 0 to 1, specifying the horizontal alignment of the band.

The value 0 represents left aligned, the value .5 represents center aligned, and the value 1 represents right aligned. Other values between 0 and 1 represent continuous horizontal alignment between left and right. When the value 1 is specified for the sizeX0to1FLOAT parameter, then the alignX0to1FLOAT parameter has no effect.

2.1.1.4. sizeY0to1FLOAT

A floating point number in the range of 0 to 1, specifying the height of the vertical band.

2.1.1.5. alignY0to1FLOAT

A floating point number in the range of 0 to 1, specifying the vertical alignment of the band.

The value 0 represents bottom aligned, the value .5 represents center aligned, and the value 1 represents top aligned. Other values between 0 and 1 represent continuous vertical alignment between bottom and top. When the value 1 is specified for the sizeY0to1FLOAT parameter, then the alignY0to1FLOAT parameter has no effect.

VARIATION

curveFUNC = Uize.Curve.Mod.band (curveFUNCorFLOAT,sizeX0to1FLOAT,alignX0to1FLOAT);

When the sizeY0to1FLOAT and alignY0to1FLOAT parameters are not specified, then no vertical banding will be performed. This is equivalent to specifying the value 1 for the sizeY0to1FLOAT parameter. In order to only perform vertical banding and no horizontal banding, you can specify the value 1 for the sizeX0to1FLOAT parameter.

NOTES

numerical values for the curveFUNCorFLOAT parameter are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Curve.Mod.bend

Returns a curve function, that is the specified source curve function bent in the specified manner in the x- and y-axes.

SYNTAX

curveFUNC = Uize.Curve.Mod.bend (curveFUNCorFLOAT,bendXFUNCorFLOAT,bendYFUNCorFLOAT);

2.2.1. Parameters

2.2.1.1. curveFUNCorFLOAT

A function reference for a curve function, or a numerical value that will be resolved to a power curve function using the Uize.Curve.resolve method.

For a linear curve, the value 1 can be specified for this parameter.

2.2.1.2. bendXFUNCorFLOAT

A function reference for a curve function, or a numerical value that will be resolved to a power curve function using the Uize.Curve.resolve method.

Values less than -1 will bend the curve towards the left. Values greater than 1 will bend the curve towards the right. When the value null, undefined, 1, 0, -1, or Uize.Curve.linear is specified, then there will be no bending in the x-axis. If a curve function is specified for bendXFUNCorFLOAT, then the source curve function will be bent horizontally according to the nature of the specified bend curve. An ease-in-out bend curve will pinch the source curve function towards the center horizontally. An ease-in-the-middle bend curve will squash the source curve function outwards horizontally towards the left and right sides.

2.2.1.3. bendYFUNCorFLOAT

A function reference for a curve function, or a numerical value that will be resolved to a power curve function using the Uize.Curve.resolve method.

Values less than -1 will bend the curve towards the bottom. Values greater than 1 will bend the curve towards the top. When the value null, undefined, 1, 0, -1, or Uize.Curve.linear is specified, then there will be no bending in the y-axis. If a curve function is specified for bendYFUNCorFLOAT, then the source curve function will be bent vertically according to the nature of the specified bend curve. An ease-in-out bend curve will pinch the source curve function towards the center vertically. An ease-in-the-middle bend curve will squash the source curve function outwards vertically towards the top and bottom sides.

VARIATION

curveFUNC = Uize.Curve.Mod.bend (curveFUNCorFLOAT,bendXFUNCorFLOAT);

When no bendYFUNCorFLOAT parameter is specified, there will be no bending in the y-axis.

NOTES

numerical values for the curveFUNCorFLOAT, bendXFUNCorFLOAT, and bendYFUNCorFLOAT parameters are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Curve.Mod.blend

Returns a curve function, that is a blend between the two specified source curve functions.

SYNTAX

curveFUNC = Uize.Curve.Mod.blend (curve1FUNCorFLOAT,curve2FUNCorFLOAT,blend0to1FLOAT);

When the value 0 is specified for the blend0to1FLOAT parameter, then the curve function

specified by the curve1FUNCorFLOAT parameter will be returned. Similarly, when the value 1 is specified, then the curve function specified by the curve2FUNCorFLOAT parameter will be returned. When the value .5 is specified, the returned curve function will be an equal blend between the two specified source curve functions.

VARIATION 1

curveFUNC = Uize.Curve.Mod.blend (curve1FUNCorFLOAT,curve2FUNCorFLOAT);

When no blend0to1FLOAT parameter is specified, then the value .5 will be used as the default for this parameter and the two curve functions specified by the curve1FUNCorFLOAT and curve2FUNCorFLOAT parameters will be blended equally.

VARIATION 2

curveFUNC = Uize.Curve.Mod.blend (curve1FUNCorFLOAT,curve2FUNCorFLOAT,blendCurveFUNC);

When the blendCurveFUNC parameter is specified in place of the blend0to1FLOAT parameter, then the blend between the two curve functions can vary across the range of input values. Consider the following example...

EXAMPLE

Uize.Curve.Mod.blend (
  Uize.Curve.easeOutPow (4),  // ease-out power curve function
  Uize.Curve.saw (20,.5),     // sawtooth curve function with 20 teeth
  Uize.Curve.line (.25,.75)   // line starting at .25 and ending at .75
)

In the above example, a quartic ease-out power curve function is being blended with a sawtooth curve function with twenty teeth. The Uize.Curve.line method is being used to create a value range from .25 to .75 to control the blend between the two curve functions across the range of input values. At the input value of 0, the blend between the curves will be .25. At the input value of 1, the blend between the curves will be .75. At the input value of .5, the blend between the curves will be .5 (the midpoint value of the line curve).

2.3.1. Encapsulating a Curve

One useful technique that can employ the Uize.Curve.Mod.blend method is to encapsulate one curve between two other curves.

Basically, if you view the curve specified by the curve1FUNCorFLOAT parameter as being the ventral side of a "capsule", and view the curve specified by the curve2FUNCorFLOAT parameter as being the dorsal side of a "capsule", then a curve specified by the blendCurveFUNC parameter will essentially be fitted inbetween those two curves.

EXAMPLE

// bouncing down the stairs

Uize.Curve.Mod.blend (
  Uize.Curve.easeInPow (3),
  Uize.Curve.easeOutPow (1.5),
  Uize.Curve.Rubber.easeOutBounce (10,4,1.1)
)

The above expression generates a curve function that can be used to produce a bouncing-down-the-stairs type of effect. The ease-out bounce curve is being encapsulated between the ease-in power curve and the ease-out power curve.

NOTES

numerical values for the curve1FUNCorFLOAT and curve2FUNCorFLOAT parameters are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Curve.Mod.multiply

Returns a curve function, that is the two specified source curve functions multiplied together.

SYNTAX

curveFUNC = Uize.Curve.Mod.multiply (curve1FUNCorFLOAT,curve2FUNCorFLOAT);

Because curve functions produce values in the scale of 0 to 1, multiplying two curve functions together will tend to produce a new curve function that bends downwards more extremely.

NOTES

numerical values for the curve1FUNCorFLOAT and curve2FUNCorFLOAT parameters are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.5. Uize.Curve.Mod.quantize

Returns a new curve function, that is the specified curve function that has been quantized to have the specified number of steps.

SYNTAX

curveFUNC = Uize.Curve.Mod.quantize (curveFUNCorFLOAT,stepsINT);

VARIATION 1

curveFUNC = Uize.Curve.Mod.quantize (curveFUNCorFLOAT,stepsINT,stepAlign0to1FLOAT);

By default, quantization steps stay at the low side of their output value range throughout their input value range. When the optional stepAlign0to1FLOAT parameter is specified, this behavior can be controlled. When the value 0 is specified, the step up to the next step is aligned to the left side of the input value range. When the value 1 is specified, the step up to the next step is aligned to the right side of the input value range. When the value .5 is specified, the step up to the next step is aligned in the center of the input value range. Other values between 0 and 1 represent continuous horizontal alignment of the step up point between the left and right of each step's input value range.

VARIATION 2

curveFUNC = Uize.Curve.Mod.quantize (curveFUNCorFLOAT,stepsINT,stepCurveFUNC);

When the stepCurveFUNC parameter is specified in place of the stepAlign0to1FLOAT parameter, then the value distortion within the vertical quantization segment can be controlled. Ease-in-out curve functions can be used to squash the output values towards the top and bottom sides of the quantization segments, and ease-in-the-middle curve functions can be used to pinch the output values towards the center of the quantization segments. Needless to say, this is easier to visualize with a graph than describe with words.

NOTES

compare to the Uize.Curve.Mod.redraw static method
numerical values for the curveFUNCorFLOAT parameter are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.6. Uize.Curve.Mod.redraw

Returns a curve function, that is a redrawn version of the specified source curve function.

SYNTAX

curveFUNC = Uize.Curve.Mod.redraw (curveFUNCorFLOAT,segmentsINT,segmentCurveFUNCorFLOAT);

The Uize.Curve.Mod.redraw method divides the specified curve function into a number of segments in the x-axis, as specified by the segmentsINT parameter. It then redraws the curve between the ends of each segment by connecting the values at each end of a segment using the segment curve specified by the segmentCurveFUNCorFLOAT parameter. So, redraw is a little bit like quantization, but in the x-axis.

The Uize.Curve.Mod.redraw method removes detail from the original curve function and replaces it with new detail, as determined by the segmentCurveFUNCorFLOAT value. This method can have the effect of producing a simpler curve than the original, or producing a more complex curve. For example, a complex elastic curve function could be simplified by redrawing it using a small number of segments and replacing a lot of the complexity within those segments by redrawing using a simple linear segment curve function. On the other hand, a simple linear curve function could be made more complex by redrawing it using an elastic curve function for the segments.

VARIATION 1

curveFUNC = Uize.Curve.Mod.redraw (curveFUNCorFLOAT,segmentsINT);

When the segmentCurveFUNCorFLOAT parameter is not specified, then a linear curve function will be used for redrawing the segments.

VARIATION 2

curveFUNC = Uize.Curve.Mod.redraw (
  curveFUNCorFLOAT,segmentsINT,segmentCurveFUNCorFLOAT,alternatingRotateBOOL
);

When the value true is specified for the optional alternatingRotateBOOL parameter, then each alternating segment will be redrawn with a 180 degree rotated version of the curve function specified by the segmentCurveFUNCorFLOAT parameter. In other words, the first segment will be normal, the second segment will be rotated, the third segment will be normal, the fourth segment will be rotated, etc.

NOTES

compare to the Uize.Curve.Mod.quantize static method
numerical values for the curveFUNCorFLOAT and segmentCurveFUNCorFLOAT parameters are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.7. Uize.Curve.Mod.repeat

Returns a curve function, that is the specified curve function repeated the specified number of times.

SYNTAX

curveFUNC = Uize.Curve.Mod.repeat (curveFUNCorFLOATorARRAY,repeatsINT);

When an array is specified for the curveFUNCorFLOATorARRAY parameter, then the elements of the array should be curve functions, and these curve functions specified in the array will be cycled through for every successive repitition. There can be a different number of curve functions in the array than the value of the repeatsINT parameter. If the value of repeatsINT is greater than the length of the curve functions array, then the array will be cycled through more than once. If the value of repeatsINT is less than the length of array, then not all the curve functions in the array will be utilized.

VARIATION 1

curveFUNC = Uize.Curve.Mod.repeat (
  curveFUNCorFLOATorARRAY,repeatsINT,stairsDegree0to1FLOAT
);

By default, the curve specified by the curveFUNCorFLOATorARRAY is repeated as thought it were a waveform, with each successive repitition occupying the full vertical range of 0 to 1. Staircasing lets you stack the repititions along a diagonal line from left to right.

When the value 1 is specified for the stairsDegree0to1FLOAT parameter, the repititions are fully staircased, so that the top right of the previous repetition connects to the bottom left of the current repitition, allowing the curve line of the previous repitition to flow into the curve line of the next repitition. When ease-in-out or ease-in-the-middle curve functions are specified for the curveFUNCorFLOATorARRAY parameter, then the curve can be made seamless, because these types of curve functions are by design diagonally symmetrical.

When the value 0 is specified for the stairsDegree0to1FLOAT parameter, the repititions all occupy the full vertical range of 0 to 1. This is the default behavior. Other values between 0 and 1 represent continuous degrees of staircasing, between no staircasing and complete staircasing.

VARIATION 2

curveFUNC = Uize.Curve.Mod.repeat (
  curveFUNCorFLOATorARRAY,repeatsINT,stairsDegree0to1FLOAT,alternatingFlipHorzBOOL
);

When the optional alternatingFlipHorzBOOL parameter is specified, horizontal flipping for alternate repititions can be controlled. When the value true is specified for this parameter, the first repitition will be normal, the second repitition will be flipped, the third repitition will be normal, the fourth repitition will be flipped, etc.

VARIATION 3

curveFUNC = Uize.Curve.Mod.repeat (
  curveFUNCorFLOATorARRAY,
  repeatsINT,
  stairsDegree0to1FLOAT,
  alternatingFlipHorzBOOL,
  alternatingFlipVertBOOL
);

When the optional alternatingFlipVertBOOL parameter is specified, vertical flipping for alternate repititions can be controlled. When the value true is specified for this parameter, the first repitition will be normal, the second repitition will be flipped, the third repitition will be normal, the fourth repitition will be flipped, etc. If you specify the value true for both the alternatingFlipHorzBOOL and alternatingFlipVertBOOL parameters, then alternating repititions will be rotated 180 degrees.

IMPORTANT

When not specifying the same value for both the alternatingFlipHorzBOOL and alternatingFlipVertBOOL parameters, you should be sure to specify an odd number for the repeatsINT parameter. Otherwise, you won't be able to guanrantee that the resulting curve function will end at the value 1. By specifying an odd number of repeats you ensure that the last repitition will not be flipped horizontally or vertically, since only the alternating repititions are flipped.

NOTES

numerical values for the curveFUNCorFLOATorARRAY parameter are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.8. Uize.Curve.Mod.rotate

Returns a curve function, that is the 180 degree rotated version of the specified source curve function, or a blend between the specified curve function and the 180 degree rotated version of it.

SYNTAX

curveFUNC = Uize.Curve.Mod.rotate (curveFUNCorFLOAT);

VARIATION

curveFUNC = Uize.Curve.Mod.rotate (curveFUNCorFLOAT,blendOfRotated0to1FLOAT);

When the optional blendOfRotated0to1FLOAT parameter is specified, this method will return a blend between the unrotated curve function and the rotated version.

INSTEAD OF...

Uize.Curve.Mod.blend (Uize.Curve.makeEaseOut (Math.sqrt),Math.sqrt,.5);

USE...

Uize.Curve.Mod.rotate (Math.sqrt,.5);

Calling the Uize.Curve.Mod.rotate method without specifying the blendOfRotated0to1FLOAT parameter is equivalent to using the Uize.Curve.makeEaseOut static method. So, it's when you use the blendOfRotated0to1FLOAT parameter that this method becomes compelling.

NOTES

numerical values for the curveFUNCorFLOAT parameter are resolved to curve functions using the Uize.Curve.resolve static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Curve.Mod.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Curve.Mod.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module