/*********************************************************************************************
 *                                                                                           *
 *                                                                                           *
 *   Copyright 1989-2018 by AutoDesSys, Inc.                                                 *
 *                                                                                           *
 *   This software and its associated documentation contains proprietary,                    *
 *   confidential, and trade secret information of AutoDesSys Inc. and may not be            *
 *   disclosed, copied in any form, or used for any purpose except as specifically           *
 *   permitted in writing by AutoDesSys, Inc.                                                *
 *                                                                                           *
 *   AutoDesSys, Inc. grants permission to use the software to those who purchase            *
 *   a license.  Such a usage will be made according to the terms and conditions             *
 *   specified in the license agreement to which a licensee agrees before installing         *
 *   and commencing usage of the software.  The license agreement can be found               *
 *   on the envelop that contains the software CD.                                           *
 *                                                                                           *
 *   AutoDesSys, Inc. also grants permission to licensees to develop extensions to           *
 *   the software, which can be in the form of scripts or plugins.  The permission           *
 *   includes calling the API and call back functions provided by AutoDesSys, Inc.           *
 *   and accessing information relevant to these functions and the general workings          *
 *   of form.Z, but only up to the point to which AutoDesSys, Inc. has chosen to             *
 *   expose, through its form.Z SDK Manual.  All extensions developed by third               *
 *   parties will include a copy of this copyright note in an easily accessible place or     *
 *   a clear instruction to read this original note by AutoDesSys, Inc.                      *
 *                                                                                           *
 *   All the software distributed under a license, either for the purpose of using it or     *
 *   for the purpose of developing extensions, is distributed AS IS, WITHOUT                 *
 *   WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, AND                                    *
 *   AutoDesSys, Inc. HEREBY DISCLAIMS ALL SUCH WARRANTIES,                                  *
 *   INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF                                         *
 *   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.                                    *
 *                                                                                           *
 *   formZ, RenderZone, and RadioZity are registered trademarks of AutoDesSys, Inc.          *
 *                                                                                           *
 *   form.Z SDK, Version 8.6.3, Dec 03, 2018                                                 *
 *                                                                                           *
 *                                                                                           *
 *********************************************************************************************/



#ifndef __FORMZ_GRUP_API_H
#define __FORMZ_GRUP_API_H 1


#include "fzpl_plugin.h"

#include "fz_api.h"

#ifdef __cplusplus
extern "C" {
#endif



/****************************************************************

	Group Manager


	Description
		The group data type and functions provides a hierarchical grouping tree used to organize 
		data in a number of areas (eg. Objects, Layers, Lights). The referenced data is stored 
		in a linear fashion which can be sequentially accessed through its own API functions. 
		The linear access is more efficient and used for internal processing where the hierarchical 
		grouping tree is designed for ease of use for the user.

		The group tree follows a family model. Each entry in the tree can be a node or a leaf. 
		A node is a branch which can can have siblings and children. The siblings are traced by 
		accessing the next or previous sibling in a closed linked list.  A leaf is a reference (tag) 
		to a member of the referenced set of data.

		Note, that in the corresponding palette, the leaf groups are not shown. Since there is always 
		exactly one leaf group for each entity (such as a layer, light or object) in the palette, 
		leafs are redundant from a user's standpoint and are therefore omitted in the palette. 
		However, when getting the group from such an entity via the repective api call, 
		the leaf group is always returned. To get to the group that shows in the palette, 
		the parent of the leaf needs to be retrieved.

		At the top of the group hierarchy is a root group, which is also not shown in the palette. 
		It is a node group, from which all other groups can be traveresed as children of the root.
 ****************************************************************/

/****************************************************************

	fz_grup_table_ptr


	Description
		Data structure for a group hierarchy.

	Availability	5.0.0.0


	See Also
		fz_grup_delete_node, fz_grup_get_child, fz_grup_get_leaf_tag,  
		fz_grup_get_next, fz_grup_get_parent, fz_grup_get_pick_status,  
		fz_grup_get_prev, fz_grup_get_root, fz_grup_get_type,  
		fz_grup_move_by_parent, fz_grup_move_by_sibling, fz_grup_new_node,  
		fz_grup_tag_to_ptr

 ****************************************************************/
typedef struct group_table_td 		*fz_grup_table_ptr;

/****************************************************************

	fz_grup_ptr


	Description
		Data structure for an entry (node or leaf) in the group hierarchy.

	Availability	5.0.0.0


	See Also
		fz_ffmt_cbak_data_model_write_cmpt, fz_ffmt_cbak_data_model_write_cmpt_obsolete, fz_grup_delete_node,  
		fz_grup_get_child, fz_grup_get_leaf_tag, fz_grup_get_next,  
		fz_grup_get_parent, fz_grup_get_pick_status, fz_grup_get_prev,  
		fz_grup_get_type, fz_grup_move_by_parent, fz_grup_move_by_sibling,  
		fz_grup_new_node, fz_grup_ptr_to_tag, fz_layr_grup_attr_get_rmtl,  
		fz_layr_grup_attr_get_rndr_lwid, fz_layr_grup_attr_get_rndr_surf, fz_layr_grup_attr_get_rndr_wire,  
		fz_layr_grup_attr_get_shad_cast, fz_layr_grup_attr_get_shad_recv, fz_layr_grup_attr_get_sshd,  
		fz_layr_grup_attr_set_rmtl, fz_layr_grup_attr_set_rndr_lwid, fz_layr_grup_attr_set_rndr_surf,  
		fz_layr_grup_attr_set_rndr_wire, fz_layr_grup_attr_set_shad_cast, fz_layr_grup_attr_set_shad_recv,  
		fz_layr_grup_attr_set_sshd, fz_layr_grup_get_parm_data, fz_layr_grup_set_parm_data,  
		fz_objt_grup_alys_get_axes, fz_objt_grup_alys_get_origin, fz_objt_grup_copy,  
		fz_objt_grup_get_parm_data, fz_objt_grup_set_parm_data, fz_objt_grup_tform,  
		fz_objt_meta_create_group, fz_objt_meta_evaluate_group, fz_grup_edit_cmpt_parm_get,  
		fz_grup_edit_cmpt_parm_set, fz_objt_cmpt_delete

 ****************************************************************/
typedef struct group_td 		*fz_grup_ptr;

/****************************************************************

	fz_grup_type_enum


	Description
		

	Members
		FZ_GRUP_TYPE_LEAF
			The group is a leaf (reference (tag) to a member of the referenced set of data)
		FZ_GRUP_TYPE_NODE
			The group is a node (branch) of the tree.

	Availability	5.0.0.0

 ****************************************************************/

typedef enum fz_grup_type_enum
{	FZ_GRUP_TYPE_LEAF = 0,
	FZ_GRUP_TYPE_NODE
} fz_grup_type_enum;

/****************************************************************

	fz_grup_tag_to_ptr



	Description
		Gets the group pointer from a group tag.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		tag  [Input]
			group tag
		grup  [Result]
			group pointer

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_ptr_to_tag

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_tag_to_ptr_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_tag_td			*tag,
	fz_grup_ptr			*grup
	);

/****************************************************************

	fz_grup_ptr_to_tag



	Description
		Gets the group tag from a group pointer.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		tag  [Result]
			group tag

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_tag_to_ptr

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_ptr_to_tag_func)(
	fzrt_int					windex,
	fz_grup_table_ptr		gtable,
	fz_grup_ptr				grup,
	fz_tag_td				*tag
	);

/****************************************************************

	fz_grup_get_root



	Description
		Gets the root of the group hierarchy. If NULL, then the hierarchy is empty.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup_root  [Result]
			pointer to the root group of the hierarchy

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_get_prev,fz_grup_get_next,fz_grup_get_child,fz_grup_get_parent

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_root_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			*grup_root
	);

/****************************************************************

	fz_grup_get_type



	Description
		Gets the type of a group entry.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		type  [Result]
			type of group entry

	Returns
		Error codes


	Availability	5.0.0.0

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_type_func)(
	fzrt_int					windex,
	fz_grup_table_ptr		gtable,
	fz_grup_ptr				grup,
	fz_grup_type_enum		*type
	);

/****************************************************************

	fz_grup_get_parent



	Description
		Gets the parent of a group entry. The parent of the root is NULL.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		grup_parent  [Result]
			pointer to the parent group

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_get_prev,fz_grup_get_next,fz_grup_get_child,fz_grup_get_root

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_parent_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fz_grup_ptr			*grup_parent
	);

/****************************************************************

	fz_grup_get_leaf_tag



	Description
		Gets the tag to the referenced data (light, layer or object) for a leaf group (FZ_GRUP_TYPE_LEAF). 
		For example, if the group hierachy is for layers, the tag returned 
		is the tag of the layer, which belongs to the leaf group.

		If the group passed in is not a leaf group, an error is returned and the tag is 
		set to a NULL tag.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		tag  [Result]
			tag of the entity, referenced by the leaf group

	Returns
		Error codes


	Availability	5.0.0.0

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_leaf_tag_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fz_tag_td 			*tag
	);

/****************************************************************

	fz_grup_get_child



	Description
		Gets the first child of a group entry. Returns NULL if the group has no children.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		grup_child  [Result]
			pointer to the first child group

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_get_prev,fz_grup_get_next,fz_grup_get_parent,fz_grup_get_root

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_child_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fz_grup_ptr			*grup_child
	);

/****************************************************************

	fz_grup_get_next



	Description
		Gets the next sibling of a group entry. Returns group (self) if the group has no siblings. 
		This function can be used to get to all groups that a re children of 
		a parent group. One would first get the first group of that parent with the 
		api call fz_grup_get_child. In a while loop all children can be 
		accessed with fz_grup_get_next.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		grup_next  [Result]
			pointer to the next sibling group

	Returns
		Error codes


	Availability	5.0.0.0

	Plugin Example
		fz_grup_get_child(windex,gtable,parent_grup,&grup); 
		while(grup != NULL) 
		{ 
		... 
		fz_grup_get_next(windex,gtable,grup,&grup); 
		}

	See Also
		fz_grup_get_prev,fz_grup_get_child,fz_grup_get_parent,fz_grup_get_root

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_next_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fz_grup_ptr			*grup_next
	);



/****************************************************************

	fz_grup_get_prev



	Description
		Gets the previous sibling of a group entry. Returns group (self) if the group has no siblings.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		grup_prev  [Result]
			previous group

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_get_next,fz_grup_get_child,fz_grup_get_parent,fz_grup_get_root

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_prev_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fz_grup_ptr			*grup_prev
	);

/****************************************************************

	fz_grup_move_by_parent



	Description
		Changes the position of the group entry in the hierarchy 
		by moving it to a new parent.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		new_parent  [Input]
			parent to become a child of or NULL for root
		first_child  [Input]
			if TRUE, then becomes the first child, else last

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_move_by_sibling

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_move_by_parent_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fz_grup_ptr			new_parent,
	fzrt_boolean		first_child
	);

/****************************************************************

	fz_grup_move_by_sibling



	Description
		Changes the position of the group entry in the hierarchy 
		by moving it adjacent to a new sibling.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group
		sibling  [Input]
			sibling to move next to
		before  [Input]
			if TRUE, then moved ahead of sibling, else after sibling

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_move_by_parent

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_move_by_sibling_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fz_grup_ptr			sibling,
	fzrt_boolean		before
	);



/****************************************************************

	fz_grup_new_node



	Description
		Creates a new group node.  If parent is NULL, the root of the hierarchy is used.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		parent  [Input]
			group or NULL for root
		first_child  [Input]
			if TRUE, then becomes the first child, else last child
		grup  [Result]
			new group entry

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_delete_node

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_new_node_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			parent,
	fzrt_boolean		first_child,
	fz_grup_ptr			*grup
	);



/****************************************************************

	fz_grup_delete_node



	Description
		Deletes a group node. The node must not contain any leaf nodes in 
		any descendents to be deleted. All descedents are deleted.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group to delete

	Returns
		Error codes


	Availability	5.0.0.0


	See Also
		fz_grup_new_node

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_delete_node_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup
	);

/****************************************************************

	fz_grup_get_pick_status



	Description
		Gets the pick status of a group. Currently there is only one value : 
		0x00000001 means that the group is picked 
		0x00000000 means that it is not 
		Other bits in the picked return variable are reserved for future use.

	Parameters
		windex  [Input]
			project window index
		gtable  [Input]
			group table
		grup  [Input]
			group to get the pick status for
		picked  [Result]
			the group's pick status. 0x00000001 if picked, 0x00000000 otherwise

	Returns
		Error codes


	Availability	6.5.5.0

 ****************************************************************/
typedef fzrt_error_td	 (*fz_grup_get_pick_status_func)(
	fzrt_int				windex,
	fz_grup_table_ptr	gtable,
	fz_grup_ptr			grup,
	fzrt_int				*picked
	);

/****************************************************************

	fz_grup_fset


	FZ_GRUP_FSET_TYPE
		formZ group function set UUID.

	FZ_GRUP_FSET_NAME
		formZ group function set name.

	FZ_GRUP_FSET_VERSION
		formZ group function set version.

	Description
		Function set for the group functions

	Availability	5.0.0.0

 ****************************************************************/


#define FZ_GRUP_FSET_TYPE		"\x0e\x4e\x2a\x7c\xdc\x6a\x4e\x63\x83\xdc\xb8\xc1\xf0\x34\x58\x25"

#define FZ_GRUP_FSET_NAME		"formZ grup funcs"

#define FZ_GRUP_FSET_VERSION	FZPL_VERS_MAKE(6,5,5,0)

typedef struct fz_grup_fset
{
	fzpl_fset_prvt_data_td					prvt_data;
	
	fz_grup_get_root_func					fz_grup_get_root;
	fz_grup_tag_to_ptr_func					fz_grup_tag_to_ptr;
	fz_grup_ptr_to_tag_func					fz_grup_ptr_to_tag;
	fz_grup_get_parent_func					fz_grup_get_parent;
	fz_grup_get_child_func					fz_grup_get_child;
	fz_grup_get_leaf_tag_func				fz_grup_get_leaf_tag;
	fz_grup_get_prev_func					fz_grup_get_prev;
	fz_grup_get_next_func					fz_grup_get_next;
	fz_grup_move_by_parent_func				fz_grup_move_by_parent;
	fz_grup_move_by_sibling_func			fz_grup_move_by_sibling;
	fz_grup_new_node_func					fz_grup_new_node;
	fz_grup_delete_node_func				fz_grup_delete_node;
	fz_grup_get_type_func					fz_grup_get_type;
	
	
	
	fz_grup_get_pick_status_func			fz_grup_get_pick_status;
	
}  fz_grup_fset;


#define fz_grup_delete fz_grup_delete_node


#ifdef __cplusplus
}
#endif

#endif

