Man shape
From LSWiki
Contents |
Files
/def/descriptor/shape.c /lib/descriptors/shape.h /lib/geometry.h /def/geometry /daemon/geometry.c /lib/common_shapes.h
Description
Shape descriptors are used to specify the shape of an object. This can, in turn, be used to determine its volume, which in conjunction with material composition elements (see 'man element') can determine its mass and other properties.
Shape descriptors are not intended to be fully precise definitions of the object's shape, and are more of an effort to define its general dimensions to a near enough tolerance for practical purposes.
When working with shape descriptors, you will generally want to #include <geometry.h>, which defines various useful macros and includes shape.h.
Shape descriptors rely heavily on the geometry definitions managed through /daemon/geometry.c, /lib/geometry.h, and /def/geometry. Some of these geometries describe precise ideal shapes (Geometry_Sphere, Geometry_Cube) and others describe useful approximations (Geometry_Anthropoid).
"Live" shape descriptors in use by objects should not be directly modified because the changes will not be properly taken into account. Changes to an object's shape should be done by calling set_shape() in it, possibly with an argument consisting of a copy of its previous shape descriptor that has been altered in some fashion.
/lib/common_shapes.h defines a number of helpful shape specifications that make it unnecessary to write your own shape dimensions in many situations, and otherwise provide useful examples.
Though the shapes most relevant to our usage are the three-dimensional shapes, the geometry mechanics also understand various two-dimensional shapes. These should never be set as the shapes of game objects, however.
There is an entire class of hollow geometries, both two-dimensional and three-dimensional, which are essentially versions of a shape with an added parameter, thickness. For instance, Geometry_Ball is a hollow version of Geometry_Sphere; Geometry_Sphere's only dimension is a Shape_Radius, where Geometry_Ball has a Shape_Radius and a Shape_Thickness. Additional values can be calculated for hollow shapes, as described under Support Functions.
Public Fields
Shape_Type: The geometric figure described; must be a valid geometry type, and will be converted to the type's integer geometry code.
Virtual Fields
The virtual fields of a shape descriptor are the various dimensions of its particular shape, as determined by the geometry definition it uses for its type. You can review /lib/descriptors/shape.h for the full list, or look at geometry definitions in /def/geometry to see which fields they use. All dimensions are always in the standard Ain Soph unit of distance, the dimin (decimeter).
Internal Fields
Shape_Params: This is where the shape dimension information derived from the virtual fields, in relation to the shape geometry, are stored.
Shape_Tag: The tag for the descriptor system.
Support Functions
float Shape_Volume(mixed spec)
Returns the volume of the specified three-dimensional shape, in balaths (liters).
float Shape_Surface_Area(mixed spec)
Returns the surface area of the specified three-dimensional shape, in square dimins (square decimeters). In the case of a hollow shape, this will include all surfaces.
float Shape_Volume_Enclosed(mixed spec)
Returns the volume enclosed by the specified hollow three-dimensional shape, in balaths (liters).
float Shape_Inner_Surface_Area(mixed spec)
Returns the inner surface area of the specified hollow three-dimensional shape, in square dimins (square decimeters).
float Shape_Outer_Surface_Area(mixed spec)
Returns the outer surface area of the specified hollow three-dimensional shape, in square dimins (square decimeters).
float array Shape_Volume_Param(mixed spec, float value)
Returns an array of the parameters necessary for a three-dimensional shape of the type and with the proportions of that specified to have a volume equal (within a small tolerance) to the value given.
float array Shape_Surface_Area_Param(mixed spec, float value)
Returns an array of the parameters necessary for a three-dimensional shape of the type and with the proportions of that specified to have a surface area equal (within a small tolerance) to the value given.
float array Shape_Volume_Enclosed_Param(mixed spec, float value)
Returns an array of the parameters necessary for a hollow three-dimensional shape of the type and with the proportions of that specified to have an enclosed volume equal (within a small tolerance) to the value given.
float array Shape_Inner_Surface_Area_Param(mixed spec, float value)
Returns an array of the parameters necessary for a hollow three-dimensional shape of the type and with the proportions of that specified to have an inner surface area equal (within a small tolerance) to the value given.
float array Shape_Outer_Surface_Area_Param(mixed spec, float value)
Returns an array of the parameters necessary for a hollow three-dimensional shape of the type and with the proportions of that specified to have an outer surface area equal (within a small tolerance) to the value given.
float Shape_Area(mixed spec)
Returns the area of the specified two-dimensional shape, in square dimins (square decimeters).
float Shape_Perimeter(mixed spec)
Returns the perimeter distance of the specified two-dimensional shape, in dimins (decimeters). In the case of a hollow two-dimensional shape, this will be the total perimeter along all edges.
float Shape_Area_Enclosed(mixed spec)
Returns the area enclosed by the specified hollow two-dimensional shape, in square dimins (square decimeters).
float Shape_Inner_Perimeter(mixed spec)
Returns the inner perimeter of the specified hollow two-dimensional shape, in dimins (decimeters).
float Shape_Outer_Perimeter(mixed spec)
Returns the outer perimeter of the specified hollow two-dimensional shape, in dimins (decimeters).
float array Shape_Area_Param(mixed spec, float value)
Returns an array of the parameters necessary for a two-dimensional shape of the type and with the proportions of that specified to have an area equal (within a small tolerance) to the value given.
float array Shape_Perimeter_Param(mixed spec, float value)
Returns an array of the parameters necessary for a two-dimensional shape of the type and with the proportions of that specified to have a perimeter equal (within a small tolerance) to the value given.
float array Shape_Area_Enclosed_Param(mixed spec, float value)
Returns an array of the parameters necessary for a hollow two-dimensional shape of the type and with the proportions of that specified to have an enclosed area equal (within a small tolerance) to the value given.
float array Shape_Area_Inner_Perimeter_Param(mixed spec, float value)
Returns an array of the parameters necessary for a hollow two-dimensional shape of the type and with the proportions of that specified to have an inner perimeter equal (within a small tolerance) to the value given.
float array Shape_Area_Outer_Perimeter_Param(mixed spec, float value)
Returns an array of the parameters necessary for a hollow two-dimensional shape of the type and with the proportions of that specified to have an outer perimeter equal (within a small tolerance) to the value given.
descriptor Shape_Resize(mixed spec, float value)
Returns a descriptor with the same relative proportions as that specified but with its volume (three-dimensional shapes) or area (two-dimensional shapes) equal (within a small tolerance) to the value given.
descriptor Shape_Universal(descriptor dxr)
Used to ensure that a given descriptor is shared via the global shape descriptor cache. The descriptor returned, which may be the same as the one sent, is guaranteed to be shared.
See Also
[[man descriiptors|descriptors(mechanisms)], set_shape(lfun), query_shape(lfun)
