1 files changed, 140 insertions, 0 deletions
diff --git a/doc/accel.doc b/doc/accel.doc
new file mode 100644
index 000000000..3597eec1b
--- /dev/null
+++ b/doc/accel.doc
@@ -0,0 +1,140 @@
+/****************************************************************************
+**
+** Help with writing Qt/Embedded accelerated drivers
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing retquirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+/*!
+\page emb-accel.html
+
+\title Adding an accelerated graphics driver to Qt/Embedded
+
+Qt/Embedded has the capacity to make use of hardware accelerators.
+To use a hardware accelerator for a PCI or AGP driver, you must
+perform the following steps:
+
+\list 1
+\i 
+Define an accelerated descendant of QLinuxFbScreen. 
+
+This should implement \c QVoodooScreen::connect() to map its
+registers. Use \c qt_probe_bus to get a pointer to the PCI config
+space. This is where you should check that you're being pointed to the
+right device (using the PCI device/manufacturer ID information). Then
+use PCI config space to locate your device's accelerator registers in
+physical memory and mmap the appropriate region from \c /dev/mem.
+There is no need to map the framebuffer, \c QLinuxFbScreen will do
+this for you. Return \c FALSE if a problem occurs at any point. \c
+QVoodooScreen::initDevice() will be called only by the QWS server and
+is guaranteed to be called before any drawing is done (and so is a
+good place to set registers to known states). \c connect() will be called
+by every connecting client.
+
+\i 
+Define an accelerated descendant of QGfxRaster. 
+
+This is where the actual drawing code goes. Anything not implemented
+in hardware can be passed back to \c QGfxRaster to do in software. Use
+the optype variable to make sure that accelerated and unaccelerated
+operations are synchronised (if you start drawing via software into an
+area where the hardware accelerator is still drawing then your drawing
+operations will appear to be in the wrong order). optype is stored in
+shared memory and is set to 0 by unaccelerated operations; accelerated
+operations should set it to 1. When a software graphics operation is
+requested and optype is 1, \c QGfxRaster::sync() is called; you should
+provide your own implementation of this that waits for the graphics
+engine to go idle. lastop is also available for optimisation and is
+stored in the shared space: this will not be set by the software-only
+\c QGfx and can be used to store the type of your last operation (e.g.
+drawing a rectangle) so that part of the setup for the next operation
+can be avoided when many of the same operations are performed in
+sequence.
+
+All drawing operations should be protected via a \c QWSDisplay::grab()
+before any registers, lastop or optype are accessed, and \c
+ungrabbed() at the end. This prevents two applications trying to
+access the accelerator at once and possibly locking up the machine.
+It's possible that your source data is not on the graphics card so you
+should check in such cases and fall back to software if necessary.
+Note that \c QGfxRaster supports some features not directly supported
+by QPainter (for instance, alpha channels in 32-bit data and
+stretchBlt's). These features are used by Qt; stretchBlt speeds up \c
+QPixmap::xForm() and \c drawPixmap() into a transformed \c QPainter,
+alpha channel acceleration is supported for 32-bit pixmaps.
+
+\i
+If you wish, define an accelerated descendant of \c QScreenCursor. \c
+restoreUnder(), \c saveUnder(), \c drawCursor() and \c draw() should
+be defined as null operations. Implement \c set(), \c move(), \c
+show() and \c hide(). 4KB is left for your cursor at the end of the
+visible part of the framebuffer (i.e. at (width*height*depth)/8 )
+
+\i
+Implement \c initCursor() and \c createGfx() in your \c QScreen
+descendant. Implement \c useOffscreen() and return \c TRUE if you can
+make use of offscreen graphics memory.
+
+\i
+Implement a small function \c qt_get_screen_mychip(), which simply
+returns a new \c QMychipScreen
+
+\i
+Add your driver to the DriverTable table in \c qgfxraster_qws.cpp,
+e.g.
+\code
+{ "MyChip", qt_get_screen_mychip,1 },
+\endcode
+
+The first parameter is the name used with QWS_DISPLAY to request your
+accelerated driver.
+
+\i
+To run with your new driver,
+\code
+export QWS_DISPLAY=MyChip 
+\endcode
+(optionally MyChip:/dev/fb\<n\> to request a different Linux
+framebuffer than \c /dev/fb0), then run the program
+
+\endlist
+
+If your driver is not PCI or AGP you'll need to inherit \c QScreen
+instead of \c QLinuxFbScreen and implement similar functionality to \c
+QLinuxFbScreen, but otherwise the process should be similar. The most
+complete example driver is \c qgfxmach64_qws.cpp; \c
+qgfxvoodoo_qws.cpp may provide a smaller and easier-to-understand
+driver.
+
+*/