Back to 5.0.0-doc main page
Buffer Options
For many years the GEOS library has allowed the customization of the ST_Buffer() standard behavior, which the previous SpatiaLite versions did not fully support.Starting with version 5.0 SpatiaLite will now offer a complete support for all Buffer Options available through GEOS:
- Buffer Options are implemented as a set of persistent settings at the connection level.
- this means that during the lifetime of a connection, any set Buffer Option will be used when calling ST_Buffer() or ST_SingleSidedBuffer()
- a set of 9 new SQL functions have been introduced so to allow users for freely set and query the Buffer Options.
A short introduction to these new SQL functions:
| SQL Function | Examples | Argument | Return Value | Notes |
|---|---|---|---|---|
| BufferOptions_SetEndCapStyle() |
SELECT BufferOptions_SetEndCapStyle('SQUARE');
----
1
SELECT BufferOptions_SetEndCapStyle('square');
----
1
SELECT BufferOptions_SetEndCapStyle('gothic');
----
0
|
the name of a valid EndCap Style; accepted values are:
Note: style names are case insensitive |
1 (aka TRUE) on success. 0 (aka FALSE) on failure or on invalid argument. |
Will set the current EndCap Style. (it will control the style of line's terminations). |
| BufferOptions_GetEndCapStyle() | SELECT BufferOptions_GetEndCapStyle(); ---- SQUARE |
none | a Text string on success. NULL on failure. |
Will return the name of the currently set EndCap Style. |
| BufferOptions_SetJoinStyle() |
SELECT BufferOptions_SetJoinStyle('BEVEL');
----
1
SELECT BufferOptions_SetJoinStyle('BeVeL');
----
1
SELECT BufferOptions_SetJoinStyle('baroque');
----
0
|
the name of a valid Join Style; accepted values are:
Note: style names are case insensitive |
1 (aka TRUE) on success. 0 (aka FALSE) on failure or on invalid argument. |
Will set the current Join Style. (it will control the style of joins connecting two consecutive lines). |
| BufferOptions_GetJoinStyle() | SELECT BufferOptions_GetJoinStyle(); ---- MITRE |
none | a Text string on success. NULL on failure. |
Will return the name of the currently set Join Style. |
| BufferOptions_SetMitreLimit() |
SELECT BufferOptions_SetMitreLimit(2.5);
----
1
SELECT BufferOptions_SetMitreLimit(5);
----
1
SELECT BufferOptions_SetMitreLimit('zero');
----
0
|
an Integer or Double positive number. Default value: 5.0 |
1 (aka TRUE) on success. 0 (aka FALSE) on failure or on invalid argument. |
Will set the current Mitre Limit value. (it will control how much acute will be a mitered join connecting two consecutive lines). Note: the MitreLimit will be considered only when the MITRE Join Style is set. |
| BufferOptions_GetMitreLimit() | SELECT BufferOptions_GetMitreLimit(); ---- 5.0 |
none | a Double number on success. NULL on failure. |
Will return the value of the currently set Mitre Limit. |
| BufferOptions_SetQuadrantSegments() |
SELECT BufferOptions_SetQuadrantSegments(8);
----
1
SELECT BufferOptions_SetQuadrantSegments('none');
----
0
|
an Integer positive number. Default value: 30 |
1 (aka TRUE) on success. 0 (aka FALSE) on failure or on invalid argument. |
Will set the current QuadrantSegments value. (it will control how many points have to be interpolated for each quadrant when approximating circular arcs). Note: both ST_Buffer() and ST_SingleSidedBuffer() support an optional points argument with the same identical meaning. An explicitly set points argument will always override the current BufferOprions QuadrantSegments value. |
| BufferOptions_GetQuadrantSegments() | SELECT BufferOptions_GetQuadrantSegments(); ---- 30 |
none | an Integer number on success. NULL on failure. |
Will return the value of the currently set QuadrantSegments. |
| BufferOptions_Reset() | SELECT BufferOptions_Reset(); --- 1 |
none | 1 (aka TRUE) on success. 0 (aka FALSE) on failure. |
Will reset the persistent BufferOptions to their initial default values. |
The easiest and quickest way to fully understand the exact effect of each Buffer Option, is by consulting the following graphic chart:
| Option | Visual Samples | ||
|---|---|---|---|
| EndCapStyle |  ROUND (default) |
 FLAT |
 SQUARE |
| JoinStyle |  ROUND (default) |
 MITRE |
 BEVEL |
| MitreLimit |  1.0 |
 2.5 |
 5.0 (default) |
| QuadrantSegments |  1 |
 2 |
 30 (default) |
Back to 5.0.0-doc main page