/*
  Copyright 2007-2011 David Robillard <http://drobilla.net>

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  THE POSSIBILITY OF SUCH DAMAGE.
*/

/**
   @file suil.h API for Suil, an LV2 UI wrapper library.
*/

#ifndef SUIL_SUIL_H
#define SUIL_SUIL_H

#include <stdbool.h>
#include <stdint.h>

#include "lv2/lv2plug.in/ns/lv2core/lv2.h"

#ifdef SUIL_SHARED
#    ifdef __WIN32__
#        define SUIL_LIB_IMPORT __declspec(dllimport)
#        define SUIL_LIB_EXPORT __declspec(dllexport)
#    else
#        define SUIL_LIB_IMPORT __attribute__((visibility("default")))
#        define SUIL_LIB_EXPORT __attribute__((visibility("default")))
#    endif
#    ifdef SUIL_INTERNAL
#        define SUIL_API SUIL_LIB_EXPORT
#    else
#        define SUIL_API SUIL_LIB_IMPORT
#    endif
#else
#    define SUIL_API
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
   @defgroup suil Suil
   A library for hosting LV2 plugin UIs.
   @{
*/

/**
   UI host descriptor.

   This contains the various functions that a plugin UI may use to communicate
   with the plugin.  It is passed to @ref suil_instance_new to provide
   these functions to the UI.
*/
typedef struct _SuilHost* SuilHost;

/** An instance of an LV2 plugin UI. */
typedef struct _SuilInstance* SuilInstance;

/** Opaque pointer to a UI widget. */
typedef void* SuilWidget;

/**
   UI controller.

   This is an opaque pointer passed by the user which is passed to the various
   UI control functions (e.g. SuilPortWriteFunc).  It is typically used to pass
   a pointer to some controller object the host uses to communicate with
   plugins.
*/
typedef void* SuilController;

/** Function to write/send a value to a port. */
typedef void (*SuilPortWriteFunc)(SuilController controller,
                                  uint32_t       port_index,
                                  uint32_t       buffer_size,
                                  uint32_t       protocol,
                                  void const*    buffer);

/** Function to return the index for a port by symbol. */
typedef uint32_t (*SuilPortIndexFunc)(SuilController controller,
                                      const char*    port_symbol);

/** Function to subscribe to notifications for a port. */
typedef uint32_t (*SuilPortSubscribeFunc)(SuilController controller,
                                          uint32_t       port_index,
                                          uint32_t       protocol);

/** Function to unsubscribe from notifications for a port. */
typedef uint32_t (*SuilPortUnsubscribeFunc)(SuilController controller,
                                            uint32_t       port_index,
                                            uint32_t       protocol);

/**
   Create a new UI host descriptor.
   @param write_func Function to send a value to a plugin port.
   @param index_func Function to get the index for a port by symbol.
   @param subscribe_func Function to subscribe to port updates.
   @param unsubscribe_func Function to unsubscribe from port updates.
*/
SUIL_API
SuilHost
suil_host_new(SuilPortWriteFunc       write_func,
              SuilPortIndexFunc       index_func,
              SuilPortSubscribeFunc   subscribe_func,
              SuilPortUnsubscribeFunc unsubscribe_func);

/**
   Free @a host.
*/
SUIL_API
void
suil_host_free(SuilHost host);

/**
   Check if suil can wrap a UI type.
   @param host_type_uri The URI of the desired widget type of the host,
   corresponding to the @a type_uri parameter of @ref suil_instance_new.
   @param ui_type_uri The URI of the UI widget type.
   @return 0 if wrapping is unsupported, otherwise the quality of the wrapping
   where 1 is the highest quality (direct native embedding with no wrapping)
   and increaing values are of a progressively lower quality and/or stability.
*/
SUIL_API
unsigned
suil_ui_supported(const char* host_type_uri,
                  const char* ui_type_uri);

/**
   Instantiate a UI for an LV2 plugin.
   @param host Host descriptor.
   @param controller Opaque host controller pointer.
   @param container_type_uri URI of the desired host container widget type.
   @param plugin_uri URI of the plugin to instantiate this UI for.
   @param ui_uri URI of a specifically desired UI, or NULL to use the
   best choice given @a type_uri.
   @param ui_type_uri URI of the actual UI widget type.
   @param ui_bundle_path Path of the UI bundle.
   @param ui_binary_path Path of the UI binary.
   @param features NULL-terminated array of supported features, or NULL.
   @return A new UI instance, or NULL if instantiation failed.
*/
SUIL_API
SuilInstance
suil_instance_new(SuilHost                  host,
                  SuilController            controller,
                  const char*               container_type_uri,
                  const char*               plugin_uri,
                  const char*               ui_uri,
                  const char*               ui_type_uri,
                  const char*               ui_bundle_path,
                  const char*               ui_binary_path,
                  const LV2_Feature* const* features);

/**
   Free a plugin UI instance.

   The caller must ensure all references to the UI have been dropped before
   calling this function (e.g. it has been removed from its parent).
*/
SUIL_API
void
suil_instance_free(SuilInstance instance);

/**
   Get the widget for a UI instance.

   Returns an opaque pointer to a widget, the type of which is defined by the
   corresponding parameter to suil_instantiate. Note this may be a wrapper
   widget created by Suil, and not necessarily the widget directly implemented
   by the UI.
*/
SUIL_API
SuilWidget
suil_instance_get_widget(SuilInstance instance);

/**
   Notify the UI about a change in a plugin port.
*/
SUIL_API
void
suil_instance_port_event(SuilInstance instance,
                         uint32_t     port_index,
                         uint32_t     buffer_size,
                         uint32_t     format,
                         const void*  buffer);

/**
   Return a data structure defined by some LV2 extension URI.
*/
SUIL_API
const void*
suil_instance_extension_data(SuilInstance instance,
                             const char*  uri);

/**
   @}
*/

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* SUIL_SUIL_H */