.\" Copyright (c) 2005-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AG_HSVPAL 3
.Os Agar 1.7
.Sh NAME
.Nm AG_HSVPal
.Nd agar HSV color picker
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(/widgets/AG_HSVPal.png, "The AG_HSVPal(3) widget")
The
.Nm
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:
.Pp
.Bl -bullet -compact
.It
A native Agar
.Xr AG_Color 3 .
.It
Single-precision Hue, Saturation, Value and Alpha.
.It
8- or 16-bit integer RGBA components.
.It
Floating-point RGBA components.
.It
A 32- or 64-bit packed pixel (with corresponding
.Xr AG_PixelFormat 3 ) .
.El
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_HSVPal *"
.Fn AG_HSVPalNew "AG_Widget *parent" "Uint flags"
.Pp
.nr nS 0
The
.Fn AG_HSVPalNew
function allocates, initializes, and attaches a new
.Nm
widget.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_HSVPAL_FORCE_NOALPHA "
.It AG_HSVPAL_SHOW_RGB
Show the RGB value in text form.
.It AG_HSVPAL_SHOW_HSV
Show the HSV value in text form.
.It AG_HSVPAL_NOALPHA
(Read-only)
Transparency control is disabled.
Set (or cleared) when
.Va pixel-format
is bound to a pixel format with (or without) alpha.
.It AG_HSVPAL_FORCE_NOALPHA
Disable the transparency control.
.It AG_HSVPAL_NOPREVIEW
Disable the color preview band.
.It AG_HSVPAL_HFILL
Expand horizontally in parent container.
.It AG_HSVPAL_VFILL
Expand vertically in parent container.
.It AG_HSVPAL_EXPAND
Shorthand for
.Dv AG_HSVPAL_HFILL | AG_HSVPAL_VFILL .
.El
.Sh UPDATING VALUES
.nr nS 1
.Ft "void"
.Fn AG_HSVPalUpdateHue "AG_HSVPal *pal" "int x" "int y"
.Pp
.Ft "void"
.Fn AG_HSVPalUpdateSV "AG_HSVPal *pal" "int x" "int y"
.Pp
.nr nS 0
.Fn AG_HSVPalUpdateHue
sets the hue to that closest to cursor coordinates
.Fa x ,
.Fa y
and triggers a refresh.
.Fn AG_HSVPalUpdateSV
sets the saturation and value to that at cursor coordinates
.Fa x ,
.Fa y
and triggers a refresh.
.Sh BINDINGS
The
.Nm
widget provides the following bindings:
.Pp
.Bl -tag -compact -width "AG_PixelFormat **pixel-format "
.It Va AG_Color *agcolor
A native
.Xr AG_Color 3
structure.
.It Va float *hue
Hue (0..1).
.It Va float *saturation
Saturation (0..1).
.It Va float *value
Value (0..1).
.It Va float *alpha
Single-precision component value (0..1).
.It Va AG_PixelFormat **pixel-format
Pointer to
.Xr AG_PixelFormat 3
describing the packed-pixel format of
.Va pixel
and
.Va pixel64 .
Note that
.Va pixel-format
should be set first.
If the format has an alpha component,
.Dv AG_HSVPAL_NOALPHA will be set accordingly
(use
.Dv AG_HSVPAL_FORCE_NOALPHA
to disable).
.It Va Uint32 *pixel
32-bit packed pixel value.
.It Va Uint64 *pixel64
64-bit packed pixel value.
Available in
.Dv AG_LARGE
build.
.It Va 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.
.It Va void *RGBAv
Same as above, except that the array has 4 elements where the last element
is the alpha component.
.El
.Sh EVENTS
The
.Nm
widget generates the following events:
.Pp
.Bl -tag -compact -width 2n
.It Fn h-changed "void"
The hue has changed.
.It Fn sv-changed "void"
The saturation or the value has changed.
.El
.Sh BUGS
Conversion between integer RGB and HSV triplets incurs 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.
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Pp
.Bl -tag -compact
.It Lk https://www.easyrgb.com/ EasyRGB
.It Lk https://en.wikipedia.org/wiki/HSV_color_space HSV Color Space
.It Lk https://en.wikipedia.org/wiki/RGB_color_model RGB Color Model
.El
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
The
.Va pixel64
binding,
.Fn AG_HSVPalUpdateHue
and
.Fn AG_HSVPalUpdateSV
appeared in Agar 1.6.0.