peng3d.model
- Model and Animation system¶
-
peng3d.model.
grouper
(iterable, n, fillvalue=None)[source]¶ Allows for iteration over multiple elements of a iterable at once.
iterable
may be any iterable, its values will be returned. Note that this may be iterated over more than once.n
is the size of each group. May be any positive integer.fillvalue
is optionally used to fill any groups that do not have enough items, for example if the length of the iterable is not divisible by n.Example:
>>> for i in grouper("foobarbaz",2,fillvalue=" "): ... print(i) fo ob ar ba z # Note the extra space after the z
-
peng3d.model.
calcSphereCoordinates
(pos, radius, rot)[source]¶ Calculates the Cartesian coordinates from spherical coordinates.
pos
is a simple offset to offset the result with.radius
is the radius of the input.rot
is a 2-tuple of(azimuth,polar)
angles.Angles are given in degrees. Most directions in this game use the same convention.
The azimuth ranges from 0 to 360 degrees with 0 degrees pointing directly to the x-axis.
The polar angle ranges from -90 to 90 with -90 degrees pointing straight down and 90 degrees straight up.
A visualization of the angles required is given in the source code of this function.
-
peng3d.model.
v_magnitude
(v)[source]¶ Simple vector helper function returning the length of a vector.
v
may be any vector, with any number of dimensions
-
peng3d.model.
v_normalize
(v)[source]¶ Normalizes the given vector.
The vector given may have any number of dimensions.
-
class
peng3d.model.
Material
(rsrcMgr, name, matdata)[source]¶ Object that describes a single material of a model.
This object stores all relevant data and caches. Note that this object is only created once for each model and shared between all rendered instances of it.
See
Model
for more information about the model system.-
id
¶ Read-only property storing the numerical ID of the texture of this material.
Used to manipulate the texture behind this material.
Commonly used in binding the texture:
glBindTexture(material.target,material.id)
.
-
target
¶ Read-only property storing the OpenGL constant representing the target of the texture of this material.
Commonly
GL_TEXTURE_2D
orGL_TEXTURE_3D
.Used in texture manipulation and activation, e.g.
glEnable(material.target)
.
-
tex_coords
¶ Read-only property storing the texture coordinates to use when drawing with this texture.
Should not be used directly, see
transformTexCoords()
.Enables substitution of pyglet
pyglet.graphics.Texture
objects with Materials in many places, e.g. inpyglet.graphics.TextureGroup
.
-
texdata
¶ Read-only property equivalent to a 3-tuple containing
target
,id
andtex_coords
.Should be faster than getting each value directly. Useful if all of these values are needed.
-
transformTexCoords
(data, texcoords, dims=2)[source]¶ Transforms the given texture coordinates using the internal texture coordinates.
Currently, the dimensionality of the input texture coordinates must always be 2 and the output is 3-dimensional with the last coordinate always being zero.
The given texture coordinates are fitted to the internal texture coordinates. Note that values higher than 1 or lower than 0 may result in unexpected visual glitches.
The length of the given texture coordinates should be divisible by the dimensionality.
-
-
class
peng3d.model.
Bone
(rsrcMgr, name, bonedata)[source]¶ Object that represents a single bone of a model.
This object stores all relevant data and caches. Note that this object is only created once for each model and shared between all rendered instances of it.
Actual bone rotation and length is stored per entity and not per model allowing for different bone rotations for multiple entities using the same model.
See
Model
for more information about the model system.-
addRegion
(region)[source]¶ Register a vertex Region as a dependent of this bone.
region
must be an instance ofRegion
.
-
ensureBones
(data)[source]¶ Helper method ensuring per-entity bone data has been properly initialized.
Should be called at the start of every method accessing per-entity data.
data
is the entity to check in dictionary form.
-
getLength
(data)[source]¶ Returns the length of this bone in the given entity.
data
is the entity to query in dictionary form.
-
getPivotPoint
(data)[source]¶ Returns the point this bone pivots around on the given entity.
This method works recursively by calling its parent and then adding its own offset.
The resulting coordinate is relative to the entity, not the world.
-
getRot
(data)[source]¶ Returns the rotation of this bone in the given entity.
data
is the entity to query in dictionary form.
-
setLength
(data, blength)[source]¶ Sets the length of this bone on the given entity.
data
is the entity to modify in dictionary form.blength
is the new length of the bone.
-
setParent
(parent)[source]¶ Sets the parent of this bone for all entities.
Note that this method must be called before many other methods to ensure internal state has been initialized.
This method also registers this bone as a child of its parent.
-
setRot
(data, rot)[source]¶ Sets the rotation of this bone on the given entity.
data
is the entity to modify in dictionary form.rot
is the rotation of the bone in the format used incalcSphereCoordinates()
.
-
setRotate
(data)[source]¶ Sets the OpenGL state required for proper drawing of the model.
Mostly rotates and translates the camera.
It is important to call
unsetRotate()
after calling this method to properly unset state and avoid OpenGL errors.
-
transformVertices
(data, vertices, dims=3)[source]¶ Currently unused method that transforms the given vertices according to the rotation of the bone.
Currently just returns the vertices unmodified, will be implemented in the future.
-
unsetRotate
(data)[source]¶ Unsets the OpenGL state that was set before calling
setRotate()
.Note that this method may cause various OpenGL errors if called without
setRotate()
having been called.
-
-
class
peng3d.model.
RootBone
(rsrcMgr, name, bonedata)[source]¶ Special bone that represents the root of a entity.
This bone is immutable and cannot be rotated or otherwise modified.
-
getLength
(data)[source]¶ Returns the length of this bone in the given entity.
data
is the entity to query in dictionary form.
-
getPivotPoint
(data)[source]¶ Returns the point this bone pivots around on the given entity.
This method works recursively by calling its parent and then adding its own offset.
The resulting coordinate is relative to the entity, not the world.
-
setRotate
(data)[source]¶ Sets the OpenGL state required for proper drawing of the model.
Mostly rotates and translates the camera.
It is important to call
unsetRotate()
after calling this method to properly unset state and avoid OpenGL errors.
-
unsetRotate
(data)[source]¶ Unsets the OpenGL state that was set before calling
setRotate()
.Note that this method may cause various OpenGL errors if called without
setRotate()
having been called.
-
-
class
peng3d.model.
Region
(rsrcMgr, name, regdata)[source]¶ Object that represents a vertex region of a model.
A vertex region is associated with a specific bone of the same model it is associated with. It has a list of vertices and optionally texture coordinates. The texture coordinates are transformed using the material it is associated with.
Most regions will use quads as their primitive type, but it is also possible to use triangles, lines and points.
To use quads as the geometry type, specify either
quads
,quad
orGL_QUADS
as itsgeometry_type
.To use triangles as the geometry type, specify either
tris
,triangles
,triangle
orGL_TRIANGLES
as itsgeometry_type
.To use lines as the geometry type, specify either
lines
,line
orGL_LINES
as itsgeometry_type
.To use points as the geometry type, specify either
points
,point
,dots
,dot
orGL_POINTS
as itsgeometry_type
.Note that the number of vertices must be divisible by the number of vertices required per primitive, e.g. 4 for quads, 3 for triangles, 2 for lines and 1 for points.
Additionally, the number of vertices and texture coordinate pairs must also match.
If any of these conditions are not fulfilled, a
ValueError
will be raised.-
getGeometryType
(data)[source]¶ Returns the OpenGL constant representing the type of primitives used by this region.
May be one of
GL_QUADS
,GL_TRIANGLES
,GL_LINES
orGL_POINTS
.
-
getTexCoords
(data)[source]¶ Returns the texture coordinates, if any, to accompany the vertices of this region already transformed.
Note that it is recommended to check the
enable_tex
flag first.Internally uses
Material.transformTexCoords()
.
-
getTexInfo
(data)[source]¶ Returns informations about the texture of this region.
Internally uses
Material.texdata
, exact specification available there.
-
getVertices
(data)[source]¶ Returns the vertices of this region already transformed and ready-to-use.
Internally uses
Bone.transformVertices()
.
-
-
class
peng3d.model.
Animation
(rsrcMgr, name, anidata)[source]¶ Object that represents an animation of a model.
Animations can be either static or animated using keyframes.
See
Model
for more information.-
setBones
(bones)[source]¶ Sets the internal dictionary of bones in the parent model.
Must be a dictionary, else errors may appear later on.
-
startAnimation
(data, jumptype)[source]¶ Callback that is called to initialize this animation on a specific actor.
Internally sets the
_anidata
key of the given dictdata
.jumptype
is eitherjump
oranimate
to define how to switch to this animation.
-
tickEntity
(data)[source]¶ Callback that should be called regularly to update the animation.
It is recommended to call this method about 60 times a second for smooth animations. Irregular calling of this method will be automatically adjusted.
This method sets all the bones in the given actor to the next state of the animation.
Note that
startAnimation()
must have been called before calling this method.
-
-
class
peng3d.model.
JSONModelGroup
(model, data, obj, parent=None)[source]¶ Pyglet group that sets the state required by a specific actor.
This group should always be set during any draw operations for the assigned actor. This can either be done by setting it as the group of a vertex list, the parent group of a group of a vertex list or manually calling
set_state()
andunset_state()
.
-
class
peng3d.model.
JSONRegionGroup
(model, data, region, parent=None)[source]¶ Pyglet group that manages the state required by a specific vertex region of an actor.
This group and the associated
JSONModelGroup
should always be set during any draw operation for the assigned region.See
JSONModelGroup
for more information about how to do this.
-
class
peng3d.model.
Model
(peng, rsrcMgr, name)[source]¶ Object that represents the model of an actor.
Note that this object is not bound to an actor but rather to a collection of materials, bones, vertex regions and animations.
A single instance of this class may be used by multiple actors at the same time. See
Actor.setModel()
for more information.A test model is available at
assets/peng3d/model/test.json
and a demo program using it undertest_model.py
.Todo
Document the format of .json model files.
-
cleanup
(obj)[source]¶ Cleans up any left over data structures, including vertex lists that reside in GPU memory.
Behaviour is undefined if it is attempted to use this model with the same object without calling
create()
first.It is very important to call this method manually during deletion as this will delete references to data objects stored in global variables of third-party modules.
-
create
(obj, cache=False)[source]¶ Initializes per-actor data on the given object for this model.
If
cache
is set to True, the entity will not be redrawn after initialization.Note that this method may set several attributes on the given object, most of them starting with underscores.
During initialization of vertex regions, several vertex lists will be created. If the given object has an attribute called
batch3d
it will be used, else it will be created.If the batch already existed, the
draw()
method will do nothing, else it will draw the batch.Memory leaks may occur if this is called more than once on the same object without calling
cleanup()
first.
-
draw
(obj)[source]¶ Actually draws the model of the given object to the render target.
Note that if the batch used for this object already existed, drawing will be skipped as the batch should be drawn by the owner of it.
-
ensureModelData
(obj)[source]¶ Ensures that the given
obj
has been initialized to be used with this model.If the object is found to not be initialized, it will be initialized.
-
redraw
(obj)[source]¶ Redraws the model of the given object.
Note that currently this method probably won’t change any data since all movement and animation is done through pyglet groups.
-