| # |
Issue |
Description |
Change |
Status |
1
|
Group.pick(Camera)
documentation
|
The
second
part of the statement "The given Camera and this Group must be in the
same scene graph, that is, they must have at least one common
ancestor." is in error.
If "this" Group is a
World, then the given Camera must be its descendant. Clearly, the World
and the Camera are now in the same scene graph, although there is no
common ancestor.
|
Remove
the
erroneous part of the statement. The first part alone is sufficient.
|
PROPOSED
|
2
|
-
|
-
|
-
|
-
|
3
|
Background
image & null crop rectangle
|
What
happens
if the Background has an Image2D set, but the crop rectangle has zero
width or height: how do we clear the color buffer?
|
Explicitly
specify that clearing should be done with the background color only in
that special case.
|
PROPOSED
|
4
|
KeyframeSequence
tangent equations
|
There
is an
error in our specification of spline and squad interpolation: the F+
and F- scaling factors for the outgoing and incoming tangent,
respectively, have swapped places. This error is inherited from the
original paper by Kochanek and Bartels.
|
Swap
the F+
and F- scaling factors.
|
PROPOSED
|
5
|
Wrong
variable
name in Transform.transform
|
The
@throws
clauses in Transform.transform(vectors) refer to an input variable
called "points", although the variable is called "vectors".
|
Change
the
name in the @throws clauses to "vectors".
|
PROPOSED
|
6
|
array.length
statements in @throws clauses
|
There
is a
minor error in the @throws clauses of, e.g., Object3D.getReferences.
The input array is allowed to be null, yet the @throws clause specifies
that the array must be certain length. Obviously, trying to check the
length of a null array will result in a NullPointerException.
|
Explicitly
rule out null arrays when checking for array length: "if (array
!=
null) && (array.length < 3)".
This affects one or more
methods in Object3D, VertexBuffer, and all Mesh classes.
|
PROPOSED
|
7
|
Dynamic
range
specification
|
The
valid
input range is currently specified to be [2-64, 263].
Behavior for values outside of that range is left undefined. However,
behavior should not really be undefined for negative values, or values
in [0, 2-64]. Also,
the lower bound 2-64 should be relaxed to 2-63 to make the required
range
symmetric. |
Allow
undefined behavior only for absolute values larger than 263.
Allow values less than 2-63 to be flushed
to zero. |
PROPOSED
|
8
|
Arithmetic
operations on zero and one
|
The
special
roles of zero and one are not emphasized in the dynamic range and
accuracy requirements.
|
Specify
that
every implementation must guarantee 0*x=0, 1*x=x, 0+x=x, and 00=1.
|
PROPOSED
|
9
|
-
|
-
|
-
|
-
|
10
|
removeChild
vs.
removeAnimationTrack
|
The
removeChild method explicitly allows null to be passed in,
removeAnimationTrack does not. Why is that, and why not make them
behave the same way?
|
Explicitly
allow null in both methods. This
is more in line with the general principle that requests to remove
something that does not exist should be ignored. It is also backwards
compatible. See also issue #11.
|
PROPOSED
|
11
|
Unnecessary
exception in Graphics3D.releaseTarget
|
Graphics3D.releaseTarget
currently throws an exception if a
rendering target is not bound. This seems unnecessary. It also
complicates the usual rendering loop, because an extra try-catch block
is needed for releaseTarget. This is also why the code example at the
beginning of Graphics3D does not work (if bindTarget fails,
releaseTarget will also fail, so you can't put releaseTarget in
"finally")..
|
Remove
the
exception. Requests to remove or release
something that does not exist are already ignored elsewhere in
the API (removeAnimationTrack, removeChild), rather than treated as
errors. See also issue #10.
|
PROPOSED
|
12
|
Rendering
quality hint combinations in Graphics3D
|
It
is
currently unspecified whether an implementation supporting more than
one of ANTIALIAS, DITHER and TRUE_COLOR needs to support their
combinations also. The developer has no way of knowing which
combinations are supported, other than testing them one-by-one on each
target device. Furthermore, if more than one hint is given, and no
combinations are supported, which hint should take precedence?
|
Make it explicit that
combinations of hints do not need to be supported.
Also make the hint
priorities explicitly unspecified.
See also issue #19.
|
PROPOSED
|
13
|
Autonormalization
of vertex normals
|
There is no statement in the spec about
normalization of vertex normals. Should they be normalized
automatically, and at which point? |
Yes;
explicitly specify that normals are normalized
before they are used in lighting. The original values in VertexArray
must be preserved, in case they are later read back or used in some
other role.
|
PROPOSED
|
14
|
VertexBuffer.setNormals
documentation
|
The
statement
in VertexBuffer.setNormals about the mapping of byte and short values
to [-1, +1] is misleading: the values 127 and 128 only apply for bytes. |
Remove
the
offending values.
|
PROPOSED |
15
|
Fog.set{Density,
Linear} documentation
|
The
specification says that the methods have "no effect unless the type of
the Fog is (or is later set to)" the appropriate type. That is
incorrect: rendering is unaffected, but the set values can be read back
at any time using the respective getters.
|
Change
the
"no
effect" part to "no effect on rendering".
|
PROPOSED
|
16
|
Accessing
bound rendering targets
|
Graphics3D
documentation contradicts itself. It first states that accessing a
bound rendering target via any other interface than the host Graphics3D
will result in unpredictable behavior. Later it states that modifying
the origin or clipping rectangle of a bound Graphics has no effect.
|
The
second statement is incorrect, and
should also read "...will result in unpredictable behavior."
|
PROPOSED
|
17
|
Can
Object3D.getReferences return null?
|
Does
one
have
to check for null references in the array returned by getReferences?
Presumably yes, but should that be changed so that nulls may not be
returned?
|
Do
not
allow
returning nulls in getReferences.
|
PROPOSED
|
18
|
Default
projection matrix in Camera
|
The documentation of Camera does not
explicitly state the initial state of the projection matrix. It does
say that the view volume has its opposite corners at (-1 -1 -1) and (1
1 1) but it does not state which one is the "near" corner and which one
is "far". The intention is, of course, that the projection matrix is
initially set to identity. |
Specify in the constructor that the
projection matrix is initially set to identity, and that the
projection
type is
GENERIC. |
PROPOSED
|
19
|
Different
target surfaces, only one getProperties
|
A
Graphics3D object can be bound to different things, e.g. a 565 surface
or an 888 image. The underlying rasterizer may have different
capabilities depending on the target surface. For instance, some
quality hints may be supported for 888 but not for 565. However,
getProperties always returns the same set of values, regardless of the
currently bound target.
In
practice, this means that all underlying rendering contexts must have
the exact same functionality, or that getProperties must return the
lowest common denominator.
|
Require
getProperties to return the highest
common denominator instead of the lowest.
In other words, the implementation must
indicate support for a capability, if that capability is
supported for at least one
type of target surface.
Also change the TCK so that it no longer requires all-or-nothing
support for quality hints.
See also issue #12.
|
PROPOSED
|
20
|
PNG
support
in
Loader
|
The
behavior of Loader for stand-alone PNG files is currently not well
defined. The specification says only that an Image2D object is
returned, but it doesn't tell whether it is immutable or mutable, or
what pixel format it will have.
The correspondence of PNG pixel formats
to Image2D formats should be made explicit. Also, if the intention is
not to require full PNG support, we should specify which features need
not be implemented.
The file format spec says
that 48-bit pixel formats in PNG need not be supported. This limitation
is not justified, because MIDP already does require them to be
supported.
|
Explicitly specify that all PNG color types and bit
depths must be supported, including palettes, tRNS chunks, alpha
channels, and 48-bit colors.
An Image2D created via
loading a PNG file with Loader.load must have the same format as the
PNG file (that is, L, LA, RGB, or RGBA).
A color-keyed PNG file must be mapped to LA or RGBA, depending on
whether the PNG is in L or RGB format, respectively.
The resulting Image2D must
always be immutable.
|
PROPOSED
|
21
|
Elementary
arithmetic operations unspecified
|
The
dynamic range and accuracy requirements for elementary arithmetic
operations are specified in the package description, but it is not
stated anywhere which operations are to be considered elementary.
Specifically, is division an elementary operation?
|
Specify that the elementary operations
include addition, subtraction, and multiplication.
Also define the requirements for converting values from IEEE float to
the internal format in more detail.
Do not define requirements for division, reciprocal, square root, sine,
and similar operations at this stage.
|
PROPOSED
|
22
|
Target
surface
larger than max viewport size
|
JSR-184, unlike OpenGL, allows the
binding of rendering targets larger than the maximum viewport
dimensions. This makes supporting the large rendering targets
impossible in an implementation built on top of OpenGL ES.
|
Make
bindTarget throw an IllegalArgumentException if the target is larger
than the maximum viewport size.
|
PROPOSED
|
23
|
Pixel
format
conversion from RGBA to ALPHA
|
In
the
Image2D constructor that takes in a MIDP Image, what should be done if
the source Image is in RGBA format and the specified destination format
is ALPHA?
|
The
expected behavior is that the RGB components are discarded and the
Alpha values are copied in as such. Make this behavior explicit in the section
"Pixel format
conversion" in package description.
|
PROPOSED
|
24
|
Bone
transform
changed between addTransforms
|
SkinnedMesh.addTransform may be called
multiple times for the same bone, because bones are often associated
with disjoint vertex ranges. What happens if a bone's
transformation is changed between subsequent addTransforms targeting
that bone? Which transformation should be adopted as the "at rest" bone
transformation?
|
Specify
that bone transformations
should not be changed between addTransforms, but if they are, the
results for the affected vertices are undefined.
|
PROPOSED
|
25
|
Out
of
bounds
offsets in Loader.load using byte[]
|
The
method Loader.load(byte[] data, int offset) specifies no exceptions for
the cases where offset lies outside of the array bounds (i.e. offset
< 0 or offset >= data.length). Most implementations probably
throw an exception nonetheless.
|
@throws
IndexOutOfBoundsException if offset
< 0 or offset >=
data.length
|
PROPOSED
|
26
|
OpenGL
rendering model and
rasterization rules
|
Although
there has been a tacit assumption that the M3G
rendering model is the same as OpenGL's, that has not been put into
writing. In particular, the spec does not explicitly say that we follow
OpenGL's
polygon rasterization
rules (chapter 3.5.1).
|
Add
a
section called "Rasterization" under
"General implementation requirements" in the package description.
Explicitly state something to the effect of "unless specified
otherwise,
vertices, primitives and
fragments are processed as in OpenGL" and "rasterization
must obey section 3.5.1 of the
OpenGL specification"
Also move the reference
pipeline diagrams from Graphics3D to package description.
|
PROPOSED
|
27
|
Unspecified
file name case sensitivity in Loader
|
The
Sony
Ericsson K700 ignores case in M3G file names, whereas the RI and all
Nokia phones are case-sensitive. For instance, if the JAR contains
"test.m3g", then trying to load "test.M3G" will work on the K700 but
fail on a Nokia phone.
|
Require
that file names be treated case
sensitive by the Loader.
|
PROPOSED
|
28
|
-
|
-
|
-
|
-
|
29
|
Negative
keyframe time stamps
|
There's
a
contradiction between the file format spec and the main spec. The file
format spec uses the data type Int32 (as opposed to UInt32) for
keyframe time stamps, whereas the method setKeyframe of
KeyframeSequence specifically disallows negative values of time.
|
Change
the data type in the file format
spec to UInt32.
Allowing negative time stamps in the API would require carefully
specified changes to how looping is handled, for no real added value.
|
PROPOSED |
30
|
Unnecessary
error checking in VertexBuffer
|
VertexBuffer
requires normal vectors to be set for all
lit meshes (i.e. meshes that have an associated Material). This error
condition has little value to the developer, because there are so many
other things that can cause an IllegalStateException while rendering.
Seeing the erroneously shaded meshes on the screen would probably be
more useful.
Also, normal vectors are not even needed if only ambient light is
applied to the mesh. The current spec requires the normals to be
present even then.
Similarly, VertexBuffer requires that texture coordinates be set for
all enabled texturing units. This does not seem to add any value over
leaving the values undefined, rather the opposite.
|
Relax
the error conditions: If
the normal vector array is null, the normals are undefined. If a
texture coordinate array is null, the coordinates are undefined.
|
PROPOSED
|
31
|
Deferred
exceptions are implementation dependent
|
The
spec is
ambiguous about error checking while rendering and picking. Currently, objects that are not rendered (or checked for
intersection)
are not required to be in valid state.
This makes exception behavior implementation dependent. For example,
some implementations may validate objects that are outside of the view
frustum while others don't. |
1) Objects that are out of scope or
disabled must not be validated
when rendering
or picking. Define
submeshes with null appearances to be disabled. Also define all
objects to be disabled when rendering from a camera that has zero view
volume.
2) Objects that are not
rendered or picked, even though they are enabled and within scope, may be validated.
3) Any data within on
object that is actually needed for rendering or picking must be validated.
|
PROPOSED
|
32
|
Relative
paths in Loader
|
If a relative path is passed into
Class.getResourceAsStream (as used in Loader.load), the name of the
class on which it is called is used as the basis to which the relative
path is added.
When a relative path is passed to
Loader.load, the class on which getResourceAsStream is actually called
is undefined, and is likely to be an implementation-defined helper
class. Therefore, using relative paths may result in undefined behavior
across platforms.
|
Explicitly
state that the results are undefined if you pass
a relative path to a resource as input to Loader.load. |
PROPOSED
|
33
|
Variable
length byte arrays in the file format
|
The
compound datatype "Byte[]" contains the length of the
array in the beginning. However, the Section and Object headers have an
extra field for the length of the array. This is redundant and
confusing. In practice, exporters are not writing the length in the
beginning of the array, and implementations are not expecting to find
it.
|
Change
the
Byte[] in the Section documentation to a
fixed-length array:
Byte[TotalSectionLength-13]
Objects
Similarly for the Object documentation:
Byte[Length] Data
|
PROPOSED
|
34
|
Handling
of
alpha in Image2D constructor
|
Assuming
the proposed solution for issue #23, the
implementations must be able to distinguish MIDP Images that are in RGB
format from those that are in RGBA, because their conversion rules to
ALPHA are different.
This is problematic, because not all implementations of MIDP make that
distinction; they can store all images as RGBA, setting the alpha to
1.0 for all pixels in an RGB image. It is thus impossible for the M3G
implementation to conclude which conversion rule to use.
|
Implementations
on MIDP 1.0 and 2.0
must treat all mutable Images as
RGB and all immutable Images as RGBA.
If the windowing system
does make a distinction between image formats, and also provides a
public method to find out that format, then the implementation must
respect the original format. Such
windowing systems include at least AWT and maybe a future version of
MIDP.
|
PROPOSED
|
35
|
Documentation
bug in Camera.setProjection
|
The
letters w and h are said to denote the width
and height of the view frustum,
although in the matrix they actually represent only half of the width
and height, respectively.
|
Simply
remove the statement. The mathematical definitions of w and h are clear enough.
|
PROPOSED
|
36
|
-
|
-
|
-
|
-
|
37
|
Sprite
alpha factor
|
The
alpha
factor currently does not apply to sprites.
Developers are generally not pleased about that. Alpha factor was
ignored to keep sprites as simple as possible, but that decision seems
unfounded, considering that all the different blending modes are
already supported.
|
Define
that
the alpha factor also affects sprites, such that the alpha channel of
the
sprite image is multiplied with the effective alpha factor.
For picking, however, the
alpha values should be used as-is. This is in line with Mesh, where the
alpha factor has no effect on picking hit/miss status.
|
PROPOSED
|
38
|
Correct
slerping
|
It
appears
that some implementations of SLERP interpolation
are checking for angles greater than 90 degrees between successive
quaternion keyframes, and negating one of them if so.
This is not allowed in the spec, because it breaks down animation
blending.
|
The
spec is
correct as it is, and the formula given for
slerping is clear.
However, we should emphasize that there are no provisions for
"adjusting" the quaternions by flipping their signs, because this is
such a common mistake.
|
PROPOSED
|
39
|
References
to Objects
|
The
package
description states that all Object3Ds are held
by reference unless stated otherwise. It does not say anything about
other Objects, such as arrays. The assumption is that they are copied
in by default, but this is not stated anywhere.
|
Objects
other than Object3Ds are copied in by default. In
particular, arrays are always copied in. Emphasize this in the package
description.
The User Object in Object3D is, however, held by reference. This is
already stated, but should be made more explicit.
|
PROPOSED
|
40
|
Camera
and
Light transformations after render(World)
|
The
transformations of the current Camera and Lights are
currently unspecified after rendering a World.
|
The
expected behavior is that the Lights and the Camera are
transformed to world space. Make that behavior mandatory.
|
PROPOSED
|
41
|
Alignment
references in the file format
|
Alignments
may introduce cyclic references in the scene
graph. However, cycles are not allowed in the file format. This
contradiction is not discussed in the file format spec.
|
Explain
in
the file format spec that there is a workaround
that involves adding dummy child nodes.
|
PROPOSED
|
42
|
Maximum
viewport width and height
|
Many
implementations could potentially support different
maxima for viewport width and height, but the setViewport and
getProperties methods in Graphics3D force the larger dimension to be
clamped to the smaller dimension.
|
Change
setViewport exception behavior so that width and
height are checked separately.
Add new entries in the
getProperties
table: maxViewportWidth
and maxViewportHeight. Also keep maxViewportDimension, which is the
minimum of width and height.
|
PROPOSED
|
43
|
-
|
-
|
-
|
-
|
44
|
Erroneous
alignment example (billboards)
|
The
following example for setAlignment that is supposed to
create a typical billboard does not work in the usual case:
setAlignment(null, Node.ORIGIN,
world, Node.Y_AXIS);
The Y alignment is constrained by
the Z
alignment , when it should be vice versa. The workaround is to
have the roles of Z and Y axes reversed, either in the modeling stage
or by using the M part of the node transformation.
|
Add
a code
comment that the axes must be set up properly.
|
PROPOSED
|
45
|
Downscaling
of sprite and background images
|
To
allow
sprites and background images to be implemented
with textures, we should allow implementations to resample images to
the nearest supported power of two dimension. For large images,
this means downsampling to the maximum texture size (often 256x256).
We should also define quality criteria for the resampling method.
|
Allow
resampling of sprites and background images, and
recommend bilinear filtering or better.
Also recommend something
better than point sampling when rendering scaled sprites and background
images.
|
PROPOSED
|
46
|
Missing
getters
|
There
are
some properties in the API and the file format
that you can only set, but not read back. This makes it difficult or
impossible to write comprehensive game engines, middleware, editors, or
testers based solely on the M3G file format. Instead, applications need
auxiliary files to store the information that you can't get from M3G.
This adds to development costs and file size.
|
Add
all
missing getters: indices, vertices, texture
filtering modes, keyframe interpolation modes, keyframe values, local
camera lighting, node alignment.
|
PROPOSED
|
47
|
The
effect
of new getters on getReferences
|
If
we add
getters for alignment reference nodes, should we
then change the behavior of Object3D.getReferences so that it also
returns the references? That could break existing applications that
rely on not encountering loops when traversing the scene graph.
|
Do
not
return alignment reference nodes in
Object3D.getReferences. Applications can retrieve them separately if
needed. This is also consistent with current behavior: for example,
parent links are not returned.
|
PROPOSED
|
48
|
Unnecessary
error checking in addChild
|
Group.addChild
throws an exception if the node that is being
added is already a child of that Group. This is annoying and
unnecessary.
|
Relax
the
current error condition ("if the given node
already has a parent") to "...has a parent other than this Group".
|
PROPOSED
|
49
|
Documentation
on Graphics3D.addLight and setLight
|
The
documentation is unclear on how to actually use addLight and setLight;
why are there two methods, when the documentation suggests they are
almost identical?
|
Clarify
that addLight should be used for creating the set of lights to be used,
and setLight for making modifications to that set.
|
PROPOSED |
50
|
Sprite
crop rectangle documentation
|
Different
implementations have interpreted the documentation on the crop
rectangle differently, and render different results.
|
Clarify
that it is the crop rectangle that should be mapped to the projected
1x1 rectangle, not the 1x1 rectangle that should be cropped.
|
PROPOSED |
51
|
Graphics3D.bindTarget
mandates a redundant copy or clear
|
bindTarget
requires that the rendering target retains the original pixel data
after binding. This mandates a redundant color buffer copy or clear for
applications that fully overwrite the color buffer and wouldn't need
either one.
|
Add
a new hint flag to Graphics3D.bindTarget, allowing the application to
signal when the color buffer contents can be discarded.
|
PROPOSED |
52
|
No
mention of winding in TriangleStripArray
|
The
class documentation on TriangleStripArray does not mention that the
winding of every other triangle should be flipped.
|
Clarify
the documentation.
|
PROPOSED |
