From ad53242e401e215dcc3c71b2e36c46235793d86b Mon Sep 17 00:00:00 2001 From: quaker Date: Sun, 11 Jan 2009 10:27:01 +0000 Subject: [PATCH] Added some missing files for make doc support git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/evas@38546 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/Doxyfile | 139 ++++++++++++++++++++++++++++++++++ doc/Makefile.am | 32 ++++++++ doc/evas.dox.in | 222 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ m4/efl_doxygen.m4 | 88 ++++++++++++++++++++++ 4 files changed, 481 insertions(+) create mode 100644 doc/Doxyfile create mode 100644 doc/Makefile.am create mode 100644 doc/evas.dox.in create mode 100644 m4/efl_doxygen.m4 diff --git a/doc/Doxyfile b/doc/Doxyfile new file mode 100644 index 0000000..c5675b1 --- /dev/null +++ b/doc/Doxyfile @@ -0,0 +1,139 @@ +PROJECT_NAME = Evas +PROJECT_NUMBER = +OUTPUT_DIRECTORY = . +INPUT = evas.dox ../src/lib +IMAGE_PATH = img +OUTPUT_LANGUAGE = English +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = head.html +HTML_FOOTER = foot.html +HTML_STYLESHEET = e.css +HTML_ALIGN_MEMBERS = YES +ENUM_VALUES_PER_LINE = 1 +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = YES +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = YES +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +INTERNAL_DOCS = NO +STRIP_CODE_COMMENTS = YES +CASE_SENSE_NAMES = YES +SHORT_NAMES = NO +HIDE_SCOPE_NAMES = NO +VERBATIM_HEADERS = NO +SHOW_INCLUDE_FILES = NO +JAVADOC_AUTOBRIEF = YES +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +DISTRIBUTE_GROUP_DOC = NO +TAB_SIZE = 2 +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ALIASES = +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +SHOW_USED_FILES = NO +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +FILE_PATTERNS = +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +INPUT_FILTER = +FILTER_SOURCE_FILES = NO +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 2 +IGNORE_PREFIX = +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = NO +LATEX_BATCHMODE = NO +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +GENERATE_MAN = YES +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = YES +GENERATE_XML = NO +XML_SCHEMA = +XML_DTD = +GENERATE_AUTOGEN_DEF = NO +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = NO +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +CLASS_DIAGRAMS = NO +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +CLASS_GRAPH = NO +COLLABORATION_GRAPH = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = NO +INCLUDED_BY_GRAPH = NO +GRAPHICAL_HIERARCHY = NO +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 512 +MAX_DOT_GRAPH_HEIGHT = 512 +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +SEARCHENGINE = NO diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..93b5340 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,32 @@ +MAINTAINERCLEANFILES = Makefile.in evas.dox + +.PHONY: doc + +PACKAGE_DOCNAME = $(PACKAGE_TARNAME)-$(PACKAGE_VERSION)-doc + +if EFL_BUILD_DOC + +doc-clean: + rm -rf html/ latex/ man/ xml/ $(PACKAGE_DOCNAME).tar* + +doc: all doc-clean + $(DOXYGEN) + cp img/* html/ + rm -rf $(PACKAGE_DOCNAME).tar* + mkdir -p $(PACKAGE_DOCNAME)/doc + cp -R html/ latex/ man/ $(PACKAGE_DOCNAME)/doc + tar cf $(PACKAGE_DOCNAME).tar $(PACKAGE_DOCNAME)/ + bzip2 -9 $(PACKAGE_DOCNAME).tar + rm -rf $(PACKAGE_DOCNAME)/ + mv $(PACKAGE_DOCNAME).tar.bz2 $(top_srcdir) + +clean-local: doc-clean + +else + +doc: + @echo "Documentation not built. Run ./configure --help" + +endif + +EXTRA_DIST = Doxyfile img e.css head.html foot.html evas.dox.in diff --git a/doc/evas.dox.in b/doc/evas.dox.in new file mode 100644 index 0000000..313ae4e --- /dev/null +++ b/doc/evas.dox.in @@ -0,0 +1,222 @@ +/** + +@mainpage Evas +@image latex evas_big.eps width=5cm +@image html evas.png +@version @PACKAGE_VERSION@ +@author Carsten Haitzler +@author Till Adam +@author Steve Ireland +@author Brett Nash +@author Tilman Sauerbeck +@author Corey Donohoe +@author Yuri Hudobin +@author Nathan Ingersoll +@author Willem Monsuwe +@author Vincent Torri +@author Gustavo Barbieri +@author Cedric Bail +@date 2000-2008 + + +@section intro What is Evas? + +Evas is a clean display canvas API for several target display systems that +can draw anti-aliased text, smooth super and sub-sampled scaled images, +alpha-blend objects much and more. + +It abstracts any need to know much about what the characteristics of your +display system are or what graphics calls are used to draw them and how. It +deals on an object level where all you do is create and manipulate objects +in a canvas, set their properties, and the rest is done for you. + +Evas optimises the rendering pipeline to minimise effort in redrawing changes +made to the canvas and so takes this work out of the programmers hand, +saving a lot of time and energy. + +It's small and lean, designed to work on embedded systems all the way to +large and powerful multi-cpu workstations. It can be compiled to only have +the features you need for your target platform if you so wish, thus keeping +it small and lean. It has several display back-ends, letting it display on +several display systems, making it portable for cross-device and +cross-platform development. + + +@section work How does Evas work? + +Evas is a canvas display library. This is markedly different from most +display and windowing systems as a Canvas is structural and is also a state +engine, wheras most display and windowing systems are immediate mode display +targets. Evas handles the logic between a structural display via its' state +engine, and controls the target windowing system in order to produce +rendered results of the current canvases state on the display. + +Immediate mode display systems retain very little, or no state. A program +will execute a series of commands: + +@verbatim +bitmap_handle = create_new_bitmap(); +draw_line(0, 0, 100, 200); +draw_rectangle(10, 30, 50, 500); +draw_bitmap(10, 30, bitmap_handle); +etc. +@endverbatim + +The series of commands is executed by the windowing system and the results +are displayed on the screen (normally). Once the commands are executed the +display system has little or no idea of how to reproduce this image again, +and so has to be instructed by the application how to redraw sections of the +screen whenever needed. Each sucessive command will be executed as +instructed by the application and either emulated by software or sent to the +graphics hardware on the device to be performed. + +The advantage of such a system is that it is simple, and gives a program +tight control over how something looks and is drawn. Given the increasing +complexity of displays and demands by users to have better looking +interfaces, more and more work is needing to be done at this level by the +internals of widget sets, custom display widgets and other programs. This +means more and more logic and display rendering code needs to be written +time and time again, each time the application needs to figure out how to +minimise redraws so that display is fast and interactive, and keep track of +redraw logic. The power comes at a high-price, lots of extra code and work. +Programmers not very familiar with graphics programming will often make +mistakes at this level and produce code that is sub optimal. Those familiar +with this kind of programming will simply get bored by writing the same code +again and again. + +Evas is a structural system in which the programmer creates and manages +display objects and their properties, and as a result of this higher level +state management, the canvas is able to redraw the set of objects when +needed to represent the current state of the canvas. + +For example: + +@verbatim +bitmap_handle = create_bitmap(); +move(bitmap_handle, 10, 30); +show(bitmap_handle); +rectangle_handle = create_rectangle(); +move(rectangle_handle, 10, 30); +resize(rectangle_handle, 50, 500); +show(rectangle_handle); +line_handle = create_line(); +set_line_coords(line_handle, 0, 0, 100, 200); +show(line_handle); +etc. +@endverbatim + +This may look longer, but when the display needs to be refreshed or updated, +the programmer only moves, resizes, shows, hides etc. the objects that they +need to change. The programmer simply thinks at the object logic level, and +the canvas software does the rest of the work for them, figuring out what +actually changed in the canvas since it was last drawn, how to most +efficiently redraw he canvas and its contents to reflect the current state, +and then it can go off and do the actual drawing of the canvas. + +This lets the programmer think in a more natural way when dealing with a +display, and saves time and effort of working out how to load and display +images, render given the current display system etc. Since Evas also is +portable across different display systems, this also gives the programmer +the ability to have their code ported and display on different display +systems with very little work. + +Evas can be seen as a display system that stands somewhere between a widget +set and an immediate mode display system. It retains basic display logic, +but does very little high-level logic such as scrollbars, sliders, push +buttons etc. + + +@section compiling How to compile using Evas? + +Evas is a library your application links to. The proceedure for this is very +simple. You simply have to compile your application with the appropriate +compiler flags that the @p evas-config script outputs. For example: + +Compiling C or C++ files into object files: + +@verbatim +gcc -c -o main.o main.c `pkg-config --cflags evas` +@endverbatim + +Linking object files into a binary executable: + +@verbatim +gcc -o my_application main.o `pkg-config --libs evas` +@endverbatim + +You simply have to make sure that pkg-config is in your shell's PATH (see +the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig +or its path is in the PKG_CONFIG_PATH environment variable. It's that simple +to link and use Evas once you have written your code to use it. + +Since the program is linked to Evas, it is now able to use any advertised +API calls to display graphics in a canvas managed by Evas, as well as use +the API calls provided to manage data as well. + +You should make sure you add any extra compile and link flags to your +compile commands that your application may need as well. The above example +is only guaranteed to make Evas add it's own requirements. + + +@section install How is it installed? + +Simple: + +@verbatim +./configure +make +su - +... +make install +@endverbatim + + +@todo (1.0) Need a way ot scaling an image and just PRODUCING the output (scaling direct to target buffe r- no blend/copy etc.) +@todo (1.0) Could improve evas's scaling down code to limit multiple samples per output pixel to maybe 2x2? +@todo (1.0) Document API +@todo (1.0) Evas needs to check delete_me member for all object functions +@todo (1.0) Evas engine that renders to Evas_Objects +@todo (1.0) OpenGL engine needs to use texture meshes +@todo (1.0) OpenGL engine needs texture cache and size setting +@todo (1.0) OpenGL Engine needs YUV import API to YUV texture +@todo (1.0) All engines need pixel import API +@todo (1.0) Add parital render through composite layer api to engines +@todo (1.0) Move callback processing to a queue and do it asynchronously??? +@todo (1.0) Add button grabbing +@todo (1.0) Add generic object method call system +@todo (1.0) Add callbacks set for smart object parents to be set on all child smart objects too. +@todo (1.0) Define image load errors (and maybe have an error to string func) +@todo (1.0) Add text styles (outline etc.) +@todo (1.0) Add font load query calls (so we know if a font load failed) +@todo (1.0) Add font listing calls +@todo (1.0) Add ability to check image comments & disk format +@todo (1.0) Add group objects +@todo (1.0) Add fontset support +@todo (1.0) Export engine rendering API cleanly to Evas API +@todo (1.0) Add smart object ability to provide rendering callback +@todo (1.1) Make freetype optional and put in optional graymap font engine +@todo (1.1) Free images if object invisible (and put back in chache) +@todo (1.1) Check robustness of malloc/calloc/realloc failures. +@todo (1.1) Add memory use reduction code if any allocations fail +@todo (1.1) If image loads fails due to memory allocatue failure, load reduced res version +@todo (1.1) If image load fails due to memory allocation failure, try split it up into tiles and demand-load them +@todo (1.2) Add external image loaders (application provided callbacks to load) +@todo (1.2) Add loadable image loader module support (evas loads file.so) +@todo (1.2) Add external image loader modules (application provides path to file.so) +@todo (1.3) Add X11 primtive engine (ie pixmap) +@todo (1.3) Add immediate mode drawing commands to image objects +@todo (1.3) Fix FB engine to allocate vt and release properly +@todo (1.4) Add ellipse objects (circle, arc, ellipse etc.) +@todo (1.5) Make software engine draw lines & polys etc. with aa +@todo (1.5) Add radial gradients to gradient objects +@todo (1.5) Add Symbian Engine +@todo (1.6) Add PalmOS Engine +@todo (1.6) Add Apple OpenGL Engine +@todo (1.7) Document engine API and other internals +@todo (1.7) Allow any object to clip any other object, and not just rectangles +@todo (1.8) Add more evas demos +@todo (1.9) Write the error mechanism in evas_xcb_buffer.c +@todo (1.9) Rewrite the render xcb engine +@todo (1.10) Improve Win32 Direct3D Engine + +*/ diff --git a/m4/efl_doxygen.m4 b/m4/efl_doxygen.m4 new file mode 100644 index 0000000..49a3dfa --- /dev/null +++ b/m4/efl_doxygen.m4 @@ -0,0 +1,88 @@ +dnl Copyright (C) 2008 Vincent Torri +dnl That code is public domain and can be freely used or copied. + +dnl Macro that check if doxygen is available or not. + +dnl EFL_CHECK_DOXYGEN([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]) +dnl Test for the doxygen program +dnl Defines DOXYGEN +dnl Defines the automake conditionnal EFL_BUILD_DOC +dnl +AC_DEFUN([EFL_CHECK_DOXYGEN], +[ + +DOXYGEN="doxygen" + +dnl +dnl Disable the build of the documentation +dnl +AC_ARG_ENABLE([doc], + AC_HELP_STRING( + [--disable-doc], + [Disable the build of the documentation]), + [if test "${disable_doc}" = "yes" ; then + enable_doc="no" + else + enable_doc="yes" + fi], + [enable_doc="yes"] +) + +dnl +dnl Specify the full file name, with path +dnl +AC_ARG_WITH([doxygen], + AC_HELP_STRING( + [--with-doxygen=FILE], + [doxygen program to use @<:@default=doxygen@:>@]), + dnl + dnl Check the given doxygen program. + dnl + [DOXYGEN=${withval} + AC_CHECK_PROG([BUILD_DOCS], + [${DOXYGEN}], + [yes], + [no]) + if test "x${BUILD_DOCS}" = "xno" ; then + echo "WARNING:" + echo "The doxygen program you specified:" + echo "$DOXYGEN" + echo "was not found. Please check the path and make sure " + echo "the program exists and is executable." + AC_MSG_WARN([Warning: no doxygen detected. Documentation will not be built]) + fi + ], + [AC_CHECK_PROG([BUILD_DOCS], + [${DOXYGEN}], + [yes], + [no]) + if test "x${BUILD_DOCS}" = "xno" ; then + echo "WARNING:" + echo "The doxygen program was not found in your execute" + echo "You may have doxygen installed somewhere not covered by your path." + echo "" + echo "If this is the case make sure you have the packages installed, AND" + echo "that the doxygen program is in your execute path (see your" + echo "shell manual page on setting the \$PATH environment variable), OR" + echo "alternatively, specify the program to use with --with-doxygen." + AC_MSG_WARN([Warning: no doxygen detected. Documentation will not be built]) + fi + ] +) + +dnl +dnl Substitution +dnl +AC_SUBST([DOXYGEN]) + +AM_CONDITIONAL(EFL_BUILD_DOC, test "x${BUILD_DOCS}" = "xyes") + +if test "x${BUILD_DOCS}" = "xyes" ; then + ifelse([$1], , :, [$1]) +else + ifelse([$2], , :, [$2]) +fi + +]) + +dnl End of doxygen.m4 -- 2.7.4