SDK support for damage rectangle computation

Support for planar rectangle intersection operations. More...

Files
file	planerects.h
	Support for planar rectangle intersection operations. This is used to track damage rectangles to optimize HVD compositing blit operations.

Data Structures
struct	rectlist_t
	A rectangle list structure, used to represent a set of planar rectangles. More...

Typedefs
typedef struct rectlist_t	rectlist_t
	A rectangle list structure, used to represent a set of planar rectangles. More...

Functions
rectlist_t *	rectlist_create (int32 x1, int32 y1, int32 x2, int32 y2)
	Allocate and initialize a planar rectangle. More...
void	rectlist_insert (rectlist_t **set, rectlist_t *in)
	Insert a rectangle into a set of planar rectangles. More...
HqBool	rectlist_intersect (const rectlist_t *set, rectlist_t *in, rectlist_t **intersects, rectlist_t **nointersects)
	Intersect a new rectangle with a set of planar rectangles, producing two sets of planar rectangles that cover the new rectangle. More...
void	rectlist_coalesce (rectlist_t **set)
	Coalesce a set of planar rectangles into fewer rectangles, if possible. More...
void	rectlist_destroy (rectlist_t **set)
	Destroy a planar rectangle set. More...

Detailed Description

Support for planar rectangle intersection operations.

These functions provide support for creation, insertion, intersection, and destruction of lists of rectangles. They are used to track areas already touched by the HVD compositing blit support.

The expected usage of these functions is that:

• The client will start with a NULL initial planar rectangle set.
• For each rectangle the client wants to process, it will create a new rectangle using rectlist_create().
• The client will intersect the new rectangle with the planar rectangle set by calling rectlist_intersect(). This splits the new rectangle into two sets of sub-rectangles that cover the same area: one output set covers the parts of the input rectangle that are already included in the planar rectangle set, the other output set covers the parts of the input rectangle that are not included in the planar rectangle set. The client may wish to process these areas differently.
• The client will call rectlist_insert() to add the output rectangles that were not already in the planar set into it, and will call rectlist_destroy() to dispose of the output rectangles that were already in the planar set.
• The client may call rectlist_coalesce() to reduce a set to a smaller number of rectangles.
• When finished with processing all rectangles, the client will call rectlist_destroy() to dispose of the planar rectangle set.

The planar rectangle type is rectlist_t. Rectangles are half-open areas: the smaller (x1,y1) coordinate is included in the rectangle, the larger (x2,y2) coordinate is excluded from the rectangle. Rectangles should be created using the rectlist_create() function. Clients should not alter the rectlist_t::next pointer.

Typedef Documentation

rectlist_t

typedef struct rectlist_t rectlist_t

A rectangle list structure, used to represent a set of planar rectangles.

Rectangles are stored as normalised exclusive coordinates with x1 < x2 and y1 < y2. The (x1,y1) point is inside the rectangle, the (x2,y2) point is just outside of the rectangle.

Function Documentation

rectlist_coalesce()

void rectlist_coalesce

(

rectlist_t **

set

)

Coalesce a set of planar rectangles into fewer rectangles, if possible.

Parameters

[in,out]

set

The location of the existing planar rectangle set. This may point to NULL.

After intersecting and inserting rectangles, a planar set may cover an area using a larger number of rectangles than necessary. This function will coalesce adjacent rectangles together to reduce the total number if it can.

rectlist_create()

rectlist_t* rectlist_create	(	int32	x1,
		int32	y1,
		int32	x2,
		int32	y2
	)

Allocate and initialize a planar rectangle.

Parameters

x1	The top left corner of the new rectangle.
y1	The top left corner of the new rectangle.
x2	The bottom right corner of the new rectangle.
y2	The bottom right corner of the new rectangle.

Returns

The planar rectangle that was created, or NULL if memory allocation failed.

rectlist_destroy()

void rectlist_destroy

(

rectlist_t **

set

)

Destroy a planar rectangle set.

Parameters

[in,out]

set

The location of the existing planar rectangle set. This may point to NULL. On exit, *set will be set to NULL.

rectlist_insert()

void rectlist_insert	(	rectlist_t **	set,
		rectlist_t *	in
	)

Insert a rectangle into a set of planar rectangles.

Parameters

[in,out]	set	The location of the existing planar rectangle set. This may point to NULL.
[in]	in	A new rectangle to insert into the existing set. This rectangle must either be disjoint from all existing rectangles in the set, or may be wholly contained by a rectangle in the set, but must not overlap the boundary of a rectangle in the set.

rectlist_intersect()

HqBool rectlist_intersect	(	const rectlist_t *	set,
		rectlist_t *	in,
		rectlist_t **	intersects,
		rectlist_t **	nointersects
	)

Intersect a new rectangle with a set of planar rectangles, producing two sets of planar rectangles that cover the new rectangle.

Parameters

[in]	set	An existing planar rectangle set. This may be NULL.
[in]	in	A new rectangle or planar set of rectangles created using rectlist_create() to intersect with the existing set. If this is NULL, the function will return FALSE. This function assumes ownership of the input rectangle(s).
[out]	intersects	A location where a set of disjoint rectangles that are fully covered by the rectangles in set are stored.
[out]	nointersects	A location where a set of disjoint rectangles that do not intersect the rectangles in set are stored.

The entire area covered by the new rectangle is added to either intersects, nointersects, or both.

Return values

TRUE	The intersection succeeded. Both *intersects and *nointersects are valid (but one of them may be NULL), and they cover the area in in.
FALSE	A memory allocation for a rectangle failed. The planar rectangles in in are destroyed, and *intersects and *nointersects are NULL.