ngPlant high-level interface (implemented in ngpcore library) allows to use designed plant models in different kinds of applications. For example, it can be used to create plant models import/export tools, use plant models in real-time 3D-engines and so on...

This document describes versions 0.9.5-0.9.12 of ngpcore library.

ngpcore library is written in standard C++ (STL is not used) and designed to be portable across different systems. It was tested on 32- and 64-bit (X86 and X86-64) Linux systems. Windows systems (32-bit) are supported too. It does not depend on any external library except standard C++ library.

Declarations of main HLI classes are located in header file ngpcore/p3dhli.h. Several classes and constants are defined in ngpcore/p3model.h and ngpcore/p3dtypes.h. To make your application portable across different versions of ngpcore library, include in your source files ngpcore/p3dhli.h header only.

libngpcore.a or ngpcore.lib (depending on platform) library must be added to your projects.

• Class P3DModelMetaInfo added.
• GetMetaInfo method added to P3DHLIPlantTemplate class.

• Now it is possible to get tangent and bi-normal vertex attributes in addition to position, normal and texture coordinates using new P3D_ATTR_TANGENT and P3D_ATTR_BINORMAL constants.
• GetGroupName method added to P3DHLIPlantTemplate class.

• Four constants describing texture layers added - P3D_TEX_DIFFUSE, P3D_TEX_NORMAL_MAP, P3D_TEX_AUX0 and P3D_TEX_AUX1.
• Layer argument added to GetTexName method of P3DMaterialDef class.
• New P3DHLIVAttrBuffers class added. This class is similar to P3DHLIVAttrFormat class but allows to describe attribute set where each attribute may be located in separate memory buffer. New method FillVAttrBuffersI added. The only difference between it and old FillVAttrBufferI method is that new method uses P3DHLIVAttrBuffers as the buffers location/format description.
• Class P3DHLIVAttrFormat and method FillVAttrBufferI are marked as obsolete and will be removed in one of the next versions. Class P3DHLIVAttrBuffers and method FillVAttrBuffersI should be used instead.
• P3DHLI_VER_MAJOR, P3DHLI_VER_MINOR and P3DHLI_VER_RELEASE constants added. These constants allow to get HLI API version in compile time.

• GetBillboardSize method added to P3DHLIPlantTemplate
• Starting from version 0.9.3 ngPlant supports two types of billboards - spherical (supported in previous versions) and cylindrical (new). To get type of billboards new GetBillboardMode method of P3DMaterialDef can be used. Three constants describing billboard types added - P3D_BILLBOARD_MODE_NONE, P3D_BILLBOARD_MODE_SPHERICAL and P3D_BILLBOARD_MODE_CYLINDRICAL.
• New vertex attribute - P3D_ATTR_BILLBOARD_POS can be used in P3DHLIVAttrFormat to extract billboards locations in model coordinate space.
• IsLODVisRangeEnabled and GetLODVisRange methods added to P3DHLIPlantTemplate class. These methods give access to branch group visibility range information.
• IsAlphaCtrlEnabled, GetAlphaFadeIn and GetAlphaFadeOut methods added to P3DMaterialDef class. These methods give access to dynamic alpha-transparency control.

ngpview directory of source code distribution contains simple plant viewer application. It can be used as an example of using HLI in real-time application.

To understand interface description, several things must be described in more details.

Look at figure on the right. People with enough imagination will say that they see a tree with a trunk (yellow), three branches (blue) and nine leaves (red). In ngpcore library all elements of the plant are branches. So we will not make distinction between trunks, branches and leaves. Every element is a branch, irrespective of its shape, size, material or any other property.

Another most frequently used term is a branch group. Each branch belongs to one and only one branch group. Branches which belong to the same branch group have the same material, vertex count and topology (edge and primitive set). This is very useful property, since it can help to minimize count of render calls required to render model and improve state change batching. It is easy find branch groups at the figure - each branch group has its own color. Although branch groups have some parent-child relationships, it is easier to work with plain array of branch groups, so branch groups are accessed by indices. For example, there are three branch groups on our sample tree and to get access to branch groups we will use indices 0, 1 and 2.

There many ways to store 3d-model description. Each of these ways has its pros and cons. Different applications choose one or another in-memory 3d-model representation, different file formats and so on, depending on their requirements.

For example, 3d-modeling applications can work with triangles, quads or even polygons with five or more vertices. Usually, these application store as much information about model as they can - what kind of primitives model consists of, which vertex attributes are shared between vertices and which are not, and so on...

Another kind of applications - real-time 3d applications. Main requirement for this kind of application is high rendering speed. Usually such applications use only triangle primitives and their modifications (triangle lists, triangle strips and triangle fans). Different kinds of vertex arrays are used to store information about vertex attributes and index arrays are used to store primitives.

To make ngpcore library usable in different kinds of applications, it supports two different sets of methods for extracting information about plant model. One method is called detailed. This method (or mode) is more suitable for creating import/export applications or plugins, since it allows to get detailed information about plant model. Another method (or mode) is called indexed. This method is suitable for real-time applications.

To show differences between detailed and indexed modes let's imagine that our plant model consists of a single rectangle. Figure on the right shows several such rectangles. Top row of rectangles shows indices of different vertex attributes. Rectangle have four vertices. Each vertex has its own position and texture coordinate set. But all four vertices share their normal. Notice, that all vertices have their normal index set to zero. In detailed mode count of different vertex attributes may differ (in our example count of position and texture coordinate attributes is 4 and count of normal attributes is 1).

Bottom rectangle shows how the same rectangle looks in the indexed mode. First of all - there is no rectangle primitive, there are two triangles that together forms rectangle. Indexed mode does not support rectangles. The only type of primitive that is supported in current version is triangle list. Support for triangle strips will be added in one of the next versions of ngPlant.

Another property that indexed mode have is that count of different vertex attributes is the same. In out example there are four position attributes, four texture coordinate attributes and four (unlike detailed mode) normal attributes. This property is required if application developer want to use different kinds of vertex arrays (for example - OpenGL vertex buffer objects) for model rendering.

Next table shows results of detailed method calls for our rectangle plant model:

Call	Result
Template.GetGroupCount()	1
Template.GetVAttrCount(0,P3D_ATTR_VERTEX)	4
Template.GetVAttrCount(0,P3D_ATTR_NORMAL)	1
Template.GetVAttrCount(0,P3D_ATTR_TEXCOORD0)	4
Template.GetPrimitiveCount(0)	1
Template.GetPrimitiveType(0,0)	P3D_QUAD
Template.FillVAttrIndexBuffer(IndexBuffer,0,P3D_ATTR_VERTEX,P3D_UNSIGNED_SHORT)	{ 0, 3, 2, 1 }
Template.FillVAttrIndexBuffer(IndexBuffer,0,P3D_ATTR_NORMAL,P3D_UNSIGNED_SHORT)	{ 0, 0, 0, 0 }
Template.FillVAttrIndexBuffer(IndexBuffer,0,P3D_ATTR_TEXCOORD0,P3D_UNSIGNED_SHORT)	{ 0, 3, 2, 1 }
Instance.GetBranchCount(0)	1
Instance.GetVAttrCount(0,P3D_ATTR_VERTEX)	4
Instance.GetVAttrCount(0,P3D_ATTR_NORMAL)	1
Instance.GetVAttrCount(0,P3D_ATTR_TEXCOORD0)	4
Instance.FillVAttrBuffer(VAttrBuffer,0,P3D_ATTR_VERTEX)	{ 1.0, 0.0, 0.0, -1.0, 0.0, 0.0, -1.0, 2.0, 0.0, 1.0, 2.0, 0.0 }
Instance.FillVAttrBuffer(VAttrBuffer,0,P3D_ATTR_NORMAL)	{ 0.0, 0.0, 1.0 }
Instance.FillVAttrBuffer(VAttrBuffer,0,P3D_ATTR_TEXCOORD0)	{ 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0 }

Indexed mode results are shown on table below:

Call	Result
Template.GetGroupCount()	1
Template.GetVAttrCountI(0)	4
Template.GetIndexCount(0,P3D_TRIANGLE_LIST)	6
Template.FillIndexBuffer(IndexBuffer,0,P3D_TRIANGLE_LIST,P3D_UNSIGNED_SHORT)	{ 0, 2, 1, 3, 1, 2 }
Instance.GetVAttrCountI(0)	4
Instance.FillVAttrBufferI(VAttrBuffer,0,&Format) /* Only P3D_ATTR_VERTEX in Format */	{ 1.0, 0.0, 0.0, -1.0, 0.0, 0.0, 1.0, 2.0, 0.0, -1.0, 2.0, 0.0 }
Instance.FillVAttrBufferI(VAttrBuffer,0,&Format) /* Only P3D_ATTR_NORMAL in Format */	{ 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0 }
Instance.FillVAttrBufferI(VAttrBuffer,0,&Format) /* Only P3D_ATTR_TEXCOORD0 in Format */	{ 1.0, 0.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0 }

P3DHLIPlantTemplate

This class represents a plant template. It is used to load plant templates from external files, create plant instances and get information which is shared between all instances created from the same template.

                   P3DHLIPlantTemplate(P3DInputStringStream
                                                          *SourceStream);

Load plant template from SourceStream.

  const P3DModelMetaInfo* GetMetaInfo () const;

Return meta information about model such as author, license and other.

  unsigned int     GetGroupCount      () const;

Return total count of branch groups in plant template.

  const char      *GetGroupName       (unsigned int        GroupIndex) const;

Return constant pointer to GroupIndex branch group name.

  const
  P3DMaterialDef  *GetMaterial        (unsigned int        GroupIndex) const;

Return constant pointer to material description of GroupIndex branch group.

  void             GetBillboardSize   (float              *Width,
                                       float              *Height,
                                       unsigned int        GroupIndex) const;

Fill *Width and *Height by width and height of GroupIndex branch group billboards. Use this method for billboard branch groups only.

  bool             IsLODVisRangeEnabled
                                      (unsigned int        GroupIndex) const;

Return true if LOD visibility range must be taken into account while rendering GroupIndex branch group and false if branch group is visible at any LOD.

  void             GetLODVisRange     (float              *MinLOD,
                                       float              *MaxLOD,
                                       unsigned int        GroupIndex) const;

Fill *MinLOD and *MaxLOD with minimal and maximum LOD values at which branch group GroupIndex is visible.

  unsigned int     GetVAttrCount      (unsigned int        GroupIndex,
                                       unsigned int        Attr) const;

Return count of different attribute values in single branch. GroupIndex - branch group index. Attr - attribute type.

  unsigned int     GetPrimitiveCount  (unsigned int        GroupIndex) const;

Return count of primitives in single branch of GroupIndex branch group.

  unsigned int     GetPrimitiveType   (unsigned int        GroupIndex,
                                       unsigned int        PrimitiveIndex) const;

Return type of PrimitiveIndex primitive of GroupIndex branch group. Result value may be P3D_TRIANGLE or P3D_QUAD.

  void             FillVAttrIndexBuffer
                                      (void               *IndexBuffer,
                                       unsigned int        GroupIndex,
                                       unsigned int        Attr,
                                       unsigned int        ElementType,
                                       unsigned int        IndexBase = 0) const;

This method fills buffer IndexBuffer by indices of attribute values. Branch group is identified by GroupIndex. Attribute type is selected by Attr. You can choose to use unsigned short for index values passing P3D_UNSIGNED_SHORT as ElementType or unsigned int passing P3D_UNSIGNED_INT. Optional IndexBase may be added to all index values - it is useful for generating indices for many branches.

Required buffer size can be calculated as: BranchVertexCount * sizeof(element_t). BranchVertexCount must be calculated as a sum of vertex count of each branch primitive. element_t will be unsigned short if ElementType is P3D_UNSIGNED_SHORT or unsigned int if ElementType is P3D_UNSIGNED_INT.

Note, that in next version platform-independent types will be used instead of unsigned short and unsigned int.

  unsigned int     GetVAttrCountI     (unsigned int        GroupIndex) const;

Return count of different attribute values in single branch of GroupIndex branch group. In fact, this is a count of vertices in branch model.

  unsigned int     GetIndexCount      (unsigned int        GroupIndex,
                                       unsigned int        PrimitiveType) const;

Return count of elements in index buffer which is required to describe branch geometry using PrimitiveType.

In current version PrimitiveType must be P3D_TRIANGLE_LIST.

  void             FillIndexBuffer    (void               *IndexBuffer,
                                       unsigned int        GroupIndex,
                                       unsigned int        PrimitiveType,
                                       unsigned int        ElementType,
                                       unsigned int        IndexBase = 0) const;

Fill buffer IndexBuffer by vertex indices required to create branch model using PrimitiveType primitives. You can choose to use unsigned short for index values passing P3D_UNSIGNED_SHORT as ElementType or unsigned int passing P3D_UNSIGNED_INT. Optional IndexBase may be added to all index values - it is useful for generating indices for many branches.

Required buffer size can be calculated as: PlantTemplate.GetIndexCount(GroupIndex,PrimitiveType) * sizeof(element_t). element_t will be unsigned short if ElementType is P3D_UNSIGNED_SHORT or unsigned int if ElementType is P3D_UNSIGNED_INT.

In current version PrimitiveType must be P3D_TRIANGLE_LIST.

  P3DHLIPlantInstance
                  *CreateInstance     (unsigned int        BaseSeed = 0) const;

Create new plant instance using BaseSeed as a seed for random number generator. Using different seeds you can get almost infinite number of similar but slightly different plant models. If argument BaseSeed is omitted, or equal to zero, default seed will be used.

P3DHLIPlantInstance object is created using operator new, so after finishing to work with it, do not forget to delete it.

P3DHLIPlantInstance

                   P3DHLIPlantInstance(const P3DPlantModel*Model,
                                       unsigned int        BaseSeed);

Create plant instance based on Model using BaseSeed as a seed for random number generator.

In most cases you will not create objects of this class directly - you should use CreateInstance method of P3DHLIPlantTemplate class to create them.

  unsigned int     GetBranchCount     (unsigned int        GroupIndex) const;

Return count of branches in GroupIndex branch group.

  void             GetBoundingBox     (float              *Min,
                                       float              *Max) const;

Fill Min and Max by bounding box coordinates of plant model. Min and Max buffers size must be at least 3 * sizeof(float).

  unsigned int     GetVAttrCount      (unsigned int        GroupIndex,
                                       unsigned int        Attr) const;

Return count of different attribute values in all branches of GroupIndex branch group. Attr - attribute type.

Another way to calculate it is: PlantTemplate.GetVAttrCount(GroupIndex,Attr) * PlantInstance.GetBranchCount(GroupIndex).

  void             FillVAttrBuffer    (void               *VAttrBuffer,
                                       unsigned int        GroupIndex,
                                       unsigned int        Attr) const;

Fill buffer VAttrBuffer by vertex Attr attribute values.

Required buffer size may be calculated as: PlantInstance.GetVAttrCount(GroupIndex,Attr) * ValCount * sizeof(float), there ValCount must be 2 for P3D_ATTR_TEXCOORD0 and 3 for P3D_ATTR_VERTEX or P3D_ATTR_NORMAL.

  unsigned int     GetVAttrCountI     (unsigned int        GroupIndex) const;

Return count of different attribute values in all branches of GroupIndex branch group. In fact, this is a count of vertices in branch group.

Another way to calculate it is: PlantTemplate.GetVAttrCountI(GroupIndex) * PlantInstance.GetBranchCount(GroupIndex).

  void             FillVAttrBufferI   (void               *VAttrBuffer,
                                       unsigned int        GroupIndex,
                                       const P3DHLIVAttrFormat
                                                          *VAttrFormat) const;

Fill buffer VAttrBuffer by vertex attribute values. Required attribute set and their locations are defined by VAttrFormat. VAttrFormat should not contain P3D_ATTR_BILLBOARD_POS attribute for non-billboard branch group.

Required buffer size can be calculated as: PlantInstance.GetVAttrCountI(GroupIndex) * VAttrFormat->GetStride()

Note, that this method allows to fill several attributes at once. Generating several attributes in a single call is always faster than generating each attribute in separate call.

This method is obsolete and will be removed in one of the next versions. Use FillVAttrBuffersI method instead.

  void             FillVAttrBuffersI  (const P3DHLIVAttrBuffers
                                                          *VAttrBuffers,
                                       unsigned int        GroupIndex) const;

Fill buffers VAttrBuffers by vertex attribute values. Required attribute set and their locations are defined by VAttrBuffers. VAttrBuffers should not contain P3D_ATTR_BILLBOARD_POS attribute for non-billboard branch group.

Required buffer size can be calculated as: PlantInstance.GetVAttrCountI(GroupIndex) * VAttrBuffers->GetAttrStride(Attr)

Note, that this method allows to fill several attributes at once. Generating several attributes in a single call is always faster than generating each attribute in separate call.

P3DHLIVAttrFormat

Objects of this class are used to describe a set of attributes which are stored in vertex buffer, their offsets and amount of space needed to store single vertex.

                   P3DHLIVAttrFormat  (unsigned int        Stride);

Initialize buffer format description. Created description has an empty attribute set.

  bool             HasAttr            (unsigned int        Attr) const;

Return true if Attr attribute is present in buffer and false otherwise.

Attr must be one of: P3D_ATTR_VERTEX, P3D_ATTR_NORMAL, P3D_ATTR_TEXCOORD0 or P3D_ATTR_BILLBOARD_POS.

  unsigned int     GetAttrOffset      (unsigned int        Attr) const;

Return offset (in bytes) of attribute Attr. If format does not have this attribute, zero will be returned.

Attr must be one of: P3D_ATTR_VERTEX, P3D_ATTR_NORMAL, P3D_ATTR_TEXCOORD0 or P3D_ATTR_BILLBOARD_POS.

  unsigned int     GetStride          () const;

Return offset between two vertices in buffer.

  void             AddAttr            (unsigned int        Attr,
                                       unsigned int        Offset);

Append attribute Attr with offset Offset to buffer format description. If attribute already exists, its offset will be updated.

Attr must be one of: P3D_ATTR_VERTEX, P3D_ATTR_NORMAL, P3D_ATTR_TEXCOORD0 or P3D_ATTR_BILLBOARD_POS.

P3DHLIVAttrBuffers

Objects of this class are used to describe location and format of memory buffers which are used to store vertex attributes.

                   P3DHLIVAttrBuffers ();

Initialize vertex attribute buffers description. Created description has an empty attribute set.

  bool             HasAttr            (unsigned int        Attr) const;

Return true if Attr attribute buffer present in description and false otherwise.

Attr must be one of: P3D_ATTR_VERTEX, P3D_ATTR_NORMAL, P3D_ATTR_TEXCOORD0 or P3D_ATTR_BILLBOARD_POS.

  void            *GetAttrBuffer      (unsigned int        Attr) const;

Return pointer to memory buffer allocated to store vertex attribute data. If attribute was not added to description, zero will be returned.

Attr must be one of: P3D_ATTR_VERTEX, P3D_ATTR_NORMAL, P3D_ATTR_TEXCOORD0 or P3D_ATTR_BILLBOARD_POS.

  unsigned int     GetAttrOffset      (unsigned int        Attr) const;

Return offset (in bytes) of attribute Attr. If attribute was not added to description, zero will be returned.

Attr must be one of: P3D_ATTR_VERTEX, P3D_ATTR_NORMAL, P3D_ATTR_TEXCOORD0 or P3D_ATTR_BILLBOARD_POS.

  unsigned int     GetAttrStride      (unsigned int        Attr) const;

Return offset between two vertex attributes in buffer.

  void             AddAttr            (unsigned int        Attr,
                                       void               *Data,
                                       unsigned int        Offset,
                                       unsigned int        Stride);

Append attribute Attr to buffer format description. Data is a pointer to memory buffer for attribute data. Offset of attribute in vertex attribute set is described by Offset argument, while Stride argument shows offset between sequential vertices in memory buffer. If attribute already exists, its buffer, offset and stridewill be updated.

Attr must be one of: P3D_ATTR_VERTEX, P3D_ATTR_NORMAL, P3D_ATTR_TEXCOORD0 or P3D_ATTR_BILLBOARD_POS.

P3DModelMetaInfo

  const char      *GetAuthor          () const;

Return name and (possibly) e-mail of model author or 0 if value is not set.

  const char      *GetLicenseName     () const;

Return the name of the license for this model or 0 if value is not set.

  const char      *GetLicenseURL      () const;

Return the URL pointing to detailed description of license or 0 if value is not set.

  const char      *GetPlantInfoURL    () const;

Return the URL pointing to detailed description of plant or 0 if value is not set.

P3DMaterialDef

  void             GetColor           (float              *R,
                                       float              *G,
                                       float              *B) const;

Fill R, G and B by red, green and blue components of material color. Current implementation does not allow to use different values for ambient, diffuse and specular components, so this value may be used as a diffuse or ambient and diffuse components.

  const char      *GetTexName         (unsigned int        Layer) const;

Return texture name binded to texture layer Layer. If selected texture layer does not have texture, NULL will be returned. Layer must be one of: P3D_TEX_DIFFUSE, P3D_TEX_NORMAL_MAP, P3D_TEX_AUX0 or P3D_TEX_AUX1.

  bool             IsDoubleSided      () const;

Return true if material is double-sided and false otherwise.

  bool             IsTransparent      () const;

Return true if material have texture with transparency and false otherwise.

  bool             IsBillboard        () const;

Return true if branches this material is attached to must be rendered as billboards and false - if not.

  unsigned int     GetBillboardMode   () const;

Return P3D_BILLBOARD_MODE_NONE if branches must not be rendered as billboards, P3D_BILLBOARD_MODE_SPHERICAL if branches must be rendered as spherical billboards and P3D_BILLBOARD_MODE_CYLINDRICAL - if branches must be rendered as cylindrical billboards.

  bool             IsAlphaCtrlEnabled () const;

Return true if alpha-test value may be used to smoothly fade-in/fade-out branches depending on branch group LOD visibility range and current LOD. Return false if smooth fade-in/fade-out is not applicable to branches of branch group.

  float            GetAlphaFadeIn     () const;

Return float value in range 0.0-1.0. If fade-in value is less than fade-out value, then alpha-test value must be interpolated from 1.0 to zero while LOD is changing from minimal visibility range value to MinVisRange + (MaxVisRange - MinVisRange) * AlphaFadeIn. If fade-in value is equal or greater than fade-out value, then alpha-test value must be interpolated from 1.0 to zero while LOD is changing from MinVisRange + (MaxVisRange - MinVisRange) * AlphaFadeIn to maximum visibility range value.

  float            GetAlphaFadeOut    () const;

Return float value in range 0.0-1.0. If fade-out value is greater than fade-in value, then alpha-test value must be interpolated from zero to 1.0 while LOD is changing from MinVisRange + (MaxVisRange - MinVisRange) * AlphaFadeOut to maximum visibility range value. If fade-out value is equal or less than fade-in value, then alpha-test value must be interpolated from zero to 1.0 while LOD is changing from minimal visibility range value to MinVisRange + (MaxVisRange - MinVisRange) * AlphaFadeOut.

P3DInputStringStream

  virtual         ~P3DInputStringStream
                                      ();

Virtual destructor - the only non-abstract method in this class.

  virtual
  void             ReadString         (char               *Buffer,
                                       unsigned int        BufferSize) = 0;

Read string from stream and store it in Buffer. Stored string is always zero-terminated. Method will never store more than BufferSize bytes - string will be splited if its length exceeds BufferSize-1.

  virtual bool     Eof                () const = 0;

Return true if end of stream have been reached and false otherwise.

P3DInputStringStreamFile

                   P3DInputStringStreamFile
                                      ();

Initialize object. After constructing object Open() method must be called to open file.

  virtual         ~P3DInputStringStreamFile
                                      ();

Free all allocated resources, close file if it was not closed previously.

  void             Open               (const char         *FileName);

Open file with FileName name. In case of error P3DExceptionIO exception will be thrown.

  void             Close              ();

Close file. After calling Close() you should not call ReadString() and Eof() methods, unless you call Open() to reopen file.

  virtual
  void             ReadString         (char               *Buffer,
                                       unsigned int        BufferSize);

Read string from stream and store it in Buffer. Stored string is always zero-terminated. Method will never store more than BufferSize bytes - string will be splited if its length exceeds BufferSize-1.

  virtual bool     Eof                () const;

Return true if end of stream have been reached and false otherwise.