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 code definition.
  41  */
  42
  43 #define ALE_CODE(ID, ...) \
  44         static const char *ale_string_ ## ID = #__VA_ARGS__ ;
  45
  46 /*
  47  * Stringification macro.
  48  */
  49
  50 #define ALE_STRINGIFY(ID) \
  51         ale_string_ ## ID
  52
  53 #if 0
  54
  55 /*
  56  * Alternative code definition and stringification macros (e.g., if the above
  57  * cause compiler warnings regarding unused statics.
  58  */
  59
  60 #define ALE_CODE(ID, ...) \
  61         inline const char *ale_stringify_ ## ID() { return #__VA_ARGS__ ; }
  62
  63 #define ALE_STRINGIFY(ID) \
  64         ale_stringify_ ## ID()
  65
  66 #endif
  67
  68 /*
  69  * Macros for shared data types used in evaluation.
  70  */
  71
  72 #define ALE_DATA_TYPE(TYPE, ...) \
  73         __VA_ARGS__ \
  74         ALE_CODE(TYPE, __VA_ARGS__ )
  75
  76 #define ALE_STRUCT(TYPE, ...) \
  77         ALE_DATA_TYPE(TYPE, struct TYPE { __VA_ARGS__ }; )
  78
  79 #define ALE_UNION(TYPE, ...) \
  80         ALE_DATA_TYPE(TYPE, union TYPE { __VA_ARGS__ }; )
  81
  82 #define ALE_TYPEDEF(TYPE, ...) \
  83         ALE_DATA_TYPE(TYPE, typedef __VA_ARGS__ TYPE; )
  84
  85 /*
  86  * Pointer for portable storage (e.g., between 32- and 64-bit architectures).
  87  * This may allow, e.g., storing compute device pointers on the host, which
  88  * could be useful for inclusion in structures to be passed back to the compute
  89  * device, etc.
  90  *
  91  * It is expected that TYPE is incomplete on the host side in the common case,
  92  * but its inclusion may be useful for type checking.  On the other hand,
  93  * dereferencing P on the host side may have unexpected result, and should not
  94  * generally be necessary.
  95  *
  96  * Note that this should also be usable for storing pointers dereferenced solely
  97  * on the host side (as might be expected for ale_context, or for its included
  98  * cl_context).
  99  *
 100  * We add a table type (T) here to allow the possibility that pointer values
 101  * change on the device for a given cl_mem object.  Cf:
 102  *
 103  * http://www.khronos.org/message_boards/viewtopic.php?p=4782#p4782
 104  *
 105  * INDEX is a (32- or) 64-bit pointer to the index of an (e.g., cl_mem) entry
 106  * in a table on the host (e.g., in such a table associated with an
 107  * ale_context).  OFFSET is measured from the start of the indexed memory area,
 108  * and is disabled for now to reduce pointer sizes, but can be enabled for
 109  * greater pointer generality.
 110  */
 111
 112 #define ALE_POINTER(TYPE, TYPEP) \
 113         ALE_DATA_TYPE( TYPEP, typedef union { TYPE *p; struct {cl_long index; /* cl_int offset; */} t; cl_long widest_pointer_type; } TYPEP;)
 114
 115 /*
 116  * Macro for API type definition
 117  *
 118  * API type name selection is based roughly on the approach taken in
 119  *
 120  * http://www.khronos.org/registry/cl/api/1.0/cl.h
 121  *
 122  * *_retain() and *_release() are patterned after OpenCL reference counting.
 123  *
 124  * *_valid() attempts to determine validity, returning non-zero if valid.
 125  */
 126
 127 #define ALE_API_TYPEDEF(TYPENAME) \
 128         ALE_DATA_TYPE( _ ## TYPENAME, struct _ ## TYPENAME; ) \
 129         ALE_POINTER( struct _ ## TYPENAME , TYPENAME ) \
 130         int TYPENAME ## _valid(TYPENAME xx_valid_argument); \
 131         TYPENAME TYPENAME ## _NULL(); \
 132         int TYPENAME ## _retain(TYPENAME xx_retain_argument); \
 133         int TYPENAME ## _release(TYPENAME xx_release_argument);
 134
 135 /*
 136  * Macros for API parameter declaration.
 137  */
 138
 139 #define ALE_API_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
 140         PARAMETER_TYPE OBJECT_TYPE ## _get_ ## PARAMETER_NAME (OBJECT_TYPE object);
 141
 142 #define ALE_API_PARAMETER_W(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
 143         int OBJECT_TYPE ## _set_ ## PARAMETER_NAME (OBJECT_TYPE object, PARAMETER_TYPE value);
 144
 145 #define ALE_API_PARAMETER_RW(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
 146         ALE_API_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
 147         ALE_API_PARAMETER_W(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE)
 148
 149 #define ALE_API_RC_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
 150         PARAMETER_TYPE OBJECT_TYPE ## _retain_ ## PARAMETER_NAME (OBJECT_TYPE object);
 151
 152 #define ALE_API_RC_PARAMETER_RW(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
 153         ALE_API_RC_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
 154         ALE_API_PARAMETER_W(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE)
 155
 156 /*
 157  * API types
 158  */
 159
 160 ALE_API_TYPEDEF(ale_context)
 161
 162 ALE_API_TYPEDEF(ale_image)
 163 ALE_API_TYPEDEF(ale_render)
 164 ALE_API_TYPEDEF(ale_trans)
 165 ALE_API_TYPEDEF(ale_align_properties)
 166
 167 ALE_API_TYPEDEF(ale_filter)
 168 ALE_API_TYPEDEF(ale_psf)
 169
 170 ALE_API_TYPEDEF(ale_certainty)
 171
 172 ALE_API_TYPEDEF(ale_exclusion_list)
 173
 174 ALE_API_TYPEDEF(ale_sequence)
 175
 176 ALE_API_TYPEDEF(ale_scene)
 177
 178
 179 /*
 180  * Bayer patterns.  (Values are based on original ALE d2::image code, but using
 181  * standard clockwise ordering rather than ALE counterclockwise ordering.)
 182  */
 183
 184 enum {
 185         ALE_BAYER_NONE = 0x0,
 186         ALE_BAYER_RGBG = 0x4,        /* binary 100 */
 187         ALE_BAYER_GRGB = 0x5,        /* binary 101 */
 188         ALE_BAYER_GBGR = 0x6,        /* binary 110 */
 189         ALE_BAYER_BGRG = 0x7         /* binary 111 */
 190 };
 191
 192 /*
 193  * Bayer utility functions.  (Based on original ALE d2::image_bayer_ale_real
 194  * code.)
 195  */
 196
 197 /*
 198  * Return the color of a given pixel, for a given bayer pattern.
 199  */
 200 static unsigned int ale_bayer_color(unsigned int i, unsigned int j, unsigned int bayer) {
 201         unsigned int r_x_offset = bayer & 0x1;
 202         unsigned int r_y_offset = (bayer & 0x2) >> 1;
 203
 204         return (i + r_y_offset) % 2 + (j + r_x_offset) % 2;
 205 }
 206
 207 /*
 208  * Return a vector indicating set channels.
 209  */
 210 static char ale_get_channels(unsigned int i, unsigned int j, unsigned int bayer) {
 211         if (bayer == ALE_BAYER_NONE)
 212                 return 0x7;
 213         return (1 << ale_bayer_color(i, j, bayer));
 214 }
 215
 216 /*
 217  * Indicate whether a given channel exists.
 218  */
 219 static int ale_has_channel(unsigned int i, unsigned int j, unsigned int k, unsigned int bayer) {
 220         return (1 << k) & ale_get_channels(i, j, bayer);
 221 }
 222
 223
 224
 225 /*
 226  * Image formats.
 227  */
 228
 229 enum {
 230         ALE_IMAGE_Y,
 231         ALE_IMAGE_RGB,
 232         ALE_IMAGE_WEIGHTED_RGB
 233 };
 234
 235 /*
 236  * Domain types.
 237  */
 238
 239 enum {
 240         ALE_TYPE_UINT_8,
 241         ALE_TYPE_UINT_16,
 242         ALE_TYPE_UINT_32,
 243         ALE_TYPE_UINT_64,
 244         ALE_TYPE_FLOAT_32,
 245         ALE_TYPE_FLOAT_64
 246 };
 247
 248 /*
 249  * Invariant types.
 250  *
 251  * For ALE avgf, use MEAN|FIRST with saturation threshold;
 252  * other invariants are analogous; e.g.,
 253  *
 254  *   MEAN|LAST,
 255  *   MEDIAN|FIRST,
 256  *   etc.
 257  *
 258  * Not all expressible combinations are accepted, or, indeed, meaningful.
 259  */
 260
 261 enum {
 262         ALE_INVARIANT_NONE = 0,
 263         ALE_INVARIANT_MEAN = 1,
 264         ALE_INVARIANT_FIRST = 2,
 265         ALE_INVARIANT_LAST = 4,
 266         ALE_INVARIANT_MAX = 8,
 267         ALE_INVARIANT_MIN = 16,
 268         ALE_INVARIANT_MEDIAN = 32
 269 };
 270
 271 /*
 272  * Status return values.
 273  *
 274  * Based loosely on OpenCL status return values.
 275  */
 276
 277 enum {
 278         ALE_UNSPECIFIED_FAILURE = -1,
 279         ALE_SUCCESS = 0
 280 };
 281
 282 /*
 283  * Image buffer types.
 284  */
 285
 286 enum {
 287         ALE_BUFFER_CL,
 288         ALE_BUFFER_HOST,
 289         ALE_BUFFER_FILE
 290 };
 291
 292 /*
 293  * Obtain a Libale context given an OpenCL context
 294  */
 295
 296 ale_context ale_new_context(cl_context cc);
 297
 298 /*
 299  * Retain an OpenCL context from a Libale context.
 300  */
 301
 302 cl_context ale_context_retain_cl(ale_context ac);
 303
 304 /*
 305  * Set a context property.
 306  */
 307
 308 int ale_context_set_property(ale_context ac, const char *name, const char *value);
 309
 310 /*
 311  * Set a context-wide signal recipient
 312  */
 313
 314 int ale_context_set_receiver(ale_context ac, void (*receiver_callback)(const char *signal, va_list ap));
 315
 316 /*
 317  * Send a context signal
 318  */
 319
 320 int ale_context_vsignal(ale_context ac, const char *signal, va_list ap);
 321 int ale_context_signal(ale_context ac, const char *signal, ...);
 322
 323 /*
 324  * Context preferred coordinate resolution.
 325  */
 326
 327 ALE_API_PARAMETER_RW(ale_context, coords_type, int)
 328
 329 /*
 330  * Context preferred color resolution.
 331  */
 332
 333 ALE_API_PARAMETER_RW(ale_context, color_type, int)
 334
 335 /*
 336  * Context preferred certainty resolution.
 337  */
 338
 339 ALE_API_PARAMETER_RW(ale_context, certainty_type, int)
 340
 341 /*
 342  * Context preferred weight resolution.
 343  */
 344
 345 ALE_API_PARAMETER_RW(ale_context, weight_type, int)
 346
 347 /*
 348  * Obtain a Libale transformation
 349  */
 350
 351 ale_trans ale_new_trans(ale_context ac, ale_image ai);
 352
 353 /*
 354  * Set original bounds for a Libale transformation.
 355  */
 356
 357 int ale_trans_set_original_bounds(ale_trans at, ale_image ai);
 358
 359 /*
 360  * Rescale a transform with a given factor.
 361  */
 362
 363 int ale_trans_rescale(ale_trans at, double factor);
 364
 365 /*
 366  * Transformation exposure parameter.
 367  */
 368
 369 ALE_API_PARAMETER_RW(ale_trans, exposure, double)
 370
 371 /*
 372  * Transformation gamma parameter.  (Default is 0.45.)
 373  */
 374
 375 ALE_API_PARAMETER_RW(ale_trans, gamma, double)
 376
 377 /*
 378  * Transformation black level parameter, expressed as a fraction of saturation.
 379  */
 380
 381 ALE_API_PARAMETER_RW(ale_trans, black, double)
 382
 383 /*
 384  * Transformation bayer parameter.
 385  */
 386
 387 ALE_API_PARAMETER_RW(ale_trans, bayer, int)
 388
 389 /*
 390  * Transformation certainty curve
 391  */
 392
 393 ALE_API_RC_PARAMETER_RW(ale_trans, certainty, ale_certainty)
 394
 395 /*
 396  * Create a Libale image.
 397  */
 398
 399 ale_image ale_new_image(ale_context ac, int format, int type);
 400
 401 /*
 402  * Convenience function to clone a Libale image (matching size and format, but
 403  * not copying contents).
 404  */
 405
 406 ale_image ale_clone_image(ale_image source, int output_type);
 407
 408 /*
 409  * Convenience function to scale a Libale image, producing a new (unit gamma,
 410  * non-bayer) image.
 411  */
 412
 413 ale_image ale_scale_image(ale_image source, double factor, int output_type, double source_gamma, int source_bayer);
 414 ale_image ale_scale_image_wt(ale_image source, double factor, int output_type, int source_bayer);
 415
 416 /*
 417  * Set a Libale image to a given OpenCL buffer, host buffer, or file buffer.
 418  */
 419
 420 int ale_image_set_cl(ale_image ai, size_t width, size_t height, cl_mem buffer);
 421 int ale_image_set_host_dynamic(ale_image ai, size_t width, size_t height, void *buffer);
 422 int ale_image_set_host_static(ale_image ai, size_t width, size_t height, void *buffer, void (*release_callback)(void *), void *callback_data);
 423 int ale_image_set_file_dynamic(ale_image ai, size_t width, size_t height, FILE *buffer);
 424 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);
 425
 426 /*
 427  * Buffer type for a given Libale image.
 428  */
 429
 430 ALE_API_PARAMETER_R(ale_image, buffer_type, int)
 431
 432 /*
 433  * Retain an OpenCL buffer, host buffer, or file buffer, given a Libale image.
 434  * (returns NULL or ((cl_mem) 0) on failure).
 435  */
 436
 437 cl_mem ale_image_retain_cl(ale_image ai);
 438 void *ale_image_retain_host(ale_image ai);
 439 FILE *ale_image_retain_file(ale_image ai);
 440
 441 /*
 442  * Release data without internal reference counters.
 443  */
 444
 445 int ale_image_release_host(ale_image ai, void *hi);
 446 int ale_image_release_file(ale_image ai, FILE *fi);
 447
 448 /*
 449  * Resize a Libale image.
 450  */
 451
 452 int ale_resize_image(ale_image ai, int x_offset, int y_offset, size_t width, size_t height);
 453
 454 /*
 455  * Get image statistics.
 456  */
 457
 458 ALE_API_PARAMETER_R(ale_image, height, size_t)
 459 ALE_API_PARAMETER_R(ale_image, width, size_t)
 460 ALE_API_PARAMETER_R(ale_image, format, int)
 461 ALE_API_PARAMETER_R(ale_image, type, int)
 462 ALE_API_PARAMETER_RW(ale_image, x_offset, int)
 463 ALE_API_PARAMETER_RW(ale_image, y_offset, int)
 464
 465 size_t ale_image_get_depth(ale_image ai);
 466
 467 /*
 468  * XXX: It is possible that minval and maxval would be better implemented
 469  * outside of the API, using other, more generic calls (such as eval).
 470  */
 471
 472 double ale_image_maxval(ale_image source);
 473 double ale_image_minval(ale_image source);
 474 ale_image ale_image_nn_fill(ale_image source, double nn_defined_radius);
 475 ale_image ale_image_get_weights(ale_image source);
 476
 477 /*
 478  * Evaluation operator.
 479  */
 480
 481 int ale_eval(const char *s, ...);
 482
 483 #if 0
 484
 485 /*
 486  * Proposed function evaluation operator, detecting types from a given named
 487  * function.
 488  */
 489
 490 int ale_eval_func(const char *s, ...);
 491
 492 #endif
 493
 494 /*
 495  * Create a Libale incremental renderer, with given invariant.
 496  */
 497
 498 ale_render ale_new_render_incremental(ale_context ac, int type, int invariant);
 499
 500 /*
 501  * Libale renderer definition threshold parameter
 502  */
 503
 504 ALE_API_PARAMETER_RW(ale_render, definition_threshold, double)
 505
 506 /*
 507  * Libale renderer saturation threshold parameter
 508  */
 509
 510 ALE_API_PARAMETER_RW(ale_render, saturation_threshold, double)
 511
 512 /*
 513  * Libale renderer maximum frame range parameter
 514  */
 515
 516 ALE_API_PARAMETER_RW(ale_render, range_threshold, double)
 517
 518 /*
 519  * Render resize.
 520  */
 521
 522 int ale_render_resize(ale_render ar, ale_trans at);
 523
 524 /*
 525  * Render extend.
 526  */
 527
 528  int ale_render_extend(ale_render ar, ale_trans at);
 529
 530 /*
 531  * Render merge.
 532  */
 533
 534 int ale_render_merge(ale_render ar, ale_trans at, ale_image ai);
 535
 536 /*
 537  * Render retain image.
 538  */
 539
 540 ale_image ale_render_retain_image(ale_render ar);
 541
 542 /*
 543  * Synchronized renderer resize.
 544  */
 545
 546 int ale_render_resize_sync(ale_render ar, ale_sequence s, int i);
 547
 548 /*
 549  * Synchronized render extend.
 550  */
 551
 552 int ale_render_extend_sync(ale_render ar, ale_sequence s, int i);
 553
 554 /*
 555  * Synchronized renderer merge.
 556  */
 557
 558 int ale_render_merge_sync(ale_render ar, ale_sequence s, int i);
 559
 560 /*
 561  * Create a Libale Irani-Peleg renderer, with given reference.
 562  */
 563
 564 ale_render ale_new_render_ip(ale_context ac, ale_render reference, int iterations);
 565
 566 /*
 567  * Create a renderer ensemble.
 568  */
 569
 570 ale_render ale_new_render_ensemble(ale_context ac);
 571
 572 /*
 573  * Retain a renderer from an ensemble.
 574  */
 575
 576 ale_render ale_render_ensemble_retain(ale_render ar, const char *spec);
 577
 578 /*
 579  * Perform any stream processing (e.g., Irani-Peleg) run.
 580  */
 581
 582 int ale_render_stream_process(ale_render ar, ale_sequence s);
 583
 584 /*
 585  * Retain an image from a sequence
 586  */
 587
 588 ale_image ale_sequence_retain_image(ale_sequence s, int i);
 589
 590 /*
 591  * Release an image from a sequence
 592  */
 593
 594 int ale_sequence_release_image(ale_sequence, int i);
 595
 596 /*
 597  * Create a filter.
 598  */
 599
 600 ale_filter ale_new_filter(ale_context ac, const char *type);
 601
 602 /*
 603  * Create a point-spread function.
 604  */
 605
 606 ale_psf ale_new_psf(ale_context ac, const char *type);
 607
 608 /*
 609  * Create an exclusion region list.
 610  */
 611
 612 ale_exclusion_list ale_new_exclusion_list(ale_context ac);
 613
 614 /*
 615  * Append an exclusion region to a list
 616  */
 617
 618 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);
 619
 620 /*
 621  * Obtain an alignment RESULT between frame A and current approximation B,
 622  * starting from transformation START, and given alignment properties
 623  * ALIGN_PROPERTIES.
 624  */
 625
 626 int ale_align(ale_context ac, ale_image a, ale_image b, ale_trans start,
 627                 ale_align_properties align_properties, ale_trans result);
 628
 629
 630 /*
 631  * Create an alignment properties structure.
 632  */
 633
 634 ale_align_properties ale_new_align_properties();
 635
 636 /*
 637  * Return a PSF error based on a captured sequence and a scene approximation.
 638  */
 639
 640 double ale_psf_error(ale_image approx, ale_sequence sequence);
 641
 642
 643
 644 #endif