qtquick3dphysics-cooking.qdoc

Go to the documentation of this file.

// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtquick3dphysics-cooking.html
\title Qt Quick 3D Physics Cooking
\brief An explanation of how Qt Quick 3D Physics handles meshes and cooking.
 
When using a mesh as a collision shape it needs to be processed and converted into a data format for efficient collision detection.
This is referred to as 'cooking'.
There are three shape types that need to be cooked before they can be used, namely ConvexMeshShape, TriangleMeshShape and HeightFieldShape.
The cooking happens automatically on the first frame of the simulation when using any of these shapes.
This cooking can incur a noticeable performance cost so to enable faster loading times it is possible to precook the meshes and load them directly.
There are two ways to do this, namely using a cache directory or the cooker tool.
 
\section1 Cache directory
 
To use the cache directory set the \c QT_PHYSICS_CACHE_PATH environment variable to a directory of choice.
When the application runs for the first time all used meshes will be cooked and stored in this directory.
The following times the application runs, the cooked meshes will be read from disk instead of being cooked.
 
\warning The cache directory's files are not validated before being loaded. Loading a malformed
or untrusted cache file may have security implications. Application developers should carefully
consider these before pointing \c QT_PHYSICS_CACHE_PATH at a directory that is writable by other
users or processes.
 
\section1 Cooker tool
 
The other way is to use the \c cooker tool. Build it, then simply call the tool with the mesh or heightfield image as the input argument:
\code
cooker input.mesh
\endcode
or
\code
cooker input.png
\endcode
 
If the input is a mesh it will generate two files:
\list
  \li \c input.cooked.tri
  \li \c input.cooked.cvx
\endlist
 
One file is a cooked triangle mesh and the other a cooked convex mesh.
These can then simply be used as the sources of TriangleMeshShape::source and ConvexMeshShape::source and the meshes will be loaded without any need for cooking.
Similiarily, if the input is an image file a heightfield is generated called \c input.cooked.hf which can then be loaded by referencing it in the HeightFieldShape::source property.
 
 
*/