.\"
.\" Copyright (c) 2010 Hypertriton, Inc. <http://hypertriton.com/>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 13, 2010
.Dt SG_BILLBOARD 3
.Os
.ds vT FreeSG API Reference
.ds oS FreeSG 1.0
.Sh NAME
.Nm SG_Billboard
.Nd FreeSG billboard node
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <freesg/sg.h>
.Ed
.Sh DESCRIPTION
.Nm
is the base class for "billboard" objects (i.e., primitives which are
always rendered facing the camera).
Billboard objects may be rendered as solid rectangles or complex polygons
calculated from image contours.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr SG_Node 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "SG_Billboard *"
.Fn SG_BillboardNew "SG_Node *parent" "const char *name"
.Pp
.Ft "SG_Billboard *"
.Fn SG_BillboardFromSurface "SG_Node *parent" "const char *name" "AG_Surface *s"
.Pp
.Ft "SG_Billboard *"
.Fn SG_BillboardFromSurfaceNODUP "SG_Node *parent" "const char *name" "AG_Surface *s"
.Pp
.Ft "SG_Billboard *"
.Fn SG_BillboardFromAnim "SG_Node *parent" "const char *name" "AG_Anim *anim"
.Pp
.Ft "SG_Billboard *"
.Fn SG_BillboardFromAnimNODUP "SG_Node *parent" "const char *name" "AG_Anim *anim"
.Pp
.Ft "void"
.Fn SG_BillboardSetSurface "SG_Billboard *bb" "AG_Surface *s"
.Pp
.Ft "void"
.Fn SG_BillboardSetSurfaceNODUP "SG_Billboard *bb" "AG_Surface *s"
.Pp
.Ft "int"
.Fn SG_BillboardSetAnim "SG_Billboard *bb" "AG_Anim *anim"
.Pp
.Ft "int"
.Fn SG_BillboardSetAnimNODUP "SG_Billboard *bb" "AG_Anim *anim"
.Pp
.Ft "void"
.Fn SG_BillboardAnimPlay "SG_Billboard *bb"
.Pp
.Ft "void"
.Fn SG_BillboardAnimStop "SG_Billboard *bb"
.Pp
.Ft "void"
.Fn SG_BillboardSetMode "SG_Billboard *bb" "enum sg_billboard_mode mode"
.Pp
.Ft "void"
.Fn SG_BillboardSetModeAuto "SG_Billboard *bb"
.Pp
.Ft "void"
.Fn SG_BillboardSetProj "SG_Billboard *bb" "int enable"
.Pp
.Ft "void"
.Fn SG_BillboardSetTolContour "SG_Billboard *bb" "float tol"
.Pp
.Ft "void"
.Fn SG_BillboardSetSize "SG_Billboard *bb" "M_Real w" "M_Real h"
.Pp
.Ft "void"
.Fn SG_BillboardSetColor "SG_Billboard *bb" "AG_Color C"
.Pp
.nr nS 0
The
.Fn SG_BillboardNew
function creates a new billboard node at the origin of the parent node.
The
.Fn SG_BillboardFromSurface
and
.Fn SG_BillboardFromAnim
variants set an initial surface or animation.
.Pp
The
.Fn SG_BillboardSetSurface
function arranges for the billboard to display the given static surface.
.Fn SG_BillboardSetAnim
accepts an
.Xr AG_Anim 3
argument.
Playback can be initiated or stopped with
.Fn SG_BillboardAnimPlay
and
.Fn SG_BillboardAnimStop .
.Pp
.Fn SG_BillboardSetMode
selects the rendering method for the billboard object.
Possible values for
.Fa mode
include:
.Bl -tag -width "SG_BILLBOARD_POLYGON "
.It SG_BILLBOARD_RECT
Render as solid rectangle.
.It SG_BILLBOARD_POLYGON
Render as a complex polygon calculated from the contours of the image.
The contour of the polygon is reduced to a manageable set of vertices
using Douglas-Peucker polygon simplification.
.El
.Pp
The
.Fn SG_BillboardSetModeAuto
function scans the image for transparent pixels and sets
.Dv SG_BILLBOARD_POLYGON
if some are found, otherwise sets
.Dv SG_BILLBOARD_RECT
mode.
.Pp
.Fn SG_BillboardSetProj
configures the billboard projection mode.
If an argument of 1 is given, the billboard object will be rendered
as to always face the camera.
Otherwise, the object is rendered as a textured plane in its original
orientation (the default).
.Pp
.Fn SG_BillboardSetTolContour
sets the tolerance for Douglas-Peucker simplification (default is 10.0).
.Pp
.Fn SG_BillboardSetSize
sets the relative size of the billboard (default is 1.0 x 1.0).
.Pp
.Fn SG_BillboardSetColor
sets the background color (RGBA) of the billboard object (default is
transparent black).
.Sh FLAGS
The following public
.Nm
flags are defined:
.Bl -tag -width "SG_BILLBOARD_WIREFRAME "
.It SG_BILLBOARD_PROJECT
Enable billboard projection, such that the item is always rendered
facing the camera.
.It SG_BILLBOARD_WIREFRAME
Overlay the wireframe structure ontop of the billboard surface.
This can be useful when adjusting the contour tolerance.
.El
.Sh STRUCTURE DATA
For the
.Nm
object:
.Pp
.Bl -tag -width "float tolContour "
.It Ft Uint flags
Option flags (see
.Dq FLAGS
section).
.It Ft M_Color color
Background color.
.It Ft AG_Surface *su
Current source surface (read-only; use
.It Ft M_Real w
Width (default is 1.0).
.It Ft M_Real h
Height (default is 1.0).
.It Ft float tolContour
Tolerance for polygon simplification (default is 10.0).
.El
.Sh SEE ALSO
.Xr AG_Surface 3 ,
.Xr M_Color 3 ,
.Xr M_Real 3 ,
.Xr M_Vector 3 ,
.Xr SG 3 ,
.Xr SG_Intro 3 ,
.Xr SG_Node 3 ,
.Xr SG_Plane 3
.Sh HISTORY
The
.Nm
node class first appeared in FreeSG 1.0.