User:Tim.Jenssen/QML Puppet Rendering in Qt Design Studio

Architecture Overview

Qt Design Studio uses a dual-process architecture for QML editing. The main application (GUI, editors, views) talks over a local IPC channel to one or more QML Puppet processes that run headless QML engines and render the items off‑screen.

Dual-process architecture

QML Puppet Side (QML runtime & rendering)	Design Application Side (QML document & editing UI)
No visible window – renders into images QmlRuntime QGuiApplication + QQmlEngine Off‑screen: QQuickWindow + QQuickRenderControl (no QQuickView) NodeInstanceServer instantiates QQuickItems executes commands from the Design Application Side create scene, create instance, update property sends data to the Design Application Side geometries, property values, pixmaps	FormEditorView built on QGraphicsView/QGraphicsScene displays content by receiving rendered images and item data from the QML Puppet Side draws selection borders, anchors, guidelines, and other overlays on top NodeInstanceView non-visual view keeps track of NodeInstance objects live presentation of a QML item on Model change it sends command to QML Puppet monitors the QML puppet’s state(restart on crash)
NodeInstanceClientProxy mediator who dispatches the commands from the Design Application Side to the NodeInstanceServer NodeInstanceClient sends information back to the Design Application Side	NodeInstanceServerProxy send origin commands gets information (geometries, property values) from QML Puppet Side dispatches replies to NodeInstanceView

Data Flow from ModelNode to Rendered Item

• ModelNode = QML DOM node without runtime.
  • Wrapped by QmlItemNode / QmlObjectNode for Qt Quick semantics supplied by the QML Puppet.
• Qt Design Studio launches QML Puppet and calls
  

  QQuickDesignerSupport::activateDesignerMode()
  

  • disables animations & user input during design.
• Qt Design Studio sends a CreateSceneCommand containing the entire ModelNode hierarchy.
  • Each node is paired with an InstanceContainer (type, id …).
• Puppet’s NodeInstanceServer builds real QObject / QQuickItem instances, importing required QML modules.
  • Nodes such as States or Behavior can be skipped or handled specially.
• After instantiation QML Puppet returns:
  • InformationChangedCommand – geometry, implicit size …
  • PixmapChangedCommand – rendered image(s)
• Qt Design Studio NodeInstanceView matches the data by id, updates its NodeInstance cache and triggers a repaint in FormEditorScene.
• Rendering pipeline inside the QML Puppet:
  • Scene graph driven manually via QQuickRenderControl
  • Root item parented to an off‑screen content item inside the hidden QQuickWindow.
  • Grabs whole window or individual items (grabToImage) into QImage`s.
• Large images are transferred through shared memory, and commands travel through a QLocalSocket stream.

Visual Representation Differences (QML Puppet vs Running App)

• Animations paused – timeline is frozen unless explicitly previewed.
• No real user input – mouse / key events are not forwarded by default.
• Native text AA disabled – to avoid platform‑specific artefacts.
• Single‑frame snapshot of OpenGL / particle effects – continuous effects are sampled at render time.
• Root item forced to (0 ; 0) – avoids clipping and simplifies layout.
• Composed by QGraphicsScene – Minor alpha‑blending or DPI rounding differences are possible.