From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/accel.doc | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 doc/accel.doc (limited to 'doc/accel.doc') diff --git a/doc/accel.doc b/doc/accel.doc new file mode 100644 index 0000000..6641241 --- /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 requirements 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\ 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. + +*/ -- cgit v1.2.3