include/ale.h

   1 /*
   2  *  Copyright 2008, 2009 David Hilvert <dhilvert@gmail.com>
   3  *
   4  *  This file is part of libale.
   5  *
   6  *  libale is free software: you can redistribute it and/or modify it under the
   7  *  terms of the GNU Affero General Public License as published by the Free
   8  *  Software Foundation, either version 3 of the License, or (at your option)
   9  *  any later version.
  10  *
  11  *  libale is distributed in the hope that it will be useful, but WITHOUT ANY
  12  *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  13  *  FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for
  14  *  more details.
  15  *
  16  *  You should have received a copy of the GNU Affero General Public License
  17  *  along with libale.  If not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef _ALE_H
  21 #define _ALE_H
  22
  23 #include <stdio.h>
  24 #include <stdarg.h>
  25
  26 /*
  27  * libale requires OpenCL
  28  *
  29  * http://www.khronos.org/registry/cl/
  30  *
  31  * We assume the following header file, according to official documentation
  32  * example code.  If this doesn't work, try OpenCL/cl.h (or perhaps CL/cl.h),
  33  * as even Khronos does not seem to be entirely consistent in OpenCL header
  34  * naming.
  35  */
  36
  37 #include <OpenCL/opencl.h>
  38
  39 /*
  40  * Macro for API type definition
  41  *
  42  * API type name selection is based roughly on the approach taken in
  43  *
  44  * http://www.khronos.org/registry/cl/api/1.0/cl.h
  45  *
  46  * *_retain() and *_release() are patterned after OpenCL reference counting.
  47  *
  48  * *_valid() attempts to determine validity, returning non-zero if valid.
  49  */
  50
  51 #define ALE_API_TYPEDEF(TYPENAME) struct _ ## TYPENAME; typedef struct _ ## TYPENAME *TYPENAME; \
  52         int TYPENAME ## _valid(TYPENAME xx_valid_argument); \
  53         int TYPENAME ## _retain(TYPENAME xx_retain_argument); \
  54         int TYPENAME ## _release(TYPENAME xx_release_argument);
  55
  56 /*
  57  * Macros for API parameter declaration.
  58  */
  59
  60 #define ALE_API_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  61         PARAMETER_TYPE OBJECT_TYPE ## _get_ ## PARAMETER_NAME (OBJECT_TYPE object);
  62
  63 #define ALE_API_PARAMETER_W(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  64         int OBJECT_TYPE ## _set_ ## PARAMETER_NAME (OBJECT_TYPE object, PARAMETER_TYPE value);
  65
  66 #define ALE_API_PARAMETER_RW(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  67         ALE_API_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  68         ALE_API_PARAMETER_W(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE)
  69
  70 /*
  71  * API types
  72  */
  73
  74 ALE_API_TYPEDEF(ale_context)
  75
  76 ALE_API_TYPEDEF(ale_image)
  77 ALE_API_TYPEDEF(ale_render)
  78 ALE_API_TYPEDEF(ale_trans)
  79 ALE_API_TYPEDEF(ale_align_properties)
  80
  81 ALE_API_TYPEDEF(ale_filter)
  82 ALE_API_TYPEDEF(ale_psf)
  83
  84 ALE_API_TYPEDEF(ale_exclusion_list)
  85
  86 ALE_API_TYPEDEF(ale_sequence)
  87
  88 ALE_API_TYPEDEF(ale_scene)
  89
  90
  91 /*
  92  * Bayer patterns.  (Values are based on original ALE d2::image code, but using
  93  * standard clockwise ordering rather than ALE counterclockwise ordering.)
  94  */
  95
  96 enum {
  97         ALE_BAYER_NONE = 0x0,
  98         ALE_BAYER_RGBG = 0x4,        /* binary 100 */
  99         ALE_BAYER_GRGB = 0x5,        /* binary 101 */
 100         ALE_BAYER_GBGR = 0x6,        /* binary 110 */
 101         ALE_BAYER_BGRG = 0x7         /* binary 111 */
 102 };
 103
 104 /*
 105  * Bayer utility functions.  (Based on original ALE d2::image_bayer_ale_real
 106  * code.)
 107  */
 108
 109 /*
 110  * Return the color of a given pixel, for a given bayer pattern.
 111  */
 112 static unsigned int ale_bayer_color(unsigned int i, unsigned int j, unsigned int bayer) {
 113         unsigned int r_x_offset = bayer & 0x1;
 114         unsigned int r_y_offset = (bayer & 0x2) >> 1;
 115
 116         return (i + r_y_offset) % 2 + (j + r_x_offset) % 2;
 117 }
 118
 119 /*
 120  * Return a vector indicating set channels.
 121  */
 122 static char ale_get_channels(unsigned int i, unsigned int j, unsigned int bayer) {
 123         if (bayer == ALE_BAYER_NONE)
 124                 return 0x7;
 125         return (1 << ale_bayer_color(i, j, bayer));
 126 }
 127
 128 /*
 129  * Indicate whether a given channel exists.
 130  */
 131 static int ale_has_channel(unsigned int i, unsigned int j, unsigned int k, unsigned int bayer) {
 132         return (1 << k) & ale_get_channels(i, j, bayer);
 133 }
 134
 135
 136
 137 /*
 138  * Image formats.
 139  */
 140
 141 enum {
 142         ALE_IMAGE_Y,
 143         ALE_IMAGE_RGB,
 144         ALE_IMAGE_WEIGHTED_RGB
 145 };
 146
 147 /*
 148  * Domain types.
 149  */
 150
 151 enum {
 152         ALE_TYPE_UINT_8,
 153         ALE_TYPE_UINT_16,
 154         ALE_TYPE_UINT_32,
 155         ALE_TYPE_UINT_64,
 156         ALE_TYPE_FLOAT_32,
 157         ALE_TYPE_FLOAT_64
 158 };
 159
 160 /*
 161  * Invariant types.
 162  *
 163  * For ALE avgf, use MEAN|FIRST with saturation threshold;
 164  * other invariants are analogous; e.g.,
 165  *
 166  *   MEAN|LAST,
 167  *   MEDIAN|FIRST,
 168  *   etc.
 169  *
 170  * Not all expressible combinations are accepted, or, indeed, meaningful.
 171  */
 172
 173 enum {
 174         ALE_INVARIANT_NONE = 0,
 175         ALE_INVARIANT_MEAN = 1,
 176         ALE_INVARIANT_FIRST = 2,
 177         ALE_INVARIANT_LAST = 4,
 178         ALE_INVARIANT_MAX = 8,
 179         ALE_INVARIANT_MIN = 16,
 180         ALE_INVARIANT_MEDIAN = 32
 181 };
 182
 183 /*
 184  * Status return values.
 185  *
 186  * Based loosely on OpenCL status return values.
 187  */
 188
 189 enum {
 190         ALE_UNSPECIFIED_FAILURE = -1,
 191         ALE_SUCCESS = 0
 192 };
 193
 194 /*
 195  * Image buffer types.
 196  */
 197
 198 enum {
 199         ALE_BUFFER_CL,
 200         ALE_BUFFER_HOST,
 201         ALE_BUFFER_FILE
 202 };
 203
 204 /*
 205  * Obtain a Libale context given an OpenCL context
 206  */
 207
 208 ale_context ale_new_context(cl_context cc);
 209
 210 /*
 211  * Retain an OpenCL context from a Libale context.
 212  */
 213
 214 cl_context ale_context_retain_cl(ale_context ac);
 215
 216 /*
 217  * Set a context property.
 218  */
 219
 220 int ale_context_set_property(ale_context ac, const char *name, const char *value);
 221
 222 /*
 223  * Set a context-wide signal recipient
 224  */
 225
 226 int ale_context_set_receiver(ale_context ac, void (*receiver_callback)(const char *signal, va_list ap));
 227
 228 /*
 229  * Send a context signal
 230  */
 231
 232 int ale_context_vsignal(ale_context ac, const char *signal, va_list ap);
 233 int ale_context_signal(ale_context ac, const char *signal, ...);
 234
 235 /*
 236  * Context preferred coordinate resolution.
 237  */
 238
 239 ALE_API_PARAMETER_RW(ale_context, coords_type, int)
 240
 241 /*
 242  * Context preferred color resolution.
 243  */
 244
 245 ALE_API_PARAMETER_RW(ale_context, color_type, int)
 246
 247 /*
 248  * Obtain a Libale transformation
 249  */
 250
 251 ale_trans ale_new_trans(ale_context ac, ale_image ai);
 252
 253 /*
 254  * Set original bounds for a Libale transformation.
 255  */
 256
 257 int ale_trans_set_original_bounds(ale_trans at, ale_image ai);
 258
 259 /*
 260  * Transformation exposure parameter.
 261  */
 262
 263 ALE_API_PARAMETER_RW(ale_trans, exposure, double)
 264
 265 /*
 266  * Transformation gamma parameter.  (Default is 0.45.)
 267  */
 268
 269 ALE_API_PARAMETER_RW(ale_trans, gamma, double)
 270
 271 /*
 272  * Transformation black level parameter, expressed as a fraction of saturation.
 273  */
 274
 275 ALE_API_PARAMETER_RW(ale_trans, black, double)
 276
 277 /*
 278  * Transformation bayer parameter.
 279  */
 280
 281 ALE_API_PARAMETER(ale_trans, bayer, int)
 282
 283 /*
 284  * Create a Libale image.
 285  */
 286
 287 ale_image ale_new_image(ale_context ac, int format, int type);
 288
 289 /*
 290  * Clone a Libale image.
 291  */
 292
 293 ale_image ale_clone_image(ale_image source);
 294
 295 /*
 296  * Scale a Libale image, producing a new image.
 297  */
 298
 299 ale_image ale_scale_image(ale_image source, ale_pos factor);
 300
 301 /*
 302  * Set a Libale image to a given OpenCL buffer, host buffer, or file buffer.
 303  */
 304
 305 int ale_image_set_cl(ale_image ai, size_t width, size_t height, cl_mem buffer);
 306 int ale_image_set_host_dynamic(ale_image ai, size_t width, size_t height, void *buffer);
 307 int ale_image_set_host_static(ale_image ai, size_t width, size_t height, void *buffer, void (*release_callback)(void *), void *callback_data);
 308 int ale_image_set_file_dynamic(ale_image ai, size_t width, size_t height, FILE *buffer);
 309 int ale_image_set_file_static(ale_image ai, size_t width, size_t height, FILE *buffer, long offset, int (*release_callback)(void *), void *callback_data);
 310
 311 /*
 312  * Buffer type for a given Libale image.
 313  */
 314
 315 ALE_API_PARAMETER_R(ale_image, buffer_type, int)
 316
 317 /*
 318  * Retain an OpenCL buffer, host buffer, or file buffer, given a Libale image.
 319  * (returns NULL or ((cl_mem) 0) on failure).
 320  */
 321
 322 cl_mem ale_image_retain_cl(ale_image ai);
 323 void *ale_image_retain_host(ale_image ai);
 324 FILE *ale_image_retain_file(ale_image ai);
 325
 326 /*
 327  * Release data without internal reference counters.
 328  */
 329
 330 int ale_image_release_host(ale_image ai, void *hi);
 331 int ale_image_release_file(ale_image ai, FILE *fi);
 332
 333 /*
 334  * Resize a Libale image.
 335  */
 336
 337 int ale_resize_image(ale_image ai, int x_offset, int y_offset, size_t width, size_t height);
 338
 339 /*
 340  * Get image statistics.
 341  */
 342
 343 ALE_API_PARAMETER_R(ale_image, height, size_t)
 344 ALE_API_PARAMETER_R(ale_image, width, size_t)
 345 ALE_API_PARAMETER_R(ale_image, format, int)
 346 ALE_API_PARAMETER_R(ale_image, type, int)
 347 ALE_API_PARAMETER_RW(ale_image, x_offset, int)
 348 ALE_API_PARAMETER_RW(ale_image, y_offset, int)
 349
 350 size_t ale_image_get_depth(ale_image ai);
 351
 352 /*
 353  * XXX: It is possible that minval and maxval would be better implemented
 354  * outside of the API, using other, more generic calls (such as eval).
 355  */
 356
 357 double ale_image_maxval(ale_image source);
 358 double ale_image_minval(ale_image source);
 359 ale_image ale_image_nn_fill(ale_image source, double nn_defined_radius);
 360 ale_image ale_image_get_weights(ale_image source);
 361
 362 /*
 363  * Evaluation operator.
 364  */
 365
 366 int ale_eval(const char *s, ...);
 367
 368 /*
 369  * Create a Libale incremental renderer, with given invariant.
 370  */
 371
 372 ale_render ale_new_render_incremental(ale_context ac, int type, int invariant);
 373
 374 /*
 375  * Libale renderer definition threshold parameter
 376  */
 377
 378 ALE_API_PARAMETER_RW(ale_render, definition_threshold, double)
 379
 380 /*
 381  * Libale renderer saturation threshold parameter
 382  */
 383
 384 ALE_API_PARAMETER_RW(ale_render, saturation_threshold, double)
 385
 386 /*
 387  * Libale renderer maximum frame range parameter
 388  */
 389
 390 ALE_API_PARAMETER_RW(ale_render, range_threshold, double)
 391
 392 /*
 393  * Render resize.
 394  */
 395
 396 int ale_render_resize(ale_render ar, ale_trans at);
 397
 398 /*
 399  * Render extend.
 400  */
 401
 402  int ale_render_extend(ale_render ar, ale_trans at);
 403
 404 /*
 405  * Render merge.
 406  */
 407
 408 int ale_render_merge(ale_render ar, ale_trans at, ale_image ai);
 409
 410 /*
 411  * Render retain image.
 412  */
 413
 414 ale_image ale_render_retain_image(ale_render ar);
 415
 416 /*
 417  * Synchronized renderer resize.
 418  */
 419
 420 int ale_render_resize_sync(ale_render ar, ale_sequence s, int i);
 421
 422 /*
 423  * Synchronized render extend.
 424  */
 425
 426 int ale_render_extend_sync(ale_render ar, ale_sequence s, int i);
 427
 428 /*
 429  * Synchronized renderer merge.
 430  */
 431
 432 int ale_render_merge_sync(ale_render ar, ale_sequence s, int i);
 433
 434 /*
 435  * Create a Libale Irani-Peleg renderer, with given reference.
 436  */
 437
 438 ale_render ale_new_render_ip(ale_context ac, ale_render reference, int iterations);
 439
 440 /*
 441  * Create a renderer ensemble.
 442  */
 443
 444 ale_render ale_new_render_ensemble(ale_context ac);
 445
 446 /*
 447  * Retain a renderer from an ensemble.
 448  */
 449
 450 ale_render ale_render_ensemble_retain(ale_render ar, const char *spec);
 451
 452 /*
 453  * Perform any stream processing (e.g., Irani-Peleg) run.
 454  */
 455
 456 int ale_render_stream_process(ale_render ar, ale_sequence s);
 457
 458 /*
 459  * Retain an image from a sequence
 460  */
 461
 462 ale_image ale_sequence_retain_image(ale_sequence s, int i);
 463
 464 /*
 465  * Release an image from a sequence
 466  */
 467
 468 int ale_sequence_release_image(ale_sequence, int i);
 469
 470 /*
 471  * Create a filter.
 472  */
 473
 474 ale_filter ale_new_filter(ale_context ac, const char *type);
 475
 476 /*
 477  * Create a point-spread function.
 478  */
 479
 480 ale_psf ale_new_psf(ale_context ac, const char *type);
 481
 482 /*
 483  * Create an exclusion region list.
 484  */
 485
 486 ale_exclusion_list ale_new_exclusion_list(ale_context ac);
 487
 488 /*
 489  * Append an exclusion region to a list
 490  */
 491
 492 int ale_exclusion_list_append(ale_exclusion_list ae, int is_frame_coords, double xmin, double xmax, double ymin, double ymax, double fmin, double fmax);
 493
 494 /*
 495  * Obtain an alignment RESULT between frame A and current approximation B,
 496  * starting from transformation START, and given alignment properties
 497  * ALIGN_PROPERTIES.
 498  */
 499
 500 int ale_align(ale_context ac, ale_image a, ale_image b, ale_trans start,
 501                 ale_align_properties align_properties, ale_trans result);
 502
 503
 504 /*
 505  * Create an alignment properties structure.
 506  */
 507
 508 ale_align_properties ale_new_align_properties();
 509
 510 /*
 511  * Return a PSF error based on a captured sequence and a scene approximation.
 512  */
 513
 514 double ale_psf_error(ale_image approx, ale_sequence sequence);
 515
 516
 517
 518 #endif