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
  25 /*
  26  * libale requires OpenCL
  27  *
  28  * http://www.khronos.org/registry/cl/
  29  *
  30  * We assume the following header file, according to official documentation
  31  * example code.  If this doesn't work, try OpenCL/cl.h (or perhaps CL/cl.h),
  32  * as even Khronos does not seem to be entirely consistent in OpenCL header
  33  * naming.
  34  */
  35
  36 #include <OpenCL/opencl.h>
  37
  38 /*
  39  * Macro for API type definition
  40  *
  41  * API type name selection is based roughly on the approach taken in
  42  *
  43  * http://www.khronos.org/registry/cl/api/1.0/cl.h
  44  *
  45  * *_retain() and *_release() are patterned after OpenCL reference counting.
  46  *
  47  * *_valid() attempts to determine validity, returning non-zero if valid.
  48  */
  49
  50 #define ALE_API_TYPEDEF(TYPENAME) struct _ ## TYPENAME; typedef struct _ ## TYPENAME *TYPENAME; \
  51         int TYPENAME ## _valid(TYPENAME xx_valid_argument); \
  52         int TYPENAME ## _retain(TYPENAME xx_retain_argument); \
  53         int TYPENAME ## _release(TYPENAME xx_release_argument);
  54
  55 /*
  56  * Macros for API parameter declaration.
  57  */
  58
  59 #define ALE_API_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  60         PARAMETER_TYPE OBJECT_TYPE ## _get_ ## PARAMETER_NAME (OBJECT_TYPE object);
  61
  62 #define ALE_API_PARAMETER_W(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  63         int OBJECT_TYPE ## _set_ ## PARAMETER_NAME (OBJECT_TYPE object, PARAMETER_TYPE value);
  64
  65 #define ALE_API_PARAMETER_RW(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  66         ALE_API_PARAMETER_R(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE) \
  67         ALE_API_PARAMETER_W(OBJECT_TYPE, PARAMETER_NAME, PARAMETER_TYPE)
  68
  69 /*
  70  * API types
  71  */
  72
  73 ALE_API_TYPEDEF(ale_context)
  74
  75 ALE_API_TYPEDEF(ale_image)
  76 ALE_API_TYPEDEF(ale_render)
  77 ALE_API_TYPEDEF(ale_trans)
  78 ALE_API_TYPEDEF(ale_align_properties)
  79
  80 ALE_API_TYPEDEF(ale_filter)
  81 ALE_API_TYPEDEF(ale_psf)
  82
  83 ALE_API_TYPEDEF(ale_exclusion_list)
  84
  85 ALE_API_TYPEDEF(ale_sequence)
  86
  87 ALE_API_TYPEDEF(ale_scene)
  88
  89
  90 /*
  91  * Bayer patterns.  (Values are based on original ALE d2::image code, but using
  92  * standard clockwise ordering rather than ALE counterclockwise ordering.)
  93  */
  94
  95 enum {
  96         ALE_BAYER_NONE = 0x0,
  97         ALE_BAYER_RGBG = 0x4,        /* binary 100 */
  98         ALE_BAYER_GRGB = 0x5,        /* binary 101 */
  99         ALE_BAYER_GBGR = 0x6,        /* binary 110 */
 100         ALE_BAYER_BGRG = 0x7         /* binary 111 */
 101 };
 102
 103 /*
 104  * Bayer utility functions.  (Based on original ALE d2::image_bayer_ale_real
 105  * code.)
 106  */
 107
 108 /*
 109  * Return the color of a given pixel, for a given bayer pattern.
 110  */
 111 static unsigned int ale_bayer_color(unsigned int i, unsigned int j, unsigned int bayer) {
 112         unsigned int r_x_offset = bayer & 0x1;
 113         unsigned int r_y_offset = (bayer & 0x2) >> 1;
 114
 115         return (i + r_y_offset) % 2 + (j + r_x_offset) % 2;
 116 }
 117
 118 /*
 119  * Return a vector indicating set channels.
 120  */
 121 static char ale_get_channels(unsigned int i, unsigned int j, unsigned int bayer) {
 122         if (bayer == ALE_BAYER_NONE)
 123                 return 0x7;
 124         return (1 << ale_bayer_color(i, j, bayer));
 125 }
 126
 127 /*
 128  * Indicate whether a given channel exists.
 129  */
 130 static int ale_has_channel(unsigned int i, unsigned int j, unsigned int k, unsigned int bayer) {
 131         return (1 << k) & ale_get_channels(i, j, bayer);
 132 }
 133
 134
 135
 136 /*
 137  * Image formats.
 138  */
 139
 140 enum {
 141         ALE_IMAGE_Y,
 142         ALE_IMAGE_RGB,
 143         ALE_IMAGE_WEIGHTED_RGB
 144 };
 145
 146 /*
 147  * Domain types.
 148  */
 149
 150 enum {
 151         ALE_TYPE_UINT_8,
 152         ALE_TYPE_UINT_16,
 153         ALE_TYPE_UINT_32,
 154         ALE_TYPE_UINT_64,
 155         ALE_TYPE_FLOAT_32,
 156         ALE_TYPE_FLOAT_64
 157 };
 158
 159 /*
 160  * Invariant types.
 161  *
 162  * For ALE avgf, use MEAN|FIRST with saturation threshold;
 163  * other invariants are analogous; e.g.,
 164  *
 165  *   MEAN|LAST,
 166  *   MEDIAN|FIRST,
 167  *   etc.
 168  *
 169  * Not all expressible combinations are accepted, or, indeed, meaningful.
 170  */
 171
 172 enum {
 173         ALE_INVARIANT_NONE = 0,
 174         ALE_INVARIANT_MEAN = 1,
 175         ALE_INVARIANT_FIRST = 2,
 176         ALE_INVARIANT_LAST = 4,
 177         ALE_INVARIANT_MAX = 8,
 178         ALE_INVARIANT_MIN = 16,
 179         ALE_INVARIANT_MEDIAN = 32
 180 };
 181
 182 /*
 183  * Status return values.
 184  *
 185  * Based loosely on OpenCL status return values.
 186  */
 187
 188 enum {
 189         ALE_UNSPECIFIED_FAILURE = -1,
 190         ALE_SUCCESS = 0
 191 };
 192
 193 /*
 194  * Image buffer types.
 195  */
 196
 197 enum {
 198         ALE_BUFFER_CL,
 199         ALE_BUFFER_HOST,
 200         ALE_BUFFER_FILE
 201 };
 202
 203 /*
 204  * Obtain a Libale context given an OpenCL context
 205  */
 206
 207 ale_context ale_new_context(cl_context cc);
 208
 209 /*
 210  * Retain an OpenCL context from a Libale context.
 211  */
 212
 213 cl_context ale_context_retain_cl(ale_context ac);
 214
 215 /*
 216  * Set a context property.
 217  */
 218
 219 int ale_context_set_property(ale_context ac, const char *name, const char *value);
 220
 221 /*
 222  * Obtain a Libale transformation
 223  */
 224
 225 ale_trans ale_new_trans(ale_context ac, ale_image ai);
 226
 227 /*
 228  * Transformation exposure parameter.
 229  */
 230
 231 ALE_API_PARAMETER_RW(ale_trans, exposure, double)
 232
 233 /*
 234  * Transformation gamma parameter.  (Default is 0.45.)
 235  */
 236
 237 ALE_API_PARAMETER_RW(ale_trans, gamma, double)
 238
 239 /*
 240  * Transformation black level parameter, expressed as a fraction of saturation.
 241  */
 242
 243 ALE_API_PARAMETER_RW(ale_trans, black, double)
 244
 245 /*
 246  * Create a Libale image.
 247  */
 248
 249 ale_image ale_new_image(ale_context ac, int format, int type);
 250
 251 /*
 252  * Set a Libale image to a given OpenCL buffer, host buffer, or file buffer.
 253  */
 254
 255 int ale_image_set_cl(ale_image ai, size_t width, size_t height, cl_mem buffer);
 256 int ale_image_set_host_dynamic(ale_image ai, size_t width, size_t height, void *buffer);
 257 int ale_image_set_host_static(ale_image ai, size_t width, size_t height, void *buffer, void (*release_callback)(void *), void *callback_data);
 258 int ale_image_set_file_dynamic(ale_image ai, size_t width, size_t height, FILE *buffer);
 259 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);
 260
 261 /*
 262  * Buffer type for a given Libale image.
 263  */
 264
 265 ALE_API_PARAMETER_R(ale_image, buffer_type, int)
 266
 267 /*
 268  * Retain an OpenCL buffer, host buffer, or file buffer, given a Libale image.
 269  * (returns NULL or ((cl_mem) 0) on failure).
 270  */
 271
 272 cl_mem ale_image_retain_cl(ale_image ai);
 273 void *ale_image_retain_host(ale_image ai);
 274 FILE *ale_image_retain_file(ale_image ai);
 275
 276 /*
 277  * Release data without internal reference counters.
 278  */
 279
 280 int ale_image_release_host(ale_image ai, void *hi);
 281 int ale_image_release_file(ale_image ai, FILE *fi);
 282
 283 /*
 284  * Resize a Libale image.
 285  */
 286
 287 int ale_resize_image(ale_image ai, int x_offset, int y_offset, size_t width, size_t height);
 288
 289 /*
 290  * Get image statistics.
 291  */
 292
 293 ALE_API_PARAMETER_R(ale_image, height, size_t)
 294 ALE_API_PARAMETER_R(ale_image, width, size_t)
 295 ALE_API_PARAMETER_R(ale_image, format, int)
 296 ALE_API_PARAMETER_R(ale_image, type, int)
 297
 298 /*
 299  * Create a Libale incremental renderer, with given invariant.
 300  */
 301
 302 ale_render ale_new_render_incremental(ale_context ac, int type, int invariant);
 303
 304 /*
 305  * Libale renderer definition threshold parameter
 306  */
 307
 308 ALE_API_PARAMETER_RW(ale_render, definition_threshold, double)
 309
 310 /*
 311  * Libale renderer saturation threshold parameter
 312  */
 313
 314 ALE_API_PARAMETER_RW(ale_render, saturation_threshold, double)
 315
 316 /*
 317  * Libale renderer maximum frame range parameter
 318  */
 319
 320 ALE_API_PARAMETER_RW(ale_render, range_threshold, double)
 321
 322 /*
 323  * Render resize.
 324  */
 325
 326 int ale_render_resize(ale_render ar, ale_trans at);
 327
 328 /*
 329  * Render merge.
 330  */
 331
 332 int ale_render_merge(ale_render ar, ale_trans at, ale_image ai);
 333
 334 /*
 335  * Render retain image.
 336  */
 337
 338 ale_image ale_render_retain_image(ale_render ar);
 339
 340 /*
 341  * Specify a synchronization sequence for a renderer.
 342  */
 343
 344 ALE_API_PARAMETER_RW(ale_render, sync, ale_sequence)
 345
 346 /*
 347  * Synchronized renderer resize.
 348  */
 349
 350 int ale_render_resize_sync(ale_render ar, int i);
 351
 352 /*
 353  * Synchronized renderer merge.
 354  */
 355
 356 int ale_render_merge_sync(ale_render ar, int i);
 357
 358 /*
 359  * Create a Libale Irani-Peleg renderer, with given reference.
 360  */
 361
 362 ale_render ale_new_render_ip(ale_context ac, ale_render reference);
 363
 364 /*
 365  * Create a renderer ensemble.
 366  */
 367
 368 ale_render ale_new_render_ensemble(ale_context ac);
 369
 370 /*
 371  * Retain a renderer from an ensemble.
 372  */
 373
 374 ale_render ale_render_ensemble_retain(ale_render ar, const char *spec);
 375
 376 /*
 377  * Perform a stream processing (e.g., Irani-Peleg) cycle.
 378  */
 379
 380 int ale_render_stream_process(ale_render ar);
 381
 382 /*
 383  * Create a filter.
 384  */
 385
 386 ale_filter ale_new_filter(ale_context ac, const char *type);
 387
 388 /*
 389  * Create a point-spread function.
 390  */
 391
 392 ale_psf ale_new_psf(ale_context ac, const char *type);
 393
 394 /*
 395  * Create an exclusion region list.
 396  */
 397
 398 ale_exclusion_list ale_new_exclusion_list(ale_context ac);
 399
 400 /*
 401  * Append an exclusion region to a list
 402  */
 403
 404 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);
 405
 406 /*
 407  * Obtain an alignment RESULT between frame A and current approximation B,
 408  * starting from transformation START, and given perturbation limits
 409  * PERTURB_LIMITS.
 410  */
 411
 412 int ale_align(ale_image a, ale_image b, ale_trans start,
 413                 ale_align_properties align_properties, ale_trans result);
 414
 415
 416 /*
 417  * Return a PSF error based on a captured sequence and a scene approximation.
 418  */
 419
 420 double ale_psf_error(ale_image approx, ale_sequence sequence);
 421
 422
 423
 424 #endif