1 files changed, 67 insertions, 0 deletions
diff --git a/examples/wayland/minimal-cpp/doc/src/minimal-cpp.qdoc b/examples/wayland/minimal-cpp/doc/src/minimal-cpp.qdoc
new file mode 100644
index 000000000..3d6894de4
--- /dev/null
+++ b/examples/wayland/minimal-cpp/doc/src/minimal-cpp.qdoc
@@ -0,0 +1,67 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+  \title Minimal CPP
+  \example minimal-cpp
+  \examplecategory {Embedded}
+  \brief Minimal CPP is an example that demonstrates how to write a Wayland compositor in C++.
+  \ingroup qtwaylandcompositor-examples
+
+  Minimal CPP is a minimalistic compositor example implementing a complete Qt Wayland Compositor
+  using C++. The C++ API of QtWaylandCompositor is low-level and intended for specialized
+  applications, such as supporting hardware features, or if Qt Quick is not available.  The QML API
+  offers more convenience and functionality. For comparison, the
+  \l{Minimal QML}{Minimal QML example} implements more functionality with 30 lines of QML than this
+  example does in 300+ lines.
+
+  \image minimal-cpp.jpg
+
+  This example is split in two parts. The Wayland logic is contained in the \c Compositor class,
+  and the user interface is in the \c Window class.
+
+  \section1 Window
+
+  The \c Window class is fairly straight-forward. To display the Wayland surfaces, it iterates
+  through the compositor's views and renders them on the screen using \l QOpenGLTextureBlitter:
+
+  \snippet minimal-cpp/window.cpp paintGL
+
+  All keyboard and mouse events are delivered to the compositor. For example:
+
+  \snippet minimal-cpp/window.cpp mousePressEvent
+
+  \section1 Compositor
+
+  The \c Compositor class is more complex, since it has to implement much of the logic that would
+  be handled by \l[QML]{WaylandCompositor} and \l[QML]{WaylandQuickItem} in a QML-based compositor.
+
+  The \c create function sets up the compositor, using the IviApplication, which is the most basic
+  shell extension. The function is called after the OpenGL context has been initialized:
+
+  \snippet minimal-cpp/compositor.cpp create
+
+  All the logic for mouse events and keyboard focus has to be implemented manually, including
+  implicit mouse grabs (sending all mouse moves to the surface that received the initial mouse
+  press). Note that mouse press events in the Wayland protocol do not contain the mouse position,
+  so we always have to send a mouse move when we reveive a mouse press:
+
+  \snippet minimal-cpp/compositor.cpp handleMousePress
+
+  For a mouse release, we end the implicit grab and notify the surface at the current mouse position:
+
+  \snippet minimal-cpp/compositor.cpp handleMousePress
+
+  When we are notified of a new surface, we create a \c View to keep track of it, and connect
+  signals so we can handle updates.
+
+  \snippet minimal-cpp/compositor.cpp surfaceCreated
+
+  The \c View class subclasses QWaylandView, which represents a specific view of a surface. The
+  \l {QWaylandView::advance}{advance} function updates the view's current buffer and returns true
+  if there is new content. The \c getTexture function makes the buffer contents available as an
+  OpenGL texture for the benefit of the \c Window class:
+
+  \snippet minimal-cpp/compositor.cpp getTexture
+
+*/