scenegraph.h

一个用于智能手机的多媒体库适合S60 WinCE的跨平台开发库

/*
 *			GPAC - Multimedia Framework C SDK
 *
 *			Copyright (c) Jean Le Feuvre 2000-2005
 *					All rights reserved
 *
 *  This file is part of GPAC / Scene Graph sub-project
 *
 *  GPAC is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation; either version 2, or (at your option)
 *  any later version.
 *   
 *  GPAC is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 *   
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; see the file COPYING.  If not, write to
 *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 
 *
 */


#ifndef _GF_SCENEGRAPH_H_
#define _GF_SCENEGRAPH_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <gpac/list.h>
#include <gpac/math.h>


/*define to enable SVG test graph with static attribute allocation but no inheritance*/
//#define	GPAC_ENABLE_SVG_SA
//#define	GPAC_ENABLE_SVG_SANI

#if defined(GPAC_ENABLE_SVG_SA) || defined(GPAC_ENABLE_SVG_SANI)
#define	GPAC_ENABLE_SVG_SA_BASE
#endif


/*
	TAG definitions are static, in order to be able to mix nodes from different standard
	in a single scenegraph. These TAGs are only used internally (they do not match any
	binary encoding)
*/
enum {
	/*no node shall use this tag*/
	TAG_ForbiddenZero = 0,
	/*undefined node: just the base node class, used for parsing*/
	TAG_UndefinedNode = 1,
	/*all MPEG-4/VRML/X3D proto instances have this tag*/
	TAG_ProtoNode,

	/*reserved TAG ranges per standard*/

	/*range for MPEG4*/
	GF_NODE_RANGE_FIRST_MPEG4,
	GF_NODE_RANGE_LAST_MPEG4 = GF_NODE_RANGE_FIRST_MPEG4+512,

	/*range for X3D*/
	GF_NODE_RANGE_FIRST_X3D, 
	GF_NODE_RANGE_LAST_X3D = GF_NODE_RANGE_FIRST_X3D+512,

	/*all nodes after this are always parent nodes*/
	GF_NODE_RANGE_LAST_VRML,

	/*DOM container for BIFS/LASeR/etc updates*/
	TAG_DOMUpdates,

	/*all nodes below MUST be parent nodes*/
	GF_NODE_FIRST_PARENT_NODE_TAG,

#ifdef GPAC_ENABLE_SVG_SA
	/*range for SVG / static alloc mode*/
	GF_NODE_RANGE_FIRST_SVG_SA, 
	GF_NODE_RANGE_LAST_SVG_SA = GF_NODE_RANGE_FIRST_SVG_SA+100,
#endif

#ifdef GPAC_ENABLE_SVG_SANI
	/*range for SVG static alloc and no inheritance mode*/
	GF_NODE_RANGE_FIRST_SVG_SANI, 
	GF_NODE_RANGE_LAST_SVG_SANI = GF_NODE_RANGE_FIRST_SVG_SANI+100,
#endif

	/*DOM text node*/
	TAG_DOMText,
	/*all nodes below MUST use the base DOM structure (with dyn attribute list)*/
	GF_NODE_FIRST_DOM_NODE_TAG,
	
	/*full node*/
	TAG_DOMFullNode = GF_NODE_FIRST_DOM_NODE_TAG,
	/*range for SVG*/
	GF_NODE_RANGE_FIRST_SVG, 
	GF_NODE_RANGE_LAST_SVG = GF_NODE_RANGE_FIRST_SVG+100,

};



/*private handler for this library on all nodes*/
#define BASE_NODE	struct _nodepriv *sgprivate;

/*base node type*/
typedef struct _base_node
{
	BASE_NODE
} GF_Node;

/*child storage - this is not integrated in the base node, because of VRML/MPEG-4 USE: a node
may be present at different places in the tree, hence have different "next" siblings.*/
typedef struct _child_node
{
	struct _child_node *next;
	GF_Node *node;
} GF_ChildNodeItem;

/*grouping nodes macro :
	children: list of children SFNodes
*/

#define CHILDREN									\
	struct _child_node *children;

typedef struct
{
	BASE_NODE
	CHILDREN
} GF_ParentNode;

/*adds a child to a given container*/
GF_Err gf_node_list_add_child(GF_ChildNodeItem **list, GF_Node *n);
/*adds a child to a given container, updating last position*/
GF_Err gf_node_list_add_child_last(GF_ChildNodeItem **list, GF_Node *n, GF_ChildNodeItem **last_child);
/*inserts a child to a given container - if pos doesn't match, append the child*/
GF_Err gf_node_list_insert_child(GF_ChildNodeItem **list, GF_Node *n, u32 pos);
/*removes a child to a given container - return 0 if child not found*/
Bool gf_node_list_del_child(GF_ChildNodeItem **list, GF_Node *n);
/*finds a child in a given container, returning its 0-based index if found, -1 otherwise*/
s32 gf_node_list_find_child(GF_ChildNodeItem *list, GF_Node *n);
/*finds a child in a given container given its index, returning the child or NULL if not found
if pos is <0, returns the last child*/
GF_Node *gf_node_list_get_child(GF_ChildNodeItem *list, s32 pos);
/*gets the number of children in a given container*/
u32 gf_node_list_get_count(GF_ChildNodeItem *list);
/*deletes node entry at given idx, returning node if found, NULL otherwise*/
GF_Node *gf_node_list_del_child_idx(GF_ChildNodeItem **list, u32 pos);



/*tag is set upon creation and cannot be modified*/
u32 gf_node_get_tag(GF_Node*);
/*set node def
	@ID: node ID, !=0 set def node - if a different node with the same ID exists, returns error. 
You may change the node ID by recalling the function with a different ID value. You may get a node ID
by calling the gf_sg_get_next_available_node_id function
	@defName: optional readable name (script, MPEGJ). To change the name, recall the function with a different name and the same ID
*/
GF_Err gf_node_set_id(GF_Node*n, u32 nodeID, const char *nodeDEFName);
/*get def name of the node , NULL if not set*/
const char *gf_node_get_name(GF_Node*);
/*get def ID of the node, 0 if node not def*/
u32 gf_node_get_id(GF_Node*);
/* gets node built-in name (eg 'Appearance', ..) */
const char *gf_node_get_class_name(GF_Node *Node);

/*unset the node ID*/
GF_Err gf_node_remove_id(GF_Node *p);

/*get/set user private stack*/
void *gf_node_get_private(GF_Node*);
void gf_node_set_private(GF_Node*, void *);

/*set rendering function. When rendering a scene graph, the render stack is passed
through the graph without being touched. If a node has no associated RenderNode(), the traversing of the 
graph won't propagate below it. It is the app responsability to setup traversing functions as needed
VRML/MPEG4:  Instanciated Protos are handled internally as well as interpolators, valuators and scripts
@is_destroy: set when the node is about to be destroyed
*/
GF_Err gf_node_set_callback_function(GF_Node *, void (*NodeFunction)(GF_Node *node, void *render_stack, Bool is_destroy) );

/*register a node (DEFed or not), specifying parent if any.
A node must be registered whenever used by something (a parent node, a command, whatever) to prevent its 
destruction (think of it as a reference counting).
NOTE: NODES ARE CREATED WITHOUT BEING REGISTERED
*/
GF_Err gf_node_register(GF_Node *node, GF_Node *parent_node);

/*unregister a node from parent (node may or not be DEF'ed). Parent may be NULL (DEF root node, commands).
This MUST be called whenever a node is destroyed (removed from a parent node)
If this is the last instance of the node, the node is destroyed
NOTE: NODES ARE CREATED WITHOUT BEING REGISTERED, hence they MUST be registered at least once before 
being destroyed
*/
GF_Err gf_node_unregister(GF_Node *node, GF_Node *parent_node);
/*deletes all node instances in the given list*/
void gf_node_unregister_children(GF_Node *node, GF_ChildNodeItem *childrenlist);

/*get all parents of the node and replace the old_node by the new node in all parents
Note: if the new node is not DEFed, only the first instance of "old_node" will be replaced, the other ones deleted*/
GF_Err gf_node_replace(GF_Node *old_node, GF_Node *new_node, Bool updateOrderedGroup);

/*returns number of instances for this node*/
u32 gf_node_get_num_instances(GF_Node *node);


/*calls RenderNode on this node*/
void gf_node_render(GF_Node *node, void *renderStack);
/*allows a node to be re-rendered - by default a node in its render phase will never be rendered a second time. 
Use this function to enable a second render for this node - this must be called while node is being rendered*/
void gf_node_allow_cyclic_render(GF_Node *node);

/*blindly calls RenderNode on all nodes in the "children" list*/
void gf_node_render_children(GF_Node *node, void *renderStack);;
/*returns number of parent for this node (parent are kept regardless of DEF state)*/
u32 gf_node_get_parent_count(GF_Node *node);
/*returns desired parent for this node (parent are kept regardless of DEF state)
idx is 0-based parent index*/
GF_Node *gf_node_get_parent(GF_Node *node, u32 idx);


enum
{
	/*flag set whenever a field of the node has been modified*/
	GF_SG_NODE_DIRTY = 1,
	/*flag set whenever a child node of this node has been modified
	NOTE: unloaded extern protos always invalidate their parent subgraph to get a chance
	of being loaded. It is the user responsability to clear the CHILD_DIRTY flag before traversing
	if relying on this flag for sub-tree discarding (eg, culling or similar)*/
	GF_SG_CHILD_DIRTY = 1<<1,

	/*SVG-specific flags due to mix of geometry and appearance & co attributes*/
	/*SVG geometry changed is the same as base flag*/
	GF_SG_SVG_GEOMETRY_DIRTY		= GF_SG_NODE_DIRTY,
	GF_SG_SVG_COLOR_DIRTY			= 1<<2,
	GF_SG_SVG_DISPLAYALIGN_DIRTY	= 1<<3,
	GF_SG_SVG_FILL_DIRTY			= 1<<4,
	GF_SG_SVG_FILLOPACITY_DIRTY		= 1<<5,
	GF_SG_SVG_FILLRULE_DIRTY		= 1<<6,
	GF_SG_SVG_FONTFAMILY_DIRTY		= 1<<7,
	GF_SG_SVG_FONTSIZE_DIRTY		= 1<<8,
	GF_SG_SVG_FONTSTYLE_DIRTY		= 1<<9,
	GF_SG_SVG_FONTVARIANT_DIRTY		= 1<<10,
	GF_SG_SVG_FONTWEIGHT_DIRTY		= 1<<11,
	GF_SG_SVG_LINEINCREMENT_DIRTY	= 1<<12,
	GF_SG_SVG_OPACITY_DIRTY			= 1<<13,
	GF_SG_SVG_SOLIDCOLOR_DIRTY		= 1<<14,
	GF_SG_SVG_SOLIDOPACITY_DIRTY	= 1<<15,
	GF_SG_SVG_STOPCOLOR_DIRTY		= 1<<16,
	GF_SG_SVG_STOPOPACITY_DIRTY		= 1<<17,
	GF_SG_SVG_STROKE_DIRTY			= 1<<18,
	GF_SG_SVG_STROKEDASHARRAY_DIRTY	= 1<<19,
	GF_SG_SVG_STROKEDASHOFFSET_DIRTY= 1<<20,
	GF_SG_SVG_STROKELINECAP_DIRTY	= 1<<21,
	GF_SG_SVG_STROKELINEJOIN_DIRTY	= 1<<22,
	GF_SG_SVG_STROKEMITERLIMIT_DIRTY= 1<<23,
	GF_SG_SVG_STROKEOPACITY_DIRTY	= 1<<24,
	GF_SG_SVG_STROKEWIDTH_DIRTY		= 1<<25,
	GF_SG_SVG_TEXTALIGN_DIRTY		= 1<<26,
	GF_SG_SVG_TEXTANCHOR_DIRTY		= 1<<27,
	GF_SG_SVG_VECTOREFFECT_DIRTY	= 1<<28,
};

/*set dirty flags.
if @flags is 0, sets the base flags on (GF_SG_NODE_DIRTY).
if @flags is not 0, adds the flags to the node dirty state

If @invalidate_parents is set, all parent subtrees for this node are marked as GF_SG_CHILD_DIRTY
Note: parent subtree marking aborts if a node in the subtree is already marked with GF_SG_CHILD_DIRTY
which means tat if you never clean the dirty flags, no propagation will take place
*/
void gf_node_dirty_set(GF_Node *node, u32 flags, Bool dirty_parents);


/*set dirty flag off. It is the user responsability to clear dirty flags
if @flags is 0, all flags are set off
if @flags is not 0, removes the indicated flags from the node dirty state
*/
void gf_node_dirty_clear(GF_Node *node, u32 flags);

/*if the node is in a dirty state, resets it and the state of all its children*/
void gf_node_dirty_reset(GF_Node *node);

/*get dirty flag value*/
u32 gf_node_dirty_get(GF_Node *node);

/*Notes on GF_FieldInfo
all scene graph implementations should answer node field query with this interface. 
In case an implementation does not use this:
	- the implementation shall handle the parent node dirty flag itself most of the time
	- the implementation shall NOT allow referencing of a graph node in a parent graph node (when inlining
content) otherwise the app is guaranteed to crash.
*/

/*other fieldTypes may be ignored by implmentation not using VRML/MPEG4 native types*/

typedef struct
{	
	/*0-based index of the field in the node*/
	u32 fieldIndex;
	/*field type - VRML/MPEG4 types are listed in scenegraph_vrml.h*/
	u32 fieldType;
	/*far ptr to the field (eg GF_Node **, GF_List**, MFInt32 *, ...)*/
	void *far_ptr;
	/*field name*/
	const char *name;
	/*NDT type in case of SF/MFNode field - cf BIFS specific tools*/
	u32 NDTtype;
	/*event type*/
	u32 eventType;
	/*eventin handler if any*/
	void (*on_event_in)(GF_Node *pNode);
} GF_FieldInfo;

/*returns number of field for this node*/
u32 gf_node_get_field_count(GF_Node *node);

/*fill the field info structure for the given field*/
GF_Err gf_node_get_field(GF_Node *node, u32 FieldIndex, GF_FieldInfo *info);

/*get the field by its name*/
GF_Err gf_node_get_field_by_name(GF_Node *node, char *name, GF_FieldInfo *field);

typedef struct __tag_scene_graph GF_SceneGraph;

/*scene graph constructor*/
GF_SceneGraph *gf_sg_new();

/*creates a sub scene graph (typically used with Inline node): independent graph with same private stack, 
and user callbacks as parent. All routes triggered in this subgraph are executed in the parent graph (this 
means you only have to activate routes on the main graph)
NOTE: the resulting graph is not destroyed when the parent graph is 
*/
GF_SceneGraph *gf_sg_new_subscene(GF_SceneGraph *scene);

/*destructor*/
void gf_sg_del(GF_SceneGraph *sg);
/*reset the full graph - all nodes, routes and protos are destroyed*/