<-- Back to AG_Intro.3


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


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)).


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


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(Read-only) Transparency control is disabled. Set (or cleared) when pixel-format is bound to a pixel format with (or without) alpha.
AG_HSVPAL_FORCE_NOALPHADisable the transparency control.
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)).


void AG_HSVPalUpdateHue (AG_HSVPal *pal, int x, int y)

void AG_HSVPalUpdateSV (AG_HSVPal *pal, int x, int y)

AG_HSVPalUpdateHue() sets the hue to that closest to cursor coordinates x, y and triggers a refresh. AG_HSVPalUpdateSV() sets the saturation and value to that at cursor coordinates x, y and triggers a refresh.


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.


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.


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.


AG_Intro(3), AG_Widget(3), AG_Window(3)

Lk EasyRGB

Lk HSV_Color_Space

Lk RGB_Color_Model


The AG_HSVPal widget first appeared in Agar 1.0.