Samples

The following primitives can be rendered:

 
SamplePrimitive3D screenshots ( left: front side; right: back side )

1. Primitives

Let's take a look at each primitive type that can be rendered in MascotCapsule V3.

1.1. Point

This primitive renders a point specified by the three-dimensional coordinates. The point to be rendered is represented by 1 pixel, regardless of the display screen setting.
The following parameters are required for rendering a point:

• Three-dimensional coordinates that render the point ( model coordinate system )
• Color of the point
• Attributes and data type of the point

1.2. Line

This primitive renders a line connecting the two points specified by the three-dimensional coordinates. The line width to be rendered is represented by 1 pixel, regardless of the display screen setting.
The following parameters are required for rendering a line:

• Three-dimensional coordinates at both ends of the line ( model coordinate system )
• Color of the line
• Attributes and data type of the line

1.3. Triangular polygon

This primitive renders a triangular polygon comprised of the three points specified by the three-dimensional coordinates. Two kinds of triangular polygons are available: a texture polygon to be applied, and a color polygon to be rendered in a single specified color.
The following parameters are required for rendering the triangular polygon:

• Three-dimensional coordinates of the three points that comprise a triangular polygon ( model coordinate system ）
• Normals of the triangular polygon
• Texture coordinates to be applied to the triangular polygon ( for a texture polygon )
• Color of the triangular polygon ( for a color polygon )
• Attributes and data type of the triangular polygon

1.4. Quadrilateral polygon

This primitive renders a quadrilateral polygon comprised of the four points specified by the three-dimensional coordinates. Similar to triangular polygons, there are two kinds of quadrilateral polygons: a texture polygon, and a color polygon.
The following parameters are required for rendering the quadrilateral polygon:

• Three-dimensional coordinates of the four points that comprise a quadrilateral polygon ( model coordinate system )
• Normals of the quadrilateral polygon
• Texture coordinates to be applied to the quadrilateral polygon ( for a texture polygon )
• Color of the quadrilateral polygon ( for a color polygon )
• Attributes and data type of the quadrilateral polygon

1.5. Point sprite

This primitive renders a quadrilateral polygon, which is centered at a point represented by the three-dimensional coordinate and always faces its front side to the viewpoint.
The following parameters are required for rendering the point sprite:

• A three-dimensional coordinate that represents the position for displaying the point sprite ( model coordinate system )
• Texture coordinates to be applied to the point sprite
• Size and angle of the point sprite
• Display flag of the point sprite
• Attributes and data type of the point sprite

Specify the following flags to determine the displaying method for the point sprite in MascotCapsule V3:

Specify the logical sum of these flags as the displaying method.
However, M3DPSF_LOCAL_SIZE and M3DPSF_PIXEL_SIZE, as well as M3DPSF_PERSPECTIVE and M3DPSF_NO_PERS are exclusive to each other.

2. Primitive rendering

Use the IMICRO3D_Render_drawPrimitive() method to perform rendering registration of multiple primitives all at once. After rendering registration, call the IMICRO3D_Render_flush() method to execute the actual rendering process. Only the same type of primitives with the same attributes can be simultaneously registered. Different types of primitives, or the same type of primitives with different attributes must be separately registered for rendering.

Example of the same primitive type, and different attributes:
        Triangular polygons that have normals per primitive, and triangular polygons that have normals per vertex, etc.


The following parameters must be specified as the arguments of the IMICRO3D_Render_drawPrimitive() method:

• Coordinates of the rendering position
• Primitive type, attribute, and data type
• The number of primitives
• Vertex array for primitive rendering
• Normal array for primitive rendering
• Texture position array for primitive rendering
• Color information array for primitive rendering
  
  

Also, in order to use a texture, a Texture object must be specified.

Let's take a look at each parameter.

2.1. Primitive types, attributes, data type, and number

Use the third argument of the IMICRO3D_Render_drawPrimitive() method to specify these parameters.
In order to specify these parameters, use a bitwise OR operator and specify the logical sum of each item as follows:

Primitive type | Primitive attribute | Primitive data type | ( Number of primitive << 16 )

If necessary, multiple attributes and data types can be defined in succession.


Use the following definition for specifying the primitive type:

Only one type of primitive must be defined per one rendering registration.


Use the following definition for specifying attributes:

Specify the logical sum of the necessary attributes.
However, some attributes are not valid for certain primitive types.
For the details of lighting, sphere mapping, color key, blending effects, etc., please also refer to the following pages of BREW - MascotCapsule V3 samples:

• Lighting
• Using the environment map ( sphere mapping )
• Semi-transparency using BlendHalf
• Additive and subtractive blending effects
  
  

Use the following definition for specifying the data type:

(*) The same effect is achieved by M3DPD_TEXCOORD_AND_PS_PARAMS_PER_FACE and M3DPD_TEXCOORD_AND_PS_PARAMS_PER_VERTEX processes; the only difference is how these definitions are used in the program.

Similar to attributes, specify the logical sum of necessary data types. Some data types are requirement. However, some data types are not valid for certain primitive types.

2.2. Vertex array

Use the fourth argument of the IMICRO3D_Render_drawPrimitive() method to specify the necessary number of vertices for the primitive.
In order to specify the vertex array, use IntArray.
Necessary number of vertices varies depending on the primitive type. Specify the necessary number as follows:

Each vertex is comprised of the three elements ( x, y, z ); therefore, the actual size of the array is the number of vertices x3 ( multiplied by 3 ). The three elements of vertex are stored in the order of x, y, and z.

2.3. Normal array

Use the fifth argument of the MICRO3D_Render_drawPrimitive() method to specify the necessary number of normal for the primitive.
In order to specify the normal array, use IntArray.
Necessary number of normals varies depending on the primitive type and data type. Specify the necessary number as follows:

Each normal is comprised of the three elements ( x, y, z ); therefore, the actual size of the array is the number of normals x3 ( multiplied by 3 ). Three elements of the normal are stored in the order of x, y, and z.
Normals must be normalized. Normalization in MascotCapsule means that the length is 4096.

2.4. Texture position array

Use the sixth argument of the IMICRO3D_Render_drawPrimitive() method to specify the necessary number of texture position information for the primitive. In order to specify the texture position array, use IntArray.
Necessary number of texture position information varies depending on the primitive type and data type. Specify the necessary number as follows:

Vertex information of the triangular polygon and quadrilateral polygon is represented by the two-dimensional coordinates ( x, y ) on the texture; therefore, the actual array size is the number of texture position information x2 ( multiplied by 2 ). Also, the triangular polygon and quadrilateral polygon's coordinates specified by the vertex information, and the coordinates specified by the texture position information are associated according to the specified order of these coordinates.

(*) If you are using a point sprite, parameters for point sprite are also contained here. Necessary parameters for the point sprite are as follows:

• Width of the point sprite
• Height of the point sprite
• Angle of the point sprite ( 360 degrees = 4096 )
• Texture position information ( x, y ) that is equivalent to the upper-left corner of the point sprite
• Texture position information ( x, y ) that is equivalent to the lower-right corner of the point sprite
• The display flag of point sprite ( Please refer to 1.5. Point sprite )
  

The size of this parameter array is the number of primitives x8 ( multiplied by 8 ).

2.5. Color information array

Use the seventh argument of the IMICRO3D_Render_drawPrimitive() method to specify the necessary number of color information for the primitive.
In order to specify the color information array, use IntArray.
Necessary number of color information varies depending on the primitive type and data type. Specify the necessary number as follows:

The color information is RGB, and must be specified in 24-bit format where each element is 8 bit. Always use this format regardless of the pixel information in the actual environment.

( R element << 16 ) | ( G << 8 ) | ( B )

As a result, the actual array size is the number of necessary color information x1.

After specifying these settings, use the IMICRO3D_Render_drawPrimitive() method to perform rendering registration for the primitives.
Let's take a look at the procedure using the following sample:

3. Primitive rendering sample code

Let's take a look at the portion of the sample code that renders primitives. The following sample renders triangular polygons.

Use the above-mentioned procedure to render a single type of multiple primitives all at once. In order to render a different type of primitive, repeat the above-mentioned procedure again.