Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VG_VIEW(3)	       FreeBSD Library Functions Manual		    VG_VIEW(3)

NAME
     VG_View --	agar-vg	visualization widget

SYNOPSIS
     #include <agar/core.h>
     #include <agar/gui.h>
     #include <agar/vg.h>

DESCRIPTION
     The VG_View widget	displays a VG(3) vector	graphics object.  VG_View also
     provides a	simple "tool" registration interface which allows modular edi-
     tors to be	implemented quickly.

INTERFACE
     VG_View * VG_ViewNew(void *parent,	VG *vg,	Uint flags)

     void VG_ViewSetVG(VG_View *vv, VG *vg)

     void VG_ViewSetScale(VG_View *vv, float c)

     void VG_ViewSetScalePreset(VG_View	*vv, int index)

     void VG_ViewSetScaleMin(VG_View *vv, float	c)

     void VG_ViewSetScaleMax(VG_View *vv, float	c)

     void VG_ViewSetSnapMode(VG_View *vv, enum vg_snap_mode mode)

     void VG_ViewSetGrid(VG_View *vv, int gridID, enum vg_grid_type type, int
     interval, VG_Color	color)

     Uint VG_AddEditArea(VG_View *vv, void *widget)

     void VG_ClearEditAreas(VG_View *vv)

     void VG_Status(VG_View *vv, const char *format, ...)

     void VG_StatusS(VG_View *vv, const	char *text)

     void VG_EditNode(VG_View *vv, Uint	editArea, VG_Node *vn)

     void VG_ApplyConstraints(VG_View *vv, VG_Vector *pos)

     void VG_GetVGCoords(VG_View *vv, int x, int y, VG_Vector *v)

     void VG_GetVGCoordsFlt(VG_View *vv, VG_Vector pos,	VG_Vector *v)

     void VG_GetViewCoords(VG_View *vv,	VG_Vector v, int *x, int *y)

     void VG_GetViewCoordsFlt(VG_View *vv, VG_Vector v,	float *x, float	*y)

     void * VG_Nearest(VG_View *vv, VG_Vector vPos)

     void * VG_NearestPoint(VG_View *vv, VG_Vector vPos, void *ignore)

     The VG_ViewNew() function allocates, initializes, and attaches a VG_View
     widget displaying the specified vg	object.	 Acceptable flags include:

     VG_VIEW_GRID	    Display the	grid; see VG_ViewSetGrid().

     VG_VIEW_EXTENTS	    Display the	bounding boxes of the VG elements.
			    This option	is only	implemented in debug mode.

     VG_VIEW_DISABLE_BG	    Disable the	VG-specific background.

     VG_VIEW_CONSTRUCTION   Display VG elements	marked as "for construction",
			    such as the	points used to construct a polygon.
			    The	exact interpretation of	this setting is	ele-
			    ment-specific.

     VG_VIEW_HFILL	    Expand horizontally	in parent (equivalent to in-
			    voking AG_ExpandHoriz(3)).

     VG_VIEW_VFILL	    Expand vertically in parent	(equivalent to invok-
			    ing	AG_ExpandVert(3)).

     VG_VIEW_EXPAND	    Shorthand for VG_VIEW_HFILL|VG_VIEW_VFILL.

     The VG object displayed can be changed at runtime with VG_ViewSetVG().
     If	a VG tool (see TOOL INTERFACE) is currently in use, changing the VG
     has the side effect of deselecting	the tool.

     VG_ViewSetScale() sets the	scaling	factor at which	the vector scene will
     be	displayed.  The	VG_ViewSetScalePreset()	variant	accepts	an index into
     the table of preset scaling factors as an argument	(0..nScaleFactors).
     VG_ViewSetScaleMin() and VG_ViewSetScaleMax() specify the range of	scal-
     ing factors the user is allowed to	select.

     VG_ViewSetSnapMode() selects the snapping constraint mode for the cursor.
     Acceptable	values of mode include:

     VG_FREE_POSITIONING   No snapping constraint.
     VG_GRID		   Snap	cursor to active grid.
     VG_ENDPOINT	   Snap	to line	endpoints.
     VG_CLOSEST_POINT	   Snap	to closest point on nearest entity.

     VG_ViewSetGrid() either creates a new grid, or changes the	parameters of
     an	existing grid gridID.  The interval argument specifies the interval of
     the grid (in pixels).  color sets the color which will be used to display
     the grid.	type specifies the style of rendering:

     VG_GRID_POINTS   Draw the grid as an array	of points.
     VG_GRID_LINES    Draw the grid using lines	only.

     The VG_AddEditArea() routine indicates a container	widget which the
     VG_View should use	to display tool-specific GUI elements.	Whenever a
     tool (or a	VG_Node) is selected, its optional edit() operation may	create
     one or more GUI elements bound to various parameters.  Multiple edition
     areas are allowed.	 VG_AddEditArea() returns an index into	the editAreas
     array of VG_View.

     VG_ClearEditAreas() destroys all widgets currently	attached to the	con-
     tainer(s) registered by VG_AddEditArea().

     VG_Status() sets the text displayed by any	AG_Statusbar(3)	associated
     with the VG_View.

     VG_EditNode() populates the specified edit	area (index as returned	by
     VG_AddEditArea()) with the	controls returned by the edit()	operation of
     the specified VG_Node.  VG_EditNode() is automatically invoked by the
     stock selection tool vgSelectTool when an entity is selected.

     The VG_ApplyConstraints() routine applies effective position constraints
     (e.g., the	snapping mode given by VG_ViewSetSnapMode()) on	the given po-
     sition, overwriting the contents of pos with the result.

     The VG_GetVGCoords() routine converts the given integer coordinates (rel-
     ative to the VG_View widget), into	real coordinates in the	VG scene.  The
     VG_GetVGCoordsFlt() variant accepts view coordinates in floating-point
     format.

     Conversely, VG_GetViewCoords() and	VG_GetViewCoordsFlt() convert the
     specified real VG coordinates v to	integer	(or floating-point) view coor-
     dinates into x, y.

     The VG_Nearest() routine returns a	pointer	to the entity nearest to the
     given coordinates.	 The VG_NearestPoint() variant searches	the scene for
     a point which intersects a	VG element and is closest to the specified VG
     coordinates vPos.	ignore is an optional pointer to an element which
     should be ignored in the computation.

RENDERING ROUTINES
     The draw()	operation of most VG(3)	elements will use the standard GUI
     rendering routines	(see AG_Widget(3), "RENDERING AND PRIMITIVES"),	or
     perform direct OpenGL calls.  Vector coordinates are typically translated
     to	view coordinates using VG_GetViewCoords().  The	following rendering
     routines are specific to VG_View and must be invoked from VG_Node()
     draw() context.

     void VG_DrawSurface(VG_View *vv, int x, int y, float degs,	int su)

     The VG_DrawSurface() routine renders the contents of a surface at view
     coordinates x, y in pixels, rotated clockwise by degs degrees.  The sur-
     face su must have been previously mapped to the VG_View object (see
     AG_WidgetMapSurface(3)).

TOOL INTERFACE
     VG_Tool * VG_ViewRegTool(VG_View *vv, const VG_ToolOps *classInfo,	void
     *userPtr)

     void VG_ViewSelectTool(VG_View *vv, VG_Tool *tool,	void *userPtr)

     void VG_ViewSelectToolEv(AG_Event *event)

     VG_Tool * VG_ViewFindTool(VG_View *vv, const char *name)

     VG_Tool * VG_ViewFindToolByOps(VG_View *vv, const VG_ToolOps *classInfo)

     void VG_ViewSetDefaultTool(VG_View	*vv, VG_Tool *tool)

     Implementing an editor using VG_View is typically done by registering a
     set of tools which	are invoked using a callback-style interface.

     VG_ViewRegTool() registers	a new tool class (described by the provided
     classInfo structure) with the VG_View.  userPtr is	an optional user
     pointer which will	be passed to the tool.	The VG_ToolOps structure is as
     follows.  Any of the callback functions may be set	to NULL.

     typedef struct vg_tool_ops	{
	     const char	*name;		/* Tool	name */
	     const char	*desc;		/* Optional description	*/
	     AG_StaticIcon *icon;	/* Optional GUI	icon */
	     size_t len;		/* Size	of instance structure */
	     Uint flags;		/* Options (see	below) */

	     void (*init)(void *);
	     void (*destroy)(void *);
	     void *(*edit)(void	*, struct vg_view *);
	     void (*predraw)(void *, struct vg_view *);
	     void (*postdraw)(void *, struct vg_view *);
	     void (*selected)(void *, struct vg_view *);
	     void (*deselected)(void *,	struct vg_view *);

	     int (*mousemotion)(void *,	VG_Vector vPos,	VG_Vector vRel,
				int buttons);
	     int (*mousebuttondown)(void *, VG_Vector vPos, int	button);
	     int (*mousebuttonup)(void *, VG_Vector vPos, int button);
	     int (*keydown)(void *, int	ksym, int kmod,	Uint32 unicode);
	     int (*keyup)(void *, int ksym, int	kmod, Uint32 unicode);
     } VG_ToolOps;

     The name field specifies a	short name for the tool.  desc is a short de-
     scription of the purpose of the tool.  icon is an optional
     AG_StaticIcon(3) for the GUI.

     The len value specifies the size, in bytes, of the	structure which	will
     be	used to	describe an instance of	the tool (either VG_Tool or a deriva-
     tive of it).

     Acceptable	flags options include:

     VG_NOSNAP		     Disable position constraints in any context.

     VG_MOUSEMOTION_NOSNAP   Disable position constraints when communicating
			     mouse motion events to the	tool.

     VG_BUTTONUP_NOSNAP	     Disable position constraints when communicating
			     mouse button release events to the	tool.

     VG_BUTTONDOWN_NOSNAP    Disable position constraints when communicating
			     mouse button press	events to the tool.

     VG_BUTTON_NOSNAP	     Implies VG_BUTTONUP_NOSNAP	and
			     VG_BUTTONDOWN_NOSNAP

     VG_NOEDITCLEAR	     When the tool is selected,	do not perform auto-
			     matic removal of GUI elements in the containers
			     specified by VG_AddEditArea().

     The init()	callback initializes an	instance of the	tool.  destroy() re-
     leases resources allocated	by an instance of the tool.

     The edit()	operation creates one or more GUI elements, typically used to
     set various tool-specific options.	 The object returned by	edit() should
     be	a derivative of	AG_Widget(3).

     The predraw() and postdraw() callbacks are	invoked	prior to, and after
     rendering of the scene by the VG_View.  Typically,	postdraw() is used to
     render specialized	cursors	or provide visual feedback to the user in a
     manner specific to	the tool.

     selected()	and deselected() are invoked whenever the tool is, respec-
     tively, selected or deselected by the user.

     Low-level mouse and keyboard events can be	handled	directly by the	tool
     using mousemotion() mousebuttondown(), mousebuttonup(), keydown() and
     keyup().  The coordinates passed to mouse-related callbacks are subject
     to	the current position constraints, unless disabled by one of the
     VG_*_NOSNAP flags in the flags field.

SEE ALSO
     VG(3)

HISTORY
     The VG_View interface first appeared in Agar 1.3, and was first docu-
     mented in Agar 1.3.3.

FreeBSD	13.0			 July 25, 2008			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INTERFACE | RENDERING ROUTINES | TOOL INTERFACE | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=VG_View&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help