From 084306783828839b957ef5073a477122f7aed679 Mon Sep 17 00:00:00 2001 From: Christiaan Janssen Date: Tue, 18 Dec 2012 13:00:29 +0100 Subject: Qt Gui Examples: Fixed QDoc files Change-Id: I160d8d186a1078f20f2b779bfbdae90459c27641 Reviewed-by: Jerome Pasion --- examples/gui/doc/analogclockwindow.qdoc | 138 ------------------------ examples/gui/doc/openglwindow.qdoc | 156 --------------------------- examples/gui/doc/rasterwindow.qdoc | 161 ---------------------------- examples/gui/doc/src/analogclockwindow.qdoc | 138 ++++++++++++++++++++++++ examples/gui/doc/src/openglwindow.qdoc | 156 +++++++++++++++++++++++++++ examples/gui/doc/src/rasterwindow.qdoc | 161 ++++++++++++++++++++++++++++ 6 files changed, 455 insertions(+), 455 deletions(-) delete mode 100644 examples/gui/doc/analogclockwindow.qdoc delete mode 100644 examples/gui/doc/openglwindow.qdoc delete mode 100644 examples/gui/doc/rasterwindow.qdoc create mode 100644 examples/gui/doc/src/analogclockwindow.qdoc create mode 100644 examples/gui/doc/src/openglwindow.qdoc create mode 100644 examples/gui/doc/src/rasterwindow.qdoc (limited to 'examples/gui') diff --git a/examples/gui/doc/analogclockwindow.qdoc b/examples/gui/doc/analogclockwindow.qdoc deleted file mode 100644 index ff361a27b1..0000000000 --- a/examples/gui/doc/analogclockwindow.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example analogclock - \title Analog Clock Window Example - - \brief The Analog Clock Window example shows how to draw the contents of - a custom window. - - \image analogclock-window-example.png Screenshot of the Analog - Clock Window example - - This example demonstrates how the transformation and scaling - features of QPainter can be used to make drawing easier. - - \section1 AnalogClockWindow Class Definition - - The \c AnalogClockWindow class provides a clock with hour and - minute hands that is automatically updated every few seconds. We - make use of the RasterWindow from the \l {Raster Window Example} - and reimplement the \c render function to draw the clock face: - - \snippet analogclock/main.cpp 5 - - \section1 AnalogClock Class Implementation - - \snippet analogclock/main.cpp 6 - - We set a title on the window and resize to a reasonable size. Then - we start a timer which we will use to redraw the clock every - second. - - \snippet analogclock/main.cpp 7 - - The timerEvent function is called every second as a result of - our startTimer call. Making use of the convenience in the base - class, we schedule the window to be repainted. - - Checking the timer's id is not strictly needed as we only have - one active timer in this instance, but it is good practice to do - so. - - \snippet analogclock/main.cpp 14 - \snippet analogclock/main.cpp 8 - - Before we set up the painter and draw the clock, we first define - two lists of \l {QPoint}s and two \l{QColor}s that will be used - for the hour and minute hands. The minute hand's color has an - alpha component of 191, meaning that it's 75% opaque. - - \snippet analogclock/main.cpp 9 - - We call QPainter::setRenderHint() with QPainter::Antialiasing to - turn on antialiasing. This makes drawing of diagonal lines much - smoother. - - \snippet analogclock/main.cpp 10 - - The translation moves the origin to the center of the window, and - the scale operation ensures that the following drawing operations - are scaled to fit within the window. We use a scale factor that - let's us use x and y coordinates between -100 and 100, and that - ensures that these lie within the length of the window's shortest - side. - - To make our code simpler, we will draw a fixed size clock face that will - be positioned and scaled so that it lies in the center of the window. - - We also determine the length of the window's shortest side so that we - can fit the clock face inside the window. - - The painter takes care of all the transformations made during the - rendering, and ensures that everything is drawn correctly. Letting - the painter handle transformations is often easier than performing - manual calculations. - - \image analogclockwindow-viewport.png - - We draw the hour hand first, using a formula that rotates the coordinate - system counterclockwise by a number of degrees determined by the current - hour and minute. This means that the hand will be shown rotated clockwise - by the required amount. - - \snippet analogclock/main.cpp 11 - - We set the pen to be Qt::NoPen because we don't want any outline, - and we use a solid brush with the color appropriate for - displaying hours. Brushes are used when filling in polygons and - other geometric shapes. - - \snippet analogclock/main.cpp 2 - - We save and restore the transformation matrix before and after the - rotation because we want to place the minute hand without having to - take into account any previous rotations. - - \snippet analogclock/main.cpp 12 - - We draw markers around the edge of the clock for each hour. We - draw each marker then rotate the coordinate system so that the - painter is ready for the next one. - - \snippet analogclock/main.cpp 13 - \snippet analogclock/main.cpp 3 - - The minute hand is rotated in a similar way to the hour hand. - - \snippet analogclock/main.cpp 4 - - Again, we draw markers around the edge of the clock, but this - time to indicate minutes. We skip multiples of 5 to avoid drawing - minute markers on top of hour markers. -*/ diff --git a/examples/gui/doc/openglwindow.qdoc b/examples/gui/doc/openglwindow.qdoc deleted file mode 100644 index d26fd477af..0000000000 --- a/examples/gui/doc/openglwindow.qdoc +++ /dev/null @@ -1,156 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example openglwindow - \title OpenGL Window Example - - \brief This example shows how to create a minimal QWindow based application - for the purpose of using OpenGL. - - \image openglwindow-example.png Screenshot of the OpenGLWindow example - - \section1 OpenGLWindow super class - - Our OpenGLWindow class acts as an API which is then subclassed to do the - actual rendering. It has functions to make a request for render() to be - called, either immediately with renderNow() or as soon as the event loop - has finished processing the current batch of events with renderLater(). - The OpenGLWindow subclass can either reimplement render() for OpenGL based - rendering, or render(QPainter *) for rendering with a QPainter. Use - OpenGLWindow::setAnimating(true) for render() to be called at the vertical - refresh rate, assuming vertical sync is enabled in the underlying OpenGL - drivers. - - In the class that does the OpenGL rendering you will typically want to - inherit from QOpenGLFunctions, as our OpenGLWindow does, in order to get - platform independent access to OpenGL ES 2.0 functions. By inheriting from - QOpenGLFunctions the OpenGL functions it contains will get precedence, and - you will not have to worry about resolving those functions if you want your - application to work with OpenGL as well as OpenGL ES 2.0. - - \snippet openglwindow/openglwindow.h 1 - - The window's surface type must be set to QSurface::OpenGLSurface to - indicate that the window is to be used for OpenGL rendering and not for - rendering raster content with QPainter using a QBackingStore. - - \snippet openglwindow/openglwindow.cpp 1 - - Any OpenGL initialization needed can be done by overriding the initialize() - function, which is called once before the first call to render(), with a - valid current QOpenGLContext. As can be seen in the following code snippet, - the default render(QPainter *) and initialize() implementations are empty, - whereas the default render() implementation initializes a - QOpenGLPaintDevice and then calls into render(QPainter *). - - \snippet openglwindow/openglwindow.cpp 2 - - The renderLater() function simply puts an update request event on - the event loop, which leads to renderNow() being called once the event - gets processed. - - We also call renderNow() when we get an expose event. The exposeEvent() is - the notification to the window that its exposure, meaning visibility, on - the screen has changed. When the expose event is received you can query - QWindow::isExposed() to find out whether or not the window is currently - exposed. Do not render to or call QOpenGLContext::swapBuffers() on a window - before it has received its first expose event, as before then its final - size might be unknown, and in addition what is rendered might not even end - up on the screen. - - \snippet openglwindow/openglwindow.cpp 3 - - In renderNow() we return if we are not currently exposed, in which case - rendering is delayed until we actually get an expose event. If we have not - yet done so, we create the QOpenGLContext with the same QSurfaceFormat as - was set on the OpenGLWindow, and call initialize() for the sake of the sub - class, and initializeOpenGLFunctions() in order for the QOpenGLFunctions - super class to be associated with the correct QOpenGLContext. In any case - we make the context current by calling QOpenGLContext::makeCurrent(), call - render() to do the actual rendering, and finally we schedule for the - rendered contents to be made visible by calling - QOpenGLContext::swapBuffers() with the OpenGLWindow as parameter. - - Once the rendering of a frame using an OpenGL context is initiated by - calling QOpenGLContext::makeCurrent(), giving the surface on which to - render as a parameter, OpenGL commands can be issued. The commands can be - issued either directly by including , which also includes the - system's OpenGL headers, or as by using QOpenGLFunctions, which can - either be inherited from for convenience, or accessed using - QOpenGLContext::functions(). QOpenGLFunctions gives access to all the - OpenGL ES 2.0 level OpenGL calls that are not already standard in both - OpenGL ES 2.0 and desktop OpenGL. For more information about the OpenGL and - OpenGL ES APIs, refer to the official \l{http://www.opengl.org/registry/}{OpenGL Registry} and - \l {http://www.khronos.org/registry/gles/}{Khronos OpenGL ES API Registry}. - - If animation has been enabled with OpenGLWindow::setAnimating(true), we - call renderLater() to put another update request on the event loop. - - \snippet openglwindow/openglwindow.cpp 4 - - Enabling animation also triggers an update request as shown in the - following code snippet. - - \snippet openglwindow/openglwindow.cpp 5 - - \section1 Example OpenGL rendering sub class - - Here we sub class OpenGLWindow to show how to do OpenGL to render a - rotating triangle. By indirectly sub classing QOpenGLFunctions we gain - access to all OpenGL ES 2.0 level functionality. - - \snippet openglwindow/main.cpp 1 - - In our main function we initialize QGuiApplication and instantiate our - TriangleOpenGLWindow. We give it a QSurfaceFormat specifying that we want - four samples of multisample antialiasing, as well as a default geometry. - Since we want to have animation we call the above mentioned setAnimating() - function with an argument of true. - - \snippet openglwindow/main.cpp 2 - - The following code snippet shows the OpenGL shader program used in this - example. The vertex and fragment shaders are relatively simple, doing - vertex transformation and interpolated vertex coloring. - - \snippet openglwindow/main.cpp 3 - - Here is the code that loads the shaders and initializes the shader program - By using QOpenGLShaderProgram instead of raw OpenGL we get the convenience - that strips out the highp, mediump, and lowp qualifiers on desktop OpenGL, - where they are not part of the standard. We store the attribute and uniform - locations in member variables to avoid having to do the location lookup - each frame. - - \snippet openglwindow/main.cpp 4 - - Finally, here is our render() function, where we use OpenGL to set up the - viewport, clear the background, and render a rotating triangle. - - \snippet openglwindow/main.cpp 5 -*/ diff --git a/examples/gui/doc/rasterwindow.qdoc b/examples/gui/doc/rasterwindow.qdoc deleted file mode 100644 index f246533c4f..0000000000 --- a/examples/gui/doc/rasterwindow.qdoc +++ /dev/null @@ -1,161 +0,0 @@ -**************************************************************************** -** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example rasterwindow - \title Raster Window Example - - \brief This example shows how to create a minimal QWindow based - application using QPainter for rendering. - - - \section1 Application Entry Point - - \snippet rasterwindow/main.cpp 1 - - The entry point for a QWindow based application is the \l - QGuiApplication class. It manages the GUI application's control - flow and main settings. We pass the command line arguments which - can be used to pick up certain system wide options. - - From there, we go on to create our window instance and then call - the \l QWindow::show() function to tell the windowing system that - this window should now be made visible on screen. - - Once this is done, we enter the application's event loop so the - application can run. - - - \section1 RasterWindow Declaration - - \snippet rasterwindow/rasterwindow.h 1 - - We first start by including the the QtGui headers. This means we - can use all classes in the Qt GUI module. Classes can also be - included individually if that is preferred. - - The RasterWindow class subclasses QWindow directly and provides a - constructor which allows the window to be a sub-window of another - QWindow. Parent-less QWindows show up in the windowing system as - top-level windows. - - The class declares a QBackingStore which is what we use to manage - the window's back buffer for QPainter based graphics. - - \e {The raster window is also reused in a few other examples and adds - a few helper functions, like renderLater().} - - - \section1 RasterWindow Implementation - - \snippet rasterwindow/rasterwindow.cpp 1 - - The constructor first of all calls \l QWindow::create(). This will - create the window in the windowing system. Without calling create, - the window will not get events and will not be visible in the - windowing system. The call to create does not show the window. We - then set the geometry to be something reasonable. - - Then we create the backingstore and pass it the window instance it - is supposed to manage. - - \snippet rasterwindow/rasterwindow.cpp 2 - - Shortly after calling \l QWindow::show() on a created window, the - virtual function \l QWindow::exposeEvent() will be called to - notify us that the window's exposure in the windowing system has - changed. The event contains the exposed sub-region, but since we - will anyway draw the entire window every time, we do not make use - of that. - - The function \l QWindow::isExposed() will tell us if the window is - showing or not. We need this as the exposeEvent is called also - when the window becomes obscured in the windowing system. If the - window is showing, we call renderNow() to draw the window - immediately. We want to draw right away so we can present the - system with some visual content. - - - \snippet rasterwindow/rasterwindow.cpp 5 - - The resize event is guaranteed to be called prior to the window - being shown on screen and will also be called whenever the window - is resized while on screen. We use this to resize the back buffer - and call renderNow() if we are visible to immediately update the - visual representation of the window on screen. - - \snippet rasterwindow/rasterwindow.cpp 3 - - The renderNow function sets up what is needed for a \l QWindow to - render its content using QPainter. As obscured windows have will - not be visible, we abort if the window is not exposed in the - windowing system. This can for instance happen when another window - fully obscures this window. - - We start the drawing by calling \l QBackingStore::beginPaint() on - the region we want to draw. Then we get the \l QPaintDevice of the - back buffer and create a QPainter to render to that paint device. - - To void leaving traces from the previous rendering and start with a - clean buffer, we fill the entire buffer with the color white. Then - we call the virtual render() function which does the actual - drawing of this window. - - After drawing is complete, we call endPaint() to signal that we - are done rendering and present the contents in the back buffer - using \l QBackingStore::flush(). - - - \snippet rasterwindow/rasterwindow.cpp 4 - - The render function contains the drawing code for the window. In - this minial example, we only draw the string "QWindow" in the - center. - - - \section1 Rendering Asynchronously - - - \snippet rasterwindow/rasterwindow.cpp 6 - - We went through a few places where the window needed to repainted - immediately. There are some cases where this is not desierable, - but rather let the application return to the event loop and - later. We acheive this by posting an even to ourself which will - then be delivered when the application returns to the \l - QGuiApplication event loop. To avoid posting new requests when one - is already pending, we store this state in the \c m_update_pending - variable. - - \snippet rasterwindow/rasterwindow.cpp 7 - - We reimplement the virtual \l QObject::event() function to handle - the update event we posted to ourselves. When the event comes in - we reset the pending update flag and call renderNow() to render - the window right away. - - */ diff --git a/examples/gui/doc/src/analogclockwindow.qdoc b/examples/gui/doc/src/analogclockwindow.qdoc new file mode 100644 index 0000000000..ff361a27b1 --- /dev/null +++ b/examples/gui/doc/src/analogclockwindow.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example analogclock + \title Analog Clock Window Example + + \brief The Analog Clock Window example shows how to draw the contents of + a custom window. + + \image analogclock-window-example.png Screenshot of the Analog + Clock Window example + + This example demonstrates how the transformation and scaling + features of QPainter can be used to make drawing easier. + + \section1 AnalogClockWindow Class Definition + + The \c AnalogClockWindow class provides a clock with hour and + minute hands that is automatically updated every few seconds. We + make use of the RasterWindow from the \l {Raster Window Example} + and reimplement the \c render function to draw the clock face: + + \snippet analogclock/main.cpp 5 + + \section1 AnalogClock Class Implementation + + \snippet analogclock/main.cpp 6 + + We set a title on the window and resize to a reasonable size. Then + we start a timer which we will use to redraw the clock every + second. + + \snippet analogclock/main.cpp 7 + + The timerEvent function is called every second as a result of + our startTimer call. Making use of the convenience in the base + class, we schedule the window to be repainted. + + Checking the timer's id is not strictly needed as we only have + one active timer in this instance, but it is good practice to do + so. + + \snippet analogclock/main.cpp 14 + \snippet analogclock/main.cpp 8 + + Before we set up the painter and draw the clock, we first define + two lists of \l {QPoint}s and two \l{QColor}s that will be used + for the hour and minute hands. The minute hand's color has an + alpha component of 191, meaning that it's 75% opaque. + + \snippet analogclock/main.cpp 9 + + We call QPainter::setRenderHint() with QPainter::Antialiasing to + turn on antialiasing. This makes drawing of diagonal lines much + smoother. + + \snippet analogclock/main.cpp 10 + + The translation moves the origin to the center of the window, and + the scale operation ensures that the following drawing operations + are scaled to fit within the window. We use a scale factor that + let's us use x and y coordinates between -100 and 100, and that + ensures that these lie within the length of the window's shortest + side. + + To make our code simpler, we will draw a fixed size clock face that will + be positioned and scaled so that it lies in the center of the window. + + We also determine the length of the window's shortest side so that we + can fit the clock face inside the window. + + The painter takes care of all the transformations made during the + rendering, and ensures that everything is drawn correctly. Letting + the painter handle transformations is often easier than performing + manual calculations. + + \image analogclockwindow-viewport.png + + We draw the hour hand first, using a formula that rotates the coordinate + system counterclockwise by a number of degrees determined by the current + hour and minute. This means that the hand will be shown rotated clockwise + by the required amount. + + \snippet analogclock/main.cpp 11 + + We set the pen to be Qt::NoPen because we don't want any outline, + and we use a solid brush with the color appropriate for + displaying hours. Brushes are used when filling in polygons and + other geometric shapes. + + \snippet analogclock/main.cpp 2 + + We save and restore the transformation matrix before and after the + rotation because we want to place the minute hand without having to + take into account any previous rotations. + + \snippet analogclock/main.cpp 12 + + We draw markers around the edge of the clock for each hour. We + draw each marker then rotate the coordinate system so that the + painter is ready for the next one. + + \snippet analogclock/main.cpp 13 + \snippet analogclock/main.cpp 3 + + The minute hand is rotated in a similar way to the hour hand. + + \snippet analogclock/main.cpp 4 + + Again, we draw markers around the edge of the clock, but this + time to indicate minutes. We skip multiples of 5 to avoid drawing + minute markers on top of hour markers. +*/ diff --git a/examples/gui/doc/src/openglwindow.qdoc b/examples/gui/doc/src/openglwindow.qdoc new file mode 100644 index 0000000000..d26fd477af --- /dev/null +++ b/examples/gui/doc/src/openglwindow.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example openglwindow + \title OpenGL Window Example + + \brief This example shows how to create a minimal QWindow based application + for the purpose of using OpenGL. + + \image openglwindow-example.png Screenshot of the OpenGLWindow example + + \section1 OpenGLWindow super class + + Our OpenGLWindow class acts as an API which is then subclassed to do the + actual rendering. It has functions to make a request for render() to be + called, either immediately with renderNow() or as soon as the event loop + has finished processing the current batch of events with renderLater(). + The OpenGLWindow subclass can either reimplement render() for OpenGL based + rendering, or render(QPainter *) for rendering with a QPainter. Use + OpenGLWindow::setAnimating(true) for render() to be called at the vertical + refresh rate, assuming vertical sync is enabled in the underlying OpenGL + drivers. + + In the class that does the OpenGL rendering you will typically want to + inherit from QOpenGLFunctions, as our OpenGLWindow does, in order to get + platform independent access to OpenGL ES 2.0 functions. By inheriting from + QOpenGLFunctions the OpenGL functions it contains will get precedence, and + you will not have to worry about resolving those functions if you want your + application to work with OpenGL as well as OpenGL ES 2.0. + + \snippet openglwindow/openglwindow.h 1 + + The window's surface type must be set to QSurface::OpenGLSurface to + indicate that the window is to be used for OpenGL rendering and not for + rendering raster content with QPainter using a QBackingStore. + + \snippet openglwindow/openglwindow.cpp 1 + + Any OpenGL initialization needed can be done by overriding the initialize() + function, which is called once before the first call to render(), with a + valid current QOpenGLContext. As can be seen in the following code snippet, + the default render(QPainter *) and initialize() implementations are empty, + whereas the default render() implementation initializes a + QOpenGLPaintDevice and then calls into render(QPainter *). + + \snippet openglwindow/openglwindow.cpp 2 + + The renderLater() function simply puts an update request event on + the event loop, which leads to renderNow() being called once the event + gets processed. + + We also call renderNow() when we get an expose event. The exposeEvent() is + the notification to the window that its exposure, meaning visibility, on + the screen has changed. When the expose event is received you can query + QWindow::isExposed() to find out whether or not the window is currently + exposed. Do not render to or call QOpenGLContext::swapBuffers() on a window + before it has received its first expose event, as before then its final + size might be unknown, and in addition what is rendered might not even end + up on the screen. + + \snippet openglwindow/openglwindow.cpp 3 + + In renderNow() we return if we are not currently exposed, in which case + rendering is delayed until we actually get an expose event. If we have not + yet done so, we create the QOpenGLContext with the same QSurfaceFormat as + was set on the OpenGLWindow, and call initialize() for the sake of the sub + class, and initializeOpenGLFunctions() in order for the QOpenGLFunctions + super class to be associated with the correct QOpenGLContext. In any case + we make the context current by calling QOpenGLContext::makeCurrent(), call + render() to do the actual rendering, and finally we schedule for the + rendered contents to be made visible by calling + QOpenGLContext::swapBuffers() with the OpenGLWindow as parameter. + + Once the rendering of a frame using an OpenGL context is initiated by + calling QOpenGLContext::makeCurrent(), giving the surface on which to + render as a parameter, OpenGL commands can be issued. The commands can be + issued either directly by including , which also includes the + system's OpenGL headers, or as by using QOpenGLFunctions, which can + either be inherited from for convenience, or accessed using + QOpenGLContext::functions(). QOpenGLFunctions gives access to all the + OpenGL ES 2.0 level OpenGL calls that are not already standard in both + OpenGL ES 2.0 and desktop OpenGL. For more information about the OpenGL and + OpenGL ES APIs, refer to the official \l{http://www.opengl.org/registry/}{OpenGL Registry} and + \l {http://www.khronos.org/registry/gles/}{Khronos OpenGL ES API Registry}. + + If animation has been enabled with OpenGLWindow::setAnimating(true), we + call renderLater() to put another update request on the event loop. + + \snippet openglwindow/openglwindow.cpp 4 + + Enabling animation also triggers an update request as shown in the + following code snippet. + + \snippet openglwindow/openglwindow.cpp 5 + + \section1 Example OpenGL rendering sub class + + Here we sub class OpenGLWindow to show how to do OpenGL to render a + rotating triangle. By indirectly sub classing QOpenGLFunctions we gain + access to all OpenGL ES 2.0 level functionality. + + \snippet openglwindow/main.cpp 1 + + In our main function we initialize QGuiApplication and instantiate our + TriangleOpenGLWindow. We give it a QSurfaceFormat specifying that we want + four samples of multisample antialiasing, as well as a default geometry. + Since we want to have animation we call the above mentioned setAnimating() + function with an argument of true. + + \snippet openglwindow/main.cpp 2 + + The following code snippet shows the OpenGL shader program used in this + example. The vertex and fragment shaders are relatively simple, doing + vertex transformation and interpolated vertex coloring. + + \snippet openglwindow/main.cpp 3 + + Here is the code that loads the shaders and initializes the shader program + By using QOpenGLShaderProgram instead of raw OpenGL we get the convenience + that strips out the highp, mediump, and lowp qualifiers on desktop OpenGL, + where they are not part of the standard. We store the attribute and uniform + locations in member variables to avoid having to do the location lookup + each frame. + + \snippet openglwindow/main.cpp 4 + + Finally, here is our render() function, where we use OpenGL to set up the + viewport, clear the background, and render a rotating triangle. + + \snippet openglwindow/main.cpp 5 +*/ diff --git a/examples/gui/doc/src/rasterwindow.qdoc b/examples/gui/doc/src/rasterwindow.qdoc new file mode 100644 index 0000000000..f246533c4f --- /dev/null +++ b/examples/gui/doc/src/rasterwindow.qdoc @@ -0,0 +1,161 @@ +**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example rasterwindow + \title Raster Window Example + + \brief This example shows how to create a minimal QWindow based + application using QPainter for rendering. + + + \section1 Application Entry Point + + \snippet rasterwindow/main.cpp 1 + + The entry point for a QWindow based application is the \l + QGuiApplication class. It manages the GUI application's control + flow and main settings. We pass the command line arguments which + can be used to pick up certain system wide options. + + From there, we go on to create our window instance and then call + the \l QWindow::show() function to tell the windowing system that + this window should now be made visible on screen. + + Once this is done, we enter the application's event loop so the + application can run. + + + \section1 RasterWindow Declaration + + \snippet rasterwindow/rasterwindow.h 1 + + We first start by including the the QtGui headers. This means we + can use all classes in the Qt GUI module. Classes can also be + included individually if that is preferred. + + The RasterWindow class subclasses QWindow directly and provides a + constructor which allows the window to be a sub-window of another + QWindow. Parent-less QWindows show up in the windowing system as + top-level windows. + + The class declares a QBackingStore which is what we use to manage + the window's back buffer for QPainter based graphics. + + \e {The raster window is also reused in a few other examples and adds + a few helper functions, like renderLater().} + + + \section1 RasterWindow Implementation + + \snippet rasterwindow/rasterwindow.cpp 1 + + The constructor first of all calls \l QWindow::create(). This will + create the window in the windowing system. Without calling create, + the window will not get events and will not be visible in the + windowing system. The call to create does not show the window. We + then set the geometry to be something reasonable. + + Then we create the backingstore and pass it the window instance it + is supposed to manage. + + \snippet rasterwindow/rasterwindow.cpp 2 + + Shortly after calling \l QWindow::show() on a created window, the + virtual function \l QWindow::exposeEvent() will be called to + notify us that the window's exposure in the windowing system has + changed. The event contains the exposed sub-region, but since we + will anyway draw the entire window every time, we do not make use + of that. + + The function \l QWindow::isExposed() will tell us if the window is + showing or not. We need this as the exposeEvent is called also + when the window becomes obscured in the windowing system. If the + window is showing, we call renderNow() to draw the window + immediately. We want to draw right away so we can present the + system with some visual content. + + + \snippet rasterwindow/rasterwindow.cpp 5 + + The resize event is guaranteed to be called prior to the window + being shown on screen and will also be called whenever the window + is resized while on screen. We use this to resize the back buffer + and call renderNow() if we are visible to immediately update the + visual representation of the window on screen. + + \snippet rasterwindow/rasterwindow.cpp 3 + + The renderNow function sets up what is needed for a \l QWindow to + render its content using QPainter. As obscured windows have will + not be visible, we abort if the window is not exposed in the + windowing system. This can for instance happen when another window + fully obscures this window. + + We start the drawing by calling \l QBackingStore::beginPaint() on + the region we want to draw. Then we get the \l QPaintDevice of the + back buffer and create a QPainter to render to that paint device. + + To void leaving traces from the previous rendering and start with a + clean buffer, we fill the entire buffer with the color white. Then + we call the virtual render() function which does the actual + drawing of this window. + + After drawing is complete, we call endPaint() to signal that we + are done rendering and present the contents in the back buffer + using \l QBackingStore::flush(). + + + \snippet rasterwindow/rasterwindow.cpp 4 + + The render function contains the drawing code for the window. In + this minial example, we only draw the string "QWindow" in the + center. + + + \section1 Rendering Asynchronously + + + \snippet rasterwindow/rasterwindow.cpp 6 + + We went through a few places where the window needed to repainted + immediately. There are some cases where this is not desierable, + but rather let the application return to the event loop and + later. We acheive this by posting an even to ourself which will + then be delivered when the application returns to the \l + QGuiApplication event loop. To avoid posting new requests when one + is already pending, we store this state in the \c m_update_pending + variable. + + \snippet rasterwindow/rasterwindow.cpp 7 + + We reimplement the virtual \l QObject::event() function to handle + the update event we posted to ourselves. When the event comes in + we reset the pending update flag and call renderNow() to render + the window right away. + + */ -- cgit v1.2.3