This
post will be updated regularly as new anomalies or corrections in the
Three.js documentation are found.
6/4/2015 It is asserted that different browsers allow webgl antialiasing to be enabled. That Firefox does, but Chrome does not. However, it is not clear to me that this is true. There is also confusion about the default of the camera attribute "antialias", and whether it defaults to true and false. Probably one should should not assume anything but set it to the appropriate value depending on need. ]
[Further exploration of this topic has discovered that (a) three.js is under active development, and (b) no effort is being made to keep the documentation even slightly current and (c) it would be crazy to volunteer to update the documentation for them because one would always fail (because the developers would not care to let you know about changes or omissions). Therefore if you want to use three.js better get ready to read the code as well as blogs like this to figure out how].
6/4/2015 It is asserted that different browsers allow webgl antialiasing to be enabled. That Firefox does, but Chrome does not. However, it is not clear to me that this is true. There is also confusion about the default of the camera attribute "antialias", and whether it defaults to true and false. Probably one should should not assume anything but set it to the appropriate value depending on need. ]
[Further exploration of this topic has discovered that (a) three.js is under active development, and (b) no effort is being made to keep the documentation even slightly current and (c) it would be crazy to volunteer to update the documentation for them because one would always fail (because the developers would not care to let you know about changes or omissions). Therefore if you want to use three.js better get ready to read the code as well as blogs like this to figure out how].
As
I have mentioned before, I think that one of the biggest issues in
keeping current and using various technologies on the Internet is the
problem of incomplete or out-of-date documentation. Now,
documentation in technology, it turns out, has only rarely been very
good. But there have been exceptions, or exceptionally good
counter-examples, and they all usually happened because it was
important for the people developing that technology to put serious
and sustained effort into it even though they had other things they
wanted to do.
But
today, when everybody is getting paid (but me) and yet no one is
getting paid, we end up using technologies that are unsponsored or
are labors of love and one is lucky to get the documentation that is
there, let alone really good and professional documentation.
What
that means is that the potential user of that technology, who often
has no choice what framework or middleware to use, is stuck learning
the technology by trial and error. Is it a waste of time, sure it
is. But two things, first, it is the way it is, and second, it is
symptomatic of the times we live in.
Some
classic examples of this is WebGL and Three.js. WebGL, wherever it
really came from, is a version of OpenGL designed to work in your
internet browser. It is as far away in philosphy as what motivated
OpenGL that you could conceive of. WebGL is insanely difficult to
use.
Built
on top of it is something called Three.js. Three.js is pretty good
in a lot of ways and I am using it on three different projects right
now. But every time I try to use it after a hiatus, I keep slamming
back into the documentation which is better than some documentation
out there, but still very irritating in what it leaves out and what
it gets wrong.
These
may seem minor to you but I think it is very important. People
are busy, we want to use these technologies and "not reinvent the wheel" but it is a pain in the ass,
literally not less than twice as time consuming as it has to be.
So
in the spirit of positive action, I am going to start documenting the
issues and mistakes that I find in the documentation. I am not sure
where this will end up, but in the short run the changes will be
added to the bottom of this post in no particular order. Then one
day, perhaps, they can be incorporated into the main documentation.
As a separate matter, I also include a brief sections on requests/suggestions, e.g. those things that would be nice to have. This is more in the area of functionality, not so much in the area of documentation.
Errata
In all the cases below, I am referring to the documentation that should be modified, not the code itself, although it is possible that the code itself should be changed to make a parameter more consistent with other parts of three.js.
Finally, all the suggestions below are the result of the following process. First I try to do something in three.js and read the relevant documentation but whatever I am trying to do either fails or in some way does not solve the problem. Then I search the internet and find examples that show me how to do what I need to do that was not mentioned in the documentation. Or I just try things that I think might be there based on how I would do things if I were writing this code. Eventually something works, I verify that it is not in the documentation and I add it to the list below.
As a separate matter, I also include a brief sections on requests/suggestions, e.g. those things that would be nice to have. This is more in the area of functionality, not so much in the area of documentation.
Errata
In all the cases below, I am referring to the documentation that should be modified, not the code itself, although it is possible that the code itself should be changed to make a parameter more consistent with other parts of three.js.
Finally, all the suggestions below are the result of the following process. First I try to do something in three.js and read the relevant documentation but whatever I am trying to do either fails or in some way does not solve the problem. Then I search the internet and find examples that show me how to do what I need to do that was not mentioned in the documentation. Or I just try things that I think might be there based on how I would do things if I were writing this code. Eventually something works, I verify that it is not in the documentation and I add it to the list below.
1.
The Three.js tutorial features a rotating cube which one rotates with "cube.rotation.x += .1;". The cube is a mesh, and the mesh documentation does not list rotation.x, position.x and they .y and .z variants as attributes which can be set.
2.
In Object3D, the parameter “position” should be documented as
“read only”. An attempt to set it will result in an error.
This attribute is not marked read only, even though other attributes
are.
3. In PointLight, the method "position.set(x, y, z)" should be added.
4. In BoxGeometry, each of the attributes that are read only, such as width, height, etc, should be listed to be consistent with other parts of the documentation.
5. In Scene, the "add(obj)" method should be added and it should be made clear what kind of objects can be added: cameras, lights, meshes, object3D, whatever.
6. It is not clear when the documentation says it is "todo", whether that means the functionality is there but not documented or whether it means that the functionality, e.g. "gyroscope" is missing entirely. In any case, it would be very helpful if all the items in the documentation that are marked "todo" could be moved to their own section so one does not waste time on a feature which is apparently not there.
7. The object "Group" is not defined anywhere in the documentation, even though there are examples that use it. It is apparently like Object3D but simpler, and is a preferred way to group various objects together before adding them to a scene. In the example I found, one creates meshes, assign each mesh its own position with mesh.position.x = whatever, add the mesh to the group, then at the end add the group to the scene. The documentation should be updated to have a page on "group" and be sure to add the method "add()" as well as all the relevant attributes and what can be updated.
8. The documentation for mesh does not list such attributes as "position", "rotation" and how to set them (e.g. by setting each parameter individually such as postion.x) or whether they should be (or could be) set with a vector. There should also be a discussion in this page of what is inherited by higher level objects associated with the mesh (e.g. if the mesh is a part of an object3D or a group, what happens when that object3D or group is rotated, etc). Although it may seem obvious that the lower level meshes will just inherit the higher level attributes, that is not always the case. First, it may never be the case with group, in that group may be just a bundle of meshes that do not inherit anything. Second, in the case of Object3D, some attributes are indeed inherited as you would expect but at least one parameter, "visibility", only sometimes is. The developers forum goes over in great detail why this exception exists (it has to do with performance issues and the use of WebGL). But had I been trying to make this work without reading the forum I would have wasted a lot of time. Had it been in the documentation, it would merely be an annoying exception which one can easily get around.
The following is information that seems plausible but has not been tested by me as of yet.
9. Also from reading the forum, one learns that the various "traverse objects" in Object3D have been renamed. Again, one would not know that from reading the documentation. Not tested by me.
10. There is supposedly a scene.remove( object ) function which is the opposite of scene.add (object ). It is not clear to me whether one can also remove other entities such as lights, groups etc. It is not clear to me if you can use the undocumented "name" property to find and remove objects.
11. It is said in one of the forums that each Object3D has a "is_ob" flag which when true indicates that this really is an Object3D and that this is necessary when traversing a list of children intending to remove things. Not tested.
12. In quite a few forum posts, it is implied that Three.js is well integrated into the DOM such that one can do such things as "getElementById" on three.js entities. Well, if true, it should be documented.
Requests / Suggestions
1. Of course the big issue when something doesn't work is "what happened?". It would be great if Three.js had a flag that could be enabled that would cause error messages to be output somewhere, presumably the console.
Three.js3. In PointLight, the method "position.set(x, y, z)" should be added.
4. In BoxGeometry, each of the attributes that are read only, such as width, height, etc, should be listed to be consistent with other parts of the documentation.
5. In Scene, the "add(obj)" method should be added and it should be made clear what kind of objects can be added: cameras, lights, meshes, object3D, whatever.
6. It is not clear when the documentation says it is "todo", whether that means the functionality is there but not documented or whether it means that the functionality, e.g. "gyroscope" is missing entirely. In any case, it would be very helpful if all the items in the documentation that are marked "todo" could be moved to their own section so one does not waste time on a feature which is apparently not there.
7. The object "Group" is not defined anywhere in the documentation, even though there are examples that use it. It is apparently like Object3D but simpler, and is a preferred way to group various objects together before adding them to a scene. In the example I found, one creates meshes, assign each mesh its own position with mesh.position.x = whatever, add the mesh to the group, then at the end add the group to the scene. The documentation should be updated to have a page on "group" and be sure to add the method "add()" as well as all the relevant attributes and what can be updated.
8. The documentation for mesh does not list such attributes as "position", "rotation" and how to set them (e.g. by setting each parameter individually such as postion.x) or whether they should be (or could be) set with a vector. There should also be a discussion in this page of what is inherited by higher level objects associated with the mesh (e.g. if the mesh is a part of an object3D or a group, what happens when that object3D or group is rotated, etc). Although it may seem obvious that the lower level meshes will just inherit the higher level attributes, that is not always the case. First, it may never be the case with group, in that group may be just a bundle of meshes that do not inherit anything. Second, in the case of Object3D, some attributes are indeed inherited as you would expect but at least one parameter, "visibility", only sometimes is. The developers forum goes over in great detail why this exception exists (it has to do with performance issues and the use of WebGL). But had I been trying to make this work without reading the forum I would have wasted a lot of time. Had it been in the documentation, it would merely be an annoying exception which one can easily get around.
The following is information that seems plausible but has not been tested by me as of yet.
9. Also from reading the forum, one learns that the various "traverse objects" in Object3D have been renamed. Again, one would not know that from reading the documentation. Not tested by me.
10. There is supposedly a scene.remove( object ) function which is the opposite of scene.add (object ). It is not clear to me whether one can also remove other entities such as lights, groups etc. It is not clear to me if you can use the undocumented "name" property to find and remove objects.
11. It is said in one of the forums that each Object3D has a "is_ob" flag which when true indicates that this really is an Object3D and that this is necessary when traversing a list of children intending to remove things. Not tested.
12. In quite a few forum posts, it is implied that Three.js is well integrated into the DOM such that one can do such things as "getElementById" on three.js entities. Well, if true, it should be documented.
Requests / Suggestions
1. Of course the big issue when something doesn't work is "what happened?". It would be great if Three.js had a flag that could be enabled that would cause error messages to be output somewhere, presumably the console.
No comments:
Post a Comment