Featuring a bean editor and a GUI editor !!!
Last update : 9/7/2000
Document written by : Artiste on the Web (A11W)
I'm not a native english speaker, so please excuse any language mistake ! If you have
corrections, just mail me !
To run the editor, just run the class opale.soya.editor.Editor :
java [-classpath yourClasspath] opale.soya.editor.Editor
The classes that correspond to the editor app are located in opale.soya.editor for generic
classes, and in the same package that the class they edit for the other.
Just after running it, you will see the editor main window. This is also the configuration
window.
In the window, you should see three text fields, they correspond to 3 pathes that soya uses
for storing objets files : one for materials (including texture), one for shapes and one for
animations. The best thing to do is to create 3 sub-directories in your home directory,
called for example materials, shapes and animations, and to enter these pathes in the
corresponding text fields.
When saving or loading a world file, soya may uses these pathes to search the corresponding
ressources (materials, shapes and animations). Such a ressource is called a "stored in path
object" (interface opale.soya.util.StoredInPathObject); and it can be saved either in the world
file (avantage : you have only one file with all), or in its path (avantage : you can share the
object between many files). If you want to save a "stored in path object" into its path, you
have to give it a name (property name from interface opale.soya.util.NamedObject).
My advice is to use those pathes!
That's all for configuration!
The editor main window provides 2 usefull menus : new and open.
The new menu allows you to create new soya object : material, shape, world, environment (a
world with a few additionnal properties). Animations cannot be created without a world; we will
see later how to create a new one.
The open menu allows you to open soya object : material, shape (opened from their pathes), or
any file. With the open file menu, you can open any serialized object (soya always uses
serialization for saving objects), including materials, shapes, worlds, environments, or even
non-soya object! This is possible because we use a bean editor.
Opale.soya editor provides 2 different editors : a bean editor and a GUI editor.
The bean editor is used for all objects. It is called after any edition. The soya bean editor
edits all non-hidden properties, including write only properties; when closing the bean editor
window, it will ask for saving if the object is saveable (=if it has a save() or save(String)
method).
The GUI editor is specially designed to edit specific objects : shapes and worlds (including
environment). It is not avalaible for other object.
Materials are edited in the bean editor.
A material describes all the surface properties, including color and texture.
At the top of the window, you can see a 3D view of the material, set over a cube. You can click
the view to rotate the cube.
Below, the bean editor lists the properties of the material :
- name the name of the material. Set it to "null" or to "" if you
don't want to save this material in the material path; else enter the name of the material. 2
material cannot have the same name!
- diffuse color (red, blue, green and alpha) the diffuse color of the
material. This is the "principal" color. Each color component ranges from 0 to 1, but you can
set them out of this range.
- specular color (red, blue, green and alpha) the specular color of
the material. This is the color of the brightness.
- shininess the shininess of the material. This ranges from 0
(metallic) to 1 (plastic). The fewer it is, the more the specular color takes importance.
- wireframed Set this to true for wireframed drawing.
- overlayed Set this to true if you want objects that have this
material to be drawn at the top, even if they are behind other objects. Warning : this can
leads to visual artifacts.
- texture The texture object of this material. You can choose
"(null)" for no texture, "opale.soya.soya2d.TextureRGB" for an RGB texture (no transparency)
"opale.soya.soya2d.TextureRGBM" for an RGB texture with a mask ("all or nothing" transparency),
or "opale.soya.soya2d.TextureRGBA" for an RGBA texture with an alpha channel
(transparency).
Shapes are edited first in the bean editor.
A shape describes a geometric shape, build with many fragments, like triangles or quad.
At the top of the window, you can see a 3D view of the shape.
Below, the bean editor lists the properties of the shape :
- name the name of the shape. Set it to "null" or to "" if you don't
want to save this shape in the shape path; else enter the name of the shape. 2 shapes cannot
have the same name!
- width, height, depth The dimension of the shape.
- x, y and z factors The scale factor of the shape. Scale factors
are not supported for shape; set them will rightly scale the shape, but the scale factors
remains to 1.
- material Write only. Sets the material for all fragments in the
shape. Select the name of the desired material, or choose "(null)" for the default white one,
or choose "(other)" to create a new one with no name (in this case it will be saved with the
shape).
- smoothLit Write only. Sets the smoothLit for all fragments in the
shape. If true, the shape will be lit as if it was smooth (even if it is not) : with 1 normal
for each point (instead of one for each face).
- visibility Write only. Sets the visibility for all fragments in the
shape. Default is all face visible; you can choose to hide one side of the face (it can speed
up the rendering). If you choose "exterior visible", soya will draws only the exterior side of
the faces, "interior visible" is just the contrary; these 2 options required your shape to be
closed. You can also choose "non-closed"; in this case only 1 side is drawn; it depend of the
order of the points of the faces.
Shapes have a special GUI editor. You can call it from the bean editor, with a click on the
"soya GUI editor..." button.
The GUI editor shows a big 3D view, at the center of it you can see the origin and the 3 axis.
You have also a menu bar at the top.
Move the mouse on the 3D view : you should see a green cube that follow the mouse cursor. This
is the 3D cursor; you can move it with the mouse (left, right, up, down) and the page up
(forward) and page down (backward) key (before typing keys, you may need to click on the 3D
view, in order to focus it). In the GUI editor, the green is always the color of the
selection.
You can rotate the camera by dragging the mouse, with the right button pressed. The view menu
have several usefull predefined views.
If you have created a new shape, there is nothing else.
Open the "face" menu, and then the "class of face submenu". this submenu allows you to choose
the type of face you will draw. Basic face are triangles (opale.soya.soya3d.model.Triangle) and
quads (opale.soya.soya3d.model.Quad); there are also many shapes elements (different from
faces), like Label3D and Sphere3D.
Choose triangles, and then select the menu "new face" in the "face" menu. Then click 3 times
on the 3D view, where you want to locate the 3 points of your triangle. You should see
something like this :
The 3 points of the triangle are materialized by 3 red cubes; such cubes are called "handles".
If you move the cursor on one of them, it will turn green; you can select this handle by left-clicking the mouse. You can move the handle by dragging it (let the left mouse button pressed
and move the mouse), and using the page up and page down keys.
To select a handle, you need to move the cursor at its exact position, including in Z; if you
think this is too constrainent, you can use the middle mouse button to select all handles
above or under (in Z) the cursor.
The shape GUI editor has several modes; you can switch to another with the selection menu. The
first and default mode is the point selection mode. Now, switch to the face selection mode!
The red handles disappear, and a blue handle appears at the center of the triangle :
The blue handle is a face handle; you can select it and move it as for the red point handles.
When you move it, the triangle moves.
The selection menu allows also to delete the selected face, or to edit the selected face. Edit
yout triangle! It will be edited in the bean editor :
With this windows, you can move all the points of the face, or change its properties :
- material Sets the material for this face. Select the name of the
desired material, or choose "(null)" for the default white one, or choose "(other)" to create
a new one with no name (in this case it will be saved with the shape). Click on the "edit"
button to edit the material in the bean editor.
- smoothLit Sets the smoothLit for this face. If true, the face will
be lit as if it was smooth (even if it is not) : with 1 normal for each point (instead of one
for each face). (You cannot see the difference if your face doesn't share at least a point with another).
- visibility Sets the visibility for this face. Default is all face
visible; you can choose to hide one side of your face (it can speed up the rendering). If you
choose "exterior visible", soya will draws only the exterior side of the face, "interior
visible" is just the contrary; these 2 options required your shape to be closed. You can also
choose "non-closed"; in this case only 1 side is drawn; it depend of the order of the points
of the face.
You can also select and edit a point :
The bean editor displays its properties :
- x, y, z The position.
- texture coordinate x, y The texture coordinates (usefull only if
the face of this point has a textured material).
- useColor This boolean property is true if the point has a valid
color.
- red, blue, green, alpha The 4 color component of this point. The
color is applied only if useColor is true.
At this time, you should try to draw a more complex shape, like a pyramid or a cube. For that,
a few hint :
- When creating a new face, click on a point handle to add this point.
- Press the control key to activate the magnetic grid.
- Press the shift key to select more than one handle at a time.
- You can enter more easily the texture coordinates by selecting the point and choose the menu
"point", and then "texture coordinates".
- The edit menu allows to change the magnetic grid step, to light off the cursor, to hide or
show the cursor coordinates, and to set the camera in orthometric (ortho) mode.
- Nearly all the menu command have a shortcut; those shortcuts can also be used without holding
the control key (type "e" to edit the selected object, "n" for a new face, ...). Type F3 for a
new triangle, and F4 for a new quad.
- You can select a face and then enter in the "point in face selection" mode (in the selection
menu) to show only the point handles for a face. This can be usefull if you want different
texture coordinates for points shared between several faces.
- You can use the "hide handles" mode to make a screen shot!
- You can save the shape with the "file" "save" menu. The "optimize and save" do the same after
omptimizing the shape (optimization isn't implemented in opale.soya 0.1).
Worlds are edited first in the bean editor.
The upper part of the bean editor is a hierarchical view of the world.
Right clicking on an element displays a context menu. You can choose whitch element is edited
in the lower part (=the list of properties) by clicking the "edit" menu; it's equivalent to
middle-click the element. You can choose "edit in new window" in order to edit in another
window.
The "reset position" and "reset orientation" menu moves the element to (0, 0, 0) and resets
its orientation to default; they are usefull when used with the GUI editor.
The "choose target" menu edits the element's target, in order to make a "look at".
The "dump" and "dump matrix" menu prints info at the console.
The "remove" menu removes and deletes the selected element.
The 2 last menus are avalaible only for world (including its sub-class).
The "add" menu contains several sub-menu will the different elements you can add. Choose
"other" and type the element full class name in order to add your own element.
The "convert to shape" menu converts the selected world into a fragmented shape, and edit this
shape in the bean editor. If you want to save it, give it a name, close the bean editor window
and say "yes" when asking for saving. This is a good way to create complex shapes, and the only
way to create static-lit shapes.
The bean editor lists the properties of the edited element, those properties depends of the
element class and there are too numerous to list all of them, but the main are :
- name The name of the element (all element). The name is not used for save.
- x, y and z The position of the element (graphical element only).
- target x, y and z The position of the target of this element (graphical element only).
The target is used for "look at" orientation.
- width, height, depth The dimension of the element (volume and world only).
- x, y and z factors The scale factor of the element (volume and world only).
- shape The shape of the element (volume and world only). The list displays all the
shapes avalaible in the shape path; you can set it to a new shape by choosing "other". You can
edit the shape by clicking on the "edit" button.
- visible The visibility of the element (graphical element only). Set it to false to
hide the element.
- ...
Worlds have a special GUI editor. You can call it from the bean editor, with a click on the
"soya GUI editor..." button.
The world GUI editor is very similar to the shape one. The cursor moves identicaly.
This GUI editor is designed to be used in parallel to the bean editor.
The world GUI editor uses blue handles for position, and yellow handles for orientation.
Dimensions cannot be changed through the GUI editor, you must use the bean editor.
To move an element, just move its blue handle. To orientate it, move its yellow handle; the
element will look at it. The look at rotates only around X and Y axis; you can rotate an
element around its Z axis by pressing the insert and home keys, while one of the element's
handles is selected.
When you add an element (in the bean editor), the GUI editor will locate it at the cursor
position; click the left mouse button to put it.
When you select an element in the hierarchical view of the bean editor, its handles are
selected, and when you select a handle, the corresponding element is selected in the tree.
This can be usefull to find an element.
A 3D scene or character rarely uses only one animation, this is why opale.soya defines a
collection, called Animations, to store many of them.
Animations cannot be edited directly; you must edit them with a world (=the world to
animate).
First edit this world in the bean editor, and in the GUI editor. Then, in the bean editor,
set the animations property of the world to the animations collection you want to edit. The
bean editor lists the animations avalaible in the animations path; you can choose "(other)"
to create a new one.
Now, in the GUI editor, click the animations edit menu. A special bean editor window appear
for the animations.
This window allows you to define the properties of the animations collection, in particular
its name (this name is used for saving, as for materials or shapes), and a list of all the
animation in the collection (empty for new animations). Below, a few buttons allow you to
create a new animation, or to edit or delete the selected animation.
Animation are also edited in the bean editor. To create an animation, you need to enter a few
"key positions", called states. Opale.Soya is able to interpole between those states.
The bean editor shows a lists of all the state in the animation (empty for new one), a few
button and a list of properties.
To add a new state, position each element as you want in the world GUI editor, choose at which
time you want to add this state (enter the time value in the correspondant textfield), and
click the "add current state" button.
You can remove the selected state in the list with the "delete state" button. Double-click
on a state to set it in the world GUI editor.
If you have added more than one state, you can use the scrollbar to define the animation time
and see the elements moving smoothly, or click the "play" checkbox to play the animation.
The properties in the bean editor include the following :
- name The name of the animation. Here, the name is not used for saving (animations are
saved with the animations collection in whitch they are added), but it can be usefull to find
the desired animation.
- cyclic lap This property allows to create cyclic animation. For non-cyclic one, set it
to 0. For cyclic animation, it must be the time lap between the last state and the first.
This is all at this time ! Thank you for a so long reading, and good 3D designing !
Artiste on the Web (A11W)