NAME

       dtk_create_complex_shape - Creates or modify a shape to display custom and evolving content

SYNOPSIS

       #include <drawtk.h>

       dtk_hshape dtk_create_complex_shape(dtk_hshape shp,
                           unsigned int nvert, const float *vertpos,
                           const float *vertcolor, const float *texcoords,
                           unsigned int nind, const unsigned int *ind,
                           unsigned int type, dtk_htex tex);

DESCRIPTION

       dtk_create_complex_shape()  creates  a  shape  displaying a complex, custom and possibly evolving content
       described by vertex attribute buffers (vertpos, vertcolor and texcoords) and an array ind containing  the
       indices  of  vertices  whose  order  describes  how  to  connect the vertices altogether in order to form
       primitives (controlled by type). tex can be used to specify a texture to be mapped onto the shape.

       vertpos should point to an array of nvert pairs of float values corresponding of the  position  (x,y)  of
       each  vertex.  vertcolor should point to an array of nvert quatuples of float values corresponding of the
       color (R,G,B,A) of each vertex. texcoords can be either NULL or can point to an array of nvert  pairs  of
       float  values  corresponding  to  the  texture  coordinates (u,v) of the vertex. If texcoords is NULL, no
       texture will be used even if tex is not null.

       ind should point to an array of nind indices of the vertices in the vertex attribute buffers.  This  list
       of  indices  determines  how  the vertices form the primitives and depends on type zhich can take one the
       following value (See OpenGL manual to have detail):

       DTK_TRIANGLE_STRIP
              The first three vertices defines the  first  triangle  (and  their  order  is  significant).  Each
              subsequent  vertex  defines  a  new  triangle  using  that  point along with two vertices from the
              previous triangle.

       DTK_TRIANGLE_FAN
              A triangle fan is the same as a triangle strip with one exception: the first vertex of the list is
              always the first vertex of each triangle.

       DTK_TRIANGLES
              Separate triangles are specified. Every 3 indices defines in the order a triangle. If nind is  not
              a multiple of 3, the excedent 1 or 2 indices are ignored.

       DTK_LINE_STRIP
              A  series of one or more connected line segments is specified by enclosing a series of two or more
              endpoints. In this case, the ith index specifies the end point of the i-1st segment and the  start
              point of the ith segment.

       DTK_LINES
              Individual  line  segments,  each  specified  by a pair of vertices. If nind is odd, then the last
              index is ignored.

       shp can be used to modify a previously created shape. If it is non-null,  the  handle  will  be  used  to
       modify  the  shape referenced by shp: no new shape is created and the returned value is ensured to be shp
       in case of success, NULL otherwise. If shp is NULL, the function will attempt to create a new shape.

       The arrays vertpos, vertcolor, texcoords and ind are not copied into internal structures of  the  created
       shape.  This  allows  one  to dynamically change any aspect of the shape. However, in return it forces to
       keep the buffers allocated during the whole life time of the shape.

RETURN VALUE

       In case of success the function returns the handle to the newly created or modified  shape.  If  the  shp
       argument is non-null, the handle returned is the same value. In case of error, NULL is returned.

THREAD SAFETY

       The  data  contained into the buffers are accessed only during the creation and the draw of the shape. So
       if the data is updated in a different thread than the one used for drawing, some locking is needed.

SEE ALSO

       dtk_create_shape(3)

EPFL                                                  2010                           DTK_CREATE_COMPLEX_SHAPE(3)