Repurpose maintainer-clean to get to clean autotools files

so changes that need to be committed via git are more clear.

10 files changed, 1113 insertions, 2325 deletions

diff --git a/INSTALL b/INSTALL
deleted file mode 120000
index 5bb6e7b..0000000
--- a/INSTALL
+++ /dev/null
@@ -1 +0,0 @@
-/usr/share/automake-1.10/INSTALL
\ No newline at end of file
diff --git a/Makefile.am b/Makefile.am
index 8a20f33..f654ac6 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,19 @@
 SUBDIRS=src  \
-	test \
-	docs
+	test
 dist_doc_DATA = README
 ACLOCAL_AMFLAGS = -I m4
 AUTOMAKE_OPTIONS = foreign
+EXTRA_DIST = autogen.sh
+
+MAINTAINERCLEANFILES = depcomp INSTALL install-sh missing aclocal.m4 config.guess config.sub configure
+
+clean-local:
+	test -d ./docs && rm -Rf ./docs || true
+
+maintainer-clean-local:
+	test -d ./m4 && rm -Rf ./m4 || true
+	test -d ./config && rm -Rf ./config || true
+	test -d ./autom4te.cache && rm -Rf ./autom4te.cache || true
+	find . -name \*~ -exec rm {} \;
+	find . -name \*.in -exec rm {} \;
+	
diff --git a/autogen.sh b/autogen.sh
index ac7d89c..3200ee6 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -1,3 +1,4 @@
 #!/bin/sh
+mkdir m4
 autoreconf --force --install -I config -I m4
         
\ No newline at end of file
diff --git a/configure.ac b/configure.ac
index 7be1a49..01ac67b 100644
--- a/configure.ac
+++ b/configure.ac
@@ -2,21 +2,23 @@
 # Process this file with autoconf to produce a configure script.
 
 AC_PREREQ([2.63])
-AC_INIT([libdlo], [1.0.0], [libdlo@displaylink.com])
+AC_INIT([libdlo], [0.1.0], [libdlo@displaylink.com])
+AC_CONFIG_AUX_DIR([config])
 AM_INIT_AUTOMAKE([-Wall -Werror foreign dist-bzip2])
 AC_CONFIG_SRCDIR([src/dlo_grfx.c])
 AC_USE_SYSTEM_EXTENSIONS
 AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_HEADERS([config.h])
-AC_PROG_LIBTOOL
 
 # Checks for programs.
 AC_PROG_CC
+AC_PROG_LIBTOOL
 
-# Checks for libraries.
+# create LIBTOOLS macros.
+LT_INIT
 
 # Checks for header files.
-AC_CHECK_HEADERS([stdint.h stdlib.h string.h])
+AC_CHECK_HEADERS([stdint.h stdlib.h string.h usb.h])
 
 # Checks for typedefs, structures, and compiler characteristics.
 AC_HEADER_STDBOOL
@@ -29,6 +31,7 @@ AC_TYPE_UINT64_T
 AC_TYPE_UINT8_T
 
 # Checks for library functions.
+PKG_CHECK_MODULES(LIBUSB, libusb >= 0.1.12)
 AC_FUNC_MALLOC
 AC_FUNC_REALLOC
 AC_CHECK_FUNCS([gettimeofday strchr])
@@ -37,7 +40,7 @@ AC_CONFIG_FILES([Makefile
                  src/Makefile
                  test/Makefile
                  test/test1/Makefile
-                 test/test1/src/Makefile])
+                ])
 AC_OUTPUT
 AC_MSG_RESULT([
 	libdlo $VERSION
diff --git a/docs/Doxyfile b/docs/Doxyfile
deleted file mode 100644
index 04671a7..0000000
--- a/docs/Doxyfile
+++ /dev/null
@@ -1,1243 +0,0 @@
-# Doxyfile 1.5.1
-#
-# DisplayLink Open Source Software (libdlo)
-# Copyright (C) 2009, DisplayLink
-# www.displaylink.com
-#
-# This library is free software; you can redistribute it and/or modify it under
-# the terms of the GNU Library General Public License as published by the Free
-# Software Foundation; LGPL version 2, dated June 1991.
-#
-# This library 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 Library General Public License for more
-# details.
-#
-# You should have received a copy of the GNU Library General Public License
-# along with this library; if not, write to the Free Software Foundation, Inc.,
-# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-
-# This file describes the settings to be used by the documentation system
-# doxygen (www.doxygen.org) for a project
-#
-# All text after a hash (#) is considered a comment and will be ignored
-# The format is:
-#       TAG = value [value, ...]
-# For lists items can also be appended using:
-#       TAG += value [value, ...]
-# Values that contain spaces should be placed between quotes (" ")
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-
-# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
-# by quotes) that should identify the project.
-
-PROJECT_NAME           = "DisplayLink Open Source Software (libdlo)"
-
-# The PROJECT_NUMBER tag can be used to enter a project or revision number.
-# This could be handy for archiving the generated documentation or
-# if some version control system is used.
-
-PROJECT_NUMBER         =
-
-# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
-# base path where the generated documentation will be put.
-# If a relative path is entered, it will be relative to the location
-# where doxygen was started. If left blank the current directory will be used.
-
-OUTPUT_DIRECTORY       = docs
-
-# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
-# 4096 sub-directories (in 2 levels) under the output directory of each output
-# format and will distribute the generated files over these directories.
-# Enabling this option can be useful when feeding doxygen a huge amount of
-# source files, where putting all generated files in the same directory would
-# otherwise cause performance problems for the file system.
-
-CREATE_SUBDIRS         = NO
-
-# The OUTPUT_LANGUAGE tag is used to specify the language in which all
-# documentation generated by doxygen is written. Doxygen will use this
-# information to generate all constant output in the proper language.
-# The default language is English, other supported languages are:
-# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
-# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian,
-# Italian, Japanese, Japanese-en (Japanese with English messages), Korean,
-# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian,
-# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian.
-
-OUTPUT_LANGUAGE        = English
-
-# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
-# include brief member descriptions after the members that are listed in
-# the file and class documentation (similar to JavaDoc).
-# Set to NO to disable this.
-
-BRIEF_MEMBER_DESC      = YES
-
-# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
-# the brief description of a member or function before the detailed description.
-# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
-# brief descriptions will be completely suppressed.
-
-REPEAT_BRIEF           = YES
-
-# This tag implements a quasi-intelligent brief description abbreviator
-# that is used to form the text in various listings. Each string
-# in this list, if found as the leading text of the brief description, will be
-# stripped from the text and the result after processing the whole list, is
-# used as the annotated text. Otherwise, the brief description is used as-is.
-# If left blank, the following values are used ("$name" is automatically
-# replaced with the name of the entity): "The $name class" "The $name widget"
-# "The $name file" "is" "provides" "specifies" "contains"
-# "represents" "a" "an" "the"
-
-ABBREVIATE_BRIEF       =
-
-# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
-# Doxygen will generate a detailed section even if there is only a brief
-# description.
-
-ALWAYS_DETAILED_SEC    = NO
-
-# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
-# inherited members of a class in the documentation of that class as if those
-# members were ordinary class members. Constructors, destructors and assignment
-# operators of the base classes will not be shown.
-
-INLINE_INHERITED_MEMB  = NO
-
-# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
-# path before files name in the file list and in the header files. If set
-# to NO the shortest path that makes the file name unique will be used.
-
-FULL_PATH_NAMES        = NO
-
-# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
-# can be used to strip a user-defined part of the path. Stripping is
-# only done if one of the specified strings matches the left-hand part of
-# the path. The tag can be used to show relative paths in the file list.
-# If left blank the directory from which doxygen is run is used as the
-# path to strip.
-
-STRIP_FROM_PATH        =
-
-# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
-# the path mentioned in the documentation of a class, which tells
-# the reader which header file to include in order to use a class.
-# If left blank only the name of the header file containing the class
-# definition is used. Otherwise one should specify the include paths that
-# are normally passed to the compiler using the -I flag.
-
-STRIP_FROM_INC_PATH    =
-
-# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
-# (but less readable) file names. This can be useful is your file systems
-# doesn't support long names like on DOS, Mac, or CD-ROM.
-
-SHORT_NAMES            = NO
-
-# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
-# will interpret the first line (until the first dot) of a JavaDoc-style
-# comment as the brief description. If set to NO, the JavaDoc
-# comments will behave just like the Qt-style comments (thus requiring an
-# explicit @brief command for a brief description.
-
-JAVADOC_AUTOBRIEF      = NO
-
-# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
-# treat a multi-line C++ special comment block (i.e. a block of //! or ///
-# comments) as a brief description. This used to be the default behaviour.
-# The new default is to treat a multi-line C++ comment block as a detailed
-# description. Set this tag to YES if you prefer the old behaviour instead.
-
-MULTILINE_CPP_IS_BRIEF = NO
-
-# If the DETAILS_AT_TOP tag is set to YES then Doxygen
-# will output the detailed description near the top, like JavaDoc.
-# If set to NO, the detailed description appears after the member
-# documentation.
-
-DETAILS_AT_TOP         = NO
-
-# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
-# member inherits the documentation from any documented member that it
-# re-implements.
-
-INHERIT_DOCS           = YES
-
-# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
-# a new page for each member. If set to NO, the documentation of a member will
-# be part of the file/class/namespace that contains it.
-
-SEPARATE_MEMBER_PAGES  = NO
-
-# The TAB_SIZE tag can be used to set the number of spaces in a tab.
-# Doxygen uses this value to replace tabs by spaces in code fragments.
-
-TAB_SIZE               = 8
-
-# This tag can be used to specify a number of aliases that acts
-# as commands in the documentation. An alias has the form "name=value".
-# For example adding "sideeffect=\par Side Effects:\n" will allow you to
-# put the command \sideeffect (or @sideeffect) in the documentation, which
-# will result in a user-defined paragraph with heading "Side Effects:".
-# You can put \n's in the value part of an alias to insert newlines.
-
-ALIASES                =
-
-# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
-# sources only. Doxygen will then generate output that is more tailored for C.
-# For instance, some of the names that are used will be different. The list
-# of all members will be omitted, etc.
-
-OPTIMIZE_OUTPUT_FOR_C  = YES
-
-# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
-# sources only. Doxygen will then generate output that is more tailored for Java.
-# For instance, namespaces will be presented as packages, qualified scopes
-# will look different, etc.
-
-OPTIMIZE_OUTPUT_JAVA   = NO
-
-# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to
-# include (a tag file for) the STL sources as input, then you should
-# set this tag to YES in order to let doxygen match functions declarations and
-# definitions whose arguments contain STL classes (e.g. func(std::string); v.s.
-# func(std::string) {}). This also make the inheritance and collaboration
-# diagrams that involve STL classes more complete and accurate.
-
-BUILTIN_STL_SUPPORT    = NO
-
-# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
-# tag is set to YES, then doxygen will reuse the documentation of the first
-# member in the group (if any) for the other members of the group. By default
-# all members of a group must be documented explicitly.
-
-DISTRIBUTE_GROUP_DOC   = NO
-
-# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
-# the same type (for instance a group of public functions) to be put as a
-# subgroup of that type (e.g. under the Public Functions section). Set it to
-# NO to prevent subgrouping. Alternatively, this can be done per class using
-# the \nosubgrouping command.
-
-SUBGROUPING            = YES
-
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-
-# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
-# documentation are documented, even if no documentation was available.
-# Private class members and static file members will be hidden unless
-# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
-
-EXTRACT_ALL            = NO
-
-# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
-# will be included in the documentation.
-
-EXTRACT_PRIVATE        = NO
-
-# If the EXTRACT_STATIC tag is set to YES all static members of a file
-# will be included in the documentation.
-
-EXTRACT_STATIC         = NO
-
-# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
-# defined locally in source files will be included in the documentation.
-# If set to NO only classes defined in header files are included.
-
-EXTRACT_LOCAL_CLASSES  = YES
-
-# This flag is only useful for Objective-C code. When set to YES local
-# methods, which are defined in the implementation section but not in
-# the interface are included in the documentation.
-# If set to NO (the default) only methods in the interface are included.
-
-EXTRACT_LOCAL_METHODS  = NO
-
-# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
-# undocumented members of documented classes, files or namespaces.
-# If set to NO (the default) these members will be included in the
-# various overviews, but no documentation section is generated.
-# This option has no effect if EXTRACT_ALL is enabled.
-
-HIDE_UNDOC_MEMBERS     = NO
-
-# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
-# undocumented classes that are normally visible in the class hierarchy.
-# If set to NO (the default) these classes will be included in the various
-# overviews. This option has no effect if EXTRACT_ALL is enabled.
-
-HIDE_UNDOC_CLASSES     = NO
-
-# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
-# friend (class|struct|union) declarations.
-# If set to NO (the default) these declarations will be included in the
-# documentation.
-
-HIDE_FRIEND_COMPOUNDS  = NO
-
-# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
-# documentation blocks found inside the body of a function.
-# If set to NO (the default) these blocks will be appended to the
-# function's detailed documentation block.
-
-HIDE_IN_BODY_DOCS      = NO
-
-# The INTERNAL_DOCS tag determines if documentation
-# that is typed after a \internal command is included. If the tag is set
-# to NO (the default) then the documentation will be excluded.
-# Set it to YES to include the internal documentation.
-
-INTERNAL_DOCS          = NO
-
-# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
-# file names in lower-case letters. If set to YES upper-case letters are also
-# allowed. This is useful if you have classes or files whose names only differ
-# in case and if your file system supports case sensitive file names. Windows
-# and Mac users are advised to set this option to NO.
-
-CASE_SENSE_NAMES       = YES
-
-# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
-# will show members with their full class and namespace scopes in the
-# documentation. If set to YES the scope will be hidden.
-
-HIDE_SCOPE_NAMES       = NO
-
-# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
-# will put a list of the files that are included by a file in the documentation
-# of that file.
-
-SHOW_INCLUDE_FILES     = YES
-
-# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
-# is inserted in the documentation for inline members.
-
-INLINE_INFO            = YES
-
-# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
-# will sort the (detailed) documentation of file and class members
-# alphabetically by member name. If set to NO the members will appear in
-# declaration order.
-
-SORT_MEMBER_DOCS       = YES
-
-# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
-# brief documentation of file, namespace and class members alphabetically
-# by member name. If set to NO (the default) the members will appear in
-# declaration order.
-
-SORT_BRIEF_DOCS        = NO
-
-# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
-# sorted by fully-qualified names, including namespaces. If set to
-# NO (the default), the class list will be sorted only by class name,
-# not including the namespace part.
-# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
-# Note: This option applies only to the class list, not to the
-# alphabetical list.
-
-SORT_BY_SCOPE_NAME     = NO
-
-# The GENERATE_TODOLIST tag can be used to enable (YES) or
-# disable (NO) the todo list. This list is created by putting \todo
-# commands in the documentation.
-
-GENERATE_TODOLIST      = YES
-
-# The GENERATE_TESTLIST tag can be used to enable (YES) or
-# disable (NO) the test list. This list is created by putting \test
-# commands in the documentation.
-
-GENERATE_TESTLIST      = YES
-
-# The GENERATE_BUGLIST tag can be used to enable (YES) or
-# disable (NO) the bug list. This list is created by putting \bug
-# commands in the documentation.
-
-GENERATE_BUGLIST       = YES
-
-# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
-# disable (NO) the deprecated list. This list is created by putting
-# \deprecated commands in the documentation.
-
-GENERATE_DEPRECATEDLIST= YES
-
-# The ENABLED_SECTIONS tag can be used to enable conditional
-# documentation sections, marked by \if sectionname ... \endif.
-
-ENABLED_SECTIONS       =
-
-# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
-# the initial value of a variable or define consists of for it to appear in
-# the documentation. If the initializer consists of more lines than specified
-# here it will be hidden. Use a value of 0 to hide initializers completely.
-# The appearance of the initializer of individual variables and defines in the
-# documentation can be controlled using \showinitializer or \hideinitializer
-# command in the documentation regardless of this setting.
-
-MAX_INITIALIZER_LINES  = 30
-
-# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
-# at the bottom of the documentation of classes and structs. If set to YES the
-# list will mention the files that were used to generate the documentation.
-
-SHOW_USED_FILES        = YES
-
-# If the sources in your project are distributed over multiple directories
-# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
-# in the documentation. The default is NO.
-
-SHOW_DIRECTORIES       = YES
-
-# The FILE_VERSION_FILTER tag can be used to specify a program or script that
-# doxygen should invoke to get the current version for each file (typically from the
-# version control system). Doxygen will invoke the program by executing (via
-# popen()) the command <command> <input-file>, where <command> is the value of
-# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file
-# provided by doxygen. Whatever the program writes to standard output
-# is used as the file version. See the manual for examples.
-
-FILE_VERSION_FILTER    =
-
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-
-# The QUIET tag can be used to turn on/off the messages that are generated
-# by doxygen. Possible values are YES and NO. If left blank NO is used.
-
-QUIET                  = NO
-
-# The WARNINGS tag can be used to turn on/off the warning messages that are
-# generated by doxygen. Possible values are YES and NO. If left blank
-# NO is used.
-
-WARNINGS               = YES
-
-# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
-# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
-# automatically be disabled.
-
-WARN_IF_UNDOCUMENTED   = YES
-
-# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
-# potential errors in the documentation, such as not documenting some
-# parameters in a documented function, or documenting parameters that
-# don't exist or using markup commands wrongly.
-
-WARN_IF_DOC_ERROR      = YES
-
-# This WARN_NO_PARAMDOC option can be abled to get warnings for
-# functions that are documented, but have no documentation for their parameters
-# or return value. If set to NO (the default) doxygen will only warn about
-# wrong or incomplete parameter documentation, but not about the absence of
-# documentation.
-
-WARN_NO_PARAMDOC       = NO
-
-# The WARN_FORMAT tag determines the format of the warning messages that
-# doxygen can produce. The string should contain the $file, $line, and $text
-# tags, which will be replaced by the file and line number from which the
-# warning originated and the warning text. Optionally the format may contain
-# $version, which will be replaced by the version of the file (if it could
-# be obtained via FILE_VERSION_FILTER)
-
-WARN_FORMAT            = "$file:$line: $text"
-
-# The WARN_LOGFILE tag can be used to specify a file to which warning
-# and error messages should be written. If left blank the output is written
-# to stderr.
-
-WARN_LOGFILE           =
-
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-
-# The INPUT tag can be used to specify the files and/or directories that contain
-# documented source files. You may enter file names like "myfile.cpp" or
-# directories like "/usr/src/myproject". Separate the files or directories
-# with spaces.
-
-INPUT                  = src include
-
-# If the value of the INPUT tag contains directories, you can use the
-# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
-# and *.h) to filter out the source-files in the directories. If left
-# blank the following patterns are tested:
-# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
-# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py
-
-FILE_PATTERNS          =
-
-# The RECURSIVE tag can be used to turn specify whether or not subdirectories
-# should be searched for input files as well. Possible values are YES and NO.
-# If left blank NO is used.
-
-RECURSIVE              = YES
-
-# The EXCLUDE tag can be used to specify files and/or directories that should
-# excluded from the INPUT source files. This way you can easily exclude a
-# subdirectory from a directory tree whose root is specified with the INPUT tag.
-
-EXCLUDE                =
-
-# The EXCLUDE_SYMLINKS tag can be used select whether or not files or
-# directories that are symbolic links (a Unix filesystem feature) are excluded
-# from the input.
-
-EXCLUDE_SYMLINKS       = NO
-
-# If the value of the INPUT tag contains directories, you can use the
-# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
-# certain files from those directories. Note that the wildcards are matched
-# against the file with absolute path, so to exclude all test directories
-# for example use the pattern */test/*
-
-EXCLUDE_PATTERNS       =
-
-# The EXAMPLE_PATH tag can be used to specify one or more files or
-# directories that contain example code fragments that are included (see
-# the \include command).
-
-EXAMPLE_PATH           =
-
-# If the value of the EXAMPLE_PATH tag contains directories, you can use the
-# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
-# and *.h) to filter out the source-files in the directories. If left
-# blank all files are included.
-
-EXAMPLE_PATTERNS       =
-
-# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
-# searched for input files to be used with the \include or \dontinclude
-# commands irrespective of the value of the RECURSIVE tag.
-# Possible values are YES and NO. If left blank NO is used.
-
-EXAMPLE_RECURSIVE      = NO
-
-# The IMAGE_PATH tag can be used to specify one or more files or
-# directories that contain image that are included in the documentation (see
-# the \image command).
-
-IMAGE_PATH             = imgs/
-
-# The INPUT_FILTER tag can be used to specify a program that doxygen should
-# invoke to filter for each input file. Doxygen will invoke the filter program
-# by executing (via popen()) the command <filter> <input-file>, where <filter>
-# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
-# input file. Doxygen will then use the output that the filter program writes
-# to standard output.  If FILTER_PATTERNS is specified, this tag will be
-# ignored.
-
-INPUT_FILTER           =
-
-# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
-# basis.  Doxygen will compare the file name with each pattern and apply the
-# filter if there is a match.  The filters are a list of the form:
-# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
-# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
-# is applied to all files.
-
-FILTER_PATTERNS        =
-
-# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
-# INPUT_FILTER) will be used to filter the input files when producing source
-# files to browse (i.e. when SOURCE_BROWSER is set to YES).
-
-FILTER_SOURCE_FILES    = NO
-
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-
-# If the SOURCE_BROWSER tag is set to YES then a list of source files will
-# be generated. Documented entities will be cross-referenced with these sources.
-# Note: To get rid of all source code in the generated output, make sure also
-# VERBATIM_HEADERS is set to NO.
-
-SOURCE_BROWSER         = NO
-
-# Setting the INLINE_SOURCES tag to YES will include the body
-# of functions and classes directly in the documentation.
-
-INLINE_SOURCES         = NO
-
-# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
-# doxygen to hide any special comment blocks from generated source code
-# fragments. Normal C and C++ comments will always remain visible.
-
-STRIP_CODE_COMMENTS    = YES
-
-# If the REFERENCED_BY_RELATION tag is set to YES (the default)
-# then for each documented function all documented
-# functions referencing it will be listed.
-
-REFERENCED_BY_RELATION = YES
-
-# If the REFERENCES_RELATION tag is set to YES (the default)
-# then for each documented function all documented entities
-# called/used by that function will be listed.
-
-REFERENCES_RELATION    = YES
-
-# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
-# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
-# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
-# link to the source code.  Otherwise they will link to the documentstion.
-
-REFERENCES_LINK_SOURCE = YES
-
-# If the USE_HTAGS tag is set to YES then the references to source code
-# will point to the HTML generated by the htags(1) tool instead of doxygen
-# built-in source browser. The htags tool is part of GNU's global source
-# tagging system (see http://www.gnu.org/software/global/global.html). You
-# will need version 4.8.6 or higher.
-
-USE_HTAGS              = NO
-
-# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
-# will generate a verbatim copy of the header file for each class for
-# which an include is specified. Set to NO to disable this.
-
-VERBATIM_HEADERS       = YES
-
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-
-# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
-# of all compounds will be generated. Enable this if the project
-# contains a lot of classes, structs, unions or interfaces.
-
-ALPHABETICAL_INDEX     = NO
-
-# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
-# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
-# in which this list will be split (can be a number in the range [1..20])
-
-COLS_IN_ALPHA_INDEX    = 5
-
-# In case all classes in a project start with a common prefix, all
-# classes will be put under the same header in the alphabetical index.
-# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
-# should be ignored while generating the index headers.
-
-IGNORE_PREFIX          =
-
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
-# generate HTML output.
-
-GENERATE_HTML          = YES
-
-# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `html' will be used as the default path.
-
-HTML_OUTPUT            = html
-
-# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
-# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
-# doxygen will generate files with .html extension.
-
-HTML_FILE_EXTENSION    = .html
-
-# The HTML_HEADER tag can be used to specify a personal HTML header for
-# each generated HTML page. If it is left blank doxygen will generate a
-# standard header.
-
-HTML_HEADER            =
-
-# The HTML_FOOTER tag can be used to specify a personal HTML footer for
-# each generated HTML page. If it is left blank doxygen will generate a
-# standard footer.
-
-HTML_FOOTER            =
-
-# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
-# style sheet that is used by each HTML page. It can be used to
-# fine-tune the look of the HTML output. If the tag is left blank doxygen
-# will generate a default style sheet. Note that doxygen will try to copy
-# the style sheet file to the HTML output directory, so don't put your own
-# stylesheet in the HTML output directory as well, or it will be erased!
-
-HTML_STYLESHEET        =
-
-# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
-# files or namespaces will be aligned in HTML using tables. If set to
-# NO a bullet list will be used.
-
-HTML_ALIGN_MEMBERS     = YES
-
-# If the GENERATE_HTMLHELP tag is set to YES, additional index files
-# will be generated that can be used as input for tools like the
-# Microsoft HTML help workshop to generate a compressed HTML help file (.chm)
-# of the generated HTML documentation.
-
-GENERATE_HTMLHELP      = NO
-
-# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
-# be used to specify the file name of the resulting .chm file. You
-# can add a path in front of the file if the result should not be
-# written to the html output directory.
-
-CHM_FILE               =
-
-# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
-# be used to specify the location (absolute path including file name) of
-# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
-# the HTML help compiler on the generated index.hhp.
-
-HHC_LOCATION           =
-
-# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
-# controls if a separate .chi index file is generated (YES) or that
-# it should be included in the master .chm file (NO).
-
-GENERATE_CHI           = NO
-
-# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
-# controls whether a binary table of contents is generated (YES) or a
-# normal table of contents (NO) in the .chm file.
-
-BINARY_TOC             = NO
-
-# The TOC_EXPAND flag can be set to YES to add extra items for group members
-# to the contents of the HTML help documentation and to the tree view.
-
-TOC_EXPAND             = NO
-
-# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
-# top of each HTML page. The value NO (the default) enables the index and
-# the value YES disables it.
-
-DISABLE_INDEX          = NO
-
-# This tag can be used to set the number of enum values (range [1..20])
-# that doxygen will group on one line in the generated HTML documentation.
-
-ENUM_VALUES_PER_LINE   = 4
-
-# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
-# generated containing a tree-like index structure (just like the one that
-# is generated for HTML Help). For this to work a browser that supports
-# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+,
-# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are
-# probably better off using the HTML help feature.
-
-GENERATE_TREEVIEW      = NO
-
-# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
-# used to set the initial width (in pixels) of the frame in which the tree
-# is shown.
-
-TREEVIEW_WIDTH         = 250
-
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
-# generate Latex output.
-
-GENERATE_LATEX         = NO
-
-# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `latex' will be used as the default path.
-
-LATEX_OUTPUT           = latex
-
-# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
-# invoked. If left blank `latex' will be used as the default command name.
-
-LATEX_CMD_NAME         = latex
-
-# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
-# generate index for LaTeX. If left blank `makeindex' will be used as the
-# default command name.
-
-MAKEINDEX_CMD_NAME     = makeindex
-
-# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
-# LaTeX documents. This may be useful for small projects and may help to
-# save some trees in general.
-
-COMPACT_LATEX          = NO
-
-# The PAPER_TYPE tag can be used to set the paper type that is used
-# by the printer. Possible values are: a4, a4wide, letter, legal and
-# executive. If left blank a4wide will be used.
-
-PAPER_TYPE             = a4wide
-
-# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
-# packages that should be included in the LaTeX output.
-
-EXTRA_PACKAGES         =
-
-# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
-# the generated latex document. The header should contain everything until
-# the first chapter. If it is left blank doxygen will generate a
-# standard header. Notice: only use this tag if you know what you are doing!
-
-LATEX_HEADER           =
-
-# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
-# is prepared for conversion to pdf (using ps2pdf). The pdf file will
-# contain links (just like the HTML output) instead of page references
-# This makes the output suitable for online browsing using a pdf viewer.
-
-PDF_HYPERLINKS         = NO
-
-# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
-# plain latex in the generated Makefile. Set this option to YES to get a
-# higher quality PDF documentation.
-
-USE_PDFLATEX           = NO
-
-# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
-# command to the generated LaTeX files. This will instruct LaTeX to keep
-# running if errors occur, instead of asking the user for help.
-# This option is also used when generating formulas in HTML.
-
-LATEX_BATCHMODE        = NO
-
-# If LATEX_HIDE_INDICES is set to YES then doxygen will not
-# include the index chapters (such as File Index, Compound Index, etc.)
-# in the output.
-
-LATEX_HIDE_INDICES     = NO
-
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
-# The RTF output is optimized for Word 97 and may not look very pretty with
-# other RTF readers or editors.
-
-GENERATE_RTF           = NO
-
-# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `rtf' will be used as the default path.
-
-RTF_OUTPUT             = rtf
-
-# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
-# RTF documents. This may be useful for small projects and may help to
-# save some trees in general.
-
-COMPACT_RTF            = NO
-
-# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
-# will contain hyperlink fields. The RTF file will
-# contain links (just like the HTML output) instead of page references.
-# This makes the output suitable for online browsing using WORD or other
-# programs which support those fields.
-# Note: wordpad (write) and others do not support links.
-
-RTF_HYPERLINKS         = NO
-
-# Load stylesheet definitions from file. Syntax is similar to doxygen's
-# config file, i.e. a series of assignments. You only have to provide
-# replacements, missing definitions are set to their default value.
-
-RTF_STYLESHEET_FILE    =
-
-# Set optional variables used in the generation of an rtf document.
-# Syntax is similar to doxygen's config file.
-
-RTF_EXTENSIONS_FILE    =
-
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
-# generate man pages
-
-GENERATE_MAN           = NO
-
-# The MAN_OUTPUT tag is used to specify where the man pages will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `man' will be used as the default path.
-
-MAN_OUTPUT             = man
-
-# The MAN_EXTENSION tag determines the extension that is added to
-# the generated man pages (default is the subroutine's section .3)
-
-MAN_EXTENSION          = .3
-
-# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
-# then it will generate one additional man file for each entity
-# documented in the real man page(s). These additional files
-# only source the real man page, but without them the man command
-# would be unable to find the correct page. The default is NO.
-
-MAN_LINKS              = NO
-
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_XML tag is set to YES Doxygen will
-# generate an XML file that captures the structure of
-# the code including all documentation.
-
-GENERATE_XML           = NO
-
-# The XML_OUTPUT tag is used to specify where the XML pages will be put.
-# If a relative path is entered the value of OUTPUT_DIRECTORY will be
-# put in front of it. If left blank `xml' will be used as the default path.
-
-XML_OUTPUT             = xml
-
-# The XML_SCHEMA tag can be used to specify an XML schema,
-# which can be used by a validating XML parser to check the
-# syntax of the XML files.
-
-XML_SCHEMA             =
-
-# The XML_DTD tag can be used to specify an XML DTD,
-# which can be used by a validating XML parser to check the
-# syntax of the XML files.
-
-XML_DTD                =
-
-# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
-# dump the program listings (including syntax highlighting
-# and cross-referencing information) to the XML output. Note that
-# enabling this will significantly increase the size of the XML output.
-
-XML_PROGRAMLISTING     = YES
-
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
-# generate an AutoGen Definitions (see autogen.sf.net) file
-# that captures the structure of the code including all
-# documentation. Note that this feature is still experimental
-# and incomplete at the moment.
-
-GENERATE_AUTOGEN_DEF   = NO
-
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_PERLMOD tag is set to YES Doxygen will
-# generate a Perl module file that captures the structure of
-# the code including all documentation. Note that this
-# feature is still experimental and incomplete at the
-# moment.
-
-GENERATE_PERLMOD       = NO
-
-# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
-# the necessary Makefile rules, Perl scripts and LaTeX code to be able
-# to generate PDF and DVI output from the Perl module output.
-
-PERLMOD_LATEX          = NO
-
-# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
-# nicely formatted so it can be parsed by a human reader.  This is useful
-# if you want to understand what is going on.  On the other hand, if this
-# tag is set to NO the size of the Perl module output will be much smaller
-# and Perl will parse it just the same.
-
-PERLMOD_PRETTY         = YES
-
-# The names of the make variables in the generated doxyrules.make file
-# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
-# This is useful so different doxyrules.make files included by the same
-# Makefile don't overwrite each other's variables.
-
-PERLMOD_MAKEVAR_PREFIX =
-
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor
-#---------------------------------------------------------------------------
-
-# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
-# evaluate all C-preprocessor directives found in the sources and include
-# files.
-
-ENABLE_PREPROCESSING   = YES
-
-# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
-# names in the source code. If set to NO (the default) only conditional
-# compilation will be performed. Macro expansion can be done in a controlled
-# way by setting EXPAND_ONLY_PREDEF to YES.
-
-MACRO_EXPANSION        = NO
-
-# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
-# then the macro expansion is limited to the macros specified with the
-# PREDEFINED and EXPAND_AS_DEFINED tags.
-
-EXPAND_ONLY_PREDEF     = NO
-
-# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
-# in the INCLUDE_PATH (see below) will be search if a #include is found.
-
-SEARCH_INCLUDES        = YES
-
-# The INCLUDE_PATH tag can be used to specify one or more directories that
-# contain include files that are not input files but should be processed by
-# the preprocessor.
-
-INCLUDE_PATH           =
-
-# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
-# patterns (like *.h and *.hpp) to filter out the header-files in the
-# directories. If left blank, the patterns specified with FILE_PATTERNS will
-# be used.
-
-INCLUDE_FILE_PATTERNS  =
-
-# The PREDEFINED tag can be used to specify one or more macro names that
-# are defined before the preprocessor is started (similar to the -D option of
-# gcc). The argument of the tag is a list of macros of the form: name
-# or name=definition (no spaces). If the definition and the = are
-# omitted =1 is assumed. To prevent a macro definition from being
-# undefined via #undef or recursively expanded use the := operator
-# instead of the = operator.
-
-PREDEFINED             =
-
-# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
-# this tag can be used to specify a list of macro names that should be expanded.
-# The macro definition that is found in the sources will be used.
-# Use the PREDEFINED tag if you want to use a different macro definition.
-
-EXPAND_AS_DEFINED      =
-
-# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
-# doxygen's preprocessor will remove all function-like macros that are alone
-# on a line, have an all uppercase name, and do not end with a semicolon. Such
-# function macros are typically used for boiler-plate code, and will confuse
-# the parser if not removed.
-
-SKIP_FUNCTION_MACROS   = YES
-
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references
-#---------------------------------------------------------------------------
-
-# The TAGFILES option can be used to specify one or more tagfiles.
-# Optionally an initial location of the external documentation
-# can be added for each tagfile. The format of a tag file without
-# this location is as follows:
-#   TAGFILES = file1 file2 ...
-# Adding location for the tag files is done as follows:
-#   TAGFILES = file1=loc1 "file2 = loc2" ...
-# where "loc1" and "loc2" can be relative or absolute paths or
-# URLs. If a location is present for each tag, the installdox tool
-# does not have to be run to correct the links.
-# Note that each tag file must have a unique name
-# (where the name does NOT include the path)
-# If a tag file is not located in the directory in which doxygen
-# is run, you must also specify the path to the tagfile here.
-
-TAGFILES               =
-
-# When a file name is specified after GENERATE_TAGFILE, doxygen will create
-# a tag file that is based on the input files it reads.
-
-GENERATE_TAGFILE       =
-
-# If the ALLEXTERNALS tag is set to YES all external classes will be listed
-# in the class index. If set to NO only the inherited external classes
-# will be listed.
-
-ALLEXTERNALS           = NO
-
-# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
-# in the modules index. If set to NO, only the current project's groups will
-# be listed.
-
-EXTERNAL_GROUPS        = YES
-
-# The PERL_PATH should be the absolute path and name of the perl script
-# interpreter (i.e. the result of `which perl').
-
-PERL_PATH              = /usr/bin/perl
-
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-
-# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
-# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base
-# or super classes. Setting the tag to NO turns the diagrams off. Note that
-# this option is superseded by the HAVE_DOT option below. This is only a
-# fallback. It is recommended to install and use dot, since it yields more
-# powerful graphs.
-
-CLASS_DIAGRAMS         = YES
-
-# If set to YES, the inheritance and collaboration graphs will hide
-# inheritance and usage relations if the target is undocumented
-# or is not a class.
-
-HIDE_UNDOC_RELATIONS   = YES
-
-# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
-# available from the path. This tool is part of Graphviz, a graph visualization
-# toolkit from AT&T and Lucent Bell Labs. The other options in this section
-# have no effect if this option is set to NO (the default)
-
-HAVE_DOT               = YES
-
-# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
-# will generate a graph for each documented class showing the direct and
-# indirect inheritance relations. Setting this tag to YES will force the
-# the CLASS_DIAGRAMS tag to NO.
-
-CLASS_GRAPH            = YES
-
-# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
-# will generate a graph for each documented class showing the direct and
-# indirect implementation dependencies (inheritance, containment, and
-# class references variables) of the class with other documented classes.
-
-COLLABORATION_GRAPH    = YES
-
-# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen
-# will generate a graph for groups, showing the direct groups dependencies
-
-GROUP_GRAPHS           = YES
-
-# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
-# collaboration diagrams in a style similar to the OMG's Unified Modeling
-# Language.
-
-UML_LOOK               = NO
-
-# If set to YES, the inheritance and collaboration graphs will show the
-# relations between templates and their instances.
-
-TEMPLATE_RELATIONS     = NO
-
-# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
-# tags are set to YES then doxygen will generate a graph for each documented
-# file showing the direct and indirect include dependencies of the file with
-# other documented files.
-
-INCLUDE_GRAPH          = YES
-
-# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
-# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
-# documented header file showing the documented files that directly or
-# indirectly include this file.
-
-INCLUDED_BY_GRAPH      = YES
-
-# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will
-# generate a call dependency graph for every global function or class method.
-# Note that enabling this option will significantly increase the time of a run.
-# So in most cases it will be better to enable call graphs for selected
-# functions only using the \callgraph command.
-
-CALL_GRAPH             = YES
-
-# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then doxygen will
-# generate a caller dependency graph for every global function or class method.
-# Note that enabling this option will significantly increase the time of a run.
-# So in most cases it will be better to enable caller graphs for selected
-# functions only using the \callergraph command.
-
-CALLER_GRAPH           = YES
-
-# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
-# will graphical hierarchy of all classes instead of a textual one.
-
-GRAPHICAL_HIERARCHY    = YES
-
-# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES
-# then doxygen will show the dependencies a directory has on other directories
-# in a graphical way. The dependency relations are determined by the #include
-# relations between the files in the directories.
-
-DIRECTORY_GRAPH        = YES
-
-# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
-# generated by dot. Possible values are png, jpg, or gif
-# If left blank png will be used.
-
-DOT_IMAGE_FORMAT       = png
-
-# The tag DOT_PATH can be used to specify the path where the dot tool can be
-# found. If left blank, it is assumed the dot tool can be found in the path.
-
-DOT_PATH               =
-
-# The DOTFILE_DIRS tag can be used to specify one or more directories that
-# contain dot files that are included in the documentation (see the
-# \dotfile command).
-
-DOTFILE_DIRS           =
-
-# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
-# graphs generated by dot. A depth value of 3 means that only nodes reachable
-# from the root by following a path via at most 3 edges will be shown. Nodes
-# that lay further from the root node will be omitted. Note that setting this
-# option to 1 or 2 may greatly reduce the computation time needed for large
-# code bases. Also note that a graph may be further truncated if the graph's
-# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH
-# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default),
-# the graph is not depth-constrained.
-
-MAX_DOT_GRAPH_DEPTH    = 0
-
-# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
-# background. This is disabled by default, which results in a white background.
-# Warning: Depending on the platform used, enabling this option may lead to
-# badly anti-aliased labels on the edges of a graph (i.e. they become hard to
-# read).
-
-DOT_TRANSPARENT        = NO
-
-# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
-# files in one run (i.e. multiple -o and -T options on the command line). This
-# makes dot run faster, but since only newer versions of dot (>1.8.10)
-# support this, this feature is disabled by default.
-
-DOT_MULTI_TARGETS      = NO
-
-# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
-# generate a legend page explaining the meaning of the various boxes and
-# arrows in the dot generated graphs.
-
-GENERATE_LEGEND        = YES
-
-# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
-# remove the intermediate dot files that are used to generate
-# the various graphs.
-
-DOT_CLEANUP            = YES
-
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine
-#---------------------------------------------------------------------------
-
-# The SEARCHENGINE tag specifies whether or not a search engine should be
-# used. If set to NO the values of all tags below this one will be ignored.
-
-SEARCHENGINE           = NO
diff --git a/src/Makefile.am b/src/Makefile.am
index 0de0683..491c97d 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -19,18 +19,7 @@ libdlo_la_SOURCES = \
 	dlo_usb.c  \
 	libdlo.c
 
-libdlo_la_LDFLAGS = \
-	-version-info $(LIBDLO_LT_CURRENT):$(LIBDLO_LT_REVISION):$(LIBDLO_LT_AGE) \
-	-export-symbols exported_symbols
-
-pkgconfigdir = $(prefix)/$(libdir_name)/pkgconfig
-pkgconfig_DATA = libdlo.pc
-
-EXTRA_DIST = \
-	exported_symbols
-
-# keep autotools from complaining there is no NEWS file
-AUTOMAKE_OPTIONS = foreign
-
-ACLOCAL_AMFLAGS = -I m4
+# here in the early use of the library, set DEBUG on to get better runtime info
+libdlo_la_CFLAGS = -DDEBUG
+libdlo_la_LDFLAGS = -lusb
 
diff --git a/src/dlo_usb.c b/src/dlo_usb.c
index fe5965f..71d83d0 100644
--- a/src/dlo_usb.c
+++ b/src/dlo_usb.c
@@ -119,10 +119,7 @@ static dlo_retcode_t usb_error_grab(void);
 

 char *dlo_usb_strerror(void)

 {

-  /* These two are published by libusb */

-  usb_error_type  = USB_ERROR_TYPE_ERRNO;

-  usb_error_errno = usberr;

-  DPRINTF("usb: error lookup %d\n", usberr);

+  //DPRINTF("usb: error lookup %d\n", usberr);

   return usb_err_str;

 }

 

@@ -149,13 +146,13 @@ dlo_retcode_t dlo_usb_final(const dlo_final_t flags)
   return dlo_ok;

 }

 

-

 dlo_retcode_t dlo_usb_enumerate(const bool init)

 {

   struct usb_bus    *bus;

   struct usb_device *dev = NULL;

   int32_t            db  = usb_find_busses();

   int32_t            dd  = usb_find_devices();

+  DPRINTF("usb: dlo_usb_enumerate\n");

 

   /* We should do this even if it looks like there are no changes on the bus because

    * an open() call might call the above functions just to check it's safe to use the

@@ -168,13 +165,124 @@ dlo_retcode_t dlo_usb_enumerate(const bool init)
    */

   IGNORE(db);

   IGNORE(dd);

-

+  

   /* Look for all DisplayLink devices on the USB busses */

-  for (bus = usb_busses; bus; bus = bus->next)

-    for (dev = bus->devices; dev; dev = dev->next)

+  for (bus = usb_get_busses(); bus; bus = bus->next) 

+    for (dev = bus->devices; dev; dev = dev->next) 

       ERR(check_device(dev)); /* Check to see if it's a DisplayLink device. If it is, add to or update the dev_list */

+  

+  return dlo_ok;

+}

+

+

+static dlo_retcode_t check_device(struct usb_device *udev)

+{

+  static char     string[255];

+  usb_dev_handle *uhand    = usb_open(udev);

+  dlo_retcode_t   err      = dlo_ok;

+  dlo_device_t   *dev      = NULL;

+  bool            not_root = false;

+  uint8_t         buf[4];

+  dlo_devtype_t   type;

+

+  //DPRINTF("usb: check: check dev &%X\n", (int)dev);

+

+  if (!uhand) {

+    // this may not be our device. We just can't open it

+    return dlo_ok;

+  }

+  

+  //DPRINTF("usb: check: uhand &%X vendorID &%X\n", (int)uhand, udev->descriptor.idVendor);

+

+  /* Reject devices that don't have the DisplayLink VendorID */

+  if (udev->descriptor.idVendor != VENDORID_DISPLAYLINK)

+  {

+    UERR(usb_close(uhand));

+    return dlo_ok;

+  }

+  //DPRINTF("usb: check: get type\n");

+

+  /* Ask the device for some status information */

+  not_root = true; /* Special case error handling here */

+  UERR_GOTO(usb_control_msg(/* handle */      uhand,

+                            /* requestType */ USB_ENDPOINT_IN | USB_TYPE_VENDOR,

+                            /* request */     NR_USB_REQUEST_STATUS_DW,

+                            /* value */       0,

+                            /* index */       0,

+                            /* bytes */       (char *)buf,

+                            /* size */        sizeof(buf),

+                            /* timeout */     ID_TIMEOUT));

+  not_root = false; /* Back to normal error handling */

+  //DPRINTF("usb: check: type buf[3] = &%X\n", buf[3]);

+

+  /* Determine what type of device we are connected to */

+  switch ((buf[3] >> 4) & 0xF)

+  {

+    case dlo_dev_base:

+      type = dlo_dev_base;

+      break;

+    case dlo_dev_alex:

+      type = dlo_dev_alex;

+      break;

+    default:

+      if (buf[3] == dlo_dev_ollie)

+        type = dlo_dev_ollie;

+      else

+        type = dlo_dev_unknown;

+  }

+

+  /* Read the device serial number as a string */

+  UERR_GOTO(usb_get_string_simple(uhand, udev->descriptor.iSerialNumber, string, sizeof(string)));

+  //DPRINTF("usb: check: type &%X serial '%s'\n", (int)type, string);

+

+  /* See if this device is already in our device list */

+  dev = dlo_device_lookup(string);

+  if (dev)

+  {

+    /* Use this opportunity to update the USB device structure pointer, just in

+     * case it has moved.

+     */

+    dev->cnct->udev = udev;

+    //DPRINTF("usb: check: already in list\n");

+  }

+  else

+  {

+    /* Add a new device to the device list */

+    //DPRINTF("usb: check: create new device\n");

+    dev = dlo_new_device(type, string);

+    NERR_GOTO(dev);

+

+    /* It's not. Create and initialise a new list node for the device */

+    dev->cnct = (dlo_usb_dev_t *)dlo_malloc(sizeof(dlo_usb_dev_t));

+    NERR_GOTO(dev->cnct);

+    dev->cnct->udev = udev;

+    dev->cnct->uhand = NULL;

+  }

+  //DPRINTF("usb: check: dlpp node &%X\n", (int)dev);

+

+  /* Close our temporary handle for the device. If this errors, we'll have a duff entry in

+   * the device list but at least the list integrity will be OK.

+   */

+  UERR_GOTO(usb_close(uhand));

 

   return dlo_ok;

+

+error:

+  /* Free our dev->cnct USB information structure */

+  if (dev->cnct)

+    dlo_free(dev->cnct);

+  dev->cnct = NULL;

+

+  /* Close our temporary handle for the device */

+  (void) usb_close(uhand);

+

+  /* If the executable wasn't run as root, this is where it normally falls over.

+   * So we'll special case that particular error to help indicate this problem.

+   */

+  if (not_root)

+    return dlo_err_not_root;

+

+  return err;

 }

 

 

@@ -182,6 +290,7 @@ dlo_retcode_t dlo_usb_open(dlo_device_t * const dev)
 {

   dlo_retcode_t   err;

   usb_dev_handle *uhand;

+  int             usb_configuration;

   int32_t         db = usb_find_busses();

   int32_t         dd = usb_find_devices();

 

@@ -201,9 +310,19 @@ dlo_retcode_t dlo_usb_open(dlo_device_t * const dev)
 

   /* Establish the connection with the device */

   //DPRINTF("usb: open: setting config...\n");

+

+  /* set configuration fails on composite devices, 

+   * such as 1st gen HP USB 2.0 docks.

+   * With libusb 1.0, we could at least only set

+   * configuration when necessary, but only partial 

+   * mitigation. Need full solution.

+   */

+  //usb_configuration = usb_get_configuration(uhand);

+  //if (usb_configuration != 1) 

   UERR(usb_set_configuration(uhand, 1));

 

   //DPRINTF("usb: open: claiming iface...\n");

+  // TODO: shouldn't assume iface 0

   UERR(usb_claim_interface(uhand, 0));

 

   /* Mark the device as claimed */

@@ -378,114 +497,6 @@ static dlo_retcode_t usb_error_grab(void)
 }

 

 

-static dlo_retcode_t check_device(struct usb_device *udev)

-{

-  static char     string[255];

-  usb_dev_handle *uhand    = usb_open(udev);

-  dlo_retcode_t   err      = dlo_ok;

-  dlo_device_t   *dev      = NULL;

-  bool            not_root = false;

-  uint8_t         buf[4];

-  dlo_devtype_t   type;

-

-  //DPRINTF("usb: check: check dev &%X\n", (int)dev);

-

-  if (!uhand)

-    return dlo_err_open;

-

-  //DPRINTF("usb: check: uhand &%X vendorID &%X\n", (int)uhand, udev->descriptor.idVendor);

-

-  /* Reject devices that don't have the DisplayLink VendorID */

-  if (udev->descriptor.idVendor != VENDORID_DISPLAYLINK)

-  {

-    UERR(usb_close(uhand));

-    return dlo_ok;

-  }

-  //DPRINTF("usb: check: get type\n");

-

-  /* Ask the device for some status information */

-  not_root = true; /* Special case error handling here */

-  UERR_GOTO(usb_control_msg(/* handle */      uhand,

-                            /* requestType */ USB_ENDPOINT_IN | USB_TYPE_VENDOR,

-                            /* request */     NR_USB_REQUEST_STATUS_DW,

-                            /* value */       0,

-                            /* index */       0,

-                            /* bytes */       (char *)buf,

-                            /* size */        sizeof(buf),

-                            /* timeout */     ID_TIMEOUT));

-  not_root = false; /* Back to normal error handling */

-  //DPRINTF("usb: check: type buf[3] = &%X\n", buf[3]);

-

-  /* Determine what type of device we are connected to */

-  switch ((buf[3] >> 4) & 0xF)

-  {

-    case dlo_dev_base:

-      type = dlo_dev_base;

-      break;

-    case dlo_dev_alex:

-      type = dlo_dev_alex;

-      break;

-    default:

-      if (buf[3] == dlo_dev_ollie)

-        type = dlo_dev_ollie;

-      else

-        type = dlo_dev_unknown;

-  }

-

-  /* Read the device serial number as a string */

-  UERR_GOTO(usb_get_string_simple(uhand, udev->descriptor.iSerialNumber, string, sizeof(string)));

-  //DPRINTF("usb: check: type &%X serial '%s'\n", (int)type, string);

-

-  /* See if this device is already in our device list */

-  dev = dlo_device_lookup(string);

-  if (dev)

-  {

-    /* Use this opportunity to update the USB device structure pointer, just in

-     * case it has moved.

-     */

-    dev->cnct->udev = udev;

-    //DPRINTF("usb: check: already in list\n");

-  }

-  else

-  {

-    /* Add a new device to the device list */

-    //DPRINTF("usb: check: create new device\n");

-    dev = dlo_new_device(type, string);

-    NERR_GOTO(dev);

-

-    /* It's not. Create and initialise a new list node for the device */

-    dev->cnct = (dlo_usb_dev_t *)dlo_malloc(sizeof(dlo_usb_dev_t));

-    NERR_GOTO(dev->cnct);

-    dev->cnct->udev = udev;

-    dev->cnct->uhand = NULL;

-  }

-  //DPRINTF("usb: check: dlpp node &%X\n", (int)dev);

-

-  /* Close our temporary handle for the device. If this errors, we'll have a duff entry in

-   * the device list but at least the list integrity will be OK.

-   */

-  UERR_GOTO(usb_close(uhand));

-

-  return dlo_ok;

-

-error:

-  /* Free our dev->cnct USB information structure */

-  if (dev->cnct)

-    dlo_free(dev->cnct);

-  dev->cnct = NULL;

-

-  /* Close our temporary handle for the device */

-  (void) usb_close(uhand);

-

-  /* If the executable wasn't run as root, this is where it normally falls over.

-   * So we'll special case that particular error to help indicate this problem.

-   */

-  if (not_root)

-    return dlo_err_not_root;

-

-  return err;

-}

-

 

 static dlo_retcode_t read_edid(dlo_device_t * const dev, usb_dev_handle *uhand)

 {

diff --git a/src/libdlo.c b/src/libdlo.c
index 2ddb3b6..12e6f33 100644
--- a/src/libdlo.c
+++ b/src/libdlo.c
@@ -331,7 +331,7 @@ dlo_devlist_t *dlo_enumerate_devices(void)
    * reason, after any error, we throw away all unclaimed devices from the devlist to try to

    * minimise the chances.

    */

-  // DPRINTF("dlo: enum: enumerating USB devices\n");

+  //DPRINTF("dlo: enum: enumerating USB devices\n");

   ERR_GOTO(dlo_usb_enumerate(false));

 

   /* Remove all devices which weren't updated or added during this enumeration and

@@ -427,6 +427,8 @@ dlo_dev_t dlo_claim_device(const dlo_dev_t uid, const dlo_claim_t flags, const u
   err = dlo_usb_open(dev);

   while (err == dlo_err_reenum)

   {

+    DPRINTF("dlo_usb_open failed with dlo_err_reenum. Retry\n");

+

     /* If the USB bus devices have changed, do the enumeration again */

     dlo_devlist_t *out = dlo_enumerate_devices();

 

@@ -473,19 +475,23 @@ dlo_dev_t dlo_claim_first_device(const dlo_claim_t flags, const uint32_t timeout
 

   /* Look for a DisplayLink device to connect to - note the first one which is unclaimed */

   node = dlo_enumerate_devices();

+  

+  // dlo_enumerate_devices allocates memory for each node, which we must free

   while (node)

   {

     dlo_device_t *dev = (dlo_device_t *)node->dev.uid;

 

     if (!uid && !dev->claimed)

-      uid = node->dev.uid;

+    {

+      uid = dlo_claim_device(node->dev.uid, flags, timeout);

+    }

 

-    /* Free this list node and move on to the next one */

+    /* If we haven't claimed a device, move on to the next one */

     next = node->next;

     dlo_free(node);

     node = next;

   }

-  return uid ? dlo_claim_device(uid, flags, timeout) : (dlo_dev_t)0;

+  return uid;

 }

 

 

@@ -723,11 +729,11 @@ dlo_device_t *dlo_device_lookup(const char * const serial)
 {

   dlo_device_t *dev = dev_list;

 

-  DPRINTF("dlo: lookup: '%s' dev_list &%X\n", serial, (int)dev_list);

+  //DPRINTF("dlo: lookup: '%s' dev_list &%X\n", serial, (int)dev_list);

 

   while (dev)

   {

-    DPRINTF("dlo: lookup: dev &%X serial '%s'\n", (int)dev, dev->serial);

+    //DPRINTF("dlo: lookup: dev &%X serial '%s'\n", (int)dev, dev->serial);

     if (0 == strcmp(dev->serial, serial))

     {

       dev->check = check_state;

diff --git a/test/test1/Makefile.am b/test/test1/Makefile.am
index cb2d0f2..0a8fe23 100644
--- a/test/test1/Makefile.am
+++ b/test/test1/Makefile.am
@@ -1,2 +1,4 @@
 bin_PROGRAMS = test1
-test1_SOURCES = test1.c
\ No newline at end of file
+test1_SOURCES = test1.c
+test1_LDADD = ../../src/libdlo.la
+test1_LDFLAGS = -lusb
\ No newline at end of file
diff --git a/test/test1/test1.c b/test/test1/test1.c
index 9c1b2ea..071764d 100644
--- a/test/test1/test1.c
+++ b/test/test1/test1.c
@@ -1,937 +1,944 @@
-/** @file test1.c

- *

- *  @brief This file demonstrates basic graphics primitive features of libdlo.

- *

- *  DisplayLink Open Source Software (libdlo)

- *  Copyright (C) 2009, DisplayLink

- *  www.displaylink.com

- *

- *  This library is free software; you can redistribute it and/or modify it under

- *  the terms of the GNU Library General Public License as published by the Free

- *  Software Foundation; LGPL version 2, dated June 1991.

- *

- *  This library 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 Library General Public License for more

- *  details.

- *

- *  You should have received a copy of the GNU Library General Public License

- *  along with this library; if not, write to the Free Software Foundation, Inc.,

- *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

- */

-

-#include <stdio.h>

-#include <string.h>

-#include <time.h>

-

-#include "sys/time.h"

-#include "libdlo.h"

-#include "dlo_defs.h"

-

-

-/** Default horizontal resolution we will use for tests (pixels).

- */

-#define SCREEN_X (1280)

-

-/** Default vertical resolution we will use for tests (pixels).

- */

-#define SCREEN_Y (1024)

-

-/** Default screen refresh rate we will use for tests (Hz).

- */

-#define SCREEN_RATE (0)

-

-/** Default screen colour depth we will use for tests (bits per pixel).

- */

-#define SCREEN_BPP (24)

-

-/** Number of random dots to plot.

- */

-#define NUM_DOTS (299)

-

-/** Number of random rectangles to plot.

- */

-#define NUM_RECTS (99)

-

-/** Number of steps (gradient) in colour blended rectangles.

- */

-#define NUM_GRAD (99)

-

-/** Division factor for scale of central rectangle.

- */

-#define MID_REC_DIV (5)

-

-/** Windows BMP magic ID bytes.

- */

-#define BMP_MAGIC (0x4D42)

-

-/** Given a bits per pixel value, return the bytes per pixel.

- */

-#define BYTES_PER_PIXEL(bpp) (unsigned int)(((bpp) + 7) / 8)

-

-/** Horizontal subdivision of the screen for overlapping rectangle copy tests.

- */

-#define ZONE_X (SCREEN_X / 3)

-

-/** Vertical subdivision of the screen for overlapping rectangle copy tests.

- */

-#define ZONE_Y (SCREEN_Y / 3)

-

-/** Horizontal size of the rectangle to copy in the overlapping rectangle copy tests.

- */

-#define COPY_X (ZONE_X / 2)

-

-/** Vertical size of the rectangle to copy in the overlapping rectangle copy tests.

- */

-#define COPY_Y (ZONE_Y / 2)

-

-/** Size of a component of a rectangle copy offset (horizontal or vertical).

- */

-#define STEP (80)

-

-

-/** Array of offsets for overlapping rectangle copy test.

- */

-const dlo_dot_t overlap[9] =

-{

-  { -STEP, -STEP },

-  {     0, -STEP },

-  {  STEP, -STEP },

-  { -STEP,     0 },

-  {     0,     0 },

-  {  STEP,     0 },

-  { -STEP,  STEP },

-  {     0,  STEP },

-  {  STEP,  STEP }

-};

-

-

-/** The main header block from a Windows BMP file.

- */

-typedef struct __packed bmp_header_s

-{

-  uint16_t magic;          /**< Magic ID bytes for Windows BMP format. */

-  uint32_t file_sz;        /**< Total bitmap file size (bytes). */

-  uint16_t reserved1;      /**< Unused. */

-  uint16_t reserved2;      /**< Unused. */

-  uint32_t pix_offset;     /**< Offset from start of file to start of pixel data (bytes). */

-} bmp_header_t;            /**< A struct @a bmp_header_s. */

-

-

-/** The DIB header block from a Windows BMP file.

- */

-typedef struct __packed dib_header_s

-{

-  uint32_t dib_hdr_sz;     /**< Size of the DIB header block (bytes). */

-  uint32_t width;          /**< Width of the bitmap (pixels). */

-  uint32_t height;         /**< Height of the bitmap (pixels). */

-  uint16_t col_planes;     /**< Number of colour planes. */

-  uint16_t bpp;            /**< Bits per pixel. */

-  uint32_t compression;    /**< Compression, pixel format. */

-  uint32_t raw_size;       /**< Size of the raw pixel data. */

-  uint32_t x_pix_meter;    /**< Horizontal resolution (pixels per meter). */

-  uint32_t y_pix_meter;    /**< Vertical resolution (pixels per meter). */

-  uint32_t pal_entries;    /**< Number of palette entries. */

-  uint32_t imp_cols;       /**< Important colours (ignored). */

-} dib_header_t;            /**< A struct @a dib_header_s. */

-

-

-/** A Windows BMP file.

- */

-typedef struct __packed bmp_s

-{

-  bmp_header_t hdr;        /**< Windows BMP header block. */

-  dib_header_t dib;        /**< DIB header block. */

-  uint8_t      data[];     /**< Pixel data. */

-} bmp_t;                   /**< A struct @a bmp_s. */

-

-

-/** Report an error and exit.

- *

- *  @param  str  Pointer to the error message string.

- */

-static void my_error(const char * const str)

-{

-  printf("test: ERROR: %s\n", str);

-  exit(1);

-}

-

-

-/** Return the microsecond time, as an unsigned 64 bit integer.

- *

- *  @return  Number of microseconds since the start of the Epoch.

- */

-static uint64_t now(void)

-{

-  static struct timeval  unix_time     = { 0 };

-  static struct timeval *unix_time_ptr = &unix_time;

-

-  gettimeofday(unix_time_ptr, NULL);

-  return ((uint64_t)unix_time.tv_sec * 1000000ll) + (uint64_t)unix_time.tv_usec;

-}

-

-

-/** Pause execution for the specified number of centiseconds.

- *

- *  @param  from      Time to start the pause interval.

- *  @param  millisec  Number of milliseconds to pause for.

- */

-static void wait_ms(const uint64_t from, const uint64_t millisec)

-{

-  uint64_t to = from + (millisec * 1000);

-

-  while (to > now()) ;

-}

-

-

-/** Plot a rectangular outline in the specified colour.

- *

- *  @param  uid   Unique ID of the device.

- *  @param  view  Viewport for plot destination.

- *  @param  rec   Rectangle co-ordinates within the viewport.

- *  @param  col   Colour of rectangle.

- *

- *  @return  Return code, zero for no error.

- */

-static dlo_retcode_t box(const dlo_dev_t uid, const dlo_view_t * const view, const dlo_rect_t * const rec, const dlo_col32_t col)

-{

-  dlo_rect_t line;

-

-  line.origin.x = rec->origin.x;

-  line.origin.y = rec->origin.y;

-  line.width    = rec->width;

-  line.height   = 1;

-  ERR(dlo_fill_rect(uid, view, &line, col));

-

-  line.width    = 1;

-  line.height   = rec->height;

-  ERR(dlo_fill_rect(uid, view, &line, col));

-

-  line.origin.y += line.height - 1;

-  line.width     = rec->width;

-  line.height    = 1;

-  ERR(dlo_fill_rect(uid, view, &line, col));

-

-  line.origin.x += line.width;

-  line.origin.y  = rec->origin.y;

-  line.width     = 1;

-  line.height    = rec->height;

-  ERR(dlo_fill_rect(uid, view, &line, col));

-

-  return dlo_ok;

-}

-

-

-/** Test the basic graphics primitives (filled rectangle and rectangle copy).

- *

- *  @param  uid  Unique ID of the device.

- *

- *  @return  Return code, zero for no error.

- */

-static dlo_retcode_t basic_grfx_test(const dlo_dev_t uid)

-{

-  dlo_mode_t     mode;

-  dlo_mode_t    *mode_info;

-  dlo_devinfo_t *dev_info;

-  dlo_view_t    *view;

-  dlo_rect_t      rec;

-  dlo_dot_t      dot;

-  uint32_t        i;

-  uint64_t        start;

-

-  /* Read some information on the device */

-  dev_info = dlo_device_info(uid);

-  NERR(dev_info);

-  printf("test: device info: uid &%X\n", (int)dev_info->uid);

-  printf("test: device info: serial '%s'\n", dev_info->serial);

-  printf("test: device info: type  &%X\n", (uint32_t)dev_info->type);

-

-  /* Read current mode information (if we're already in the display's native mode) */

-  mode_info = dlo_get_mode(uid);

-  NERR(mode_info);

-  printf("test: native mode info...\n");

-  printf("  %ux%u @ %u Hz %u bpp base &%X\n", mode_info->view.width, mode_info->view.height, mode_info->refresh, mode_info->view.bpp, (int)mode_info->view.base);

-

-  /* Select a fairly standard mode */

-  printf("test: set_mode...\n");

-  mode.view.width  = SCREEN_X;

-  mode.view.height = SCREEN_Y;

-  mode.view.bpp    = SCREEN_BPP;

-  mode.view.base   = 0;

-  mode.refresh     = SCREEN_RATE;

-  ERR(dlo_set_mode(uid, &mode));

-

-  /* Read current mode information */

-  mode_info = dlo_get_mode(uid);

-  NERR(mode_info);

-  printf("test: mode info...\n");

-  printf("  %ux%u @ %u Hz %u bpp base &%X\n", mode_info->view.width, mode_info->view.height, mode_info->refresh, mode_info->view.bpp, (int)mode_info->view.base);

-  view = &(mode_info->view);

-

-  /* Clear screen */

-  printf("test: cls...");

-  start = now();

-  ERR(dlo_fill_rect(uid, NULL, NULL, DLO_RGB(0, 0, 0)));

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Plot some random white dots */

-  printf("test: random white dots...");

-  start      = now();

-  rec.width  = 1;

-  rec.height = 1;

-  for (i = 0; i < NUM_DOTS; i++)

-  {

-    rec.origin.x = rand() % view->width;

-    rec.origin.y = rand() % view->height;

-    ERR(dlo_fill_rect(uid, view, &rec, DLO_RGB(0xFF, 0xFF, 0xFF)));

-  }

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Plot random filled rectangles */

-  printf("test: random rectangles...");

-  start = now();

-  for (i = 0; i < NUM_RECTS; i++)

-  {

-    rec.width    = rand() % (view->width  / 4);

-    rec.height   = rand() % (view->height / 4);

-    rec.origin.x = (rand() % (uint32_t)(1.25 * view->width))  - (view->width  / 8);

-    rec.origin.y = (rand() % (uint32_t)(1.25 * view->height)) - (view->height / 8);

-    ERR(dlo_fill_rect(uid, view, &rec, DLO_RGB(rand() % 0xFF, rand() % 0xFF, rand() % 0xFF)));

-  }

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Plot a set of rectangles, one over the other (colour gradient) */

-  printf("test: central rectangles...");

-  start = now();

-  for (i = 0; i < NUM_GRAD; i++)

-  {

-    dlo_col32_t col = DLO_RGB((i*3) % 256, (i*5) % 256, 255 - ((i*7) % 256));

-

-    rec.width    = (view->width  / MID_REC_DIV) - 2*i;

-    rec.height   = (view->height / MID_REC_DIV) - 2*i;

-    rec.origin.x = i + (view->width  / 2) - (view->width / MID_REC_DIV / 2);

-    rec.origin.y = i + (view->height / 2) - (view->height/ MID_REC_DIV / 2);

-    ERR(dlo_fill_rect(uid, view, &rec, col));

-  }

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Plot the outline of the box we're going to copy */

-  printf("test: white box outline...");

-  start = now();

-  rec.width    = view->width  / MID_REC_DIV;

-  rec.height   = view->height / MID_REC_DIV;

-  rec.origin.x = (view->width  / 2) - (rec.width  / 2);

-  rec.origin.y = (view->height / 2) - (rec.height / 2);

-  ERR(box(uid, view, &rec, DLO_RGB(0xFF, 0xFF, 0xFF)));

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Copy a rectangle from the centre of the screen to other locations */

-  printf("test: copy central box...");

-  start = now();

-  rec.origin.x++;

-  rec.origin.y++;

-  rec.width  -= 2;

-  rec.height -= 2;

-  dot.x       = 8;

-  dot.y       = 8;

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  dot.x = view->width - 8 - rec.width;

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  dot.y = view->height - 8 - rec.height;

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  dot.x = 8;

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Check that basic clipping works */

-  printf("test: copy central box (off edges of viewport)...");

-  start = now();

-  dot.x = -(rec.width / 2);

-  dot.y = (view->height / 2) - (rec.height / 2) - 32;

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  dot.x += view->width;

-  dot.y += 64;

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  dot.x = (view->width / 2) - (rec.width / 2) - 128;

-  dot.y = -(rec.height / 2);

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  dot.x += 256;

-  dot.y += view->height;

-  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  return dlo_ok;

-}

-

-

-/** Plot a few coloured rectangles one above another.

- *

- *  @param  uid    Unique ID of the device.

- *  @param  inrec  Input rectangle (the outer bounding box of the design).

- *

- *  @return  Return code, zero for no error.

- */

-static dlo_retcode_t squares(const dlo_dev_t uid, const dlo_rect_t * const inrec)

-{

-  dlo_rect_t rec = *inrec;

-

-  /* Plot the outer (red) rectangle */

-  ERR(dlo_fill_rect(uid, NULL, &rec, DLO_RGB(0xCC, 0, 0)));

-

-  /* Plot the middle (white) rectangle */

-  rec.origin.x += 20;

-  rec.origin.y += 20;

-  rec.width    -= 40;

-  rec.height   -= 40;

-  ERR(dlo_fill_rect(uid, NULL, &rec, DLO_RGB(0xCC, 0xCC, 0xCC)));

-

-  /* Plot the inner (blue) rectangle */

-  rec.origin.x += 20;

-  rec.origin.y += 20;

-  rec.width    -= 40;

-  rec.height   -= 40;

-

-  return dlo_fill_rect(uid, NULL, &rec, DLO_RGB(0, 0, 0xCC));

-}

-

-

-/** Test copying rectangles to and from overlapping regions (in various directions).

- *

- *  @param  uid  Unique ID of the device.

- *

- *  @return  Return code, zero for no error.

- */

-static dlo_retcode_t overlap_test(const dlo_dev_t uid)

-{

-  dlo_rect_t rec;

-  dlo_dot_t mid, dot;

-  uint32_t   idx = 0;

-

-  /* Clear screen to black */

-  ERR(dlo_fill_rect(uid, NULL, NULL, DLO_RGB(0, 0, 0)));

-

-  rec.width  = COPY_X;

-  rec.height = COPY_Y;

-  for (mid.y = ZONE_Y / 2; mid.y < SCREEN_Y; mid.y += ZONE_Y)

-  {

-    for (mid.x = ZONE_X / 2; mid.x < SCREEN_X; mid.x += ZONE_X)

-    {

-      rec.origin.x = mid.x - (COPY_X / 2);

-      rec.origin.y = mid.y - (COPY_Y / 2);

-      dot.x        = rec.origin.x + overlap[idx].x;

-      dot.y        = rec.origin.y + overlap[idx].y;

-      idx++;

-      ERR(squares(uid, &rec));

-      ERR(dlo_copy_rect(uid, NULL, &rec, NULL, &dot));

-    }

-  }

-  return dlo_ok;

-}

-

-

-/** Convert a bits per pixel value into a bytes per pixel value.

- *

- *  @param  bpp  Bits per pixel.

- *

- *  @return  Bytes per pixel.

- */

-static uint8_t bpp_to_bytes(const uint32_t bpp)

-{

-  return (uint8_t)((bpp + 7) / 8);

-}

-

-

-/** Test the use of viewports as screen banks (ensure clipping is working).

- *

- *  @param  uid  Unique ID of the device.

- *

- *  @return  Return code, zero for no error.

- *

- *  Create three viewports (screen banks) and switch the display between them.

- *  While we're at it, test the filled rectangle plotting clips correctly and

- *  doesn't overflow into surrounding screen banks or off the edges of the

- *  screen.

- */

-static dlo_retcode_t viewport_test(const dlo_dev_t uid)

-{

-  dlo_mode_t  mode;

-  dlo_mode_t *desc;

-  dlo_view_t  view[3];

-  dlo_rect_t   rec;

-  uint32_t     i;

-  uint64_t     start;

-

-  /* Read current mode information */

-  desc = dlo_get_mode(uid);

-  NERR(desc);

-

-  /* Create three viewports - each representing a screen bank */

-  view[0]      = desc->view;

-  view[1]      = view[0];

-  view[1].base = view[0].base + (view[1].width * view[1].height * bpp_to_bytes(view[1].bpp));

-  view[2]      = view[1];

-  view[2].base = view[1].base + (view[2].width * view[2].height * bpp_to_bytes(view[2].bpp));

-

-  /* Clear screens to different colours */

-  printf("test: cls (three banks)...");

-  start = now();

-  ERR(dlo_fill_rect(uid, NULL,     NULL, DLO_RGB(0, 0, 0xFF)));

-  ERR(dlo_fill_rect(uid, &view[1], NULL, DLO_RGB(0, 0xFF, 0)));

-  ERR(dlo_fill_rect(uid, &view[2], NULL, DLO_RGB(0xFF, 0, 0)));

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Plot a couple of rectangles in each bank to test the clipping */

-  printf("test: plot crosses (three banks)...");

-  start = now();

-  rec.width    = view[0].width / 8;

-  rec.height   = view[0].height * 1.5;

-  rec.origin.x = (view[0].width / 2) - (rec.width / 2);

-  rec.origin.y = -(view[0].height / 4);

-  ERR(dlo_fill_rect(uid, NULL,     &rec, DLO_RGB(0, 0xFF, 0xFF)));

-  ERR(dlo_fill_rect(uid, &view[1], &rec, DLO_RGB(0xFF, 0xFF, 0)));

-  ERR(dlo_fill_rect(uid, &view[2], &rec, DLO_RGB(0xFF, 0, 0xFF)));

-  rec.width    = view[0].width * 1.5;

-  rec.height   = view[0].height / 8;

-  rec.origin.x = -(view[0].width / 4);

-  rec.origin.y = (view[0].height / 2) - (rec.height / 2);

-  ERR(dlo_fill_rect(uid, NULL,     &rec, DLO_RGB(0, 0xFF, 0xFF)));

-  ERR(dlo_fill_rect(uid, &view[1], &rec, DLO_RGB(0xFF, 0xFF, 0)));

-  ERR(dlo_fill_rect(uid, &view[2], &rec, DLO_RGB(0xFF, 0, 0xFF)));

-  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);

-

-  /* Switch through the screen banks */

-  for (i = 1; i < 4; i++)

-  {

-    wait_ms(now(), 1000);

-

-    printf("test: switching to screen bank %u...\n", i % 3);

-    mode.view.width  = view[i % 3].width;

-    mode.view.height = view[i % 3].height;

-    mode.view.bpp    = view[i % 3].bpp;

-    mode.view.base   = view[i % 3].base;

-    mode.refresh     = 0;

-    ERR(dlo_set_mode(uid, &mode));

-  }

-

-  return dlo_ok;

-}

-

-

-/** Load a Windows BMP file into memory.

- *

- *  @param  bmpfile  Pointer to the filename.

- *

- *  @return  Pointer to the loaded bitmap's structure (or NULL if failed).

- *

- *  Load a bitmap from a file and create a @a dlo_fbuf_t structure to suit.

- *  If the bitmap has a palette, we need to swap the red/blue order of the

- *  colour components in order to convert the palette entries into

- *  @a dlo_col32_t values.

- */

-static bmp_t *load_bmp(const char * const bmpfile)

-{

-  long int      size;

-  bmp_t        *bmp;

-  FILE         *fp;

-

-  fp = fopen(bmpfile, "rb");

-  if (!fp)

-    return NULL;

-

-  if (fseek(fp, 0, SEEK_END))

-    return NULL;

-

-  size = ftell(fp);

-  if (size == -1L)

-    return NULL;

-

-  if (fseek(fp, 0, SEEK_SET))

-    return NULL;

-

-  bmp = malloc(size);

-  if (!bmp)

-    return NULL;

-

-  if (1 != fread(bmp, size, 1, fp))

-    goto error;

-

-  if (bmp->hdr.magic != BMP_MAGIC)

-    goto error;

-

-  /* If there is a palette, we need to reverse the RGB component order */

-  if (bmp->dib.pal_entries)

-  {

-    dlo_col32_t *palette;

-    uint32_t      i;

-

-    palette = (dlo_col32_t *)((unsigned long)bmp + sizeof(bmp_header_t) + sizeof(dib_header_t));

-

-    for (i = 0; i < bmp->dib.pal_entries; i++)

-    {

-      dlo_col32_t col = palette[i];

-

-      palette[i] = DLO_RGB(DLO_RGB_GETBLU(col), DLO_RGB_GETGRN(col), DLO_RGB_GETRED(col));

-    }

-  }

-  return bmp;

-

-error:

-  free(bmp);

-

-  return NULL;

-}

-

-

-/** Given a bitmap pointer, check various aspects of it and return a framebuffer structure pointer.

- *

- *  @param  bmp  Pointer to a loaded bitmap structure.

- *

- *  @return  Pointer to a framebuffer structure associated with the bitmap.

- *

- *  NOTE: the bitmap plotting code requires some special-case Windows BMP format

- *  bitmaps as input; they must include a DIB header (very common) and their width

- *  must be such that they don't require any padding bytes at the end of each pixel

- *  row.

- *

- *  The padding issue could be fixed very simply by calling the dlo_copy_host_bmp()

- *  for each pixel row individually but for the sake of a simple demo, we impose

- *  the constraint and make only one call to dlo_copy_host_bmp() here.

- */

-static dlo_fbuf_t *bmp_to_fbuf(const bmp_t * const bmp)

-{

-  static dlo_fbuf_t fbuf;

-

-  printf("bmp->hdr.magic       %04X\n"

-         "bmp->hdr.file_sz     %08X (%u)\n"

-         "bmp->hdr.reserved1   %04X\n"

-         "bmp->hdr.reserved2   %04X\n"

-         "bmp->hdr.pix_offset  %08X\n"

-         "bmp->dib.dib_hdr_sz  %08X\n"

-         "bmp->dib.width       %08X (%u)\n"

-         "bmp->dib.height      %08X (%u)\n"

-         "bmp->dib.col_planes  %04X\n"

-         "bmp->dib.bpp         %04X (%u)\n"

-         "bmp->dib.compression %08X\n"

-         "bmp->dib.raw_size    %08X (%u)\n"

-         "bmp->dib.x_pix_meter %08X\n"

-         "bmp->dib.y_pix_meter %08X\n"

-         "bmp->dib.pal_entries %08X (%u)\n"

-         "bmp->dib.imp_cols    %08X\n",

-         bmp->hdr.magic,

-         bmp->hdr.file_sz, bmp->hdr.file_sz,

-         bmp->hdr.reserved1,

-         bmp->hdr.reserved2,

-         bmp->hdr.pix_offset,

-         bmp->dib.dib_hdr_sz,

-         bmp->dib.width, bmp->dib.width,

-         bmp->dib.height, bmp->dib.height,

-         bmp->dib.col_planes,

-         bmp->dib.bpp, bmp->dib.bpp,

-         bmp->dib.compression,

-         bmp->dib.raw_size, bmp->dib.raw_size,

-         bmp->dib.x_pix_meter,

-         bmp->dib.y_pix_meter,

-         bmp->dib.pal_entries, bmp->dib.pal_entries,

-         bmp->dib.imp_cols);

-

-  if (bmp->dib.compression)

-    my_error("Unsupported bitmap compression mode");

-  if (bmp->dib.col_planes != 1)

-    my_error("Unsupported bitmap colour plane specification");

-  if ((bmp->dib.width * BYTES_PER_PIXEL(bmp->dib.bpp)) & 3)

-    my_error("Bitmap width must be whole multiple of four bytes (no padding)");

-

-  fbuf.width  = bmp->dib.width;

-  fbuf.height = bmp->dib.height;

-  fbuf.base   = bmp->hdr.pix_offset + (uint8_t *)bmp;

-  fbuf.stride = fbuf.width;

-  switch (bmp->dib.bpp)

-  {

-    case 8:

-    {

-      fbuf.fmt = (dlo_pixfmt_t)(sizeof(bmp_header_t) + sizeof(dib_header_t) + (uint8_t *)bmp);

-      if (bmp->dib.pal_entries != 256)

-        my_error("Unsupported bitmap palette size");

-      break;

-    }

-    case 16:

-    {

-      fbuf.fmt = dlo_pixfmt_srgb1555;

-      break;

-    }

-    case 24:

-    {

-      fbuf.fmt = dlo_pixfmt_rgb888;

-      break;

-    }

-    case 32:

-    {

-      fbuf.fmt = dlo_pixfmt_argb8888;

-      break;

-    }

-    default:

-      my_error("Unsupported bitmap colour depth");

-  }

-  return &fbuf;

-}

-

-

-/** Run some tests involving the loading, scraping and plotting of a bitmap.

- *

- *  @param  uid      Unique ID of the device.

- *  @param  bmpfile  Pointer to a Windows BMP filename.

- *

- *  @return  Return code, zero for no error.

- *

- *  Load a bitmap, clear the screen and plot the bitmap at the centre of the

- *  screen as well as off each edge of the screen.

- */

-static dlo_retcode_t bitmap_test(const dlo_dev_t uid, const bool cross, const char * const bmpfile)

-{

-  dlo_bmpflags_t flags = { 0 };

-  dlo_retcode_t  err;

-  dlo_mode_t    *desc;

-  dlo_fbuf_t    *fbuf;

-  dlo_view_t     view;

-  dlo_dot_t      dot;

-  bmp_t          *bmp;

-

-  printf("\ntest: bitmap file '%s'\n", bmpfile);

-

-  /* Read current mode information */

-  desc = dlo_get_mode(uid);

-  NERR(desc);

-  view = desc->view;

-

-  /* Clear screen to black */

-  ERR(dlo_fill_rect(uid, NULL, NULL, DLO_RGB(0, 0, 0)));

-

-  /* Load the Windows BMP bitmap file into memory */

-  bmp = load_bmp(bmpfile);

-  NERR(bmp);

-

-  /* Initialise a dlo_fbuf structure from our loaded bitmap file  */

-  fbuf = bmp_to_fbuf(bmp);

-  NERR_GOTO(fbuf);

-

-  /* Test plotting of bitmap in centre of screen */

-  dot.x = (view.width  / 2) - (fbuf->width  / 2);

-  dot.y = (view.height / 2) - (fbuf->height / 2);

-  flags.v_flip = 1;

-  ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-

-  /* Now a few plots that lie a little off the edges of the screen */

-  flags.v_flip = 0;

-  if (cross)

-  {

-    dot.y = -fbuf->height / 2;

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-    dot.y += view.height;

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-    dot.x = -fbuf->width / 2;

-    dot.y = (view.height / 2) - (fbuf->height / 2);

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-    dot.x += view.width;

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-  }

-  else

-  {

-    dot.x  = -fbuf->width  / 2;

-    dot.y  = -fbuf->height / 2;

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-    dot.y += view.height;

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-    dot.x += view.width;

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-    dot.y -= view.height;

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));

-  }

-

-  /* Discard the bitmap */

-  free(bmp);

-

-  return dlo_ok;

-

-error:

-  free(bmp);

-  return err;

-}

-

-

-/** Run some screen scraping tests with a set of input bitmaps.

- *

- *  @param  uid  Unique ID of the device.

- *

- *  @return  Return code, zero for no error.

- *

- *  This test sequence checks that the @c dlo_copy_host_bmp() call works correctly for

- *  a number of source pixel formats by loading some different bitmaps and scraping

- *  directly from them (using their palette where required).

- */

-static dlo_retcode_t scrape_tests(const dlo_dev_t uid)

-{

-  ERR(bitmap_test(uid, false, "images/test08.bmp"));

-

-  wait_ms(now(), 1000);

-  ERR(bitmap_test(uid, true, "images/test16.bmp"));

-

-  wait_ms(now(), 1000);

-  ERR(bitmap_test(uid, false, "images/test24.bmp"));

-

-  wait_ms(now(), 1000);

-  return bitmap_test(uid, true, "images/test32.bmp");

-}

-

-

-/** Test the clipping of bitmaps relative to other screen banks.

- *

- *  @param  uid  Unique ID of the device.

- *

- *  @return  Return code, zero for no error.

- *

- *  The point of this test is to plot lots of bitmaps in random positions (some

- *  completely off-screen) into the middle of three screen banks. We switch between

- *  each bank to check that the bitmaps only appear on the middle one and haven't

- *  spilled over into the surrounding memory.

- */

-static dlo_retcode_t bmp_clip_test(const dlo_dev_t uid)

-{

-  dlo_bmpflags_t flags = { 0 };

-  dlo_retcode_t  err;

-  dlo_mode_t     mode;

-  dlo_mode_t    *desc;

-  dlo_fbuf_t    *fbuf;

-  dlo_view_t     view[3];

-  dlo_dot_t      dot;

-  bmp_t          *bmp;

-  uint32_t        i;

-

-  /* Read current mode information */

-  desc = dlo_get_mode(uid);

-  NERR(desc);

-

-  /* Create three viewports - each representing a screen bank */

-  view[0]      = desc->view;

-  view[1]      = view[0];

-  view[1].base = view[0].base + (view[1].width * view[1].height * bpp_to_bytes(view[1].bpp));

-  view[2]      = view[1];

-  view[2].base = view[1].base + (view[2].width * view[2].height * bpp_to_bytes(view[2].bpp));

-

-  /* Clear screen banks */

-  wait_ms(now(), 2000);

-  ERR(dlo_fill_rect(uid, NULL,     NULL, DLO_RGB(0, 0, 0x50)));

-  ERR(dlo_fill_rect(uid, &view[1], NULL, DLO_RGB(0, 0, 0)));

-  ERR(dlo_fill_rect(uid, &view[2], NULL, DLO_RGB(0, 0x50, 0)));

-

-  /* Load the Windows BMP bitmap file into memory */

-  bmp = load_bmp("images/test08.bmp");

-  NERR(bmp);

-

-  /* Initialise a dlo_fbuf structure from our loaded bitmap file  */

-  fbuf = bmp_to_fbuf(bmp);

-  NERR_GOTO(fbuf);

-

-  /* Plot lots of bitmaps into the second screen bank */

-  for (i = 0; i < 399; i++)

-  {

-    flags.v_flip = rand() % 2;

-    dot.x        = -fbuf->width  + (rand() % (view[1].width  + fbuf->width));

-    dot.y        = -fbuf->height + (rand() % (view[1].height + fbuf->height));

-    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, &view[1], &dot));

-  }

-

-  /* Switch to middle bank */

-  wait_ms(now(), 2000);

-  mode.view.width  = view[1].width;

-  mode.view.height = view[1].height;

-  mode.view.bpp    = view[1].bpp;

-  mode.view.base   = view[1].base;

-  mode.refresh     = 0;

-  ERR_GOTO(dlo_set_mode(uid, &mode));

-

-  /* Switch to third bank */

-  wait_ms(now(), 2000);

-  mode.view.width  = view[2].width;

-  mode.view.height = view[2].height;

-  mode.view.bpp    = view[2].bpp;

-  mode.view.base   = view[2].base;

-  mode.refresh     = 0;

-  ERR_GOTO(dlo_set_mode(uid, &mode));

-

-  /* Switch to middle bank */

-  wait_ms(now(), 2000);

-  mode.view.width  = view[1].width;

-  mode.view.height = view[1].height;

-  mode.view.bpp    = view[1].bpp;

-  mode.view.base   = view[1].base;

-  mode.refresh     = 0;

-  ERR_GOTO(dlo_set_mode(uid, &mode));

-

-  /* Discard the bitmap */

-  free(bmp);

-

-  return dlo_ok;

-

-error:

-  free(bmp);

-  return err;

-}

-

-

-/**********************************************************************/

-int main(int argc, char *argv[])

-{

-  dlo_init_t     ini_flags = { 0 };

-  dlo_final_t    fin_flags = { 0 };

-  dlo_claim_t    cnf_flags = { 0 };

-  dlo_retcode_t  err;

-  dlo_dev_t      uid = 0;

-

-  IGNORE(argc);

-  IGNORE(argv);

-

-  /* Initialise the random number generator with the microsecond time as a seed */

-  srand((unsigned int)now());

-

-  /* Initialise libdlo */

-  printf("test: init...\n");

-  ERR_GOTO(dlo_init(ini_flags));

-

-  /* Look for a DisplayLink device to connect to */

-  uid = dlo_claim_first_device(cnf_flags, 0);

-

-  /* If we found one, perform some tests with it */

-  if (uid)

-  {

-    printf("\ntest: basic graphics tests...\n");

-    ERR_GOTO(basic_grfx_test(uid));

-    wait_ms(now(), 3000);

-

-    printf("\test: overlapping copy tests...\n");

-    ERR_GOTO(overlap_test(uid));

-

-    wait_ms(now(), 3000);

-

-    printf("\ntest: viewport tests...\n");

-    ERR_GOTO(viewport_test(uid));

-

-    printf("\ntest: screen scraping tests...\n");

-    ERR_GOTO(scrape_tests(uid));

-

-    printf("test: bitmap clipping test...\n");

-    ERR_GOTO(bmp_clip_test(uid));

-

-    printf("test: release &%X...\n", (uintptr_t)uid);

-    ERR_GOTO(dlo_release_device(uid));

-  }

-

-  /* Finalise libdlo, free up resources */

-  printf("test: final...\n");

-  ERR_GOTO(dlo_final(fin_flags));

-  printf("test: finished.\n");

-  return 0;

-

-error:

-  printf("test: error %u '%s'\n", (int)err, dlo_strerror(err));

-  return 0;

-}

+/** @file test1.c
+ *
+ *  @brief This file demonstrates basic graphics primitive features of libdlo.
+ *
+ *  DisplayLink Open Source Software (libdlo)
+ *  Copyright (C) 2009, DisplayLink
+ *  www.displaylink.com
+ *
+ *  This library is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU Library General Public License as published by the Free
+ *  Software Foundation; LGPL version 2, dated June 1991.
+ *
+ *  This library 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 Library General Public License for more
+ *  details.
+ *
+ *  You should have received a copy of the GNU Library General Public License
+ *  along with this library; if not, write to the Free Software Foundation, Inc.,
+ *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+
+#include "sys/time.h"
+#include "libdlo.h"
+#include "../../src/dlo_defs.h"
+
+
+/** Default horizontal resolution we will use for tests (pixels).
+ */
+#define SCREEN_X (1280)
+
+/** Default vertical resolution we will use for tests (pixels).
+ */
+#define SCREEN_Y (1024)
+
+/** Default screen refresh rate we will use for tests (Hz).
+ */
+#define SCREEN_RATE (0)
+
+/** Default screen colour depth we will use for tests (bits per pixel).
+ */
+#define SCREEN_BPP (24)
+
+/** Number of random dots to plot.
+ */
+#define NUM_DOTS (299)
+
+/** Number of random rectangles to plot.
+ */
+#define NUM_RECTS (99)
+
+/** Number of steps (gradient) in colour blended rectangles.
+ */
+#define NUM_GRAD (99)
+
+/** Division factor for scale of central rectangle.
+ */
+#define MID_REC_DIV (5)
+
+/** Windows BMP magic ID bytes.
+ */
+#define BMP_MAGIC (0x4D42)
+
+/** Given a bits per pixel value, return the bytes per pixel.
+ */
+#define BYTES_PER_PIXEL(bpp) (unsigned int)(((bpp) + 7) / 8)
+
+/** Horizontal subdivision of the screen for overlapping rectangle copy tests.
+ */
+#define ZONE_X (SCREEN_X / 3)
+
+/** Vertical subdivision of the screen for overlapping rectangle copy tests.
+ */
+#define ZONE_Y (SCREEN_Y / 3)
+
+/** Horizontal size of the rectangle to copy in the overlapping rectangle copy tests.
+ */
+#define COPY_X (ZONE_X / 2)
+
+/** Vertical size of the rectangle to copy in the overlapping rectangle copy tests.
+ */
+#define COPY_Y (ZONE_Y / 2)
+
+/** Size of a component of a rectangle copy offset (horizontal or vertical).
+ */
+#define STEP (80)
+
+
+/** Array of offsets for overlapping rectangle copy test.
+ */
+const dlo_dot_t overlap[9] =
+{
+  { -STEP, -STEP },
+  {     0, -STEP },
+  {  STEP, -STEP },
+  { -STEP,     0 },
+  {     0,     0 },
+  {  STEP,     0 },
+  { -STEP,  STEP },
+  {     0,  STEP },
+  {  STEP,  STEP }
+};
+
+
+/** The main header block from a Windows BMP file.
+ */
+typedef struct __packed bmp_header_s
+{
+  uint16_t magic;          /**< Magic ID bytes for Windows BMP format. */
+  uint32_t file_sz;        /**< Total bitmap file size (bytes). */
+  uint16_t reserved1;      /**< Unused. */
+  uint16_t reserved2;      /**< Unused. */
+  uint32_t pix_offset;     /**< Offset from start of file to start of pixel data (bytes). */
+} bmp_header_t;            /**< A struct @a bmp_header_s. */
+
+
+/** The DIB header block from a Windows BMP file.
+ */
+typedef struct __packed dib_header_s
+{
+  uint32_t dib_hdr_sz;     /**< Size of the DIB header block (bytes). */
+  uint32_t width;          /**< Width of the bitmap (pixels). */
+  uint32_t height;         /**< Height of the bitmap (pixels). */
+  uint16_t col_planes;     /**< Number of colour planes. */
+  uint16_t bpp;            /**< Bits per pixel. */
+  uint32_t compression;    /**< Compression, pixel format. */
+  uint32_t raw_size;       /**< Size of the raw pixel data. */
+  uint32_t x_pix_meter;    /**< Horizontal resolution (pixels per meter). */
+  uint32_t y_pix_meter;    /**< Vertical resolution (pixels per meter). */
+  uint32_t pal_entries;    /**< Number of palette entries. */
+  uint32_t imp_cols;       /**< Important colours (ignored). */
+} dib_header_t;            /**< A struct @a dib_header_s. */
+
+
+/** A Windows BMP file.
+ */
+typedef struct __packed bmp_s
+{
+  bmp_header_t hdr;        /**< Windows BMP header block. */
+  dib_header_t dib;        /**< DIB header block. */
+  uint8_t      data[];     /**< Pixel data. */
+} bmp_t;                   /**< A struct @a bmp_s. */
+
+
+/** Report an error and exit.
+ *
+ *  @param  str  Pointer to the error message string.
+ */
+static void my_error(const char * const str)
+{
+  printf("test: ERROR: %s\n", str);
+  exit(1);
+}
+
+
+/** Return the microsecond time, as an unsigned 64 bit integer.
+ *
+ *  @return  Number of microseconds since the start of the Epoch.
+ */
+static uint64_t now(void)
+{
+  static struct timeval  unix_time     = { 0 };
+  static struct timeval *unix_time_ptr = &unix_time;
+
+  gettimeofday(unix_time_ptr, NULL);
+  return ((uint64_t)unix_time.tv_sec * 1000000ll) + (uint64_t)unix_time.tv_usec;
+}
+
+
+/** Pause execution for the specified number of centiseconds.
+ *
+ *  @param  from      Time to start the pause interval.
+ *  @param  millisec  Number of milliseconds to pause for.
+ */
+static void wait_ms(const uint64_t from, const uint64_t millisec)
+{
+  uint64_t to = from + (millisec * 1000);
+
+  while (to > now()) ;
+}
+
+
+/** Plot a rectangular outline in the specified colour.
+ *
+ *  @param  uid   Unique ID of the device.
+ *  @param  view  Viewport for plot destination.
+ *  @param  rec   Rectangle co-ordinates within the viewport.
+ *  @param  col   Colour of rectangle.
+ *
+ *  @return  Return code, zero for no error.
+ */
+static dlo_retcode_t box(const dlo_dev_t uid, const dlo_view_t * const view, const dlo_rect_t * const rec, const dlo_col32_t col)
+{
+  dlo_rect_t line;
+
+  line.origin.x = rec->origin.x;
+  line.origin.y = rec->origin.y;
+  line.width    = rec->width;
+  line.height   = 1;
+  ERR(dlo_fill_rect(uid, view, &line, col));
+
+  line.width    = 1;
+  line.height   = rec->height;
+  ERR(dlo_fill_rect(uid, view, &line, col));
+
+  line.origin.y += line.height - 1;
+  line.width     = rec->width;
+  line.height    = 1;
+  ERR(dlo_fill_rect(uid, view, &line, col));
+
+  line.origin.x += line.width;
+  line.origin.y  = rec->origin.y;
+  line.width     = 1;
+  line.height    = rec->height;
+  ERR(dlo_fill_rect(uid, view, &line, col));
+
+  return dlo_ok;
+}
+
+
+/** Test the basic graphics primitives (filled rectangle and rectangle copy).
+ *
+ *  @param  uid  Unique ID of the device.
+ *
+ *  @return  Return code, zero for no error.
+ */
+static dlo_retcode_t basic_grfx_test(const dlo_dev_t uid)
+{
+  dlo_mode_t     mode;
+  dlo_mode_t    *mode_info;
+  dlo_devinfo_t *dev_info;
+  dlo_view_t    *view;
+  dlo_rect_t      rec;
+  dlo_dot_t      dot;
+  uint32_t        i;
+  uint64_t        start;
+
+  /* Read some information on the device */
+  dev_info = dlo_device_info(uid);
+  NERR(dev_info);
+  printf("test: device info: uid &%X\n", (int)dev_info->uid);
+  printf("test: device info: serial '%s'\n", dev_info->serial);
+  printf("test: device info: type  &%X\n", (uint32_t)dev_info->type);
+
+  /* Read current mode information (if we're already in the display's native mode) */
+  mode_info = dlo_get_mode(uid);
+  NERR(mode_info);
+  printf("test: native mode info...\n");
+  printf("  %ux%u @ %u Hz %u bpp base &%X\n", mode_info->view.width, mode_info->view.height, mode_info->refresh, mode_info->view.bpp, (int)mode_info->view.base);
+
+  /* Select a fairly standard mode */
+  printf("test: set_mode...\n");
+  mode.view.width  = SCREEN_X;
+  mode.view.height = SCREEN_Y;
+  mode.view.bpp    = SCREEN_BPP;
+  mode.view.base   = 0;
+  mode.refresh     = SCREEN_RATE;
+  ERR(dlo_set_mode(uid, &mode));
+  wait_ms(now(), 1000);
+      
+
+  /* Read current mode information */
+  mode_info = dlo_get_mode(uid);
+  NERR(mode_info);
+  printf("test: mode info...\n");
+  printf("  %ux%u @ %u Hz %u bpp base &%X\n", mode_info->view.width, mode_info->view.height, mode_info->refresh, mode_info->view.bpp, (int)mode_info->view.base);
+  view = &(mode_info->view);
+
+  /* Clear screen */
+  printf("test: cls...");
+  start = now();
+  ERR(dlo_fill_rect(uid, NULL, NULL, DLO_RGB(0, 0, 0)));
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Plot some random white dots */
+  printf("test: random white dots...");
+  start      = now();
+  rec.width  = 1;
+  rec.height = 1;
+  for (i = 0; i < NUM_DOTS; i++)
+  {
+    rec.origin.x = rand() % view->width;
+    rec.origin.y = rand() % view->height;
+    ERR(dlo_fill_rect(uid, view, &rec, DLO_RGB(0xFF, 0xFF, 0xFF)));
+  }
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Plot random filled rectangles */
+  printf("test: random rectangles...");
+  start = now();
+  for (i = 0; i < NUM_RECTS; i++)
+  {
+    rec.width    = rand() % (view->width  / 4);
+    rec.height   = rand() % (view->height / 4);
+    rec.origin.x = (rand() % (uint32_t)(1.25 * view->width))  - (view->width  / 8);
+    rec.origin.y = (rand() % (uint32_t)(1.25 * view->height)) - (view->height / 8);
+    ERR(dlo_fill_rect(uid, view, &rec, DLO_RGB(rand() % 0xFF, rand() % 0xFF, rand() % 0xFF)));
+  }
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Plot a set of rectangles, one over the other (colour gradient) */
+  printf("test: central rectangles...");
+  start = now();
+  for (i = 0; i < NUM_GRAD; i++)
+  {
+    dlo_col32_t col = DLO_RGB((i*3) % 256, (i*5) % 256, 255 - ((i*7) % 256));
+
+    rec.width    = (view->width  / MID_REC_DIV) - 2*i;
+    rec.height   = (view->height / MID_REC_DIV) - 2*i;
+    rec.origin.x = i + (view->width  / 2) - (view->width / MID_REC_DIV / 2);
+    rec.origin.y = i + (view->height / 2) - (view->height/ MID_REC_DIV / 2);
+    ERR(dlo_fill_rect(uid, view, &rec, col));
+  }
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Plot the outline of the box we're going to copy */
+  printf("test: white box outline...");
+  start = now();
+  rec.width    = view->width  / MID_REC_DIV;
+  rec.height   = view->height / MID_REC_DIV;
+  rec.origin.x = (view->width  / 2) - (rec.width  / 2);
+  rec.origin.y = (view->height / 2) - (rec.height / 2);
+  ERR(box(uid, view, &rec, DLO_RGB(0xFF, 0xFF, 0xFF)));
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Copy a rectangle from the centre of the screen to other locations */
+  printf("test: copy central box...");
+  start = now();
+  rec.origin.x++;
+  rec.origin.y++;
+  rec.width  -= 2;
+  rec.height -= 2;
+  dot.x       = 8;
+  dot.y       = 8;
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  dot.x = view->width - 8 - rec.width;
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  dot.y = view->height - 8 - rec.height;
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  dot.x = 8;
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Check that basic clipping works */
+  printf("test: copy central box (off edges of viewport)...");
+  start = now();
+  dot.x = -(rec.width / 2);
+  dot.y = (view->height / 2) - (rec.height / 2) - 32;
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  dot.x += view->width;
+  dot.y += 64;
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  dot.x = (view->width / 2) - (rec.width / 2) - 128;
+  dot.y = -(rec.height / 2);
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  dot.x += 256;
+  dot.y += view->height;
+  ERR(dlo_copy_rect(uid, view, &rec, view, &dot));
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  return dlo_ok;
+}
+
+
+/** Plot a few coloured rectangles one above another.
+ *
+ *  @param  uid    Unique ID of the device.
+ *  @param  inrec  Input rectangle (the outer bounding box of the design).
+ *
+ *  @return  Return code, zero for no error.
+ */
+static dlo_retcode_t squares(const dlo_dev_t uid, const dlo_rect_t * const inrec)
+{
+  dlo_rect_t rec = *inrec;
+
+  /* Plot the outer (red) rectangle */
+  ERR(dlo_fill_rect(uid, NULL, &rec, DLO_RGB(0xCC, 0, 0)));
+
+  /* Plot the middle (white) rectangle */
+  rec.origin.x += 20;
+  rec.origin.y += 20;
+  rec.width    -= 40;
+  rec.height   -= 40;
+  ERR(dlo_fill_rect(uid, NULL, &rec, DLO_RGB(0xCC, 0xCC, 0xCC)));
+
+  /* Plot the inner (blue) rectangle */
+  rec.origin.x += 20;
+  rec.origin.y += 20;
+  rec.width    -= 40;
+  rec.height   -= 40;
+
+  return dlo_fill_rect(uid, NULL, &rec, DLO_RGB(0, 0, 0xCC));
+}
+
+
+/** Test copying rectangles to and from overlapping regions (in various directions).
+ *
+ *  @param  uid  Unique ID of the device.
+ *
+ *  @return  Return code, zero for no error.
+ */
+static dlo_retcode_t overlap_test(const dlo_dev_t uid)
+{
+  dlo_rect_t rec;
+  dlo_dot_t mid, dot;
+  uint32_t   idx = 0;
+
+  /* Clear screen to black */
+  ERR(dlo_fill_rect(uid, NULL, NULL, DLO_RGB(0, 0, 0)));
+
+  rec.width  = COPY_X;
+  rec.height = COPY_Y;
+  for (mid.y = ZONE_Y / 2; mid.y < SCREEN_Y; mid.y += ZONE_Y)
+  {
+    for (mid.x = ZONE_X / 2; mid.x < SCREEN_X; mid.x += ZONE_X)
+    {
+      rec.origin.x = mid.x - (COPY_X / 2);
+      rec.origin.y = mid.y - (COPY_Y / 2);
+      dot.x        = rec.origin.x + overlap[idx].x;
+      dot.y        = rec.origin.y + overlap[idx].y;
+      idx++;
+      ERR(squares(uid, &rec));
+      ERR(dlo_copy_rect(uid, NULL, &rec, NULL, &dot));
+    }
+  }
+  return dlo_ok;
+}
+
+
+/** Convert a bits per pixel value into a bytes per pixel value.
+ *
+ *  @param  bpp  Bits per pixel.
+ *
+ *  @return  Bytes per pixel.
+ */
+static uint8_t bpp_to_bytes(const uint32_t bpp)
+{
+  return (uint8_t)((bpp + 7) / 8);
+}
+
+
+/** Test the use of viewports as screen banks (ensure clipping is working).
+ *
+ *  @param  uid  Unique ID of the device.
+ *
+ *  @return  Return code, zero for no error.
+ *
+ *  Create three viewports (screen banks) and switch the display between them.
+ *  While we're at it, test the filled rectangle plotting clips correctly and
+ *  doesn't overflow into surrounding screen banks or off the edges of the
+ *  screen.
+ */
+static dlo_retcode_t viewport_test(const dlo_dev_t uid)
+{
+  dlo_mode_t  mode;
+  dlo_mode_t *desc;
+  dlo_view_t  view[3];
+  dlo_rect_t   rec;
+  uint32_t     i;
+  uint64_t     start;
+
+  /* Read current mode information */
+  desc = dlo_get_mode(uid);
+  NERR(desc);
+
+  /* Create three viewports - each representing a screen bank */
+  view[0]      = desc->view;
+  view[1]      = view[0];
+  view[1].base = view[0].base + (view[1].width * view[1].height * bpp_to_bytes(view[1].bpp));
+  view[2]      = view[1];
+  view[2].base = view[1].base + (view[2].width * view[2].height * bpp_to_bytes(view[2].bpp));
+
+  /* Clear screens to different colours */
+  printf("test: cls (three banks)...");
+  start = now();
+  ERR(dlo_fill_rect(uid, NULL,     NULL, DLO_RGB(0, 0, 0xFF)));
+  ERR(dlo_fill_rect(uid, &view[1], NULL, DLO_RGB(0, 0xFF, 0)));
+  ERR(dlo_fill_rect(uid, &view[2], NULL, DLO_RGB(0xFF, 0, 0)));
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Plot a couple of rectangles in each bank to test the clipping */
+  printf("test: plot crosses (three banks)...");
+  start = now();
+  rec.width    = view[0].width / 8;
+  rec.height   = view[0].height * 1.5;
+  rec.origin.x = (view[0].width / 2) - (rec.width / 2);
+  rec.origin.y = -(view[0].height / 4);
+  ERR(dlo_fill_rect(uid, NULL,     &rec, DLO_RGB(0, 0xFF, 0xFF)));
+  ERR(dlo_fill_rect(uid, &view[1], &rec, DLO_RGB(0xFF, 0xFF, 0)));
+  ERR(dlo_fill_rect(uid, &view[2], &rec, DLO_RGB(0xFF, 0, 0xFF)));
+  rec.width    = view[0].width * 1.5;
+  rec.height   = view[0].height / 8;
+  rec.origin.x = -(view[0].width / 4);
+  rec.origin.y = (view[0].height / 2) - (rec.height / 2);
+  ERR(dlo_fill_rect(uid, NULL,     &rec, DLO_RGB(0, 0xFF, 0xFF)));
+  ERR(dlo_fill_rect(uid, &view[1], &rec, DLO_RGB(0xFF, 0xFF, 0)));
+  ERR(dlo_fill_rect(uid, &view[2], &rec, DLO_RGB(0xFF, 0, 0xFF)));
+  printf(" took %u ms\n", (uint32_t)(now() - start) / 1000);
+
+  /* Switch through the screen banks */
+  for (i = 1; i < 4; i++)
+  {
+    wait_ms(now(), 1000);
+
+    printf("test: switching to screen bank %u...\n", i % 3);
+    mode.view.width  = view[i % 3].width;
+    mode.view.height = view[i % 3].height;
+    mode.view.bpp    = view[i % 3].bpp;
+    mode.view.base   = view[i % 3].base;
+    mode.refresh     = 0;
+    ERR(dlo_set_mode(uid, &mode));
+  }
+
+  return dlo_ok;
+}
+
+
+/** Load a Windows BMP file into memory.
+ *
+ *  @param  bmpfile  Pointer to the filename.
+ *
+ *  @return  Pointer to the loaded bitmap's structure (or NULL if failed).
+ *
+ *  Load a bitmap from a file and create a @a dlo_fbuf_t structure to suit.
+ *  If the bitmap has a palette, we need to swap the red/blue order of the
+ *  colour components in order to convert the palette entries into
+ *  @a dlo_col32_t values.
+ */
+static bmp_t *load_bmp(const char * const bmpfile)
+{
+  long int      size;
+  bmp_t        *bmp;
+  FILE         *fp;
+
+  fp = fopen(bmpfile, "rb");
+  if (!fp)
+    return NULL;
+
+  if (fseek(fp, 0, SEEK_END))
+    return NULL;
+
+  size = ftell(fp);
+  if (size == -1L)
+    return NULL;
+
+  if (fseek(fp, 0, SEEK_SET))
+    return NULL;
+
+  bmp = malloc(size);
+  if (!bmp)
+    return NULL;
+
+  if (1 != fread(bmp, size, 1, fp))
+    goto error;
+
+  if (bmp->hdr.magic != BMP_MAGIC)
+    goto error;
+
+  /* If there is a palette, we need to reverse the RGB component order */
+  if (bmp->dib.pal_entries)
+  {
+    dlo_col32_t *palette;
+    uint32_t      i;
+
+    palette = (dlo_col32_t *)((unsigned long)bmp + sizeof(bmp_header_t) + sizeof(dib_header_t));
+
+    for (i = 0; i < bmp->dib.pal_entries; i++)
+    {
+      dlo_col32_t col = palette[i];
+
+      palette[i] = DLO_RGB(DLO_RGB_GETBLU(col), DLO_RGB_GETGRN(col), DLO_RGB_GETRED(col));
+    }
+  }
+  return bmp;
+
+error:
+  free(bmp);
+
+  return NULL;
+}
+
+
+/** Given a bitmap pointer, check various aspects of it and return a framebuffer structure pointer.
+ *
+ *  @param  bmp  Pointer to a loaded bitmap structure.
+ *
+ *  @return  Pointer to a framebuffer structure associated with the bitmap.
+ *
+ *  NOTE: the bitmap plotting code requires some special-case Windows BMP format
+ *  bitmaps as input; they must include a DIB header (very common) and their width
+ *  must be such that they don't require any padding bytes at the end of each pixel
+ *  row.
+ *
+ *  The padding issue could be fixed very simply by calling the dlo_copy_host_bmp()
+ *  for each pixel row individually but for the sake of a simple demo, we impose
+ *  the constraint and make only one call to dlo_copy_host_bmp() here.
+ */
+static dlo_fbuf_t *bmp_to_fbuf(const bmp_t * const bmp)
+{
+  static dlo_fbuf_t fbuf;
+
+  printf("bmp->hdr.magic       %04X\n"
+         "bmp->hdr.file_sz     %08X (%u)\n"
+         "bmp->hdr.reserved1   %04X\n"
+         "bmp->hdr.reserved2   %04X\n"
+         "bmp->hdr.pix_offset  %08X\n"
+         "bmp->dib.dib_hdr_sz  %08X\n"
+         "bmp->dib.width       %08X (%u)\n"
+         "bmp->dib.height      %08X (%u)\n"
+         "bmp->dib.col_planes  %04X\n"
+         "bmp->dib.bpp         %04X (%u)\n"
+         "bmp->dib.compression %08X\n"
+         "bmp->dib.raw_size    %08X (%u)\n"
+         "bmp->dib.x_pix_meter %08X\n"
+         "bmp->dib.y_pix_meter %08X\n"
+         "bmp->dib.pal_entries %08X (%u)\n"
+         "bmp->dib.imp_cols    %08X\n",
+         bmp->hdr.magic,
+         bmp->hdr.file_sz, bmp->hdr.file_sz,
+         bmp->hdr.reserved1,
+         bmp->hdr.reserved2,
+         bmp->hdr.pix_offset,
+         bmp->dib.dib_hdr_sz,
+         bmp->dib.width, bmp->dib.width,
+         bmp->dib.height, bmp->dib.height,
+         bmp->dib.col_planes,
+         bmp->dib.bpp, bmp->dib.bpp,
+         bmp->dib.compression,
+         bmp->dib.raw_size, bmp->dib.raw_size,
+         bmp->dib.x_pix_meter,
+         bmp->dib.y_pix_meter,
+         bmp->dib.pal_entries, bmp->dib.pal_entries,
+         bmp->dib.imp_cols);
+
+  if (bmp->dib.compression)
+    my_error("Unsupported bitmap compression mode");
+  if (bmp->dib.col_planes != 1)
+    my_error("Unsupported bitmap colour plane specification");
+  if ((bmp->dib.width * BYTES_PER_PIXEL(bmp->dib.bpp)) & 3)
+    my_error("Bitmap width must be whole multiple of four bytes (no padding)");
+
+  fbuf.width  = bmp->dib.width;
+  fbuf.height = bmp->dib.height;
+  fbuf.base   = bmp->hdr.pix_offset + (uint8_t *)bmp;
+  fbuf.stride = fbuf.width;
+  switch (bmp->dib.bpp)
+  {
+    case 8:
+    {
+      fbuf.fmt = (dlo_pixfmt_t)(sizeof(bmp_header_t) + sizeof(dib_header_t) + (uint8_t *)bmp);
+      if (bmp->dib.pal_entries != 256)
+        my_error("Unsupported bitmap palette size");
+      break;
+    }
+    case 16:
+    {
+      fbuf.fmt = dlo_pixfmt_srgb1555;
+      break;
+    }
+    case 24:
+    {
+      fbuf.fmt = dlo_pixfmt_rgb888;
+      break;
+    }
+    case 32:
+    {
+      fbuf.fmt = dlo_pixfmt_argb8888;
+      break;
+    }
+    default:
+      my_error("Unsupported bitmap colour depth");
+  }
+  return &fbuf;
+}
+
+
+/** Run some tests involving the loading, scraping and plotting of a bitmap.
+ *
+ *  @param  uid      Unique ID of the device.
+ *  @param  bmpfile  Pointer to a Windows BMP filename.
+ *
+ *  @return  Return code, zero for no error.
+ *
+ *  Load a bitmap, clear the screen and plot the bitmap at the centre of the
+ *  screen as well as off each edge of the screen.
+ */
+static dlo_retcode_t bitmap_test(const dlo_dev_t uid, const bool cross, const char * const bmpfile)
+{
+  dlo_bmpflags_t flags = { 0 };
+  dlo_retcode_t  err;
+  dlo_mode_t    *desc;
+  dlo_fbuf_t    *fbuf;
+  dlo_view_t     view;
+  dlo_dot_t      dot;
+  bmp_t          *bmp;
+
+  printf("\ntest: bitmap file '%s'\n", bmpfile);
+
+  /* Read current mode information */
+  desc = dlo_get_mode(uid);
+  NERR(desc);
+  view = desc->view;
+
+  /* Clear screen to black */
+  ERR(dlo_fill_rect(uid, NULL, NULL, DLO_RGB(0, 0, 0)));
+
+  /* Load the Windows BMP bitmap file into memory */
+  bmp = load_bmp(bmpfile);
+  NERR(bmp);
+
+  /* Initialise a dlo_fbuf structure from our loaded bitmap file  */
+  fbuf = bmp_to_fbuf(bmp);
+  NERR_GOTO(fbuf);
+
+  /* Test plotting of bitmap in centre of screen */
+  dot.x = (view.width  / 2) - (fbuf->width  / 2);
+  dot.y = (view.height / 2) - (fbuf->height / 2);
+  flags.v_flip = 1;
+  ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+
+  /* Now a few plots that lie a little off the edges of the screen */
+  flags.v_flip = 0;
+  if (cross)
+  {
+    dot.y = -fbuf->height / 2;
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+    dot.y += view.height;
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+    dot.x = -fbuf->width / 2;
+    dot.y = (view.height / 2) - (fbuf->height / 2);
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+    dot.x += view.width;
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+  }
+  else
+  {
+    dot.x  = -fbuf->width  / 2;
+    dot.y  = -fbuf->height / 2;
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+    dot.y += view.height;
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+    dot.x += view.width;
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+    dot.y -= view.height;
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, NULL, &dot));
+  }
+
+  /* Discard the bitmap */
+  free(bmp);
+
+  return dlo_ok;
+
+error:
+  free(bmp);
+  return err;
+}
+
+
+/** Run some screen scraping tests with a set of input bitmaps.
+ *
+ *  @param  uid  Unique ID of the device.
+ *
+ *  @return  Return code, zero for no error.
+ *
+ *  This test sequence checks that the @c dlo_copy_host_bmp() call works correctly for
+ *  a number of source pixel formats by loading some different bitmaps and scraping
+ *  directly from them (using their palette where required).
+ */
+static dlo_retcode_t scrape_tests(const dlo_dev_t uid)
+{
+  ERR(bitmap_test(uid, false, "images/test08.bmp"));
+
+  wait_ms(now(), 1000);
+  ERR(bitmap_test(uid, true, "images/test16.bmp"));
+
+  wait_ms(now(), 1000);
+  ERR(bitmap_test(uid, false, "images/test24.bmp"));
+
+  wait_ms(now(), 1000);
+  return bitmap_test(uid, true, "images/test32.bmp");
+}
+
+
+/** Test the clipping of bitmaps relative to other screen banks.
+ *
+ *  @param  uid  Unique ID of the device.
+ *
+ *  @return  Return code, zero for no error.
+ *
+ *  The point of this test is to plot lots of bitmaps in random positions (some
+ *  completely off-screen) into the middle of three screen banks. We switch between
+ *  each bank to check that the bitmaps only appear on the middle one and haven't
+ *  spilled over into the surrounding memory.
+ */
+static dlo_retcode_t bmp_clip_test(const dlo_dev_t uid)
+{
+  dlo_bmpflags_t flags = { 0 };
+  dlo_retcode_t  err;
+  dlo_mode_t     mode;
+  dlo_mode_t    *desc;
+  dlo_fbuf_t    *fbuf;
+  dlo_view_t     view[3];
+  dlo_dot_t      dot;
+  bmp_t          *bmp;
+  uint32_t        i;
+
+  /* Read current mode information */
+  desc = dlo_get_mode(uid);
+  NERR(desc);
+
+  /* Create three viewports - each representing a screen bank */
+  view[0]      = desc->view;
+  view[1]      = view[0];
+  view[1].base = view[0].base + (view[1].width * view[1].height * bpp_to_bytes(view[1].bpp));
+  view[2]      = view[1];
+  view[2].base = view[1].base + (view[2].width * view[2].height * bpp_to_bytes(view[2].bpp));
+
+  /* Clear screen banks */
+  wait_ms(now(), 2000);
+  ERR(dlo_fill_rect(uid, NULL,     NULL, DLO_RGB(0, 0, 0x50)));
+  ERR(dlo_fill_rect(uid, &view[1], NULL, DLO_RGB(0, 0, 0)));
+  ERR(dlo_fill_rect(uid, &view[2], NULL, DLO_RGB(0, 0x50, 0)));
+
+  /* Load the Windows BMP bitmap file into memory */
+  bmp = load_bmp("images/test08.bmp");
+  NERR(bmp);
+
+  /* Initialise a dlo_fbuf structure from our loaded bitmap file  */
+  fbuf = bmp_to_fbuf(bmp);
+  NERR_GOTO(fbuf);
+
+  /* Plot lots of bitmaps into the second screen bank */
+  for (i = 0; i < 399; i++)
+  {
+    flags.v_flip = rand() % 2;
+    dot.x        = -fbuf->width  + (rand() % (view[1].width  + fbuf->width));
+    dot.y        = -fbuf->height + (rand() % (view[1].height + fbuf->height));
+    ERR_GOTO(dlo_copy_host_bmp(uid, flags, fbuf, &view[1], &dot));
+  }
+
+  /* Switch to middle bank */
+  wait_ms(now(), 2000);
+  mode.view.width  = view[1].width;
+  mode.view.height = view[1].height;
+  mode.view.bpp    = view[1].bpp;
+  mode.view.base   = view[1].base;
+  mode.refresh     = 0;
+  ERR_GOTO(dlo_set_mode(uid, &mode));
+  wait_ms(now(), 1000);
+    
+  /* Switch to third bank */
+  wait_ms(now(), 2000);
+  mode.view.width  = view[2].width;
+  mode.view.height = view[2].height;
+  mode.view.bpp    = view[2].bpp;
+  mode.view.base   = view[2].base;
+  mode.refresh     = 0;
+  ERR_GOTO(dlo_set_mode(uid, &mode));
+  wait_ms(now(), 1000);
+
+  /* Switch to middle bank */
+  wait_ms(now(), 2000);
+  mode.view.width  = view[1].width;
+  mode.view.height = view[1].height;
+  mode.view.bpp    = view[1].bpp;
+  mode.view.base   = view[1].base;
+  mode.refresh     = 0;
+  ERR_GOTO(dlo_set_mode(uid, &mode));
+  wait_ms(now(), 1000);
+
+  /* Discard the bitmap */
+  free(bmp);
+
+  return dlo_ok;
+
+error:
+  free(bmp);
+  return err;
+}
+
+
+/**********************************************************************/
+int main(int argc, char *argv[])
+{
+  dlo_init_t     ini_flags = { 0 };
+  dlo_final_t    fin_flags = { 0 };
+  dlo_claim_t    cnf_flags = { 0 };
+  dlo_retcode_t  err;
+  dlo_dev_t      uid = 0;
+
+  IGNORE(argc);
+  IGNORE(argv);
+
+  /* Initialise the random number generator with the microsecond time as a seed */
+  srand((unsigned int)now());
+
+  /* Initialise libdlo */
+  printf("test: init...\n");
+  ERR_GOTO(dlo_init(ini_flags));
+
+  /* Look for a DisplayLink device to connect to */
+  uid = dlo_claim_first_device(cnf_flags, 0);
+
+  /* If we found one, perform some tests with it */
+  if (uid)
+  {
+    printf("\ntest: basic graphics tests...\n");
+    ERR_GOTO(basic_grfx_test(uid));
+    wait_ms(now(), 3000);
+
+    printf("\test: overlapping copy tests...\n");
+    ERR_GOTO(overlap_test(uid));
+
+    wait_ms(now(), 3000);
+
+    printf("\ntest: viewport tests...\n");
+    ERR_GOTO(viewport_test(uid));
+
+    printf("\ntest: screen scraping tests...\n");
+    ERR_GOTO(scrape_tests(uid));
+
+    printf("test: bitmap clipping test...\n");
+    ERR_GOTO(bmp_clip_test(uid));
+
+    printf("test: release &%X...\n", (uintptr_t)uid);
+    ERR_GOTO(dlo_release_device(uid));
+  } else {
+    printf("test: no DisplayLink devices found\n");
+  }
+
+  /* Finalise libdlo, free up resources */
+  printf("test: final...\n");
+  ERR_GOTO(dlo_final(fin_flags));
+  printf("test: finished.\n");
+  return 0;
+
+error:
+  printf("test: error %u '%s'\n", (int)err, dlo_strerror(err));
+  return 0;
+}