A color band is a type of Texture that allows you to create a series of color gradients in pixels along a single band. They are usually used to create different type of effect or procedurally generated at runtime based on different scenarios or user inputs.

See Also

Static Variables

Name	Description
`texture`	The parent Texture asset the ColorBand belongs to.
Declaration Texture *texture
`colorkey_count`	The current amount of ColorKey the ColorBand contains
Declaration unsigned char colorkey_count

Variables

Name	Description
`selected`	The unique id of the ColorKey currently selected.
Declaration unsigned int selected
`interpolation_type`	The type of interpolation to used to generate the ColorBand gradient.
Declaration InterpolationType interpolation_type Note Refer to the InterpolationType API help section to learn more about how each interpolation can affect the final gradient generated for the active ColorBand.

Functions

Name	Description
`AddColorKey`	Create and add a new ColorKey to the ColorBand.
Declaration unsigned char AddColorKey( unsigned int uid, float position, const vec4 color ) Parameters `uid`: Unique id of the ColorKey (pass 0 for a new one). `position`: Normalized position of the ColorKey within the band. `color`: The color to use for the key. Return Value The index of the newly created ColorKey.
`SetColorKey`	Update the parameters of an existing ColorKey.
Declaration bool SetColorKey( unsigned char index, float position, const vec4 color ) Parameters `index`: ColorKey index to update. `position`: The new position to use. `color`: The new color to use. Return Value `true` if the ColorKey have been updated; `false` if the `index` parameter provided does not refer to any existing ColorKey defined on the band.
`GetColorKey`	Retrieve a specific ColorKey using its unique id as key.
Declaration ColorKey GetColorKey( unsigned int uid ) Parameters* `uid`: The unique id of the ColorKey to retrieve. Return Value A reference to the ColorKey; else return `nil` if the unique id does not match any.
`GetColorKeyAt`	Get an existing ColorKey by index.
Declaration ColorKey GetColorKeyAt( unsigned char index ) Parameters* `index`: The index of the ColorKey to retrieve. Return Value The reference of the ColorKey pointed by `index`; else return `nil` if the index is invalid.
`GetColorAtPosition`	Get the color used by a ColorKey using a position on the band as key.
Declaration vec4 GetColorAtPosition( float position ) Parameters `position`: The position of the ColorKey to retrieve. Return Value A `vec4` containing the interpolated color for the position specified; else return a negative vector if the ColorBand is not attached to a Texture or if the size of the Texture is less than 8 pixels.
`GetColorKeyAtPosition`	Retrieve an existing ColorKey using its position as key.
Declaration ColorKey GetColorKeyAtPosition( float position, float threshold ) Parameters* `position`: The relative position of the ColorKey within the band. `threshold`: Specify the maximum distance to the `position` the key can be located at. Return Value The reference of the ColorKey located at the `position`; else return `nil`.
`ColorKeyIndex`	Get the index of an existing ColorKey.
Declaration int ColorKeyIndex( const ColorKey colorkey ) Parameters* `colorkey`: Reference to a ColorKey. Return Value The index of the `colorkey` pass in parameter; else return `nil` if it does not belong to the current ColorBand.
`RemoveColorKey`	Remove an existing ColorKey using its reference as key.
Declaration bool RemoveColorKey( ColorKey colorkey ) Parameters* `colorkey`: An existing ColorKey that belongs to the active ColorBand. Return Value `true` if the `colorkey` have been removed; else `false` if the `colorkey` does not belong to the current ColorBand.
`RemoveColorKeyAt`	Remove a ColorKey from the active band using its index.
Declaration bool RemoveColorKeyAt( int index ) Parameters `index`: The index of the ColorKey to remove. Return Value `true` if the ColorKey have been removed; else `false` if the `index` is invalid (non existent). Note Using a negative value as `index` will remove all existing ColorKey.
`ToTexture`	Generate a Texture based on the active ColorBand configuration.
Declaration bool ToTexture( void ) Return Value `true` if the ColorBand have successfully been converted to a Texture else return `false` if the band is not connected to a Texture, or if the size in pixels of the Texmap is less than 8 pixels.

ColorKey

Structure that holds the information of a single color placed on the band.

Static Variables

Name Description

uid Unique id to identify the color key within the ColorBand.

Declaration

unsigned int uid

Variables

Name	Description
`position`	Normalized location of the color key within the band.
Declaration float position Range 0.0 to 1.0 Note The position should be specified within the range of 0.0 to 1.0; zero represent the left side of the band and one the right side.
`color`	The current color set for the active ColorKey.
Declaration vec4 color Remarks The color variable is a normalized RGBA value (ranging from 0.0 to 1.0) where `x` is the red component and `w` is the alpha value.