Geometry and Appearances

[pjcozzi]

Sandcastle example screenshot:

For context, read the draft tutorials. From the tutorials:

A geometry defines the primitive's structure, i.e., the triangles, lines, or points composing the primitive. An appearance defines the primitive's shading, including its full GLSL vertex and fragment shaders, and render state.

Also see the roadmap for an intro (slightly outdated) and future work.

From CHANGES.md:

• Breaking changes:
  • Replaced tessellators and meshes with geometry. In particular:
    • Replaced CubeMapEllipsoidTessellator with EllipsoidGeometry.
    • Replaced BoxTessellator with BoxGeometry.
    • Replaced ExtentTessletaor with ExtentGeometry.
    • Removed PlaneTessellator. It was incomplete and not used.
    • Renamed MeshFilters to GeometryPipeline.
    • Renamed MeshFilters.toWireframeInPlace to GeometryPipeline.toWireframe.
    • Removed MeshFilters.mapAttributeIndices. It was not used.
    • Renamed Context.createVertexArrayFromMesh to Context.createVertexArrayFromGeometry. Likewise, renamed mesh constructor property to geometry.
  • Renamed ComponentDatatype.*.toTypedArray to ComponentDatatype.*.createTypedArray.
  • Removed Polygon.configureExtent. Use ExtentPrimitive instead.
  • Removed Polygon.bufferUsage. It is no longer needed.
  • Removed height and textureRotationAngle arguments from Polygon setPositions and configureFromPolygonHierarchy functions. Use Polygon height and textureRotationAngle properties.
  • Renamed PolygonPipeline.cleanUp to PolygonPipeline.removeDuplicates.
  • Removed PolygonPipeline.wrapLongitude. Use GeometryPipeline.wrapLongitude instead.
  • Added height parameter to BoundingSphere.fromExtent3D.
  • Added height parameter to Extent.subsample.
• Added ExtentPrimitive.
• Added Geometry and GeometryInstance. Added the following geometry types:
  • PolygonGeometry
  • ExtentGeometry
  • EllipseGeometry
  • CircleGeometry
  • WallGeometry
  • SimplePolylineGeometry
  • BoxGeometry
  • EllipsoidGeometry
• Added appearances, which describe the visual characteristics for geometry instances. Added the following types:
  • Appearance
  • PerInstanceColorAppearance
  • EllipsoidSurfaceAppearance
• Added Primitive, which is a generic primitive that combines geometry instances and appearances.
• Added GeometryPipeline.combine to combine meshes for better batching.
• Added GeometryPipeline.computeNormal to compute normals for a geometry.
• Added GeometryPipeline.computeBinormalAndTangent to compute binormals and tangent vectors for a geometry.
• Added GeometryPipeline.wrapLongitude to split geometry across the International Date Line.
• Added GeometryPipeline.createLineSegmentsForVectors and createTangentSpaceDebugPrimitive for debugging.
• Added PolylinePipeline.removeDuplicates.
• Added barycentricCoordinates to compute the barycentric coordinates of a point in a triangle.
• Added BoundingSphere.fromEllipsoid.
• Added BoundingSphere.projectTo2D.
• Added Extent.fromDegrees.
• Added czm_tangentToEyeSpaceMatrix built-in GLSL function.
• Improved the performance of drawing polygons created with configureFromPolygonHierarchy.

@bagnell - with some help from @hpinkos - will do the changes needed to merge this. I'm moving on to models. There are still a few outstanding changes that will be part of this:

• Finish tests and remove test code from Cesium Viewer.
• Fix texture coordinates on ellipses/circles, which look wrong in the Sandcastle example.
• Fix wall normals / faceForward, which look wrong in the Sandcastle example.

Other features - like extruded polygons and extents, and performance improvements (all in the near-term section of the roadmap) - will be separate pull requests.

The draft tutorials will be finalized and published on the blog in August after b19.

[mramato]

Get rid of - or a single geometry instance -, This function has to take an array and it makes it sound like it can take a GeometryInstance object as well as an array.

[bagnell]

It can take a single GeometryInstance object as well as an array.

[mramato]

Okay, then change {Array} to {Array | GeometryInstance} since that's how we normally document parameters that can be multiple things.

[mramato]

Okay, I'm done my review. That was exhausting. 😉 I didn't look at the Specs too closely, but coverage looks good and we'll add additional specs to verify any future bugs we find. Let me know when you are done with all your changes and I can do final tests/confirmation before merging.

Overall, this is awesome. Obviously there's going to be a lot of work to be done to leverage this at the higher-level (DynamicScene/CZML/GeoJSON/etc...) but this is a huge step to making Cesium even more awesome. Thanks guys.

[bagnell]

@mramato This is ready for another review.

[mramato]

Does anyone else want to take a look at this? If I don't hear anything, or find any issues in the next 15 minutes or so, I think we're ready.