/**
* Create a surface specification for a surface type.
* This can be used with mir_surface_create() to create a surface or with
* mir_surface_apply_spec() to change an existing surface.
* \remark For use with mir_surface_create() at least the width, height and
* format must be set. (And for types requiring a parent that too must be set.)
*
* \remark For use with mir_surface_apply_spec() the shell need not support
* arbitrary changes of type and some target types may require the setting of
* properties such as "parent" if they are not already present on the surface.
* The type transformations the server is required to support are:\n
* regular => utility, dialog or satellite\n
* utility => regular, dialog or satellite\n
* dialog => regular, utility or satellite\n
* satellite => regular, utility or dialog\n
* popup => satellite
*
* \param [in] connection Connection the surface will be created on
* \param [in] type the target type of the surface
*
* \return A handle that can ultimately be passed to
* mir_surface_create() or mir_surface_apply_spec()
*/
MirSurfaceSpec* mir_connection_create_surface_spec(
MirConnection* connection,
MirSurfaceType type);
~~~~
/**
* Create a surface specification.
* This can be used with mir_surface_create() to create a surface or with
* mir_surface_apply_spec() to change an existing surface.
* \remark For use with mir_surface_create() at least the type, width, height
* and format must be set. (And for types requiring a parent that too must be
* set.)
*
* \param [in] connection Connection the surface will be created on
*
* \return A handle that can ultimately be passed to
* mir_surface_create() or mir_surface_apply_spec()
*/
MirSurfaceSpec* mir_connection_create_surface_spec(MirConnection* connection);
/**
* Update a surface specification with a surface type.
* This can be used with mir_surface_create() to create a surface or with
* mir_surface_apply_spec() to change an existing surface.
* \remark For use with mir_surface_apply_spec() the shell need not support
* arbitrary changes of type and some target types may require the setting of
* properties such as "parent" that are not already present on the surface.
* The type transformations the server is required to support are:\n
* regular => utility, dialog or satellite\n
* utility => regular, dialog or satellite\n
* dialog => regular, utility or satellite\n
* satellite => regular, utility or dialog\n
* popup => satellite
*
* \param [in] spec Specification to mutate
* \param [in] type the target type of the surface
*
* \return A handle that can ultimately be passed to
* mir_surface_create() or mir_surface_apply_spec()
*/
bool mir_surface_spec_set_type(MirSurfaceSpec* spec, MirSurfaceType type);