3.1 场景查询
上一节把相机、视口与投影算清楚了,这一节开始问一个问题:场景里某个区域到底有什么。拾取(把鼠标点转成世界射线、问它打中了谁)、AI 感知、范围搜索,都是这种「区域 → 对象列表」的查询。OGRE 把它统一抽象成 SceneQuery:一种按包围体积做事前粗筛、结果只保证「潜在相交」的机制。注意 OGRE 文档自己强调过那个词——potentially,查询基于包围盒,三角形级别的精确判定要由调用方继续做。
本章与站内既有内容的分工
helio 四卷是 TypeScript 从零实现,不碰这份接口;cg 三卷讲图形学原理,不落成类;卷一 ogre-core 只讲到 SceneManager 有查询职责但没展开;卷二 ogre-render 讲渲染队列怎么消费可见对象。本节的 SceneQuery 体系正是「场景内容侧」第一个真正落地到类的可见性机制——它和 3.2 的视锥剔除、3.3 的 Octree 一起,构成卷三第 3 章「可见性剔除」。
SceneQuery 基类与查询掩码
OgreSceneQuery.h 开头就把语义说清楚了:查询结果基于包围体积生成,不是三角形级精确。不同 SceneManager 用各自的场景组织实现不同子类,而「查询掩码」让应用自己决定每个比特的含义:
// OgreMain/include/OgreSceneQuery.h:SceneQuery(v14.6.3 教学示意,参照上游同名实现,已删减)
class _OgreExport SceneQuery : public SceneMgtAlloc
{
protected:
SceneManager* mParentSceneMgr;
uint32 mQueryMask;
uint32 mQueryTypeMask;
public:
/** Standard constructor, should be called by SceneManager. */
SceneQuery(SceneManager* mgr);
virtual ~SceneQuery();
/** Sets the mask for results of this query. ...
The actual meaning of this value is up to the application; basically
MovableObject instances will only be returned from this query if a
bitwise AND operation between this mask value and the
MovableObject::getQueryFlags value is non-zero.
*/
virtual void setQueryMask(uint32 mask);
/** Returns the current mask for this query. */
virtual uint32 getQueryMask(void) const;
/** Sets the type mask for results of this query. ...
Both may exclude an object from query results.
*/
virtual void setQueryTypeMask(uint32 mask);
/** Returns the current mask for this query. */
virtual uint32 getQueryTypeMask(void) const;
};
构造时 mQueryMask 默认 0xFFFFFFFF(全放行),mQueryTypeMask 默认排除灯光与特效——这是「逐实例旗标」与「逐类型旗标」两条独立过滤线,一个对象要被查中,两条都得通过。MovableObject 一侧对应的旗标接口在卷一已经出现过:setQueryFlags 存到 mQueryFlags,查询执行时用 mQueryMask & obj->getQueryFlags() 是否非零决定要不要结果里带上它。位非零即返回,含义由应用自定义,这就是 OGRE 不做「谁是谁」的硬编码、把语义交给上层的原因。
区域查询:球、盒与平面体积
RegionSceneQuery 是「区域返回一批对象」的中间抽象,下面按区域形状分三种:轴对齐盒、球、平面包围体积。它们各自只多一个成员——存住查询用的那个区域对象:
// OgreMain/include/OgreSceneQuery.h:SphereSceneQuery(v14.6.3 源码摘录,已删减)
/** Specialises the SceneQuery class for querying within a sphere. */
class _OgreExport SphereSceneQuery : public RegionSceneQuery
{
protected:
Sphere mSphere;
public:
SphereSceneQuery(SceneManager* mgr);
virtual ~SphereSceneQuery();
/** Sets the sphere which is to be used for this query. */
void setSphere(const Sphere& sphere);
/** Gets the sphere which is being used for this query. */
const Sphere& getSphere() const;
};
// OgreMain/include/OgreSceneQuery.h:PlaneBoundedVolumeListSceneQuery(v14.6.3 源码摘录,已删减)
/** Specialises the SceneQuery class for querying within a plane-bounded volume.
*/
class _OgreExport PlaneBoundedVolumeListSceneQuery : public RegionSceneQuery
{
protected:
PlaneBoundedVolumeList mVolumes;
public:
PlaneBoundedVolumeListSceneQuery(SceneManager* mgr);
virtual ~PlaneBoundedVolumeListSceneQuery();
/** Sets the volume which is to be used for this query. */
void setVolumes(const PlaneBoundedVolumeList& volumes);
/** Gets the volume which is being used for this query. */
const PlaneBoundedVolumeList& getVolumes() const;
};
三种查询分别对应三种「提问形状」:
| 查询 | 体积成员 | 典型用途 |
|---|---|---|
AxisAlignedBoxSceneQuery | AxisAlignedBox mAABB | 瓦片触发、区域扫描 |
SphereSceneQuery | Sphere mSphere | 爆炸半径、圆形感知 |
PlaneBoundedVolumeListSceneQuery | PlaneBoundedVolumeList mVolumes | 凸体积、视锥式查询 |
SceneQueryResult 是结果容器,movables 列表装可移动对象、worldFragments 只在 BSP 场景管理器有意义。RegionSceneQuery::execute() 有两种口味:一次收集返回 SceneQueryResult&(带 getLastResults 缓存),或走 SceneQueryListener 逐个回调(更轻量,不缓存)。Sphere 查询的命中判定就是「球 vs 对象世界包围盒」的相交测试——这也是本节 lab 复现的核心。
Ray 查询与距离排序
射线查询特殊在结果带距离。RaySceneQueryListener 因此独立于 SceneQueryListener,回调签名里多一个 Real distance:
// OgreMain/include/OgreSceneQuery.h:RaySceneQueryListener(v14.6.3 源码摘录,已删减)
/** Alternative listener class for dealing with RaySceneQuery. ...
Because the RaySceneQuery returns results in an extra bit of information, namely
distance, the listener interface must be customised from the standard SceneQueryListener.
*/
class _OgreExport RaySceneQueryListener
{
public:
virtual ~RaySceneQueryListener() { }
/** Called when a movable objects intersects the ray. ...
*/
virtual bool queryResult(MovableObject* obj, Real distance) = 0;
...
};
结果条目 RaySceneQueryResultEntry 里存着距离、可移动对象与世界碎片,比较运算符按距离排序——这决定了 std::sort 的默认行为:
// OgreMain/include/OgreSceneQuery.h:RaySceneQueryResultEntry(v14.6.3 源码摘录,已删减)
/** This struct allows a single comparison of result data no matter what the type */
struct _OgreExport RaySceneQueryResultEntry
{
/// Distance along the ray
Real distance;
/// The movable, or NULL if this is not a movable result
MovableObject* movable;
/// Only relevant for the BSP Scene Manager. The world fragment, or NULL if this is not a fragment result
SceneQuery::WorldFragment* worldFragment;
/// Comparison operator for sorting
bool operator < (const RaySceneQueryResultEntry& rhs) const
{
return this->distance < rhs.distance;
}
};
要不要排序由 setSortByDistance 决定,第二个参数 maxresults 在排序开启时约束返回条数(0 表示不限):
// OgreMain/include/OgreSceneQuery.h:setSortByDistance(v14.6.3 教学示意,参照上游同名实现,已删减)
/** Sets whether the results of this query will be sorted by distance along the ray. ...
@param sort If true, results will be sorted.
@param maxresults If sorting is enabled, this value can be used to constrain the maximum number
of results that are returned. ... 0 means unlimited results.
*/
virtual void setSortByDistance(bool sort, ushort maxresults = 0);
/** Gets whether the results are sorted by distance. */
virtual bool getSortByDistance(void) const;
/** Gets the maximum number of results returned from the query ... */
virtual ushort getMaxResults(void) const;
execute() 先清空结果,再以自身为 listener 收集命中,最后按 mSortByDistance 决定全排还是部分排——条数受限时用 std::partial_sort 取 N 个最近者再裁剪,省掉无谓的全排序:
// OgreMain/src/OgreSceneQuery.cpp:RaySceneQuery::execute(v14.6.3 源码摘录,已删减)
if (mSortByDistance)
{
if (mMaxResults != 0 && mMaxResults < mResult.size())
{
// Partially sort the N smallest elements, discard others
std::partial_sort(mResult.begin(), mResult.begin()+mMaxResults, mResult.end());
mResult.resize(mMaxResults);
}
else
{
// Sort entire result array
std::sort(mResult.begin(), mResult.end());
}
}
构造时 mSortByDistance 默认 false、mMaxResults 默认 0——OGRE 把「要排序」「限多少条」都留给调用方显式打开。射线对盒的命中距离用 slab 法求出入射点参数 t,最近命中者排最前,这正是拾取「点到第一个物体」的实现路径。
源码定位
OgreMain/include/OgreSceneQuery.h:SceneQuery基类、setQueryMask/getQueryMaskOgreMain/src/OgreSceneQuery.cpp:SceneQuery::SceneQuery(默认 mask0xFFFFFFFF)OgreMain/include/OgreSceneQuery.h:SphereSceneQuery、AxisAlignedBoxSceneQuery、PlaneBoundedVolumeListSceneQueryOgreMain/include/OgreSceneQuery.h:RaySceneQueryListener、RaySceneQueryResultEntry、setSortByDistanceOgreMain/src/OgreSceneQuery.cpp:RaySceneQuery::execute(std::sort/std::partial_sort)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现 SceneQuery 的三件机制:默认 mQueryMask=0xFFFFFFFF 与 setQueryMask 覆盖;SphereSceneQuery 的 mask 位与 + 球-盒相交判定;RaySceneQuery 的 setSortByDistance 与 std::sort/partial_sort 距离排序。它与 src/03-1-scene-query.cpp 逐字节一致:
// file: src/03-1-scene-query.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/03-1-scene-query.cpp -o bin/03-1-scene-query && ./bin/03-1-scene-query
//
// 复现 OgreSceneQuery.h 的场景查询体系:
// SceneQuery 的 mQueryMask(默认 0xFFFFFFFF)与 setQueryMask/getQueryMask;
// SphereSceneQuery 的球-包围盒命中判定(query mask 位与非零才返回);
// RaySceneQuery 的 setSortByDistance + std::sort/partial_sort 按距离排序。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <algorithm>
#include <cstdint>
#include <vector>
namespace ogre_repro {
// 对应 OgreMovableObject.h:查询标志位(setQueryFlags/getQueryFlags)
class MovableObject {
public:
uint32_t queryFlags = 0xFFFFFFFF; // 默认全开
explicit MovableObject(uint32_t flags) : queryFlags(flags) {}
uint32_t getQueryFlags() const { return queryFlags; }
};
// 世界空间轴对齐盒
struct AABB {
float minx, miny, minz, maxx, maxy, maxz;
// 球-盒相交:最近点距离平方 <= r^2
bool intersects(const float cx, const float cy, const float cz,
const float r) const {
const float px = std::clamp(cx, minx, maxx);
const float py = std::clamp(cy, miny, maxy);
const float pz = std::clamp(cz, minz, maxz);
const float dx = px - cx, dy = py - cy, dz = pz - cz;
return dx * dx + dy * dy + dz * dz <= r * r;
}
};
// 携带包围盒的可移动对象
struct Object : MovableObject {
AABB box;
Object(uint32_t flags, const AABB& b) : MovableObject(flags), box(b) {}
};
// 对应 OgreSceneQuery.h:SceneQuery 基类,mQueryMask 默认 0xFFFFFFFF
class SceneQuery {
public:
uint32_t mQueryMask = 0xFFFFFFFF;
uint32_t mQueryTypeMask = 0xFFFFFFFF;
void setQueryMask(uint32_t mask) { mQueryMask = mask; }
uint32_t getQueryMask() const { return mQueryMask; }
virtual ~SceneQuery() = default;
};
// 对应 SphereSceneQuery:mask 过滤后做球-盒命中
std::vector<Object*> sphereQuery(const std::vector<Object*>& objects,
const SceneQuery& query, float cx, float cy,
float cz, float r) {
std::vector<Object*> hits;
for (Object* o : objects) {
if ((query.mQueryMask & o->getQueryFlags()) == 0) continue; // mask 过滤
if (o->box.intersects(cx, cy, cz, r)) hits.push_back(o);
}
return hits;
}
// 射线(原点 + 方向),slab 法求 AABB 最近命中距离
struct Ray {
float ox, oy, oz, dx, dy, dz;
bool intersects(const AABB& b, float& dist) const {
float tmin = -1e20f, tmax = 1e20f;
if (std::abs(dx) < 1e-9f) {
if (ox < b.minx || ox > b.maxx) return false;
} else {
float t1 = (b.minx - ox) / dx, t2 = (b.maxx - ox) / dx;
if (t1 > t2) std::swap(t1, t2);
tmin = std::max(tmin, t1);
tmax = std::min(tmax, t2);
if (tmin > tmax) return false;
}
if (std::abs(dy) < 1e-9f) {
if (oy < b.miny || oy > b.maxy) return false;
} else {
float t1 = (b.miny - oy) / dy, t2 = (b.maxy - oy) / dy;
if (t1 > t2) std::swap(t1, t2);
tmin = std::max(tmin, t1);
tmax = std::min(tmax, t2);
if (tmin > tmax) return false;
}
if (std::abs(dz) < 1e-9f) {
if (oz < b.minz || oz > b.maxz) return false;
} else {
float t1 = (b.minz - oz) / dz, t2 = (b.maxz - oz) / dz;
if (t1 > t2) std::swap(t1, t2);
tmin = std::max(tmin, t1);
tmax = std::min(tmax, t2);
if (tmin > tmax) return false;
}
if (tmax < 0) return false;
dist = tmin > 0 ? tmin : 0.0f;
return true;
}
};
// 对应 RaySceneQueryResultEntry:按距离比较
struct RaySceneQueryResultEntry {
float distance;
Object* movable;
bool operator<(const RaySceneQueryResultEntry& rhs) const {
return this->distance < rhs.distance;
}
};
// 对应 RaySceneQuery:mSortByDistance/mMaxResults 与排序执行
class RaySceneQuery {
public:
std::vector<RaySceneQueryResultEntry> mResult;
bool mSortByDistance = false;
uint16_t mMaxResults = 0;
// 模拟 SceneManager 收集到的候选命中(调用方预先填充)
std::vector<RaySceneQueryResultEntry> mCandidates;
void setSortByDistance(bool sort, uint16_t maxresults = 0) {
mSortByDistance = sort;
mMaxResults = maxresults;
}
bool getSortByDistance() const { return mSortByDistance; }
uint16_t getMaxResults() const { return mMaxResults; }
// 对应 RaySceneQueryListener::queryResult:把单条命中收进结果表
void queryResult(Object* obj, float distance) {
mResult.push_back({distance, obj});
}
std::vector<RaySceneQueryResultEntry>& execute() {
// 对应 OgreSceneQuery.cpp:先清空,再以 listener 回调收集,最后按需排序
mResult.clear();
for (const auto& c : mCandidates) queryResult(c.movable, c.distance);
if (mSortByDistance) {
if (mMaxResults != 0 && mMaxResults < mResult.size()) {
std::partial_sort(mResult.begin(), mResult.begin() + mMaxResults,
mResult.end());
mResult.resize(mMaxResults);
} else {
std::sort(mResult.begin(), mResult.end());
}
}
return mResult;
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// SceneQuery 默认 mask 为 0xFFFFFFFF
SceneQuery query;
CHECK_EQ(query.getQueryMask(), 0xFFFFFFFFu);
query.setQueryMask(0xFF00u);
CHECK_EQ(query.getQueryMask(), 0xFF00u);
// 三个对象:A 旗标 0x1、B 旗标 0x2、C 旗标 0x8
Object a(0x1u, AABB{0, 0, 0, 2, 2, 2});
Object b(0x2u, AABB{100, 100, 100, 110, 110, 110});
Object c(0x8u, AABB{20, 20, 20, 22, 22, 22});
std::vector<Object*> objects = {&a, &b, &c};
// 球查询:球心(1,1,1) r=1 命中 A
SceneQuery maskAny;
maskAny.setQueryMask(0xFFFFFFFFu);
auto hits = sphereQuery(objects, maskAny, 1, 1, 1, 1);
CHECK_EQ(hits.size(), 1u);
CHECK(hits[0] == &a);
// mask 只允许 0x2:A 与 C 被滤掉,只剩 B(球心在盒内必命中)
SceneQuery maskOnlyB;
maskOnlyB.setQueryMask(0x2u);
auto hits2 = sphereQuery(objects, maskOnlyB, 105, 105, 105, 100);
CHECK_EQ(hits2.size(), 1u);
CHECK(hits2[0] == &b);
// 球心落在 C 的盒内:r=1 也命中 C
auto hits3 = sphereQuery(objects, maskAny, 21, 21, 21, 1);
CHECK_EQ(hits3.size(), 1u);
CHECK(hits3[0] == &c);
// Ray:原点(1,1,-10) 朝 +z,A 的 z∈[0,2] → t=10;D 的 z∈[100,102] → t=110
Object d(0x10u, AABB{0, 0, 100, 2, 2, 102});
Ray ray{1, 1, -10, 0, 0, 1};
float distA = 0, distD = 0;
CHECK(ray.intersects(a.box, distA));
CHECK(ray.intersects(d.box, distD));
CHECK_EQ(distA, 10.0f);
CHECK_EQ(distD, 110.0f);
// RaySceneQuery:默认不排序,打开 setSortByDistance 后最近者在前
RaySceneQuery rq;
CHECK(!rq.getSortByDistance());
CHECK_EQ(rq.getMaxResults(), 0u);
rq.setSortByDistance(true);
CHECK(rq.getSortByDistance());
rq.mCandidates = {{distD, &d}, {distA, &a}};
rq.execute();
CHECK_EQ(rq.mResult.size(), 2u);
CHECK(rq.mResult[0].movable == &a);
CHECK(rq.mResult[1].movable == &d);
// 只保留最近 1 条(partial_sort + resize)
RaySceneQuery rqTop1;
rqTop1.setSortByDistance(true, 1);
rqTop1.mCandidates = {{distD, &d}, {distA, &a}};
rqTop1.execute();
CHECK_EQ(rqTop1.mResult.size(), 1u);
CHECK(rqTop1.mResult[0].movable == &a);
return lab::report("03-1 场景查询:SceneQuery 体系");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译零警告,断言 20/20 通过。
小结
SceneQuery是场景区域查询的统一抽象,结果基于包围体积、只保证潜在相交。mQueryMask(默认0xFFFFFFFF)与对象getQueryFlags做位与,非零才返回,语义交给应用。- 区域查询分盒、球、平面体积三种,都只多存一个体积成员,结果走
SceneQueryResult或 listener 回调。 RaySceneQuery的结果带距离,setSortByDistance决定排序,maxresults限制条数并改用std::partial_sort。- 射线拾取「最近命中者优先」正是
RaySceneQueryResultEntry::operator<按距离比较的落地。
阅读导航:上一节:2.3 投影与裁剪 · 下一节:3.2 视锥剔除 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。