The following primitives can be rendered:

Sample screenshot

1. Primitives

Let's take a look at each primitive 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 specified one 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 of MascotCapsule V3:

Specify the logical sum of these flags as a displaying method.
However, POINT_SPRITE_LOCAL_SIZE and POINT_SPRITE_PIXEL_SIZE, as well as POINT_SPRITE_PERSPECTIVE and POINT_SPRITE_NO_PERS are exclusive to each other.

2. Primitive rendering

Use the Graphics3D.renderPrimitives() method to perform rendering registration of multiple primitives all at once. After rendering registration, call the Graphics3D.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 primitives, and triangular polygons that have normals per vertex, etc.

The following parameters must be specified for the Graphics3D.renderPrimitives() 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

Even if any of these vertex array, normal array, texture position array, or color information array is not used, an arbitrary array must be specified. 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, and data type

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

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 refer to the following MIDP + MascotCapsule V3 API samples:

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

Use the following definition for specifying the data type:

(*) The same effect is achieved by PDATA_POINT_SPRITE_PARAMS_PER_FACE and PDATA_POINT_SPRITE_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.

If you have specified PDATA_POINT_SPRITE_PARAMS_PER_CMD for the point sprite, you can use the same texture position information, i.e., point sprite parameters.
Similarly, if you have specified PDATA_COLOR_PER_COMMAND, you can use the same color information in this case as well.

2.2. Vertex array

In order to specify the vertex array, use the int array.
Necessary number of vertices varies depending on the primitive type; therefore, 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

In order to specify the normal array, use the int array. Necessary number of normals varies depending on the primitive type and data type; therefore, 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). The three elements of 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

In order to specify the texture position array, use the int array. Necessary number of texture position information varies depending on the primitive type and data type; therefore, 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 these coordinates' specified order.


(*) 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 of the point sprite
• Texture position information ( x, y ) that is equivalent to the lower-right of the point sprite
• Display flag of the point sprite

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

2.5. Color information array

In order to specify the color information array, use the int array. Necessary number of color information varies depending on the primitive type and data type; therefore, 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.

3. Primitive rendering sample code

Let's take a look at the portion of the sample code that renders primitives. As an example, let's look at how to render triangular polygons as described in “1. Primitives” and “2. Primitive rendering”.

Perform the rendering registration to the Graphics class, and execute rendering.

Similarly, specify the setting for other primitives.

Line

Point sprite

Quadrilateral polygon (* Texture data is shared with the point sprite)

Sample screenshots (Settings for normals and the back side display)

Enabled normals: front side (left), back side (right)

Disabled normals: front side (left), back side (right)