p8est_build.h File Reference

Create a new p8est object by adding individual quadrants in order. More...

#include <p8est.h>

Include dependency graph for p8est_build.h:

Go to the source code of this file.

Typedefs
typedef struct p8est_build	p8est_build_t
	Context object for building a new p4est from individual quadrants.

Functions
p8est_build_t *	p8est_build_new (p8est_t *from, size_t data_size, p8est_init_t init_fn, void *user_pointer)
	Allocate a context for building a new forest. More...
void	p8est_build_init_add (p8est_build_t *build, p8est_init_t add_init_fn)
	Set a dedicated initialization callback for manually added quadrants. More...
int	p8est_build_add (p8est_build_t *build, p4est_topidx_t which_tree, p8est_quadrant_t *quadrant)
	This function is usable from a p8est_search_local_t callback. More...
p8est_t *	p8est_build_complete (p8est_build_t *build)
	Finalize the construction of the new forest after adding quadrants. More...

Detailed Description

Create a new p8est object by adding individual quadrants in order.

This can for example be driven by running p8est_search_local. This allows to create a heavily coarsened forest in one pass. It is also legal to add more highly refined quadrants.

The only rules are to respect the original partition boundary and to add non-overlapping quadrants in Morton order.

Function Documentation

p8est_build_add()

int p8est_build_add	(	p8est_build_t *	build,
		p4est_topidx_t	which_tree,
		p8est_quadrant_t *	quadrant
	)

This function is usable from a p8est_search_local_t callback.

It can also be used outside of a search context using proper care.

It may be called multiple times in order of trees and then quadrants. The quadrant added in each call must fit entirely into the current tree. This means that inner nodes of the tree may not be legal to pass in here. It is safest to call this function only on leaves of the original tree. However, other calls are possible if subsequent quadrants do not overlap.

It is legal to call this function twice with the same quadrant. In this case the second call does nothing.

Parameters

[in,out]	build	The building context must be passed through.
[in]	which_tree	The tree number is passed from the search callback.
[in]	quadrant	The quadrant is passed from the search callback.

Returns

True if the quadrant was added, false if it was identical to the previous one and thus not added.

p8est_build_complete()

p8est_t * p8est_build_complete

(

p8est_build_t *

build

)

Finalize the construction of the new forest after adding quadrants.

Parameters

[in,out]

build

The building context will be deallocated inside.

Returns

A valid forest object. Its revision number is set to zero.

p8est_build_init_add()

void p8est_build_init_add	(	p8est_build_t *	build,
		p8est_init_t	add_init_fn
	)

Set a dedicated initialization callback for manually added quadrants.

Parameters

[in,out]	build	The building context at any stage.
[in]	add_init_fn	Henceforth used for quadrants added by p8est_build_add. NULL leaves the quadrant data uninitialized.

p8est_build_new()

p8est_build_t * p8est_build_new	(	p8est_t *	from,
		size_t	data_size,
		p8est_init_t	init_fn,
		void *	user_pointer
	)

Allocate a context for building a new forest.

Parameters

[in]	from	This forest is used as a template for creation.
[in]	data_size	Data size of the created forest, may be zero.
[in]	init_fn	This functions is called for created quadrants, added manually by p8est_build_add or by the internal completion of the subtrees. It may be overridden for added quadrants by p8est_build_init_add. NULL leaves the quadrant data uninitialized.
[in]	user_pointer	Registered into the newly built forest.

Returns

A context that needs to be processed further.