Changes between Version 9 and Version 10 of DevWikiPostGISCoding

Timestamp:

Dec 11, 2010, 9:21:53 AM (13 years ago)

Author:

pramsey

Comment:

—

DevWikiPostGISCoding

@@ -59 +59 @@
 PG_RETURN_TEXT_P(text);
 }}}
+
+== LWGEOM ==
+
+LWGEOM are the working structure of the PostGIS algorithms. Because PostGIS is written in C, LWGEOM is not quite a abstract superclass of all the geometry variants, but it tries hard to be. Every LWGEOM variant can be cast to LWGEOM, and will retain common references to lgeom->type, lwgeom->flags, and lwgeom->bbox. The type in an integer type number (POINT, LINE, POLYGON, etc). The flags is a set of eight binary bits indicating the presence of Z or M dimensions, whether the interpretation of the coordinates in geodetic, and so on. The the bbox is a pointer to a GBOX which defines the extend of the geometry in up to 4 dimensions.
+
+After the standard components, the LWGEOM variants start to differ. LWLINE, LWPOINT, TRIANGLE< and LWCIRCSTRING have a pointer to a POINTARRAY (the coordinates). POLYGON has ring count, then a pointer to a list of POINTARRAY pointers (the rings). All other variants have a sub-element counts, then a pointer to a list of LWGEOM pointers. For homogenous collections, the sub-geometries may be appropriately types, but from a memory-layout point-of-view, they are all identical.
+
+All geometries are, at their core, collections of coordinates, just with different organizations and different interpretations between the coordinates (multi geometries versus single, or linear versus curved, or cartesian versus geodetic). The coordinates are managed inside the POINTARRAY type, in a "serialized_pointlist". When LWGEOMs are constructed from WKT or WKB (using ptarray_construct_copy_data() ), each POINTARRAY has it's own serialized_pointlist allocated and the coordinates copied into that list. When LWGEOMs are constructed from database serializations (see GSERIALIZED and PG_LWGEOM below) the serialized_pointlist is not separately allocated, it is a pointer into a position in the GSERIALIZED or PG_LWGEOM, constructed using ptarray_construct_reference_data().
+
+Regardless of whether a POINTARRAY is database-backed, or independently allocated, the memory management should automatically "do the right thing", if the POINTARRAY was constructed using one of the constructors provided by the POINTARRAY API. When constructed with ptarray_construct_reference_data(), a POINTARRAY has its FLAGS_READ_ONLY bit set, which tells the ptarray_free() function to not free the underlying serialized_pointlist (because it is not managed by the POINTARRAY, but by the database).