Manual: Geoms

From KODE Wiki
Jump to: navigation, search
KODEManual.png
This article is part
of the KODE Manual
Chapters
Introduction
Install and Use
Concepts
Quick Tutorial
API Reference
World
Body
Joints
Geoms
Spaces
Vector3

Geoms are entities representing collision shapes. Geoms can be attached to bodies, or can be used independently.

Geom[edit]

class Geom {
    // ...

    enum class Type : unsigned {
        Box,
        Capsule,
        Cylinder,
        Plane,
        Sphere,
        Unknown
    };

    simpsig::Signal<Geom*> onMove;

    Geom() noexcept;
    ~Geom() noexcept;

    Type getType() const noexcept;

    // ...
};

Geom is the base class for all shapes. The actual type can be queried with getType().

Collisions[edit]

class Geom {
    // ...

    bool isEnabled() const noexcept; // default: true
    void enable() noexcept;
    void disable() noexcept;

    bool rejectAABB(const AxisAlignedBox& box) const noexcept;

    uint32_t getCategory() const noexcept; // default: 0xffffffff
    void setCategory(uint32_t cat) noexcept;
    uint32_t getFilter() const noexcept; // default: 0xffffffff
    void setFilter(uint32_t fil) noexcept;

    const AxisAlignedBox& getAABB() const noexcept;

    const Space* getSpace() const noexcept;
    Space*       getSpace() noexcept;

    Real pointDepth(const Vector3& point) const noexcept;
    Real pointDepth(Real x, Real y, Real z) const noexcept;

    Interval projected(const Vector3& axis) const;
    Interval projected(Real x, Real y, Real z) const;

    Vector3 support(const Vector3& dir) const;
    Vector3 support(Real x, Real y, Real z) const;

    // ...
};

These routines affect how collisions are detected.

The Filter and Category bit masks determine if a collision between a pair of geoms will be detected or not. If a bit of the category of geom g1 and a bit of the filter of geom g2 (or vice-versa) is set to 1, then g1 and g2 will be considered for collisions. this feature is useful to avoid collisions between geoms that are attached to the same body, or geoms that are part of the static environment.

The rejectAABB() allows a geom to quickly reject a collision with another based on its axis-aligned bounding box; this is useful when a geom has infinite extent (such as planes).

Position and Orientation[edit]

class Geom {
    // ...

    const Body* getBody() const noexcept;
    Body*       getBody() noexcept;

    const Vector3& getPosition() const noexcept;
    void setPosition(const Vector3& pos) noexcept;
    void setPosition(Real x, Real y, Real z) noexcept;

    void translate(const Vector3& delta) noexcept;
    void translate(Real dx, Real dy, Real dz) noexcept;

    const Matrix3& getLocalAxes() const noexcept;
    Quaternion getOrientation() const noexcept;
    void setLocalAxes(const Matrix3& axes) noexcept;
    void setOrientation(const Quaternion& q) noexcept;

    void rotate(Radian angle, const Vector3& axis) noexcept;
    void rotate(const Vector3& axis, Radian angle) noexcept;

    const Vector3& getOffsetPosition() const noexcept;
    void setOffsetPosition(const Vector3& pos);
    void setOffsetPosition(Real ox, Real oy, Real oz);

    const Matrix3& getOffsetLocalAxes() const noexcept;
    Quaternion getOffsetOrientation() const noexcept;
    void setOffsetLocalAxes(const Matrix3& axes);
    void setOffsetOrientation(const Quaternion& q);

    // ...
};

Utility[edit]

class Geom {
    // ...

    Vector3 localPointToWorld(const Vector3& localPoint) const noexcept;
    Vector3 localPointToWorld(Real x, Real y, Real z) const noexcept;

    Vector3 worldPointToLocal(const Vector3& worldPoint) const noexcept;
    Vector3 worldPointToLocal(Real x, Real y, Real z) const noexcept;

    Vector3 localVectorToWorld(const Vector3& localVector) const noexcept;
    Vector3 localVectorToWorld(Real x, Real y, Real z) const noexcept;

    Vector3 worldVectorToLocal(const Vector3& worldVector) const noexcept;
    Vector3 worldVectorToLocal(Real x, Real y, Real z) const noexcept;

    // ...
};

Box[edit]

class Box : public Geom {
    // ...
public:
    Box(Real sX, Real sY, Real sZ) noexcept;
    Box(const Vector3& size) noexcept;

    Vector3 getSize() const noexcept;
    void setSize(const Vector3& newSize);
    const Vector3& getHalfSize() const noexcept;

    Vector3 getCorner(unsigned idx) const noexcept;
};

This represents a rectangular box.

The getCorner(idx) method returns the position of one of the 8 box corners.

Capsule[edit]

class Capsule : public Geom {
public:
    Capsule(Real radius, Real length);

    void setRadius(Real r);
    Real getRadius() const noexcept;

    void setLength(Real len);
    Real getLength() const noexcept;
    Real getHalfLength() const noexcept;

    void setRadiusLength(Real radius, Real length);
};

Represents a cylinder with spherical endpoints, along the Z axis.

Cylinder[edit]

class Cylinder : public Geom {
    // ...
public:
    Cylinder(Real radius, Real length);

    void setRadius(Real r);
    Real getRadius() const noexcept;

    void setLength(Real len);
    Real getLength() const noexcept;

    void setRadiusLength(Real rad, Real len);
};

Represents a cylinder along the Z axis.

Plane[edit]

class Plane : public Geom {
    // ...
public:
    Plane(const Vector3& point, const Vector3& normal);
    Plane(Real a, Real b, Real c, Real d);
    Plane(const Vector3& p1, const Vector3& p2, const Vector3& p3);

    const Vector3& getLocalNormal();
    const Vector3& getNormal() const noexcept;

    Real distance(const Vector3& point) const noexcept;
    Real distance(Real x, Real y, Real z) const noexcept;
};

Represents an infinitely-thick plane (aka half-space). Any given point inside will have a negative distance to the plane.

The second constructor takes the plane equation (ax + by + cz + d = 0). The plane's "position" is set to the closest point to the origin.

The third constructor takes 3 points in the plane. The plane's "position" is the first point.

Sphere[edit]

class Sphere : public Geom {
    // ...
public:
    Sphere(Real radius);

    Real getRadius() const noexcept;
    void setRadius(Real radius);
};

Represents a sphere.