AG_HSVPAL(3)

NAME
AG_HSVPal - agar HSV color wheel widget

SYNOPSIS

    #include <agar/core.h>
    #include <agar/gui.h>

DESCRIPTION
The AG_HSVPal widget is a HSV (Hue, Saturation, Value) color editor which allows the user to edit a color's hue, saturation, value and alpha components. The widget can bind directly to different color representations:

•   Individual Hue / Saturation / Value / Alpha floats.
•   Individual R/G/B/A component integers or floats.
•   An AG_Color(3) structure.
•   A pixel element in packed-pixel format (e.g., an Uint32 and a corresponding AG_PixelFormat(3)).

INHERITANCE HIERARCHY
AG_Object(3) -> AG_Widget(3) -> AG_HSVPal.

INITIALIZATION
AG_HSVPal * AG_HSVPalNew(AG_Widget *parent, Uint flags)

The AG_HSVPalNew() function allocates, initializes, and attaches a new AG_HSVPal widget. Acceptable flags include:

AG_HSVPAL_NOALPHA
    Disable the alpha component editor. This flag is automatically set or cleared whenever pixel-format is bound to a pixel format with or without alpha channel.

AG_HSVPAL_FORCE_NOALPHA
    Disable the alpha component editor, regardless of whether the pixel format includes alpha support.

AG_HSVPAL_NOPREVIEW
    Disable the color preview band.

AG_HSVPAL_HFILL
    Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).

AG_HSVPAL_VFILL
    Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).

AG_HSVPAL_EXPAND
    Shorthand for AG_HSVPAL_HFILL|AG_HSVPAL_VFILL.

BINDINGS
The AG_HSVPal widget provides the following bindings:

float *hue
    Color hue (0..1).
float *saturation
    Color saturation (0..1).
float *value
    Color brightness (0..1).
float *alpha
    Alpha component value (0..1).
AG_PixelFormat **pixel-format
    Pointer to the AG_PixelFormat(3) to use for generating the pixel value. The AG_HSVPAL_NOALPHA flag will be set automatically depending on the presence of an alpha component in the newly bound format (use AG_HSVPAL_FORCE_NOALPHA to disable this test).
Uint32 *pixel
    Resulting pixel value. The pixel's components are extracted immediately when this binding is made (using the current pixel-format) so make sure to always bind pixel-format prior to pixel.
void *RGBv
    A three-element array containing the RGB components. Acceptable binding types include FLOAT and DOUBLE, INT and UINT8. For floating point types, the values are scaled to 0.0-1.0. For integral types, the values are scaled to 0-255.
void *RGBAv
    Same as above, except that the array has 4 elements where the last element is the alpha component.

EVENTS
The AG_HSVPal widget generates the following events:

h-changed(void)
    The hue has changed.
sv-changed(void)
    The saturation or the value has changed.

TROUBLETONS
The conversion between integer RGB and HSV triplets is not reversible without loss of precision. In cases where it is desirable to maintain the same hue throughout changes in saturation, the color should be stored in HSV format.

SEE ALSO
AG_Intro(3), AG_Widget(3), AG_Window(3)

EasyRGB: http://www.easyrgb.com/

The HSV color model: https://en.wikipedia.org/wiki/HSV_color_space

The RGB color model: https://en.wikipedia.org/wiki/RGB_color_model

HISTORY
The AG_HSVPal widget first appeared in Agar 1.0.