# GeomPrimitive¶

from panda3d.core import GeomPrimitive

class GeomPrimitive

This is an abstract base class for a family of classes that represent the fundamental geometry primitives that may be stored in a Geom.

They all have in common the fact that they are defined by tables of vertex data stored in a GeomVertexData object. Each GeomPrimitive object contains an ordered list of integers, which index into the vertex array defined by the GeomVertexData and define the particular vertices of the GeomVertexData that are used for this primitive.

The meaning of a given arrangement of vertices is defined by each individual primitive type; for instance, a GeomTriangle renders a triangle from each three consecutive vertices, while a GeomTriangleStrip renders a strip of (n - 2) connected triangles from each sequence of n vertices.

Inheritance diagram

addConsecutiveVertices(start: int, num_vertices: int)None

Adds a consecutive sequence of vertices, beginning at start, to the primitive.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

addNextVertices(num_vertices: int)None

Adds the next n vertices in sequence, beginning from the last vertex added to the primitive + 1.

This is most useful when you are building up a primitive and a GeomVertexData at the same time, and you just want the primitive to reference the first n vertices from the data, then the next n, and so on.

addVertex(vertex: int)None

Adds the indicated vertex to the list of vertex indices used by the graphics primitive type. To define a primitive, you must call addVertex() for each vertex of the new primitive, and then call closePrimitive() after you have specified the last vertex of each primitive.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

addVertices(v1: int, v2: int)None

Adds several vertices in a row.

addVertices(v1: int, v2: int, v3: int)None

Adds several vertices in a row.

addVertices(v1: int, v2: int, v3: int, v4: int)None

Adds several vertices in a row.

assign(copy: GeomPrimitive)GeomPrimitive
checkValid(vertex_data: GeomVertexData)bool

Verifies that the primitive only references vertices that actually exist within the indicated GeomVertexData. Returns true if the primitive appears to be valid, false otherwise.

checkValid(data_reader: GeomVertexDataPipelineReader)bool
clearMinmax()None

Undoes a previous call to setMinmax(), and allows the minimum and maximum values to be recomputed normally.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

clearVertices()None

Removes all of the vertices and primitives from the object, so they can be re-added.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

closePrimitive()bool

Indicates that the previous n calls to addVertex(), since the last call to closePrimitive(), have fully defined a new primitive. Returns true if successful, false otherwise.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

property data_size_bytesint

Returns the number of bytes stored in the vertices array.

decompose()GeomPrimitive

Decomposes a complex primitive type into a simpler primitive type, for instance triangle strips to triangles, and returns a pointer to the new primitive definition. If the decomposition cannot be performed, this might return the original object.

This method is useful for application code that wants to iterate through the set of triangles on the primitive without having to write handlers for each possible kind of primitive type.

doubleside()GeomPrimitive

Duplicates triangles in the primitive so that each triangle is back-to-back with another triangle facing in the opposite direction. Note that this doesn’t affect vertex normals, so this operation alone won’t work in the presence of lighting (but see SceneGraphReducer::doubleside()).

Also see CullFaceAttrib, which can enable rendering of both sides of a triangle without having to duplicate it (but which doesn’t necessarily work in the presence of lighting).

property geom_renderingint

Returns the set of GeomRendering bits that represent the rendering properties required to properly render this primitive.

static getClassType()TypeHandle
getDataSizeBytes()int

Returns the number of bytes stored in the vertices array.

getEnds()CPTA_int

Returns a const pointer to the primitive ends array so application code can read it directly. Do not attempt to modify the returned array; use modifyEnds() or setEnds() for this.

Note that simple primitive types, like triangles, do not have a ends array: since all the primitives have the same number of vertices, it is not needed.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getFirstVertex()int

Returns the first vertex number referenced by the primitive. This is particularly important in the case of a nonindexed primitive, in which case getFirstVertex() and getNumVertices() completely define the extent of the vertex range.

getGeomRendering()int

Returns the set of GeomRendering bits that represent the rendering properties required to properly render this primitive.

getIndexStride()int

A convenience function to return the gap between successive index numbers, in bytes, of the index data.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getIndexType() → NumericType

Returns the numeric type of the index column. Normally, this will be either NT_uint16 or NT_uint32.

getMaxVertex()int

Returns the maximum vertex index number used by all the primitives in this object.

getMaxs()GeomVertexArrayData

Returns a const pointer to the primitive maxs array so application code can read it directly. Do not attempt to modify the returned array; use setMinmax().

Note that simple primitive types, like triangles, do not have a maxs array.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getMinNumVerticesPerPrimitive()int

Returns the minimum number of vertices that must be added before closePrimitive() may legally be called.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getMinVertex()int

Returns the minimum vertex index number used by all the primitives in this object.

getMins()GeomVertexArrayData

Returns a const pointer to the primitive mins array so application code can read it directly. Do not attempt to modify the returned array; use setMinmax() for this.

Note that simple primitive types, like triangles, do not have a mins array.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getModified()UpdateSeq

Returns a sequence number which is guaranteed to change at least every time the vertex index array is modified.

getNumBytes()int

Returns the number of bytes consumed by the primitive and its index table(s).

getNumFaces()int

Returns the number of triangles or other fundamental type (such as line segments) represented by all the primitives in this object.

getNumPrimitives()int

Returns the number of individual primitives stored within this object. All primitives are the same type.

getNumUnusedVerticesPerPrimitive()int

Returns the number of vertices that are added between primitives that aren’t, strictly speaking, part of the primitives themselves. This is used, for instance, to define degenerate triangles to connect otherwise disconnected triangle strips.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getNumUsedVertices()int

Returns the number of vertices used by all of the primitives. This is the same as summing get_primitive_num_vertices(n) for n in getNumPrimitives(). It is like getNumVertices() except that it excludes all of the degenerate vertices and strip-cut indices.

getNumVertices()int

Returns the number of indices used by all the primitives in this object.

getNumVerticesPerPrimitive()int

If the primitive type is a simple type in which all primitives have the same number of vertices, like triangles, returns the number of vertices per primitive. If the primitive type is a more complex type in which different primitives might have different numbers of vertices, for instance a triangle strip, returns 0.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getPrimitiveEnd(n: int)int

Returns the element within the _vertices list at which the nth primitive ends. This is one past the last valid element for the nth primitive.

getPrimitiveMaxVertex(n: int)int

Returns the maximum vertex index number used by the nth primitive in this object.

getPrimitiveMinVertex(n: int)int

Returns the minimum vertex index number used by the nth primitive in this object.

getPrimitiveNumFaces(n: int)int

Returns the number of triangles or other fundamental type (such as line segments) represented by the nth primitive in this object.

getPrimitiveNumVertices(n: int)int

Returns the number of vertices used by the nth primitive. This is the same thing as get_primitive_end(n) - get_primitive_start(n).

getPrimitiveStart(n: int)int

Returns the element within the _vertices list at which the nth primitive starts.

If i is one more than the highest valid primitive vertex, the return value will be one more than the last valid vertex. Thus, it is generally true that the vertices used by a particular primitive i are the set get_primitive_start(n) <= vi < get_primitive_start(n + 1) (although this range also includes the unused vertices between primitives).

getPrimitiveType() → PrimitiveType
getShadeModel() → ShadeModel

Returns the ShadeModel hint for this primitive. This is intended as a hint to the renderer to tell it how the per-vertex colors and normals are applied.

getStripCutIndex()int

If relevant, returns the index value that may be used in some cases to signify the end of a primitive. This is typically the highest value that the numeric type can store.

getUsageHint() → UsageHint

Returns the usage hint for this primitive. See geomEnums.h. This has nothing to do with the usage hint associated with the primitive’s vertices; this only specifies how often the vertex indices that define the primitive will be modified.

It is perfectly legal (and, in fact, common) for a GeomPrimitive to have UH_static on itself, while referencing vertex data with UH_dynamic. This means that the vertices themselves will be animated, but the primitive will always reference the same set of vertices from the pool.

getVertex(i: int)int

Returns the ith vertex index in the table.

getVertexList()list
getVertices()GeomVertexArrayData

Returns a const pointer to the vertex index array so application code can read it directly. This might return NULL if the primitive is nonindexed. Do not attempt to modify the returned array; use modifyVertices() or setVertices() for this.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

getVerticesHandle(current_thread: Thread)GeomVertexArrayDataHandle

Equivalent to get_vertices().get_handle().

property index_strideint

A convenience function to return the gap between successive index numbers, in bytes, of the index data.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

property index_type → NumericType

Returns the numeric type of the index column. Normally, this will be either NT_uint16 or NT_uint32.

isComposite()bool

Returns true if the primitive is a composite primitive such as a tristrip or trifan, or false if it is a fundamental primitive such as a collection of triangles.

isIndexed()bool

Returns true if the primitive is indexed, false otherwise. An indexed primitive stores a table of index numbers into its GeomVertexData, so that it can reference the vertices in any order. A nonindexed primitive, on the other hand, stores only the first vertex number and number of vertices used, so that it can only reference the vertices consecutively.

makeAdjacency()GeomPrimitive

Adds adjacency information to this primitive. May return null if this type of geometry does not support adjacency information.

New in version 1.10.0.

makeCopy()GeomPrimitive
makeIndexed()None

Converts the primitive from nonindexed form to indexed form. This will simply create an index table that is numbered consecutively from getFirstVertex(); it does not automatically collapse together identical vertices that may have been split apart by a previous call to makeNonindexed().

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

makeLines()GeomPrimitive

Returns a new GeomLines primitive that represents each of the edges in the original primitive rendered as a line. If the original primitive is already a GeomLines primitive, returns the original primitive unchanged.

makeNonindexed(dest: GeomVertexData, source: GeomVertexData)None

Converts the primitive from indexed to nonindexed by duplicating vertices as necessary into the indicated dest GeomVertexData. Note: does not support primitives with strip cut indices.

makePatches()GeomPrimitive

Decomposes a complex primitive type into a simpler primitive type, for instance triangle strips to triangles, puts these in a new GeomPatches object and returns a pointer to the new primitive definition. If the decomposition cannot be performed, this might return the original object.

This method is useful for application code that wants to use tesselation shaders on arbitrary geometry.

makePoints()GeomPrimitive

Returns a new GeomPoints primitive that represents each of the vertices in the original primitive, rendered exactly once. If the original primitive is already a GeomPoints primitive, returns the original primitive unchanged.

matchShadeModel(shade_model: ShadeModel)GeomPrimitive

Returns a new primitive that is compatible with the indicated shade model, if possible, or NULL if this is not possible.

In most cases, this will return either NULL or the original primitive. In the case of a SM_flat_first_vertex vs. a SM_flat_last_vertex (or vice- versa), however, it will return a rotated primitive.

property maxs → ConstPointerTo_GeomVertexArrayData

Returns a const pointer to the primitive maxs array so application code can read it directly. Do not attempt to modify the returned array; use setMinmax().

Note that simple primitive types, like triangles, do not have a maxs array.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

property min_num_vertices_per_primitiveint

Returns the minimum number of vertices that must be added before closePrimitive() may legally be called.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

property mins → ConstPointerTo_GeomVertexArrayData

Returns a const pointer to the primitive mins array so application code can read it directly. Do not attempt to modify the returned array; use setMinmax() for this.

Note that simple primitive types, like triangles, do not have a mins array.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

property modifiedUpdateSeq

Returns a sequence number which is guaranteed to change at least every time the vertex index array is modified.

modifyEnds()PTA_int

Returns a modifiable pointer to the primitive ends array, so application code can directly fiddle with this data. Use with caution, since there are no checks that the data will be left in a stable state.

Note that simple primitive types, like triangles, do not have a ends array: since all the primitives have the same number of vertices, it is not needed.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

modifyVertices(num_vertices: int)GeomVertexArrayData

Returns a modifiable pointer to the vertex index list, so application code can directly fiddle with this data. Use with caution, since there are no checks that the data will be left in a stable state.

If this is called on a nonindexed primitive, it will implicitly be converted to an indexed primitive.

If num_vertices is not -1, it specifies an artificial limit to the number of vertices in the array. Otherwise, all of the vertices in the array will be used.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

modifyVerticesHandle(current_thread: Thread)GeomVertexArrayDataHandle

Equivalent to modify_vertices().get_handle().

property num_bytesint

Returns the number of bytes consumed by the primitive and its index table(s).

property num_unused_vertices_per_primitiveint

Returns the number of vertices that are added between primitives that aren’t, strictly speaking, part of the primitives themselves. This is used, for instance, to define degenerate triangles to connect otherwise disconnected triangle strips.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

property num_vertices_per_primitiveint

If the primitive type is a simple type in which all primitives have the same number of vertices, like triangles, returns the number of vertices per primitive. If the primitive type is a more complex type in which different primitives might have different numbers of vertices, for instance a triangle strip, returns 0.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

offsetVertices(offset: int)None

Adds the indicated offset to all vertices used by the primitive.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

offsetVertices(offset: int, begin_row: int, end_row: int)None

Adds the indicated offset to the indicated segment of vertices used by the primitive. Unlike the other version of offsetVertices(), this makes the geometry indexed if it isn’t already.

Note that end_row indicates one past the last row that should be offset. In other words, the number of vertices touched is (end_row - begin_row).

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

operatorNew(size: int)None
output(out: ostream)None
packVertices(dest: GeomVertexData, source: GeomVertexData)None

Packs the vertices used by the primitive from the indicated source array onto the end of the indicated destination array.

property primitive_type → PrimitiveType
requestResident(current_thread: Thread)bool

Returns true if the primitive data is currently resident in memory. If this returns false, the primitive data will be brought back into memory shortly; try again later.

reserveNumVertices(num_vertices: int)None

This ensures that enough memory space for n vertices is allocated, so that you may increase the number of vertices to n without causing a new memory allocation. This is a performance optimization only; it is especially useful when you know ahead of time that you will be adding n vertices to the primitive.

Note that the total you specify here should also include implicit vertices which may be added at each closePrimitive() call, according to getNumUnusedVerticesPerPrimitive().

Note also that making this call will implicitly make the primitive indexed if it is not already, which could result in a performance penalty. If you would prefer not to lose the nonindexed nature of your existing GeomPrimitives, check isIndexed() before making this call.

reverse()GeomPrimitive

Reverses the winding order in the primitive so that each triangle is facing in the opposite direction it was originally. Note that this doesn’t affect vertex normals, so this operation alone won’t work in the presence of lighting (but see SceneGraphReducer::reverse()).

Also see CullFaceAttrib, which can change the visible direction of a triangle without having to duplicate it (but which doesn’t necessarily work in the presence of lighting).

rotate()GeomPrimitive

Returns a new primitive with the shade_model reversed (if it is flat shaded), if possible. If the primitive type cannot be rotated, returns the original primitive, unrotated.

If the current shade_model indicates flat_vertex_last, this should bring the last vertex to the first position; if it indicates flat_vertex_first, this should bring the first vertex to the last position.

setEnds(ends: PTA_int)None

Completely replaces the primitive ends array with a new table. Chances are good that you should also replace the vertices list with setVertices() at the same time.

Note that simple primitive types, like triangles, do not have a ends array: since all the primitives have the same number of vertices, it is not needed.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

setIndexType(index_type: NumericType)None

Changes the numeric type of the index column. Normally, this should be either NT_uint16 or NT_uint32.

The index type must be large enough to include all of the index values in the primitive. It may be automatically elevated, if necessary, to a larger index type, by a subsequent call to add_index() that names an index value that does not fit in the index type you specify.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

setMinmax(min_vertex: int, max_vertex: int, mins: GeomVertexArrayData, maxs: GeomVertexArrayData)None

Explicitly specifies the minimum and maximum vertices, as well as the lists of per-component min and max.

Use this method with extreme caution. It’s generally better to let the GeomPrimitive compute these explicitly, unless for some reason you can do it faster and you absolutely need the speed improvement.

Note that any modification to the vertex array will normally cause this to be recomputed, unless you set it immediately again.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

setNonindexedVertices(first_vertex: int, num_vertices: int)None

Sets the primitive up as a nonindexed primitive, using the indicated vertex range.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

setShadeModel(shade_model: ShadeModel)None

Changes the ShadeModel hint for this primitive. This is different from the ShadeModelAttrib that might also be applied from the scene graph. This does not affect the shade model that is in effect when rendering, but rather serves as a hint to the renderer to tell it how the per-vertex colors and normals on this primitive are applied.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

setUsageHint(usage_hint: UsageHint)None

Changes the UsageHint hint for this primitive. See getUsageHint().

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

setVertices(vertices: GeomVertexArrayData, num_vertices: int)None

Completely replaces the vertex index list with a new table. Chances are good that you should also replace the ends list with setEnds() at the same time.

If num_vertices is not -1, it specifies an artificial limit to the number of vertices in the array. Otherwise, all of the vertices in the array will be used.

Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.

This method is intended for low-level usage only. There are higher-level methods for more common usage. We recommend you do not use this method directly. If you do, be sure you know what you are doing!

property shade_model → ShadeModel

Returns the ShadeModel hint for this primitive. This is intended as a hint to the renderer to tell it how the per-vertex colors and normals are applied.

property strip_cut_indexint

If relevant, returns the index value that may be used in some cases to signify the end of a primitive. This is typically the highest value that the numeric type can store.

Returns the index of the indicated type that is reserved for use as a strip cut index, if enabled for the primitive. When the renderer encounters this index, it will restart the primitive. This is guaranteed not to point to an actual vertex.

property usage_hint → UsageHint

Returns the usage hint for this primitive. See geomEnums.h. This has nothing to do with the usage hint associated with the primitive’s vertices; this only specifies how often the vertex indices that define the primitive will be modified.

It is perfectly legal (and, in fact, common) for a GeomPrimitive to have UH_static on itself, while referencing vertex data with UH_dynamic. This means that the vertices themselves will be animated, but the primitive will always reference the same set of vertices from the pool.

write(out: ostream, indent_level: int)None