Types [Water Reference Manual]

	Reference Manual - draft
Water Types

WaterScalar

A single integer, fixed or floating point value (union)

	int			i		Ordinary or fixed point integer value
	float			f		Floating point value

WaterScalarType

Type of scalar [4]

WST_UNKNOWN	0x0	Unknown/invalid scalar type
WST_INTEGER	0x1	Ordinary (pure) integer value
WST_FIXED_12_20	0x2	Fixed point with 12 sign+integral and 20 fractional bits
WST_FIXED_16_16	0x3	Fixed point with 16 sign+integral and 16 fractional bits
WST_FIXED_24_8	0x4	Fixed point with 24 sign+integral and 8 fractional bits
WST_FLOAT	0x8	Single precision floating point value

WATER_SCALAR_TYPE_IS_INT (type)

Macro determines if scalar is an ordinary (pure) integer or fixed point integer

((type) >= 0x1 && (type) <= 0x7)

WATER_SCALAR_TYPE_IS_FLOAT (type)

Macro determines if scalar is a single precision float

((type) == WST_FLOAT)

WaterTransformFlags

Flags choosing predefined or free transformation and other things [8]

WTF_NONE	0x00	None of these
WTF_SCALAR	0x01	The format of the scalar values has been set
WTF_TYPE	0x02	The type of the matrix has been set or determined
WTF_MATRIX	0x04	The matrix is filled with all (any) six values
WTF_REPLACE	0x10	Replace previous transformation completely, otherwise append to it
WTF_ALL	0x17	All of these

WaterTransformType

Common types of transformations [16]

	WTT_NONE		0x0000
	WTT_ZERO		0x0001
	WTT_IDENTITY		0x0002
	WTT_TRANSLATE_X		0x0004
	WTT_TRANSLATE_Y		0x0008
	WTT_TRANSLATE_MASK		0x000C
	WTT_SCALE_X		0x0010
	WTT_SCALE_Y		0x0020
	WTT_SCALE_MASK		0x0030
	WTT_FLIP_X		0x0040
	WTT_FLIP_Y		0x0080
	WTT_FLIP_MASK		0x00C0
	WTT_SKEW_X		0x0100
	WTT_SKEW_Y		0x0200
	WTT_SKEW_MASK		0x0300
	WTT_ROTATE_Q_90		0x1000
	WTT_ROTATE_Q_180		0x2000
	WTT_ROTATE_Q_270		0x4000
	WTT_ROTATE_Q_MASK		0x7000
	WTT_ROTATE_FREE		0x8000
	WTT_ROTATE_MASK		0xF000
	WTT_ALL		0xF3FF

WaterTransform

Transformation

WaterTransformFlags	flags : 8	Transformation flags
WaterScalarType	scalar : 4	Set scalar type for matrix entries
unsigned int	_rsrv1 : 4	reserved bits
WaterTransformType	type : 16	Predefined type of transformation (using none, one or two values)
WaterScalar	matrix[6]	All six entries of the 3x2 matrix from left to right, top to bottom

WaterRenderMode

Options generally applying to rendering or the destination [16]

WRM_NONE	0x0000	None of these
WRM_ANTIALIAS	0x0001	Use anti-aliasing
WRM_COLORKEY	0x0002	Only write to pixels having a specific value
WRM_KEYPROTECT	0x0004	Ensure that a certain pixel value is not written, e.g. by toggling the LSB when the protected value is to be written
WRM_ALL	0x0007	All of these

WaterPaintOptions

Options regarding the source of drawing/filling operations [16]

WPO_NONE	0x0000	None of these
WPO_COLOR	0x0001	Use solid color, modulating RGB of pattern if used in conjunction
WPO_GRADIENT	0x0002	Use color gradient, modulating RGB of pattern if used in conjunction
WPO_PATTERN	0x0004	Use source pattern, surface containing ARGB values
WPO_MASK	0x0008	Use source mask, surface containing A(RGB) values
WPO_ALPHA	0x0010	Use alpha factor, modulating alpha of color\|gradient\|pattern\|mask
WPO_BLEND	0x0020	Use alpha blending, applying source/destination blend functions
WPO_PREMULTIPLY	0x0040	Premultiply alpha values, modulating RGB when reading the source data
WPO_COLORKEY	0x0080	Skip pixels having a specific value, not writing the pixel at all
WPO_TILE_PATTERN	0x0100	Use tiling mode for pattern data, see WaterTileMode
WPO_TILE_MASK	0x0200	Use tiling mode for mask data, see WaterTileMode
WPO_ALL	0x03FF	All of these

WaterTileMode

Tiling mode for patterns and masks [4]

WTM_SCALE	0x0	Single tile, but scaled to cover all of the destination.
WTM_TILE	0x1	Tiles are simply repeated
WTM_FLIP_X	0x2	Tiles are flipped horizontally each column
WTM_FLIP_Y	0x3	Tiles are flipped vertically each row
WTM_FLIP_XY	0x4	Tiles are flipped horizontally/vertically each column/row

To apply any of these tile modes, WPO_TILE_PATTERN and/or WPO_TILE_MASK must be set. Otherwise a single tile is being drawn and the area that is not covered is filled with the color set via WaterAttributeType::WAT_DRAW_TILECOLOR or WaterAttributeType::WAT_FILL_TILECOLOR.

See also WaterPaintOptions::WPO_TILE_PATTERN and WaterPaintOptions::WPO_TILE_MASK

WaterQualityLevel

Quality levels [4]

WQL_FAIR	0x0	Performance should be OK, quality still acceptable (use best possible and fast)
WQL_FAST	0x1	Performance should be best, quality is secondary (use best possible at fastest)
WQL_BEST	0x2	Quality should be best, no matter what performance will
WQL_OFF	0x3	Disable setting, always using worst quality

WaterColor

A simple color definition

u8	a	Alpha channel value (0-255)
u8	r	Red channel value (0-255)
u8	g	Green channel value (0-255)
u8	b	Blue channel value (0-255)

See also WaterAttributeType::WAT_DRAW_COLOR and WaterAttributeType::WAT_FILL_COLOR

API FIXME: Add more color definitions using better precision.

WaterBlendMode

Blend modes as defined by SVG 1.2 [8]

WBM_SRC	0x00	The source is copied to the destination. The destination is not used as input.
WBM_DST	0x01	The destination is left untouched.
WBM_SRCOVER	0x02	The source is composited over the destination.
WBM_DSTOVER	0x03	The destination is composited over the source and the result replaces the destination.
WBM_SRCIN	0x04	The part of the source lying inside of the destination replaces the destination.
WBM_DSTIN	0x05	The part of the destination lying inside of the source replaces the destination.
WBM_SRCOUT	0x06	The part of the source lying outside of the destination replaces the destination.
WBM_DSTOUT	0x07	The part of the destination lying outside of the source replaces the destination.
WBM_SRCATOP	0x08	The part of the source lying inside of the destination is composited onto the destination.
WBM_DSTATOP	0x09	The part of the destination lying inside of the source is composited over the source and replaces the destination.
WBM_CLEAR	0x0A	Both the color and the alpha of the destination are cleared.
WBM_XOR	0x0B	The part of the source that lies outside of the destination is combined with the part of the destination that lies outside of the source.
WBM_ADD	0x0C	The source is added to the destination and replaces the destination.
WBM_MULTIPLY	0x0D	The source is multiplied by the destination and replaces the destination.
WBM_SCREEN	0x0E	The source and destination are complemented and then multiplied and then replace the destination.
WBM_OVERLAY	0x0F	Multiplies or screens the colors, dependent on the destination color.
WBM_DARKEN	0x10	Selects the darker of the destination and source colors.
WBM_LIGHTEN	0x11	Selects the lighter of the destination and source colors.
WBM_COLORDODGE	0x12	Brightens the destination color to reflect the source color.
WBM_COLORBURN	0x13	Darkens the destination color to reflect the source color.
WBM_HARDLIGHT	0x14	Multiplies or screens the colors, dependent on the source color value.
WBM_SOFTLIGHT	0x15	Darkens or lightens the colors, dependent on the source color value.
WBM_DIFFERENCE	0x16	Subtracts the darker of the two constituent colors from the lighter.
WBM_EXCLUSION	0x17	Produces an effect similar to that of 'difference', but appears as lower contrast.

WaterFillRule

Fill rules as defined by SVG 1.1 [4]

	WFR_NONZERO		0x0		This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and then examining the places where a segment of the shape crosses the ray.
	WFR_EVENODD		0x1		This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses.

WaterLineCapStyle

Style of line end points [4]

WLCS_BUTT	0x0	Cut the line perpendicular where the cut hits the end points
WLCS_ROUND	0x1	WLCS_BUTT with half a circle being appended (radius is half of line width)
WLCS_QUARE	0x2	WLCS_BUTT cut off/after end point (longer by half of line width)

See also WaterAttributeType::WAT_LINE_STYLE and WaterAttributeType::WAT_LINE_CAP_STYLE

WaterLineJoinStyle

Style of line junctions [4]

WLJS_MITER	0x0	Draw miter (sharp edge), see also WaterAttributeType::WAT_LINE_MITER_LIMIT and WaterAttributeType::WAT_LINE_STYLE
WLJS_ROUND	0x1	Round corners with a circle around the junction point (half line width radius)
WLJS_BEVEL	0x2	Cut off corner at half of the line width further than the junction point

See also WaterAttributeType::WAT_LINE_STYLE and WaterAttributeType::WAT_LINE_JOIN_STYLE

WaterGradientType

Gradients [4]

WGT_LINEAR	0x0	Linear gradient
WGT_RADIAL	0x1	Radial gradient
WGT_CONICAL	0x2	Conical gradient

WaterValueFlags

Flags for a group of element values [16]

WVF_NONE	0x0000	None of these
WVF_X	0x0001	X coordinate is given
WVF_Y	0x0002	Y coordinate is given
WVF_RX	0x0004	X radius (or just length/radius) is given
WVF_RY	0x0008	Y radius is given
WVF_A	0x0010	Angle is given
WVF_F	0x0020	Flags are given
WVF_RELATIVE	0x0040	All coordinate values (X & Y) are relative
WVF_ABSOLUTE	0x0080	All coordinate values (X & Y) are absolute
WVF_COLOR	0x0100	Fill color is given
WVF_OFFSET	0x0200	Offset within pattern space is given (two values!)
WVF_SCALAR	0x8000	Scalar type is following
WVF_ALL	0x83FF	All of these
WVF_L	WVF_RX	Alias of rx used for spans or trapezoids
WVF_R	WVF_RX	Alias of rx used for circles
WVF_XY	WVF_X \| WVF_Y	Point or part of line, triangle, rectangle, curve...
WVF_XY_L	WVF_XY \| WVF_L	Span line
WVF_XY_R	WVF_XY \| WVF_R	Circle
WVF_XY_RXRY	WVF_XY \| WVF_RX \| WVF_RY	Ellipse
WVF_XY_R_A	WVF_XY_R \| WVF_A	Arc of a circle
WVF_XY_R_A_F	WVF_XY_R \| WVF_A \| WVF_F	Arc of a circle with flags
WVF_XY_RXRY_A	WVF_XY_RXRY \| WVF_A	Arc of an ellipse
WVF_XY_RXRY_A_F	WVF_XY_RXRY \| WVF_A \| WVF_F	Arc of an ellipse with flags

General meaning

X, Y, RX (=L/R), RY, A and F indicate presence of element values within a group. When essential values are not given, their current value is kept. Relative values are still applied each time.

RELATIVE and ABSOLUTE apply to X and Y values and are mutually exclusive. Neither of them might be set. The default depends on the element type and whether it is the first group of an element (or list item).

COLOR indicates presence of a simple color definition for filling.

OFFSET indicates presence of a starting offset within the source pattern for filling.

SCALAR indicates presence of a scalar type (first in group).

Other flags are convenience definitions.

Specifying value flags

Value flags can be specified per group and/or per element (multiple groups).

Per element flags define the initial set of flags being used.
Per group flags are merged into the current set of flags.
When no initial flags are given for an element, defaults are used depending on the element type.

The way per group flags are merged into the current set isn't trivial.

X, Y and other indicators of presence of values are completely replaced.
When a mutually exclusive flag is set, other flags being mutually exclusive with it are cleared.

API FIXME: Do we need it that flexible?

API FIXME: Default to INTEGER is fine?

API FIXME: When are values relative/absolute per default?

WaterValue

A single value (union)

WaterScalar		scalar
WaterScalarType		scalar_type
WaterOperator		op
WaterValueFlags		value_flags
WaterTransformFlags		transform_flags
WaterTransformType		transform_type
WaterRenderMode		render
WaterQualityLevel		quality
WaterPaintOptions		paint
WaterColor		color
WaterBlendMode		blend
WaterFillRule		fill_rule
WaterLineCapStyle		line_cap
WaterLineJoinStyle		line_join
void	*	pointer

None of these union elements should be bigger than sizeof(void*)!

API FIXME: The union is packed, otherwise the 32 bit values (using their type alone) were not stored at the same address as the bigger union type, at least on my EM64T CPU.

WaterAttributeFlags

Flags per attribute [8]

WAF_NONE	0x00	None of these
WAF_SCALAR	0x01	The format of scalar values has been set (where appropriate)
WAF_OPERATOR	0x02	Indicates that a WaterOperator is set in op (API FIXME: unused)
WAF_ALL	0x03	All of these

WaterAttributeType

Attributes include all settings of a rendering context [16]

WAT_UNKNOWN	0x0000	Unknown/invalid attribute
WAT_RENDER_MODE	0x0001	Select anti-aliasing etc. see WaterRenderMode
WAT_RENDER_OFFSET	0x0002	Set/add an offset to apply, being independent from any transformation
WAT_RENDER_CLIP	0x0003	Set/add a clipping region, allowing 0-n rectangles being specified, using multiple passes if more rectangles are defined than hardware supports
WAT_RENDER_TRANSFORM	0x0004	Modify transformation of coordinates (path user to surface), see WaterTransform
WAT_RENDER_QUALITY_AA	0x0005	Select quality level for anti-aliased edges, see WaterQualityLevel
WAT_DRAW_OPTIONS	0x0010	Draw color, gradient, pattern, mask etc. see WaterPaintOptions
WAT_DRAW_COLOR	0x0011	Color for drawing, overridden by element colors (per group), see WaterColor
WAT_DRAW_GRADIENT	0x0012	Gradient for drawing
WAT_DRAW_PATTERN	0x0013	Select pattern surface for drawing
WAT_DRAW_MASK	0x0014	Select mask surface for drawing
WAT_DRAW_ALPHA	0x0015	Change alpha factor for drawing, see WaterScalar
WAT_DRAW_BLEND	0x0016	Select a predefined set of blend functions for drawing, see WaterBlendMode
WAT_DRAW_TRANSFORM	0x0017	Set the transformation from the source (stroke paint to user), see WaterTransform
WAT_DRAW_COLORKEY	0x0018	Colorkey for drawing, see WaterColor
WAT_DRAW_TILECOLOR	0x0019	Border color for drawing with WaterPaintOptions::WPO_TILE_PATTERN and/or WaterPaintOptions::WPO_TILE_MASK, see WaterColor
WAT_FILL_OPTIONS	0x0020	Fill color, gradient, pattern, mask etc. see WaterPaintOptions
WAT_FILL_COLOR	0x0021	Color for filling, overridden by element colors (per group), see WaterColor
WAT_FILL_GRADIENT	0x0022	Gradient for filling
WAT_FILL_RULE	0x0023	Choose the fill rule, see WaterFillRule and WaterShapeFlags
WAT_FILL_PATTERN	0x0024	Select pattern surface for filling
WAT_FILL_MASK	0x0025	Select mask surface for filling
WAT_FILL_ALPHA	0x0026	Change alpha factor for filling, see WaterScalar
WAT_FILL_BLEND	0x0027	Select a predefined set of blend functions for filling, see WaterBlendMode
WAT_FILL_TRANSFORM	0x0028	Set the transformation from the source (fill paint to user), see WaterTransform
WAT_FILL_COLORKEY	0x0029	Colorkey for filling, see WaterColor
WAT_FILL_TILECOLOR	0x002A	Border color for filling with WaterPaintOptions::WPO_TILE_PATTERN and/or WaterPaintOptions::WPO_TILE_MASK, see WaterColor
WAT_LINE_WIDTH	0x0030	Set line width for strokes, see WaterScalar
WAT_LINE_CAPSTYLE	0x0031	Change line cap style, see WaterLineCapStyle
WAT_LINE_JOINSTYLE	0x0032	Change line join style, see WaterLineJoinStyle
WAT_LINE_MITER	0x0033	Change miter limit, see WaterScalar
WAT_LINE_STYLE	0x0034	Change line cap, join style and miter limit
WAT_LINE_DASHES	0x0035	Change dashes

Each attribute can be changed, affecting rendering, e.g. in a network of attributes and elements.

There are different groups of attributes:

Rendering attributes affecting both drawing and filling, WAT_RENDER_...
Drawing attributes for the drawn outline, WAT_DRAW_...
Filling attributes for the filled area, same as drawing plus WaterFillRule, WAT_FILL_...
Line attributes for the style of the drawn outline, WAT_LINE_...

The range of type values is limited and has been split into the following sub ranges:

Base types fit into the base header WaterAttribute with official type range of 0x0000-0x3F00.
Extended types are bigger than the base header and have their official range at 0x4000-0x7F00.
At 0x8000 starts the private area of base types with extended types at 0xC000-0xEF00.
The remaining space starting at 0xF000 is RESERVED!

API FIXME: Still working on final set of attributes...

WATER_ATTRIBUTE_IS_BASE (type)

(!((type) & 0x4000))

WATER_ATTRIBUTE_IS_OFFICIAL (type)

(!((type) & 0x8000))

WATER_ATTRIBUTE_IS_EXTENDED (type)

( ((type) & 0x4000) && ((type) < 0xF000))

WATER_ATTRIBUTE_IS_PRIVATE (type)

( ((type) & 0x8000) && ((type) < 0xF000))

WATER_ATTRIBUTE_IS_RESERVED (type)

( ((type) & 0xF000) == ( 0xF000))

WaterAttribute

Header of an attribute in a stream or array

WaterAttributeType	type : 16	Attribute type (always set)
WaterAttributeFlags	flags : 8	Attribute flags (always set)
WaterScalarType	scalar : 4	Set scalar type for values
WaterOperator	op : 4	Choose way of applying the value(s)
unsigned int	_rsrv1 : 8	reserved bits
unsigned int	bytes : 24	Offset to next joint after this in bytes, if used in a stream, set to the difference in size between this and the base header of the stream plus amount of data following.
WaterValue	value	Single value or pointer to values or NULL. In case of NULL and if values are needed for the attribute, they simply follow this struct, with bytes set accordingly.

WaterBasicElement

A basic element denotes a simple part of a shape using straight lines [32]

WBE_NONE	0x00000000	None of these
WBE_POINT	0x00000001	Single point or point list
WBE_SPAN	0x00000002	Single span or list of spans
WBE_LINE	0x00000010	Single line or list of lines
WBE_LINE_STRIP	0x00000020	Plain strip of lines
WBE_LINE_LOOP	0x00000040	Closing line strip
WBE_TRIANGLE	0x00000100	Single triangle or list of triangles
WBE_TRIANGLE_FAN	0x00000200	Triangle fan
WBE_TRIANGLE_STRIP	0x00000400	Triangle strip
WBE_RECTANGLE	0x00001000	Single rectangle or list of rectangles
WBE_RECTANGLE_STRIP	0x00002000	Strip of rectangles
WBE_TRAPEZOID	0x00004000	Single trapezoid or list of trapezoids
WBE_TRAPEZOID_STRIP	0x00008000	Strip of trapezoids
WBE_QUADRANGLE	0x00010000	Single quadrangle or list of quadrangles
WBE_QUADRANGLE_STRIP	0x00020000	Strip of quadrangles
WBE_POLYGON	0x00100000	A polygon FIXME: maybe add more types for convex etc
WBE_ALL	0x0013F773	All of these

Points can be seen as lines with length zero, only applying line width to make up the dot.

API FIXME: Do we need vertical lines or other stuff?

WaterAdvancedElement

An advanced element denotes a complex part of a shape containing non-straight lines [32]

WAE_NONE	0x00000000	None of these
WAE_CIRCLE	0x00000001	Single circle or list of circles
WAE_ELLIPSE	0x00000002	Single ellipse or list of ellipses
WAE_ARC_CIRCLE	0x00000004	Single arc of a circle or list of arcs
WAE_ARC_ELLIPSE	0x00000008	Single arc of an ellipse or list of arcs
WAE_QUAD_CURVE	0x00000010	Single quadratic curve or list of curves
WAE_QUAD_CURVE_STRIP	0x00000020	Strip of (smooth) quadratic curves
WAE_CUBIC_CURVE	0x00000040	Single cubic curve or list of curves
WAE_CUBIC_CURVE_STRIP	0x00000080	Strip of (smooth) cubic curves
WAE_NURB_CURVE	0x00000100	Single NURB curve or list of curves
WAE_NURB_CURVE_STRIP	0x00000200	Strip of (smooth) NURB curves
WAE_ALL	0x000003FF	All of these

API FIXME: Should we split up arc types and avoid flags, but loose mixing of small/large etc. in one element?

WATER_ELEMENT_TYPE ( index, advanced, offset, initial, additional )

Macro for generation of WaterElementType constants

        |----:----|----:eeed|dddc:cccc|baaa:aaaa|

a) Element type index
b) Basic or advanced element?
c) Bit offset within basic or advanced types
d) Number of coordinate values for initial element
e) Number of coordinate values for additional elements, e.g. in a line strip

In case of a polygon the number of elements is always one, but the initial and additional count are chosen as three and one for generic validation of number of values.

WATER_ELEMENT_TYPE_INDEX ( type )

(((type) >> 0) & 0x7f)

WATER_ELEMENT_TYPE_IS_ADVANCED ( type )

(((type) >> 7) & 0x01)

WATER_ELEMENT_TYPE_OFFSET ( type )

(((type) >> 8) & 0x1f)

WATER_ELEMENT_TYPE_VALUES_INITIAL ( type )

(((type) >> 13) & 0x0f)

WATER_ELEMENT_TYPE_VALUES_ADDITIONAL ( type )

(((type) >> 17) & 0x07)

WaterElementType

Compound type for basic and advanced elements with additional information [32]

WET_UNKNOWN	0	Invalid or unknown / unspecified element type
WET_POINT	WATER_ELEMENT_TYPE( 0, 0, D_BITn32(WBE_POINT ), 2, 2 )	x y
WET_SPAN	WATER_ELEMENT_TYPE( 1, 0, D_BITn32(WBE_SPAN ), 3, 3 )	x y l
WET_LINE	WATER_ELEMENT_TYPE( 2, 0, D_BITn32(WBE_LINE ), 4, 4 )	x1 y1 x2 y2
WET_LINE_STRIP	WATER_ELEMENT_TYPE( 3, 0, D_BITn32(WBE_LINE_STRIP ), 4, 2 )	[x1 y1] x2 y2
WET_LINE_LOOP	WATER_ELEMENT_TYPE( 4, 0, D_BITn32(WBE_LINE_LOOP ), 4, 2 )	[x1 y1] x2 y2
WET_TRIANGLE	WATER_ELEMENT_TYPE( 5, 0, D_BITn32(WBE_TRIANGLE ), 6, 6 )	x1 y1 x2 y2 x3 y3
WET_TRIANGLE_FAN	WATER_ELEMENT_TYPE( 6, 0, D_BITn32(WBE_TRIANGLE_FAN ), 6, 2 )	[x1 y1 x2 y2] x3 y3
WET_TRIANGLE_STRIP	WATER_ELEMENT_TYPE( 7, 0, D_BITn32(WBE_TRIANGLE_STRIP ), 6, 2 )	[x1 y1 x2 y2] x3 y3
WET_RECTANGLE	WATER_ELEMENT_TYPE( 8, 0, D_BITn32(WBE_RECTANGLE ), 4, 4 )	x1 y1 x2 y2
WET_RECTANGLE_STRIP	WATER_ELEMENT_TYPE( 9, 0, D_BITn32(WBE_RECTANGLE_STRIP ), 4, 2 )	[x1 y1] x2 y2
WET_TRAPEZOID	WATER_ELEMENT_TYPE( 10, 0, D_BITn32(WBE_TRAPEZOID ), 6, 6 )	x1 y1 l1 x2 y2 l2
WET_TRAPEZOID_STRIP	WATER_ELEMENT_TYPE( 11, 0, D_BITn32(WBE_TRAPEZOID_STRIP ), 6, 3 )	[x1 y1 l1] x2 y2 l2
WET_QUADRANGLE	WATER_ELEMENT_TYPE( 12, 0, D_BITn32(WBE_QUADRANGLE ), 8, 8 )	x1 y1 x2 y2 x3 y3 x4 y4
WET_QUADRANGLE_STRIP	WATER_ELEMENT_TYPE( 13, 0, D_BITn32(WBE_QUADRANGLE_STRIP ), 8, 4 )	[x1 y1 x2 y2] x3 y3 x4 y4
WET_POLYGON	WATER_ELEMENT_TYPE( 14, 0, D_BITn32(WBE_POLYGON ), 6, 2 )	[x1 y1 x2 y2] x3 y3
WET_CIRCLE	WATER_ELEMENT_TYPE( 15, 1, D_BITn32(WAE_CIRCLE ), 3, 3 )	x y r
WET_ELLIPSE	WATER_ELEMENT_TYPE( 16, 1, D_BITn32(WAE_ELLIPSE ), 4, 4 )	x y rx ry
WET_ARC_CIRCLE	WATER_ELEMENT_TYPE( 17, 1, D_BITn32(WAE_ARC_CIRCLE ), 4, 4 )	x y r a f
WET_ARC_ELLIPSE	WATER_ELEMENT_TYPE( 18, 1, D_BITn32(WAE_ARC_ELLIPSE ), 5, 5 )	x y rx ry a f
WET_QUAD_CURVE	WATER_ELEMENT_TYPE( 19, 1, D_BITn32(WAE_QUAD_CURVE ), 4, 4 )	x y x2 y2
WET_QUAD_CURVE_STRIP	WATER_ELEMENT_TYPE( 20, 1, D_BITn32(WAE_QUAD_CURVE_STRIP ), 4, 2 )	x y [x2 y2]
WET_CUBIC_CURVE	WATER_ELEMENT_TYPE( 21, 1, D_BITn32(WAE_CUBIC_CURVE ), 6, 6 )	x y x2 y2 x3 y3
WET_CUBIC_CURVE_STRIP	WATER_ELEMENT_TYPE( 22, 1, D_BITn32(WAE_CUBIC_CURVE_STRIP ), 6, 4 )	x y [x2 y2] x3 y3
WET_NURB_CURVE	WATER_ELEMENT_TYPE( 23, 1, D_BITn32(WAE_NURB_CURVE ), 1, 1 )	x y D x2 y2 x3 y3 ... xD yD
WET_NURB_CURVE_STRIP	WATER_ELEMENT_TYPE( 24, 1, D_BITn32(WAE_NURB_CURVE_STRIP ), 1, 1 )	x y [D x2 y2] x3 y3 ... xD yD

The symbols in the descriptions declare the essential element values for each item, e.g. a line or a rectangle.

Values in brackets are non-essential for further items, e.g. in a line strip or smooth curve.

WATER_NUM_ELEMENT_TYPES

WaterArcFlags

Flags per arc (F value) [4]

WARC_NONE	0x0	None of these
WARC_LARGE	0x1	Large arc flag
WARC_SWEEP	0x2	Sweep flag
WARC_ALL	0x3	All of these

WaterElementFlags

Flags per element [8]

WEF_NONE	0x00	None of these
WEF_DRAW	0x01	Draw outline (low level flag), see also WaterShapeFlags
WEF_FILL	0x02	Fill area (low level flag), see also WaterShapeFlags
WEF_VALUEFLAGS_ONCE	0x04	Value flags present (once, fixed number of values per group)
WEF_VALUEFLAGS_PERGROUP	0x08	Value flags present (per value group, variable number of values per group)
WEF_INDEXED	0x10	Indexed element (using WaterElementIndexed extension to struct)
WEF_ALL	0x1F	All of these

API FIXME: Not really used, yet.

API FIXME: Find better names.

WaterElement

Base header of an element in a stream or array

unsigned int		index : 8	Element type index (always set)
unsigned int		bytes : 24	Offset to next joint after this in bytes, if used in a stream, set to the difference in size between this and the base header of the stream plus amount of data following.
WaterElementFlags		flags : 8	Flags for all values in this block (always set)
unsigned int		num_values : 24	Number of values present in value array
const WaterValue	*	values	Points to an array of values, NULL means data follows this struct immediately

WaterElementIndexed

Extended header for an indexed element in a stream or array

WaterElement		base	Base header
unsigned int		num_indices	Number of indices present in index array
const unsigned int	*	indices	Points to an array of indices, NULL means data follows this struct, but after values if also appended

For extended headers the minimum offset that needs to be written into the base header is the difference in size between this and the base header.

WaterJointType

Joints are universal entities for building networks of attributes, elements and other joints... [16]

WJT_UNKNOWN	0x0000	Unknown/invalid joint
WJT_JOINT_STREAM	0x0001	Stream of joints, see WaterJointStream
WJT_JOINT_POINTERS	0x0002	Array of joint pointers, see WaterJointPointers
WJT_JOINT_LIST	0x0003	Linked list head, see WaterJointList
WJT_JOINT_LINK	0x8001	Extended joint serving as a linked list item, with a stream of the actual joints, see WaterJointLink
WJT_ATTRIBUTE_STREAM	0x0101	Stream of attributes, see WaterJointAttributeStream
WJT_ATTRIBUTE_POINTERS	0x0102	Array of attribute pointers, see WaterJointAttributePointers
WJT_ELEMENT_STREAM	0x0103	Stream of elements, see WaterJointElementStream
WJT_ELEMENT_POINTERS	0x0104	Array of element pointers, see WaterJointElementPointers
WJT_SHAPE_STREAM	0x0105	Stream of shapes, see WaterJointShapeStream
WJT_SHAPE_POINTERS	0x0106	Array of shape pointers, see WaterJointShapePointers
WJT_SHAPE	0x8101	Shape (extended joint) with flags, opacity and root joint, see WaterShape
WJT_PRIVATE	0x4000	First private joint
WJT_PRIVATE_EXTENDED	0xC000	First private extended joint

A network can be seen as a scene graph with a versatile structure and extensible types.

Different joint types exist to allow efficiency in all use cases:

Declaration of a complete network by using static buffers and initializers
Building a huge network quickly by connecting a few bigger networks, e.g. static buffers
Complete initialization of a network by just reading a single stream from disk/net, or mmapping a file
Dynamic management of the network including modifications of attributes and basic reconfiguration
Rapid reconfiguration of the whole network structure, adding and removing a lot
Loading and rendering parts of excessively big and complex scenes like maps easily without much overhead

The range of type values is limited and has been split into the following sub ranges:

Base types with official type range of 0x0000-0x3FFF and private range of 0x4000-0x7FFF.
Extended types with official type range of 0x8000-0xBFFF and private range of 0xC000-0xEFFF.
The remaining space starting at 0xF000 is RESERVED!

The base types allow further traversal without knowing anything about the actual joint type, because it is guaranteed that the number of bytes to skip this joint are calculated based on WaterJoint.

Extended types are usually logical groups of other joint types, with small to large networks behind them, not meant to be processed further anyhow, if the type is not known by the traversing party, library, application, hardware...

There's no way to put an extended joint without a known base "around" for jumping over it beforehand(ling).

If there's a stream of an extended type, e.g. WJT_SHAPE_STREAM, the number of bytes to skip between each stream item is based on the size of WaterShape. If that type of stream is not supported, only the bytes set in the base header WaterJointShapeStream (or WaterJoint) is required to skip it.

WATER_JOINT_IS_BASE (type)

Macro that determines if the joint is of a base type

(!((type) & 0x8000) )

WATER_JOINT_IS_OFFICIAL (type)

Macro that determines if the joint is of an official type

(!((type) & 0x4000) )

WATER_JOINT_IS_EXTENDED (type)

Macro that determines if the joint is of an extended type

( ((type) & 0x8000) && (type) < 0xF000 )

WATER_JOINT_IS_PRIVATE (type)

Macro that determines if the joint is of a private type

( ((type) & 0x4000) && (type) < 0xF000 )

WATER_JOINT_IS_RESERVED (type)

Macro that determines if the joint is in the reserved area

( ((type) & 0xF000) == 0xF000 )

WaterJoint

Base header of a joint in a stream or array

WaterJointType		type : 16	The actual type of joint
unsigned int		count : 16	Number of items in the buffer
unsigned int		bytes	Offset to next joint after this in bytes, if used in a stream, set to the difference in size between this and the base header of the stream, plus amount of data following.
const void	*	buffer	A pointer to a buffer, NULL means data follows the struct, NULL means data follows this struct immediately

WaterJointStream

0x0001| Joint Stream

WaterJointType		type : 16	The actual type of joint, WJT_JOINT_STREAM in this case
unsigned int		count : 16	Number of items in the buffer
unsigned int		bytes	Offset to next joint after this in bytes, if used in a stream, set to the difference in size between this and the base header of the stream, plus amount of data following.
const WaterJoint	*	joints	Start of stream (mixed types of joints), NULL means data follows this struct immediately

This joint incorporates a stream of other joints, suitable for fast loading.

The bytes set for each joint are honored to skip extra data following the joint.

WaterJointPointers

0x0002| Joint Pointer Array

WaterJointType		type : 16	The actual type of joint, WJT_JOINT_POINTERS in this case
unsigned int		count : 16	Number of items in the buffer
unsigned int		bytes	Offset to next joint after this in bytes, if used in a stream, set to the difference in size between this and the base header of the stream, plus amount of data following.
const WaterJoint	**	joints	Array of joint pointers, NULL means data follows this struct immediately

This joint incorporates an array of pointers to other joints, suitable for static and dynamic structures.

WaterJointList

0x0003| Joint List (Head)

	WaterJointType			type : 16		The actual type of joint, WJT_JOINT_LIST in this case
	unsigned int			count : 16

WOP_SET	0x0	Set the value
WOP_ADD	0x1	Add the value
WOP_SUB	0x2	Subtract the value
WOP_MUL	0x3	Multiply with the value
WOP_DIV	0x4	Divide by the value

The IWater interface version