Compose rectangle support for libv4l2subdev
[media-ctl.git] / src / mediactl.h
index 65ad890..2296fe2 100644 (file)
@@ -1,20 +1,22 @@
 /*
  * Media controller interface library
  *
- * Copyright (C) 2010 Ideas on board SPRL <laurent.pinchart@ideasonboard.com>
+ * Copyright (C) 2010-2011 Ideas on board SPRL
+ *
+ * Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
  *
  * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; either version 2.1 of the License, or
  * (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * GNU Lesser General Public License for more details.
  *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
 #ifndef __MEDIA_H__
@@ -38,6 +40,7 @@ struct media_pad {
 };
 
 struct media_entity {
+       struct media_device *media;
        struct media_entity_desc info;
        struct media_pad *pads;
        struct media_link *links;
@@ -51,15 +54,55 @@ struct media_entity {
 
 struct media_device {
        int fd;
+       struct media_device_info info;
        struct media_entity *entities;
        unsigned int entities_count;
+       void (*debug_handler)(void *, ...);
+       void *debug_priv;
        __u32 padding[6];
 };
 
+#define media_dbg(media, ...) \
+       (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
+
+/**
+ * @brief Set a handler for debug messages.
+ * @param media - device instance.
+ * @param debug_handler - debug message handler
+ * @param debug_priv - first argument to debug message handler
+ *
+ * Set a handler for debug messages that will be called whenever
+ * debugging information is to be printed. The handler expects an
+ * fprintf-like function.
+ */
+void media_debug_set_handler(
+       struct media_device *media, void (*debug_handler)(void *, ...),
+       void *debug_priv);
+
+/**
+ * @brief Open a media device with debugging enabled.
+ * @param name - name (including path) of the device node.
+ * @param debug_handler - debug message handler
+ * @param debug_priv - first argument to debug message handler
+ *
+ * Open the media device referenced by @a name and enumerate entities, pads and
+ * links.
+ *
+ * Calling media_open_debug() instead of media_open() is equivalent to
+ * media_open() and media_debug_set_handler() except that debugging is
+ * also enabled during media_open().
+ *
+ * @return A pointer to a newly allocated media_device structure instance on
+ * success and NULL on failure. The returned pointer must be freed with
+ * media_close when the device isn't needed anymore.
+ */
+struct media_device *media_open_debug(
+       const char *name, void (*debug_handler)(void *, ...),
+       void *debug_priv);
+
 /**
  * @brief Open a media device.
  * @param name - name (including path) of the device node.
- * @param verbose - whether to print verbose information on the standard output.
  *
  * Open the media device referenced by @a name and enumerate entities, pads and
  * links.
@@ -68,7 +111,7 @@ struct media_device {
  * success and NULL on failure. The returned pointer must be freed with
  * media_close when the device isn't needed anymore.
  */
-struct media_device *media_open(const char *name, int verbose);
+struct media_device *media_open(const char *name);
 
 /**
  * @brief Close a media device.
@@ -121,7 +164,11 @@ struct media_entity *media_get_entity_by_name(struct media_device *media,
  * @param media - media device.
  * @param id - entity ID.
  *
- * Search for an entity with an ID equal to @a id.
+ * This function searches for an entity based on its ID using an exact match or
+ * next ID method based on the given @a id. If @a id is ORed with
+ * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
+ * ID larger than @a id. Otherwise it will return the entity with an ID equal to
+ * @a id.
  *
  * @return A pointer to the entity if found, or NULL otherwise.
  */