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.13 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.
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 } |
Name | Short description |
---|---|
P3DHLIPlantTemplate | Plant template class |
P3DHLIPlantInstance | Plant instance class |
P3DHLIVAttrFormat | Vertex buffer format description class |
P3DHLIVAttrBuffers | Vertex buffers location and format description class |
P3DModelMetaInfo | Model meta information class |
P3DMaterialDef | Material description class |
P3DInputStringStream | Input string stream abstract base class |
P3DInputStringStreamFile | Input string stream class which works with files |
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.
Name | Short description |
---|---|
P3DHLIPlantTemplate | Constructor |
GetMetaInfo | Return meta information about model |
GetGroupCount | Return branch group count |
GetGroupName | Return branch group name |
GetMaterial | Return material description of branch group |
GetBillboardSize | Return size of branch group billboards |
IsLODVisRangeEnabled | Return state of LOD visibility range |
GetLODVisRange | Return LOD visibility range |
GetVAttrCount | Return count of different attribute values in single branch (detailed mode) |
GetPrimitiveCount | Return count of primitives in single branch (detailed mode) |
GetPrimitiveType | Return primitive type for given primitive (detailed mode) |
FillVAttrIndexBuffer | Fill buffer with indices of attribute values (detailed mode) |
GetVAttrCountI | Return count of attribute values (vertex count) in single branch (indexed mode) |
GetIndexCount | Return count of indices, required to describe single branch, using given primitive type (indexed mode) |
FillIndexBuffer | Fill buffer with indices which describe single branch (indexed mode) |
CreateInstance | Create new plant instance using given seed |
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.
Name | Short description |
---|---|
P3DHLIPlantInstance | Constructor |
GetBranchCount | Return count of branches in branch group |
GetBoundingBox | Return plant instance bounding box |
GetVAttrCount | Return count of different attribute values in branch group (detailed mode) |
FillVAttrBuffer | Fill buffer with attribute values (detailed mode) |
GetVAttrCountI | Return total vertex count of branch group (indexed mode) |
FillVAttrBufferI | Fill buffer with attribute values (indexed mode) |
FillVAttrBuffersI | Fill buffers with attribute values (indexed mode) |
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.
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.
Name | Short description |
---|---|
P3DHLIVAttrFormat | Constructor |
HasAttr | Check attribute presence |
GetAttrOffset | Get offset of attribute |
GetStride | Get offset between sequential vertices |
AddAttr | Add attribute information |
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.
Objects of this class are used to describe location and format of memory buffers which are used to store vertex attributes.
Name | Short description |
---|---|
P3DHLIVAttrBuffers | Constructor |
HasAttr | Check attribute presence |
GetAttrBuffer | Get pointer to attribute data |
GetAttrOffset | Get offset of attribute |
GetAttrStride | Get offset between sequential attribute data |
AddAttr | Add attribute buffer information |
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.
Name | Short description |
---|---|
GetAuthor | Return author information |
GetAuthorURL | Return author URL |
GetLicenseName | Return the license name |
GetLicenseURL | Return the license URL |
GetPlantInfoURL | Return the plant description URL |
const char *GetAuthor () const;
Return name of model author or 0 if value is not set.
const char *GetAuthorURL () const;
Return model author URL 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.
Name | Short description |
---|---|
GetColor | Return material color |
GetTexName | Return material texture name |
IsDoubleSided | Return material double-sided property |
IsTransparent | Return material transparency property |
IsBillboard | Return material billboard property |
GetBillboardMode | Return billboards mode |
IsAlphaCtrlEnabled | Return state of dynamic alpha-transparency control |
GetAlphaFadeIn | Return alpha fade-in value |
GetAlphaFadeOut | Return alpha fade-out value |
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.
Name | Short description |
---|---|
~P3DInputStringStream | Destructor |
ReadString | Read string from stream |
Eof | Return true if end of stream have been reached |
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.
Name | Short description |
---|---|
P3DInputStringStreamFile | Constructor |
~P3DInputStringStreamFile | Destructor |
Open | Open file |
Close | Close file |
ReadString | Read string from stream |
Eof | Return true if end of stream have been reached |
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.