# Add library project
add_subdirectory(src)
+add_subdirectory(doc)
--- /dev/null
+# add a target to generate API documentation with Doxygen
+find_package(Doxygen)
+if(DOXYGEN_FOUND)
+ configure_file("Doxyfile.in" "Doxyfile" @ONLY IMMEDIATE)
+
+ add_custom_target(doc
+ ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Generating API documentation with Doxygen" VERBATIM
+ )
+endif(DOXYGEN_FOUND)
--- /dev/null
+# Doxyfile 1.7.6.1
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = @PROJECT_NAME@
+PROJECT_NUMBER = @PROJECT_APIVER@
+PROJECT_BRIEF = "@PROJECT_DESCRIPTION@"
+PROJECT_LOGO =
+OUTPUT_DIRECTORY = @DOC_OUTPUT_PATH@
+CREATE_SUBDIRS = NO
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF =
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH = @CMAKE_SOURCE_DIR@
+STRIP_FROM_INC_PATH =
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = YES
+QT_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 8
+ALIASES =
+TCL_SUBST =
+OPTIMIZE_OUTPUT_FOR_C = YES
+OPTIMIZE_OUTPUT_JAVA = NO
+OPTIMIZE_FOR_FORTRAN = NO
+OPTIMIZE_OUTPUT_VHDL = NO
+EXTENSION_MAPPING =
+BUILTIN_STL_SUPPORT = NO
+CPP_CLI_SUPPORT = NO
+SIP_SUPPORT = NO
+IDL_PROPERTY_SUPPORT = YES
+DISTRIBUTE_GROUP_DOC = NO
+SUBGROUPING = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS = NO
+TYPEDEF_HIDES_STRUCT = NO
+SYMBOL_CACHE_SIZE = 0
+LOOKUP_CACHE_SIZE = 0
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL = NO
+EXTRACT_PRIVATE = NO
+EXTRACT_STATIC = NO
+EXTRACT_LOCAL_CLASSES = NO
+EXTRACT_LOCAL_METHODS = NO
+EXTRACT_ANON_NSPACES = NO
+HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_CLASSES = NO
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = NO
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = YES
+HIDE_SCOPE_NAMES = NO
+SHOW_INCLUDE_FILES = YES
+FORCE_LOCAL_INCLUDES = NO
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES = NO
+SORT_BY_SCOPE_NAME = NO
+STRICT_PROTO_MATCHING = NO
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS =
+MAX_INITIALIZER_LINES = 30
+SHOW_USED_FILES = YES
+SHOW_DIRECTORIES = NO
+SHOW_FILES = YES
+SHOW_NAMESPACES = YES
+FILE_VERSION_FILTER =
+LAYOUT_FILE =
+CITE_BIB_FILES =
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_NO_PARAMDOC = NO
+WARN_FORMAT = "$file:$line: $text"
+WARN_LOGFILE =
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT = @CMAKE_CURRENT_SOURCE_DIR@/ \
+ @CMAKE_SOURCE_DIR@/src/
+INPUT_ENCODING = UTF-8
+FILE_PATTERNS = *.dox \
+ *.h \
+ *.c
+RECURSIVE = NO
+EXCLUDE =
+EXCLUDE_SYMLINKS = NO
+EXCLUDE_PATTERNS =
+EXCLUDE_SYMBOLS =
+EXAMPLE_PATH =
+EXAMPLE_PATTERNS =
+EXAMPLE_RECURSIVE = NO
+IMAGE_PATH =
+INPUT_FILTER =
+FILTER_PATTERNS =
+FILTER_SOURCE_FILES = NO
+FILTER_SOURCE_PATTERNS =
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER = YES
+INLINE_SOURCES = YES
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = YES
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX = YES
+COLS_IN_ALPHA_INDEX = 5
+IGNORE_PREFIX =
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+HTML_HEADER =
+HTML_FOOTER =
+HTML_STYLESHEET =
+HTML_EXTRA_FILES =
+HTML_COLORSTYLE_HUE = 220
+HTML_COLORSTYLE_SAT = 100
+HTML_COLORSTYLE_GAMMA = 80
+HTML_TIMESTAMP = YES
+HTML_ALIGN_MEMBERS = YES
+HTML_DYNAMIC_SECTIONS = NO
+GENERATE_DOCSET = NO
+DOCSET_FEEDNAME = "Doxygen generated docs"
+DOCSET_BUNDLE_ID = org.doxygen.Project
+DOCSET_PUBLISHER_ID = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME = Publisher
+GENERATE_HTMLHELP = NO
+CHM_FILE =
+HHC_LOCATION =
+GENERATE_CHI = NO
+CHM_INDEX_ENCODING =
+BINARY_TOC = NO
+TOC_EXPAND = NO
+GENERATE_QHP = NO
+QCH_FILE =
+QHP_NAMESPACE = org.doxygen.Project
+QHP_VIRTUAL_FOLDER = doc
+QHP_CUST_FILTER_NAME =
+QHP_CUST_FILTER_ATTRS =
+QHP_SECT_FILTER_ATTRS =
+QHG_LOCATION =
+GENERATE_ECLIPSEHELP = NO
+ECLIPSE_DOC_ID = org.doxygen.Project
+DISABLE_INDEX = NO
+GENERATE_TREEVIEW = NO
+ENUM_VALUES_PER_LINE = 4
+USE_INLINE_TREES = NO
+TREEVIEW_WIDTH = 250
+EXT_LINKS_IN_WINDOW = NO
+FORMULA_FONTSIZE = 10
+FORMULA_TRANSPARENT = YES
+USE_MATHJAX = NO
+MATHJAX_RELPATH = http://www.mathjax.org/mathjax
+MATHJAX_EXTENSIONS =
+SEARCHENGINE = YES
+SERVER_BASED_SEARCH = NO
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX = NO
+LATEX_OUTPUT = latex
+LATEX_CMD_NAME = latex
+MAKEINDEX_CMD_NAME = makeindex
+COMPACT_LATEX = NO
+PAPER_TYPE = a4
+EXTRA_PACKAGES =
+LATEX_HEADER =
+LATEX_FOOTER =
+PDF_HYPERLINKS = YES
+USE_PDFLATEX = YES
+LATEX_BATCHMODE = NO
+LATEX_HIDE_INDICES = NO
+LATEX_SOURCE_CODE = NO
+LATEX_BIB_STYLE = plain
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF = NO
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+RTF_STYLESHEET_FILE =
+RTF_EXTENSIONS_FILE =
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_LINKS = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_SCHEMA =
+XML_DTD =
+XML_PROGRAMLISTING = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = NO
+EXPAND_ONLY_PREDEF = NO
+SEARCH_INCLUDES = YES
+INCLUDE_PATH =
+INCLUDE_FILE_PATTERNS =
+PREDEFINED =
+EXPAND_AS_DEFINED =
+SKIP_FUNCTION_MACROS = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+TAGFILES =
+GENERATE_TAGFILE =
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+PERL_PATH = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS = NO
+MSCGEN_PATH =
+HIDE_UNDOC_RELATIONS = YES
+HAVE_DOT = NO
+DOT_NUM_THREADS = 0
+DOT_FONTNAME = Helvetica
+DOT_FONTSIZE = 10
+DOT_FONTPATH =
+CLASS_GRAPH = YES
+COLLABORATION_GRAPH = YES
+GROUP_GRAPHS = YES
+UML_LOOK = NO
+TEMPLATE_RELATIONS = NO
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = NO
+CALLER_GRAPH = NO
+GRAPHICAL_HIERARCHY = YES
+DIRECTORY_GRAPH = YES
+DOT_IMAGE_FORMAT = png
+INTERACTIVE_SVG = NO
+DOT_PATH =
+DOTFILE_DIRS =
+MSCFILE_DIRS =
+DOT_GRAPH_MAX_NODES = 50
+MAX_DOT_GRAPH_DEPTH = 0
+DOT_TRANSPARENT = NO
+DOT_MULTI_TARGETS = YES
+GENERATE_LEGEND = YES
+DOT_CLEANUP = YES
--- /dev/null
+/**
+@mainpage libam7xxx
+
+@author Antonio Ospite <ospite@studenti.unina.it>
+@copyright GNU General Public License version 2.
+
+Website: http://git.ao2.it/libam7xxx.git
+
+@section libam7xxxIntro Introduction
+
+libam7xxx is an Open Source library to communicate via USB with projectors and
+Digital Picture Frames based on the Actions Micro AM7XXX family if ICs.
+
+libam7xxx makes it possible to use these devices as USB displays on
+non-Windows Operating Systems like GNU/Linux or Android/Linux just to name
+a few, and on non-PC platforms like for instance mobile phones, tablets or
+game consoles.
+
+@section libam7xxxSupportedDevices Supported Devices
+
+- Acer C110
+- Philips/SagemCom PicoPix 1020
+
+@section libam7xxxDesignOverview Design Overview
+
+libam7xxx provides access to devices via two structs:
+
+- A context, which manages aspects of thread safety when using
+ multiple devices on multiple threads.
+- A device, which talks to the hardware and manages transfers and configuration.
+
+Either or both of these structs are passed to the functions in order
+to interact with the hardware. The USB access is handled by
+libusb-1.0, which should work in a mostly non-blocking fashion across
+all platforms (see function documentation for specifics).
+
+The API and the project structure has been inspired by
+<a href="http://openkinect.org">libfreenect</a>.
+
+*/
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @file
+ * Public libam7xxx API.
+ */
+
#ifndef __AM7XXX_H
#define __AM7XXX_H
#endif
+/**
+ * @typedef am7xxx_context
+ *
+ * An opaque data type representing a context.
+ */
struct _am7xxx_context;
typedef struct _am7xxx_context am7xxx_context;
+/**
+ * @typedef am7xxx_device
+ *
+ * An opaque data type representing an am7xxx device.
+ */
struct _am7xxx_device;
typedef struct _am7xxx_device am7xxx_device;
+/**
+ * A struct describing device specific properties.
+ *
+ * A user program may want to inspect these before providing data to the
+ * device. For instance, when sending an image the user may want to rescale it
+ * to the device native width and height in order to be sure the image will be
+ * displayed in its entirety.
+ */
typedef struct {
- unsigned int native_width;
- unsigned int native_height;
+ unsigned int native_width; /**< The device native width. */
+ unsigned int native_height; /**< The device native height. */
} am7xxx_device_info;
+/**
+ * The verbosity level of logging messages.
+ *
+ * This can be set with am7xxx_set_log_level() and the level will be used
+ * internally by libam7xxx to adjust the granularity of the information
+ * exposed to the user about the internal library operations.
+ */
typedef enum {
- AM7XXX_LOG_FATAL = 0,
- AM7XXX_LOG_ERROR = 1,
- AM7XXX_LOG_WARNING = 2,
- AM7XXX_LOG_INFO = 3,
- AM7XXX_LOG_DEBUG = 4,
- AM7XXX_LOG_TRACE = 5,
+ AM7XXX_LOG_FATAL = 0, /**< Fatal messages, the user application should stop if it gets one of this. */
+ AM7XXX_LOG_ERROR = 1, /**< Error messages, typically they describe API functions failures. */
+ AM7XXX_LOG_WARNING = 2, /**< Warnings about conditions worth mentioning to the user. */
+ AM7XXX_LOG_INFO = 3, /**< Informations about the device operations. */
+ AM7XXX_LOG_DEBUG = 4, /**< Informations about the library internals. */
+ AM7XXX_LOG_TRACE = 5, /**< Verbose informations about the communication with the hardware. */
} am7xxx_log_level;
+/**
+ * The image formats accepted by the device.
+ */
typedef enum {
- AM7XXX_IMAGE_FORMAT_JPEG = 1,
- AM7XXX_IMAGE_FORMAT_NV12 = 2,
+ AM7XXX_IMAGE_FORMAT_JPEG = 1, /**< JPEG format. */
+ AM7XXX_IMAGE_FORMAT_NV12 = 2, /**< Raw YUV in the NV12 variant. */
} am7xxx_image_format;
+/**
+ * The device power modes.
+ *
+ * An am7xxx device can operate in several power modes. A certain power mode
+ * may have effect on the display brightness or on the device power
+ * consumption.
+ *
+ * @note Most am7xxx devices come with a Y-shaped USB cable with a Master and
+ * a Slave connector, higher power modes may require that both connectors are
+ * plugged in to the host system for the device to work properly.
+ *
+ * @note At higher power modes some devices may use a fan to cool down the
+ * internal hardware components, and hence may be noisier in this case.
+ */
typedef enum {
- AM7XXX_POWER_OFF = 0,
- AM7XXX_POWER_LOW = 1,
- AM7XXX_POWER_MIDDLE = 2,
- AM7XXX_POWER_HIGH = 3,
- AM7XXX_POWER_TURBO = 4,
+ AM7XXX_POWER_OFF = 0, /**< Display is powered off, no image shown. */
+ AM7XXX_POWER_LOW = 1, /**< Low power consumption but also low brightness. */
+ AM7XXX_POWER_MIDDLE = 2, /**< Middle level of brightness. */
+ AM7XXX_POWER_HIGH = 3, /**< More brightness, but more power consumption. */
+ AM7XXX_POWER_TURBO = 4, /**< Max brightness and power consumprion. This may need both the Master and Slave USB connectors plugged. */
} am7xxx_power_mode;
+/**
+ * Initialize the library context and data structures, and scan for devices.
+ *
+ * @param[out] ctx A pointer to the context the library will be used in.
+ *
+ * @return 0 on success, a negative value on error
+ */
int am7xxx_init(am7xxx_context **ctx);
+/**
+ * Cleanup the library data structures and free the context.
+ *
+ * @param[in,out] ctx The context to free.
+ */
void am7xxx_shutdown(am7xxx_context *ctx);
+/**
+ * Set verbosity level of log messages.
+ *
+ * @note The level is per-context.
+ *
+ * @note Messages of level AM7XXX_LOG_FATAL are always shown, regardless
+ * of the value of the log_level parameter.
+ *
+ * @param[in] ctx The context to set the log level for
+ * @param[in] log_level The verbosity level to use in the context (see @link am7xxx_log_level @endlink)
+ */
void am7xxx_set_log_level(am7xxx_context *ctx, am7xxx_log_level log_level);
+/**
+ * Open an am7xxx_device according to a index.
+ *
+ * The semantics of the 'device_index' argument follows the order
+ * of the devices as found when scanning the bus at am7xxx_init() time.
+ *
+ * @note When the user tries to open a device already opened the function
+ * returns -EBUSY and the device is left open.
+ *
+ * @param[in] ctx The context to open the device in
+ * @param[out] dev A pointer to the structure representing the device to open
+ * @param[in] device_index The index of the device on the bus
+ *
+ * @return 0 on success, a negative value on error
+ */
int am7xxx_open_device(am7xxx_context *ctx,
am7xxx_device **dev,
unsigned int device_index);
+/**
+ * Close an am7xxx_device.
+ *
+ * Close an am7xxx_device so that it becomes available for some other
+ * user/process to open it.
+ *
+ * @param[in] dev A pointer to the structure representing the device to close
+ *
+ * @return 0 on success, a negative value on error
+ */
int am7xxx_close_device(am7xxx_device *dev);
+/**
+ * Get info about an am7xxx device.
+ *
+ * Get information about a device, in the form of a
+ * @link am7xxx_device_info @endlink structure.
+ *
+ * @param[in] dev A pointer to the structure representing the device to get info of
+ * @param[out] device_info A pointer to the structure where to store the device info (see @link am7xxx_device_info @endlink)
+ *
+ * @return 0 on success, a negative value on error
+ */
int am7xxx_get_device_info(am7xxx_device *dev,
am7xxx_device_info *device_info);
+/**
+ * Send an image for display on a am7xxx device.
+ *
+ * This is the function that actually makes the device display something.
+ * Static pictures can be sent just once and the device will keep showing them
+ * until another image get sent or some command resets or turns off the display.
+ *
+ * @param[in] dev A pointer to the structure representing the device to get info of
+ * @param[in] format The format the image is in (see @link am7xxx_image_format @endlink enum)
+ * @param[in] width The width of the image
+ * @param[in] height The height of the image
+ * @param[in] image A buffer holding data in the format specified by the format parameter
+ * @param[in] image_size The size in bytes of the image buffer
+ *
+ * @return 0 on success, a negative value on error
+ */
int am7xxx_send_image(am7xxx_device *dev,
am7xxx_image_format format,
unsigned int width,
unsigned char *image,
unsigned int image_size);
-/*
- * NOTE: if we set the mode to AM7XXX_POWER_OFF we can't turn the
- * display on again by using only am7xxx_set_power_mode().
+/**
+ * Set the power mode of an am7xxx device.
+ *
+ * \note If we set the mode to AM7XXX_POWER_OFF we can't turn the
+ * display on again by using only am7xxx_set_power_mode(). This needs to be
+ * investigated, maybe some other command can reset the device.
+ *
+ * @param[in] dev A pointer to the structure representing the device to get info of
+ * @param[in] mode The power mode to put the device in (see @link am7xxx_power_mode @endlink enum)
+ *
+ * @return 0 on success, a negative value on error
*
- * Remember to mention that when writing the API doc.
*/
int am7xxx_set_power_mode(am7xxx_device *dev, am7xxx_power_mode mode);
projects / libam7xxx.git / commitdiff