trusty (3) dtk_create_complex_shape.3.gz

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)