src/calf/lv2_progress.h

   1 /* -*- Mode: C ; c-basic-offset: 2 -*- */
   2 /*****************************************************************************
   3  *
   4  *  This work is in public domain.
   5  *
   6  *  This file is distributed in the hope that it will be useful,
   7  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
   8  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   9  *
  10  *  Author of this extension is Nedko Arnaudov <nedko@arnaudov.name>
  11  *
  12  *  Several people helped improving the extension:
  13  *   * Krzysztof Foltman <wdev@foltman.com>
  14  *   * Dave Robillard <dave@drobilla.net>
  15  *
  16  *  If you have questions ask in the #lv2 or #lad channel,
  17  *  FreeNode IRC network or use the lv2 mailing list.
  18  *
  19  *****************************************************************************/
  20
  21 #ifndef LV2_PROGRESS_H__F576843C_CA13_49C3_9BF9_CFF3A15AD18C__INCLUDED
  22 #define LV2_PROGRESS_H__F576843C_CA13_49C3_9BF9_CFF3A15AD18C__INCLUDED
  23
  24 /**
  25  * @file lv2_progress.h
  26  * @brief LV2 progress notification extension definition
  27  *
  28  * @par Purpose and scope
  29  * The purpose of this extension is to prevent thread (often the main one)
  30  * freeze for plugins doing intensive computations during instantiation.
  31  * Host may want to display progress bar of some sort and if it is using
  32  * GUI toolkit event loop, to dispatch queued events.
  33  *
  34  * @par
  35  * Using this extension for reporting progress of other lengthy operations
  36  * is possible and encouraged but not subject of this extension alone.
  37  * It is probably not good idea to call progress callback from plugin created
  38  * thread nor it is good idea to call it from a LV2 audio class function.
  39  * Any extension that wants to work in conjuction with progress extension
  40  * must define thread context semantics for calling the progress callback.
  41  *
  42  * @par Plugin instantiation progress usage
  43  * Plugin calls the host provided callback on regular basis during
  44  * instantiation. One second between calls is good target. Everything between
  45  * half second and two seconds should provide enough motion so user does
  46  * not get "the thing froze" impression.
  47  */
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52 #if 0
  53 } /* Adjust editor indent */
  54 #endif
  55
  56 /** URI for the plugin progress feature */
  57 #define LV2_PROGRESS_URI "http://lv2plug.in/ns/dev/progress"
  58
  59 /** @brief host feature structure */
  60 typedef struct _LV2_Progress
  61 {
  62   /** to be supplied as first parameter of progress() callback  */
  63   void * context;
  64
  65   /**
  66    * This function is called by plugin to notify host about progress of a
  67    * lengthy operation.
  68    *
  69    * @param context Host context
  70    * @param progress Progress, from 0.0 to 100.0
  71    * @param message Optional (may be NULL) string describing current operation.
  72    * If called once with non-NULL message, subsequent calls will NULL message
  73    * mean that host will reuse the previous message.
  74    */
  75   void (*progress)(void * context, float progress, const char * message);
  76 } LV2_Progress;
  77
  78 #if 0
  79 { /* Adjust editor indent */
  80 #endif
  81 #ifdef __cplusplus
  82 } /* extern "C" */
  83 #endif
  84
  85 #endif /* #ifndef LV2_PROGRESS_H__F576843C_CA13_49C3_9BF9_CFF3A15AD18C__INCLUDED */