Agar


Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

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_NOALPHADisable 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_NOALPHADisable the alpha component editor, regardless of whether the pixel format includes alpha support.
AG_HSVPAL_NOPREVIEWDisable the color preview band.
AG_HSVPAL_HFILLExpand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_HSVPAL_VFILLExpand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_HSVPAL_EXPANDShorthand 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 reacts to the following events:
mouse-button-*Edit the selected RGBA component.
boundIf a new pixel binding is made, the pixel's components are extracted and the hue, saturation, value and alpha values are updated to reflect an approximation.

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 - http://en.wikipedia.org/wiki/HSV_color_space
The RGB color model - http://en.wikipedia.org/wiki/RGB_color_model

HISTORY

The AG_HSVPal widget first appeared in Agar 1.0.