When should I use BatchMesh, and when should I use TriMesh? I see that TriMesh has been updated more recently in CVS, but is that a reliable indication of maturity?
Also, the contracts for either class aren't spelled out in the class descriptions. I couldn't find anything in the Wiki, either. Is there better documentation somewhere?
Use Trimesh for everything, unless you need a special batch type (like lines or quads instead of triangles). TriMesh has more features.
Use TriMesh any time you can, it is the standard jME geometry class, and it supports all features like picking and intersection. It's always better to use triangles for geometry since stuff like quads or polygons need to be tessellated on most hardware to be rendered, and doing that in real time means performance loss. The general contract for TriMesh is that contains only TriangleBatches, e.g. only triangle based geometry, while BatchMesh can contain QuadBatches, LineBatches, etc.
Well, I'm more interested in the data contract. If I update the data in the FloatStream for vertex positions, will that data be reflected in the rendered data? If so, is that implemented using dumb system memory vertex arrays, or something more efficient like Vertex Buffer Objects in STREAM_DRAW mode? If I don't update the data, will it use STATIC_DRAW mode? I notice there's some form of "lock" functions, but they also aren't terribly well documented.
Also, I don't get why indices HAS to be non-NULL. It would make sense to draw a triangle list without indices (plain glDrawArrays()) if there wasn't an index buffer, for data that doesn't really use indexing anyway. That's more of a feature request, though – but documenting the actual usage patterns of the class, and how the class contract fulfills those patterns, would be great.
Hmm, reading the source, I came across the implementation of setSolidColor(). I'll post about that in another thread.
The data contract is that all updates done to the geometry buffers immediately take effect on rendering; unless you set vbo or a locking mode, the renderer will use array pointers to upload the data.
If VBO is set, the renderer assumes the data will not be modified (it's in STATIC_DRAW mode), and if locking is set, the renderer will create a display list for the data. I suggested in another thread that jME should support the other modes for vertex buffer objects, hopefully that will get implemented in jME 2.0. Also I think that locking should be less-renderer specific (VBO is only an OpenGL feature). It's best if the user specified several parameters for how the geometry data would be handled and then the renderer makes the rest of the choices depending on which features or extensions are supported.
I agree with your sentiment. Thanks for explaining the contract.
I'll go looking for a bug tracker to file that explanation as a documentation request 