aboutsummaryrefslogtreecommitdiffstats
path: root/libglitter.h
blob: 9b2f30f07c8b07d2b1d7b4095fff1c3b881778b6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
/* See LICENSE file for copyright and license details. */
#ifndef LIBGLITTER_H
#define LIBGLITTER_H

#include <stddef.h>
#include <stdint.h>


/**
 * The application will use `double`-typed rasters
 */
#define LIBGLITTER_FEATURE_DOUBLE_TYPE     UINT64_C(0x0000000000000001)

/**
 * The application will use `float`-typed rasters
 */
#define LIBGLITTER_FEATURE_FLOAT_TYPE      UINT64_C(0x0000000000000002)

/**
 * The application will use `uint64_t`-typed rasters
 */
#define LIBGLITTER_FEATURE_UINT64_TYPE     UINT64_C(0x0000000000000004)

/**
 * The application will use `uint32_t`-typed rasters
 */
#define LIBGLITTER_FEATURE_UINT32_TYPE     UINT64_C(0x0000000000000008)

/**
 * The application will use `uint16_t`-typed rasters
 */
#define LIBGLITTER_FEATURE_UINT16_TYPE     UINT64_C(0x0000000000000010)

/**
 * The application will use `uint8_t`-typed rasters
 */
#define LIBGLITTER_FEATURE_UINT8_TYPE      UINT64_C(0x0000000000000020)

/**
 * The allocation will use at least one of the functions
 * `libglitter_compose_double`,
 * `libglitter_compose_float`,
 * `libglitter_compose_uint64`,
 * `libglitter_compose_uint32`,
 * `libglitter_compose_uint16`, and
 * `libglitter_compose_uint8`
 */
#define LIBGLITTER_FEATURE_COMPOSE         UINT64_C(0x0000000000000040)

/**
 * The allocation will use at least one of the functions
 * `libglitter_desaturate_double`, and
 * `libglitter_desaturate_float`
 */
#define LIBGLITTER_FEATURE_CU_DESATURATION UINT64_C(0x0000000000000080) /* CU = channel-uniform */

/**
 * The allocation will use at least one of the functions
 * `libglitter_per_channel_desaturate_double`, and
 * `libglitter_per_channel_desaturate_float`
 */
#define LIBGLITTER_FEATURE_PC_DESATURATION UINT64_C(0x0000000000000100) /* PC = per channel */

/**
 * The allocation will use at least one of the functions
 * `libglitter_colour_model_convert_rasters_double`, and
 * `libglitter_colour_model_convert_rasters_float`
 */
#define LIBGLITTER_FEATURE_COLOUR_MODEL    UINT64_C(0x0000000000000200)


/**
 * The CIE xyY values of the D65 illuminant
 */
#define LIBGLITTER_ILLUMINANT_D65\
	0.312726871026564878786047074755,\
	0.329023206641284038376227272238, 1.0\


/**
 * Rendering context for an input raster's specifications
 * 
 * Render context's are thread-safe, however updating them are not
 */
typedef struct libglitter_render_context LIBGLITTER_RENDER_CONTEXT;


/**
 * Output primary colour
 */
enum libglitter_colour {
	/**
	 * Red primary colour
	 */
	LIBGLITTER_CHANNEL_RED = 0,

	/**
	 * Green primary colour
	 */
	LIBGLITTER_CHANNEL_GREEN = 1,

	/**
	 * Blue primary colour
	 */
	LIBGLITTER_CHANNEL_BLUE = 2
};


/**
 * Attempt to enable hardware acceleration
 * 
 * Currently this function doesn't do anything but call the
 * callback function and return 0; it is provided for application
 * to use know and get hardware acceleration when it is implemented
 * 
 * @param   features  Set of features to enable hardware acceleration
 *                    for, unrecognised bits are silently ignored.
 *                    Recognised bit values are:
 *                    - LIBGLITTER_FEATURE_DOUBLE_TYPE,
 *                    - LIBGLITTER_FEATURE_FLOAT_TYPE,
 *                    - LIBGLITTER_FEATURE_UINT64_TYPE,
 *                    - LIBGLITTER_FEATURE_UINT32_TYPE,
 *                    - LIBGLITTER_FEATURE_UINT16_TYPE,
 *                    - LIBGLITTER_FEATURE_UINT8_TYPE,
 *                    - LIBGLITTER_FEATURE_COMPOSE,
 *                    - LIBGLITTER_FEATURE_CU_DESATURATION,
 *                    - LIBGLITTER_FEATURE_PC_DESATURATION, and
 *                    - LIBGLITTER_FEATURE_COLOUR_MODEL.
 * @param   async     Whether the function shall return immediately
 *                    rather than when complete
 * @param   callback  Callback function that is called at function
 *                    completion, the first argument will be either
 *                    1 on success with hardware acceleration enabled,
 *                    0 on success without hardware acceleration enabled,
 *                    or -1 on failure; the second argument will be 0
 *                    on success or an error code on failure; the third
 *                    argument will be `userdata`. This argument may
 *                    also be `NULL` if no callback function shall be
 *                    called
 * @param   userdata  User-specific data to pass into `callback`, may be `NULL`
 * @param   unused    Reserved for future use, shall be `NULL`
 * @return            1 on success with hardware acceleration enabled,
 *                    0 on success without hardware acceleration enabled,
 *                    or -1 on failure
 */
int libglitter_enable_acceleration(uint64_t, int, void (*)(int, int, void *), void *, void *);


/**
 * Create a render context for an input raster's specifications
 * 
 * Render context's are thread-safe
 * 
 * @param  noutputs     The number of output buffers
 * @param  rowsize      The number of cells per row in the input raster
 * @param  widthmul     The horizontal number of cells per pixel in the input raster
 * @param  heightmul    The vertical number of cells per pixel in the input raster
 * @param  cellmap      Subpixel map of size `heightmul * widthmul` that maps a
 *                      cell for a pixel in the input raster to an output raster
 *                      (the output raster's index); this is row-major map, and
 *                      each valid value must appear at least once
 * @param  ncellvalues  For each `i` in [0, `noutputs`), `ncellvalues[i]`
 *                      shall be the number of times the value `i` occurs
 *                      in `cellmap`
 * @return              A render context that can be deallocate using
 *                      `libglitter_free_render_context` or updated with
 *                      `libglitter_update_render_context`; `NULL` on failure
 *
 * @throws  ENOMEM  Couldn't not allocate enough memory
 * 
 * If `noutputs` is 3 and either `widthmul` or `heightmul` is 3 and
 * the other one is 1, `ncellvalues` will not be used as it is preknown
 * that all its values are 1; in the future this could also happen for
 * other situations where `noutputs == widthmul * heightmul`
 */
LIBGLITTER_RENDER_CONTEXT *libglitter_create_render_context(size_t, size_t, size_t, size_t,
                                                            const uint8_t *, const uint8_t *);

/**
 * Update a render context (created by `libglitter_create_render_context`)
 * for a new input raster buffer
 * 
 * Updating a render context is not thread-safe
 * 
 * @param  this     The render context to refresh
 * @param  rowsize  The number of cells per row in the input raster
 */
void libglitter_update_render_context(LIBGLITTER_RENDER_CONTEXT *, size_t);

/**
 * Deallocates a render context (created by `libglitter_create_render_context`)
 * 
 * @param  this  The render context to deallocate
 */
void libglitter_free_render_context(LIBGLITTER_RENDER_CONTEXT *);


/**
 * Create one raster per monitor colour from a raster of
 * subpixels (which may be further divided in the raster)
 * 
 * Note that this function does not regard the colour
 * model's transfer function: it does not directly give
 * you appropriate sRGB values
 * 
 * @param  outputs          Array of output rasters, one for each subpixel colour.
 *                          The function may change the offset for each raster,
 *                          as such, the given pointer shall not be used anywhere
 *                          else during the execution of the function and the
 *                          inner pointers shall be considered undefined after
 *                          the execution of the function.
 * @param  input            Input raster; cells are adjacent
 * @param  output_rowsize   The number of cells in a row in each output raster
 * @param  output_cellsize  The number of values stored in each output raster,
 *                          between each cell, plus 1 (that is, the number of
 *                          values per cell)
 * @param  width            The horizontal number of pixels in the rasters
 * @param  height           The vertical number of pixels in the rasters
 * @param  render_ctx       Rendering context created for the input raster's
 *                          specification
 */
void libglitter_compose_double(double **, const double *restrict, size_t, size_t,
                               size_t, size_t, const LIBGLITTER_RENDER_CONTEXT *);

/**
 * This value is identical to `libglitter_compose_double`,
 * apart from it parameter types, see `libglitter_compose_double`
 * for details about this function
 */
void libglitter_compose_float(float **, const float *restrict, size_t, size_t,
                              size_t, size_t, const LIBGLITTER_RENDER_CONTEXT *);

/**
 * Create one raster per monitor colour from a raster of
 * subpixels (which may be further divided in the raster)
 * 
 * Note that this function does not regard the colour
 * model's transfer function: it does not directly give
 * you appropriate sRGB values
 * 
 * @param  outputs          Array of output rasters, one for each subpixel colour.
 *                          The function may change the offset for each raster,
 *                          as such, the given pointer shall not be used anywhere
 *                          else during the execution of the function and the
 *                          inner pointers shall be considered undefined after
 *                          the execution of the function.
 * @param  input            Input raster; cells are adjacent
 * @param  output_rowsize   The number of cells in a row in each output raster
 * @param  output_cellsize  The number of values stored in each output raster,
 *                          between each cell, plus 1 (that is, the number of
 *                          values per cell)
 * @param  width            The horizontal number of pixels in the rasters
 * @param  height           The vertical number of pixels in the rasters
 * @param  render_ctx       Rendering context created for the input raster's
 *                          specification
 */
void libglitter_compose_uint64(uint64_t **, const uint64_t *restrict, size_t, size_t,
                               size_t, size_t, const LIBGLITTER_RENDER_CONTEXT *);

/**
 * This value is identical to `libglitter_compose_uint64`,
 * apart from it parameter types, see `libglitter_compose_uint64`
 * for details about this function
 */
void libglitter_compose_uint32(uint32_t **, const uint32_t *restrict, size_t, size_t,
                               size_t, size_t, const LIBGLITTER_RENDER_CONTEXT *);

/**
 * This value is identical to `libglitter_compose_uint64`,
 * apart from it parameter types, see `libglitter_compose_uint64`
 * for details about this function
 */
void libglitter_compose_uint16(uint16_t **, const uint16_t *restrict, size_t, size_t,
                               size_t, size_t, const LIBGLITTER_RENDER_CONTEXT *);

/**
 * This value is identical to `libglitter_compose_uint64`,
 * apart from it parameter types, see `libglitter_compose_uint64`
 * for details about this function
 */
void libglitter_compose_uint8(uint8_t **, const uint8_t *restrict, size_t, size_t,
                              size_t, size_t, const LIBGLITTER_RENDER_CONTEXT *);


/**
 * Reorders a set of three rasters
 * 
 * When the function `libglitter_create_render_context` is called,
 * the parameter named `cellmap` contains the values 0, 1, and 2,
 * representing different channels: indices in the raster array.
 * The values are not necessarily 0 for red, 1 for green, and 2 for blue,
 * but this function lets the user reorder the rasters so that before
 * calling this function the rasters may be in this order, but when
 * call a `libglitter_compose_*` function after calling this function,
 * that function will write to the correct rasters
 * 
 * @param  rasters  The array of the three rasters, on input the rasters
 *                  shall be in the order (0) red, (1) green, (2) blue;
 *                  the function will reorder them
 * @param  colour1  The colour of the channel value 0 represents in `cellmap`
 * @param  colour2  The colour of the channel value 1 represents in `cellmap`
 * @param  colour3  The colour of the channel value 2 represents in `cellmap`
 *
 * The values `colour1`, `colour2`, `colour3` must be valid but distinct
 */
void libglitter_reorder_rasters(void **, enum libglitter_colour, enum libglitter_colour, enum libglitter_colour);


/**
 * Splits a `uint64_t` raster into one `uint16_t` raster per channel
 * 
 * @param  rasters   Output array for the rasters, they will be in the
 *                   order (0) red, (1) green, (2) blue
 * @param  alphap    Output parameter for the alpha mask raster, or `NULL`
 * @param  raster    The raster that is being split
 * @param  red       The value `0xFFFF` shifted such that value
 *                   expresses pure red (closest primary colour)
 * @param  green     The value `0xFFFF` shifted such that value
 *                   expresses pure green (closest primary colour)
 * @param  blue      The value `0xFFFF` shifted such that value
 *                   expresses pure blue (closest primary colour)
 */
void libglitter_split_uint64_raster(uint16_t *[3], uint16_t **, uint64_t *, uint64_t, uint64_t, uint64_t);

/**
 * Splits a `uint32_t` raster into one `uint8_t` raster per channel
 * 
 * @param  rasters   Output array for the rasters, they will be in the
 *                   order (0) red, (1) green, (2) blue
 * @param  alphap    Output parameter for the alpha mask raster, or `NULL`
 * @param  raster    The raster that is being split
 * @param  red       The value `0xFF` shifted such that value
 *                   expresses pure red (closest primary colour)
 * @param  green     The value `0xFF` shifted such that value
 *                   expresses pure green (closest primary colour)
 * @param  blue      The value `0xFF` shifted such that value
 *                   expresses pure blue (closest primary colour)
 */
void libglitter_split_uint32_raster(uint8_t *[3], uint8_t **, uint32_t *, uint32_t, uint32_t, uint32_t);


/**
 * Transform rasters from fully using subpixel rendering to
 * balance between subpixel rendering and greyscale antialiasing
 * 
 * @param  rasters     Array of rasters, one for each subpixel colour.
 *                     The function may change the offset for each raster,
 *                     as such, the given pointer shall not be used anywhere
 *                     else during the execution of the function and the
 *                     inner pointers shall be considered undefined after
 *                     the execution of the function
 * @param  nrasters    The number of rasters
 * @param  rowsize     The number of cells in a row in each raster
 * @param  cellsize    The number of values stored in each raster,
 *                     between each cell, plus 1 (that is, the number of
 *                     values per cell)
 * @param  width       The horizontal number of pixels in the rasters
 * @param  height      The vertical number of pixels in the rasters
 * @param  saturation  The subpixel rendering saturation, 1 for regular
 *                     subpixel rendering, 0 for greyscale, values
 *                     in between for a compromise
 * @param  primary_ys  The CIE Y value (in e.g. CIE xyY or CIE XYZ) for
 *                     each subpixel colour; or `NULL` for the sRGB values
 *                     (this is only allowed if there are exactly 3 rasters)
 */
void libglitter_desaturate_double(double **, size_t, size_t, size_t, size_t, size_t, double, const double *restrict);

/**
 * This value is identical to `libglitter_desaturate_double`,
 * apart from it parameter types, see `libglitter_desaturate_double`
 * for details about this function
 */
void libglitter_desaturate_float(float **, size_t, size_t, size_t, size_t, size_t, float, const float *restrict);

/**
 * Transform rasters from fully using subpixel rendering to
 * balance between subpixel rendering and greyscale antialiasing
 * 
 * @param  rasters      Array of rasters, one for each subpixel colour.
 *                      The function may change the offset for each raster,
 *                      as such, the given pointer shall not be used anywhere
 *                      else during the execution of the function and the
 *                      inner pointers shall be considered undefined after
 *                      the execution of the function.
 * @param  nrasters     The number of rasters
 * @param  rowsize      The number of cells in a row in each raster
 * @param  cellsize     The number of values stored in each raster,
 *                      between each cell, plus 1 (that is, the number of
 *                      values per cell)
 * @param  width        The horizontal number of pixels in the rasters
 * @param  height       The vertical number of pixels in the rasters
 * @param  saturations  The subpixel rendering saturation for each raster,
 *                      1 for regular subpixel rendering, 0 for greyscale,
 *                      values in between for a compromise
 * @param  primary_ys   The CIE Y value (in e.g. CIE xyY or CIE XYZ) for
 *                      each subpixel colour; or `NULL` for the sRGB values
 *                      (this is only allowed if there are exactly 3 rasters)
 */
void libglitter_per_channel_desaturate_double(double **, size_t, size_t, size_t, size_t, size_t,
                                              const double *restrict, const double *restrict);

/**
 * This value is identical to `libglitter_per_channel_desaturate_double`,
 * apart from it parameter types, see `libglitter_per_channel_desaturate_double`
 * for details about this function
 */
void libglitter_per_channel_desaturate_float(float **, size_t, size_t, size_t, size_t, size_t,
                                             const float *restrict, const float *restrict);


/**
 * Get the matrix each pixel shall be multiplied with
 * to convert it from the output's colour model to sRGB
 * or CIE XYZ
 * 
 * This is useful when the output does not use sRGB, or
 * CIE XYZ, but the application does. If the application
 * uses some other colour model, this function can output
 * the conversion matrix for the CIE XYZ colour model,
 * which can that be right-hand multiplied to get the
 * conversion matrix for some other colour; but be aware
 * that the output matrix is in column-major order, not
 * row-major order
 * 
 * @param  matrix   Output buffer for the conversion matrix, in column-major order
 * @param  c1x      The CIE x value (as in CIE xyY) of the output's first primary colour
 * @param  c1y      The CIE y value (as in CIE xyY) of the output's first primary colour
 * @param  c2x      The CIE x value (as in CIE xyY) of the output's second primary colour
 * @param  c2y      The CIE y value (as in CIE xyY) of the output's second primary colour
 * @param  c3x      The CIE x value (as in CIE xyY) of the output's third primary colour
 * @param  c3y      The CIE y value (as in CIE xyY) of the output's third primary colour
 * @param  white_x  The CIE x value (as in CIE xyY) of the output's white point
 * @param  white_y  The CIE y value (as in CIE xyY) of the output's white point
 * @param  white_Y  The CIE Y value (as in CIE xyY) of the output's white point, normally 1
 * @param  xyz      Whether the output conversion matrix should be to CIE XYZ rather the sRGB
 * @param  c1Yp     Output parameter for the first primary colour CIE Y value, or `NULL`
 * @param  c2Yp     Output parameter for the second primary colour CIE Y value, or `NULL`
 * @param  c3Yp     Output parameter for the third primary colour CIE Y value, or `NULL`
 * 
 * `LIBGLITTER_ILLUMINANT_D65` can be input in place of
 * `white_x, white_y, white_Y` (it expands to three arguments)
 * if the output's whitepoint is the D65 illuminant
 */
void libglitter_get_colour_model_conversion_matrix_double(double[3][3], double, double, double, double,
                                                          double, double, double, double, double, int,
                                                          double *, double *, double *);

/**
 * This value is identical to `libglitter_get_colour_model_conversion_matrix_double`,
 * apart from it parameter types, see `libglitter_get_colour_model_conversion_matrix_double`
 * for details about this function
 */
void libglitter_get_colour_model_conversion_matrix_float(float[3][3], float, float, float, float,
                                                         float, float, float, float, float, int,
                                                         float *, float *, float *);


/**
 * Convert set of rasters from one colour model to another
 * 
 * @param  n                The number of input rasters
 * @param  m                The number of output rasters
 * @param  outputs          Array of output rasters. The function may change
 *                          the offset for each raster, as such, the given
 *                          pointer shall not be used anywhere else during
 *                          the execution of the function and the inner
 *                          pointers shall be considered undefined after the
 *                          execution of the function.
 * @param  inputs           Array of input rasters. The function may change
 *                          the offset for each raster, as such, the given
 *                          pointer shall not be used anywhere else during
 *                          the execution of the function and the inner
 *                          pointers shall be considered undefined after the
 *                          execution of the function.
 * @param  output_rowsize   The number of cells in a row in each output raster
 * @param  output_cellsize  The number of values stored in each output raster,
 *                          between each cell, plus 1 (that is, the number of
 *                          values per cell)
 * @param  input_rowsize    The number of cells in a row in each input raster
 * @param  input_cellsize   The number of values stored in each input raster,
 *                          between each cell, plus 1 (that is, the number of
 *                          values per cell)
 * @param  width            The horizontal number of pixels in the rasters
 * @param  height           The vertical number of pixels in the rasters
 * @param  matrix           Colour model conversion matrix, in column-major order
 */
void libglitter_colour_model_convert_rasters_double(size_t n, size_t m, double **, const double **, size_t,
                                                    size_t, size_t, size_t, size_t, size_t, const double[m][n]);

/**
 * This value is identical to `libglitter_colour_model_convert_rasters_double`,
 * apart from it parameter types, see `libglitter_colour_model_convert_rasters_double`
 * for details about this function
 */
void libglitter_colour_model_convert_rasters_float(size_t n, size_t m, float **, const float **, size_t,
                                                   size_t, size_t, size_t, size_t, size_t, const float[m][n]);


#endif
/* TODO add `restrict` where appropriate */