diff options
Diffstat (limited to 'libquanta_quantise.3')
| -rw-r--r-- | libquanta_quantise.3 | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/libquanta_quantise.3 b/libquanta_quantise.3 new file mode 100644 index 0000000..3a5db49 --- /dev/null +++ b/libquanta_quantise.3 @@ -0,0 +1,246 @@ +.TH LIBQUANTA_QUANTISE 3 libquanta +.SH NAME +libquanta_quantise \- Colour-quantise an image + +.SH SYNPOSIS +.nf +#include <libquanta.h> + +\fBstruct libquanta_image\fP { + size_t \fIwidth\fP; + size_t \fIheight\fP; + size_t \fIimage\fP[]; +}; + +\fBstruct libquanta_palette\fP { + size_t \fIsize\fP; + uint64_t \fIpalette\fP[]; +}; + +\fBstruct libquanta_channel\fP { + size_t \fIbits_in\fP; + size_t \fIbits_out\fP; + size_t \fIimage_width\fP; + size_t \fIimage_height\fP; + size_t \fIimage_row_size\fP; + size_t \fIimage_cell_size\fP; + const void *\fIimage\fP; +}; + +struct libquanta_image *\fBlibquanta_quantise\fP(struct libquanta_palette *\fIpalette\fP, ...); +struct libquanta_image *\fBlibquanta_vquantise\fP(struct libquanta_palette *\fIpalette\fP, va_list \fIargs\fP); +.fi +.PP +Link with +.I -lquanta +.IR -lm . + +.SH DESCRIPTION +The +.BR libquanta_quantise () +creates and returnes a colour-quantised image from +input image and desired palette size. +.PP +.I palette->size +shall the desired palette size: the maximum number +of colours. This value must be at least 1. +.I *palette +may be otherwise uninitialised. +.PP +Upon successful completion, +.I palette->size +will be set to the actual number of colours stored +in the palette, which will not exceed the input +value of +.IR palette->size. +Additionally, +.I palette->palette +will be filled with the colours in the colour +palette choosen by the function. For a colour index +.I i +(integer within [0, +.IR palette->size ) +(using the output value of +.IR palette->size )) +and channel index +.I j +(integer within [0, +.IR n ), +where +.I n +is the number of colour channels (the number of +arguments between +.I palette +and the +.I NULL +at the end of the argument list), +.I palette->palette[i*n+j] +is the value of the +.IR j -th +primary colour of the +.IR i -th +palette colour. +On failure, arbitrary values may be stored in +.IR palette->palette . +.PP +After +.I palette +the caller shall provide one +.B const struct libquanta_channel * +per primary colour (at least one) in the image's +colour model. This list shall be terminated by a +.I NULL +as the final argument. +For each such argument, +.I .bits_in +shall be the number of bits used to stored colour +values for that colour channel in the input image. +This value must be at least 1, but no greater than 64. +.I .bits_out +shall be the number of bits used to stored colour +values for that colour channel in the output colour +palette. This value must be at least 1, but no +greater than +.IR .bits_in . +.I .image_width +shall be the number of pixels the image is wide. +.I .image_height +shall be the number of pixels the image is tall. +.IR .image , +.IR .image_row_size , +and +.IR image_cell_size +shall be configured so that +.I &((const char *).image)[y * .image_row_size + x * .image_cell_size] +points to the value of pixel +.RI ( x , +.IR y ) +for the colour channel. +Although the naming of +.I .image_row_size +and +.I .image_cell_size +imply row-major layout, column-major layout +is also supported. If +.I .bits_in +is between 1 and 8 (inclusively), +values in +.I .image +shall use the type +.BR uint8_t . +If +.I .bits_in +is between 9 and 16, +.B uint16_t +is used. If +.I .bits_in +is between 17 and 32, +.B uint32_t +is used. If +.I .bits_in +is between 33 and 64, +.B uint64_t +is used. +.PP +For the returned +.BR "struct libquanta_image" , +.I width +will be set to the image width +.RI ( .image_width +used for the input +.IR "struct libquanta_channel" s), +.I height +will be set to the image height +.RI ( .image_height +used for the input +.IR "struct libquanta_channel" s), +and +.I .image[y*.width+x] +for each +.I y +in [0, +.IR .height ) +and each +.I x +in [0, +.IR .width ) +will be set to the index of the +palette colour selected for pixel +.RI ( x , +.IR y ), +will be less than the value assigned to +.I palette->size +when the function returns. +.PP +Unused elements in +.I palette->palette +may remain uninitialised or contain +arbitrary values when the function +returns. +.PP +The +.BR libquanta_vquantise () +function is a variant of the +.BR libquanta_quantise () +function, that uses +.I va_list args +to hold variadic arguments. + +.SH RETURN VALUE +Upon successful completion, the +.BR libquanta_quantise (3) +and +.BR libquanta_vquantise (3) +functions return a pointer to a newly +allocated colour-quantised image. The +caller is responsible for deallocating +the image by calling the +.BR free (3) +with the returned pointer. +On failure, the functions return +.I NULL +and set +.I errno +to indicate the error. + +.SH ERRORS +The +.BR libquanta_quantise () +and +.BR libquanta_vquantise () +functions will fail if: +.TP +.B EINVAL +.I palette +is +.IR NULL . +.TP +.B EINVAL +.I palette->size +is 0. +.TP +.B EINVAL +No colour cannel is provided (the first +variadic argument is +.IR NULL ). +.TP +.B EINVAL +At least one of the colour channel descriptions +have an invalid configuration +.RI ( .bits_in +is less than 1 or greater than 64, or +.I .bits_out +is less than 1 or greater than +.IR .bits_in ). +.TP +.B EINVAL +The colour channel descriptions do not have the +same image dimensions configured. +.TP +.B ENOMEM +Storage space available is insufficient. + +.SH SEE ALSO +.BR libquanta (7), +.BR libquanta_malloc_palette (3), +.BR libquanta_quantise_wu (3) |