详细说明

QGLAbstractScene 这个类可以表示由0或更多个 QGLSceneNode 的实例组成的3D场景.

场景一般通过3D程序包创建，然后经由 QGLSceneFormatPlugin 存入应用程序. The functions in this class provide access to major scene objects so that they can be applied or drawn whenever the application decides.

QGLAbstractScene presents a very simple model of a 3D scene. Subclasses implement the specific scene graph and object representations in a manner specific to the package's format. Subclasses may also provide functionality to create new objects at runtime, but this is not required.

The scene is defined to consist of a number of important objects of the following types:

• Camera objects define a viewing position in world-coordinates and a projection that maps 3D world co-ordinates to 2D screen co-ordinates. Camera objects should inherit from QGLCamera.
• Main objects designate the major elements of the scene besides cameras, lights, and effects. Usually they inherit from QGLSceneNode.
• Light objects define positions and parameters for lighting the scene. Light objects should inherit fromQGLLightParameters.
• Effect objects define materials, shaders, and textures for use in rendering the surface of objects. Normally effects are activated automatically when main objects are drawn. But effects can be used independently if the 3D format is acting as a library of effects.
• Mesh objects define geometry information independently of effects. Normally meshes are drawn automatically with an appropriate effect when main objects are drawn. But meshes can be used independently if the 3D format is acting as a library of meshes. Mesh objects should inherit from QGLSceneNode.

Typically, the full scene represented by an external model format is not interesting to the application. 3D modelling packages regularly insert cameras, lights, effects, and other library objects that are useful to the modelling package, but not the application. The mainNode() is usually the most interesting to applications.

QGLAbstractScene makes it easy to access the major scene elements with object(), objects(), and mainNode().

There are many other kinds of objects in the scene that may not be accessible via QGLAbstractScene because they are not considered "important" enough. For example, a file that contains the data for a skateboard object would contain many objects for the board, wheels, texturing effects, animations, and so on. The application may only be interested in the skateboard as a whole, and not its sub-components. The skateboard would be considered an important main object in this case, which can be easily accessed and incorporated into the application's logic.

Each Subclass needs to provide its own policy for deciding which objects are considered "important".

Member Type Documentation

enum QGLAbstractScene::FormatListType

This enum specifies the format of the list returned by the supportedFormats() function.

Member Function Documentation

QGLAbstractScene::QGLAbstractScene ( QObject * parent = 0 )

Constructs a 3D scene and attaches it to parent.

QGLAbstractScene::~QGLAbstractScene () [virtual]

Destroys this 3D scene.

void QGLAbstractScene::generatePickNodes () [virtual]

Generates QGLPickNode instances for important QGLSceneNode instances that are pickable. Objects that are either not important or not pickable can be omitted. The default implementation simply generates pick nodes for every top level object of type QGLSceneNode.

Sub-classes may implement different schemes for picking. When doing so parent the QGLPickNode objects onto the scene, so that they will appear in the list returned by pickNodes()

See also pickNodes() and setPickable().

QGLAbstractScene * QGLAbstractScene::loadScene ( const QUrl & url, const QString & format = QString(), const QString & options = QString() ) [static]

Loads a scene from the internet in the specified format using the registered scene format plugins. If format is an empty string, then the format will be autodetected from the filename extension of the url, which specifies the location of the data online.

The options string is passed to the underlying format loader and its meaning and format depend on the loader. For example the format string for the .3ds loader accepts the following options:

• ForceSmooth - average normals for a smooth appearance
• ForceFaceted - per face normals for a faceted appearance
• NativeIndices - map native indices for poorly smoothed models
• CorrectNormals - fix inverted normals on models with bad windings
• CorrectAcute - fix normals on models that smooth acute angles

The options may be specified globally for the whole model, or just for a particular mesh.

In this example smoothing is forced on globally, and native indices are used on just the mesh called "BattCoverMesh".

 QString op = "ForceSmooth BattCoverMesh=NativeIndices";

 QString url = "http://www.example.url.com/music-player.3ds";

 QGLAbstractScene *scene = QGLAbstractScene::loadScene(url, QString(), op);

Returns the scene object, or null if the scene could not be loaded or the format was not supported by any of the plugins.

The scene object returned by this will contain only a single stub node at the root of the scenegraph, which will be filled out later once the asynchronous download of the scene data is complete.

See also QGLSceneFormatPlugin.

QGLAbstractScene * QGLAbstractScene::loadScene ( QIODevice * device, const QUrl & url, const QString & format = QString(), const QString & options = QString() ) [static]

Loads a scene from device in the specified format using the registered scene format plugins. If format is an empty string, then the format will be autodetected from the filename extension of device. The url specifies the location of the data in device so that relative resources can be located.

The options string is passed to the underlying format loader and its meaning and format depend on the loader. For example the format string for the .3ds loader accepts the following options:

• ForceSmooth - average normals for a smooth appearance
• ForceFaceted - per face normals for a faceted appearance
• NativeIndices - map native indices for poorly smoothed models
• CorrectNormals - fix inverted normals on models with bad windings
• CorrectAcute - fix normals on models that smooth acute angles

The options may be specified globally for the whole model, or just for a particular mesh.

In this example smoothing is forced on globally, and native indices are used on just the mesh called "BattCoverMesh".

 QString op = "ForceSmooth BattCoverMesh=NativeIndices";

 QString file = "music-player.3ds";

 QGLAbstractScene *scene = QGLAbstractScene::loadScene(file, QString(), op);

Returns the scene object, or null if the scene could not be loaded or the format was not supported by any of the plugins.

To debug scene loading export the environment variable QT3D_DEBUG_MODEL, and (depending on backend implementation) the loader can produce useful debugging information on the console.

See also QGLSceneFormatPlugin.

QGLAbstractScene * QGLAbstractScene::loadScene ( const QString & fileName, const QString &format = QString(), const QString & options = QString() ) [static]

Loads a scene from fileName in the specified format, with the supplied options, and using the registered scene format plugins.

If format is an empty string, then the format will be autodetected from the extension of fileName.

The options string is passed to the underlying format loader and its meaning and format depend on the loader. See the doc above for loadScene() for details on the 3ds format options.

Returns the scene object, or null if the scene could not be loaded or the format was not supported by any of the plugins.

See also QGLSceneFormatPlugin.

QGLSceneNode * QGLAbstractScene::mainNode () const [pure virtual]

Returns the main mesh node in the scene, or null if the scene does not contain a main mesh node.

See also objects().

int QGLAbstractScene::nextPickId ()

Increments and returns the next available pick id for this scene.

QObject * QGLAbstractScene::object ( const QString & name ) const [virtual]

Returns the scene object that has the specified name; or null if the object was not found.

The default implementation searches objects() for an object that matches name.

See also objects().

QStringList QGLAbstractScene::objectNames () const [virtual]

Returns a list of the names of all objects in the scene which are considered important, and which have non-empty names associated with them.

The default implementation calls objects() and then compiles a list of all non-empty object names.

See also objects().

QList<QObject *> QGLAbstractScene::objects () const [pure virtual]

Returns a list of all objects in the scene which are considered important.

Important objects will typically be the main mesh object, cameras, lights, and other top-level objects. Sub-meshes and effects are normally not considered important unless the scene is acting as a library of meshes and effects.

See also objectNames(), object(), and mainNode().

QList<QGLPickNode *> QGLAbstractScene::pickNodes () const

Returns a list of the pick nodes that have been parented onto this scene.

See also generatePickNodes().

bool QGLAbstractScene::pickable () const [virtual]

Returns true if this scene is pickable.

See also setPickable().

void QGLAbstractScene::setPickable ( bool enable ) [virtual]

Sets this scene to be pickable if enable is true, otherwise picking is disabled. If the scene is set to be pickable, pick nodes are generated by calling generatePickNodes().

See also generatePickNodes() and pickable().

QStringList QGLAbstractScene::supportedFormats ( FormatListType t = AsFilter ) [static]

Returns a list of all supported formats known by currently available sceneformat plugins, in the format type t.

If t is QGLAbstractScene::AsFilter then the result may be passed to QDir::setNameFilters(), or used in other filters. This is the default.

For example to create a file dialog to load model files use this:

 QString modelsDir = QDir::toNativeSeperators(QDir::homePath());

 QString filter = tr("Models (%1)").arg(QAbstractScene::supportedFormats().join(" "));

 QString fileName = QFileDialog::getOpenFileName(this,

     tr("Open File"), modelsDir, filter));

Otherwise (when t is QGLAbstractScene::AsSuffix) it is simply a list of file name suffixes.

Note that this function may be expensive to call since it scans for available plugins, and loads each one it finds to get an accurate report of formats supported at run-time.