Well, I deleted the PDF, since it isn't always current. Please use the OpenOffice document until we release it on xith.org. Exporting it to PDF and committing this everytime Amos or me modified it just increases the repository size.

When Amos added the screenshots he's talking about, we'll release it on xith.org.

@Amos: What do you think about splitting XIN into two parts? Part one just explains the very basics to get started with Xith3D, like the current version does. So the current version (together with the screenshots) could be "XIN - Part I" and the following chapters could be summed up in "XIN - Part II".

@Amos: What do you think about splitting XIN into two parts? Part one just explains the very basics to get started with Xith3D, like the current version does. So the current version (together with the screenshots) could be "XIN - Part I" and the following chapters could be summed up in "XIN - Part II".

Btw. I just read the current version. Thumbs up for this nice tutorial!

Splitting it into two parts, maybe "XIN - Getting Started" and "XIN - Advanced Topics", seems like a good idea.

Great idea. But what about making it a little more dramatic by using subtitles

1 2

XIN - PartIGettingStarted

and

1 2

XIN - PartIIAdvancedTopics

I object !

XIN is supposed to explain Xith "in a nutshell".I had the project to co-write (with you, Qudus) a second book named "Xith Under The Hood" (UTH) which explain the low-level scenegraph and renderer structures how precisely it is handled and how you do to add features.

What would you put in "Advanced Topics" ? Even advanced graphics effects should be made simple ! If a code snippet takes more than one-two page, it is (IMHO) bad and it needs to be simplified. However, explanations with the snippets can be made longer (2-4 pages) if the subject is big. But for XIN, it's the "KISS" philosophy (Keep It Simple Stupid)...

. the use of the demo folder code [ new Xith3DDemoFolder() ]assumes a sub directory pattern, texture etc. this should be spelled out in the tutorial so a new user understands his image data etc needs to be in a specific subdirectory

. the use of the demo folder code [ new Xith3DDemoFolder() ]assumes a sub directory pattern, texture etc. this should be spelled out in the tutorial so a new user understands his image data etc needs to be in a specific subdirectory

No. The Xith3DDemoFolder class has nothing to do with the XIN book. The info, you're talking about needs to be noted in Xith3DDemoFolder's JavaDoc. And I'll add it there. But this class is never used in XIN and is only a helper for the org.xith3d.test classes and is not meant to be used for other projects.

. the use of the demo folder code [ new Xith3DDemoFolder() ]assumes a sub directory pattern, texture etc. this should be spelled out in the tutorial so a new user understands his image data etc needs to be in a specific subdirectory

No. The Xith3DDemoFolder class has nothing to do with the XIN book. The info, you're talking about needs to be noted in Xith3DDemoFolder's JavaDoc. And I'll add it there. But this class is never used in XIN and is only a helper for the org.xith3d.test classes and is not meant to be used for other projects.

Though we'd have to :- Ensure that all can be loaded properly both in filesystems and jars- Talk of how to do that in XIN

Do you consider the TextureLoader framework as stable for 1.0 or will it be changed till then?

I was a little confused by the TextureLoader, ImageComponentLoader, TextureStreamLoader and TextureStreamLocator interfaces. I think they could be better seperated by renaming them:

TextureLoader -> ResourceLoaderSince I think it could be usefull to extend the TextureLoader singleton to locate and load all resources needed by Xith (sounds, models etv.)

TextureStreamLocator -> ResourceLocatorWhich would be an obvious change, if the TextureLoader is renamed

TextureStreamLoader -> TextureFactoryTo ensure that XXXLoader is not mistakable for XXXLocator

ImageComponentLoader - ImageComponentFactoryto follow the scheme

Also I would vote for a ClasspathLocator implementation, that takes a ClassLoader instance as contructor parameter. I think it would be very convenient to have the ResourceLoader initialized to ResourceLoader.class.getClassLoader() per default, so you always have access to resources on the classpath where xith.jar is loaded from.

I find the names Loader and Locator confusing, too. So I would be happy, if they'd get renamed in some way. I'm not sure, if all these locators and things actually make sense. I guess, it's not the most efficient way. And the textures must not be loaded from java internal ImageIO into a BufferedImage and then converted into a Texture, but directly load them by faster loaders into a Texture. I would prefer to get the createTexture() methods out of TextureLoader and put them into a new class called TextureCreator or maybe TextureFactory.

But TextureLoader and ModelLoader should stay separated, since they're too different to unite them in a common loader system.

We don't have a common Sound loader yet. So it would make sense to write one and put it to com.xith3d.loaders.sound.

Maybe you want to write a wrapper class, that loads resources and makes use of TextureLoader and the model-/scene loaders. I've just improved org.xith3d.loaders.base.* to make the classes more general (not committed yet). If all model-/scene loaders would inherit from this loader base, we'd be a big step further.

I find the names Loader and Locator confusing, too. So I would be happy, if they'd get renamed in some way.

Let's see what Amos says to this. Is there any background info, where they came from? They seem to be quite new, since the GSG examples don't uses this scheme.

Quote

And the textures must not be loaded from java internal ImageIO into a BufferedImage and then converted into a Texture, but directly load them by faster loaders into a Texture. I would prefer to get the createTexture() methods out of TextureLoader and put them into a new class called TextureCreator or maybe TextureFactory.(...)

We don't have a common Sound loader yet. So it would make sense to write one and put it to com.xith3d.loaders.sound.

Hmm, so there should be dedicated Factories for textures, models and sound. I can think of three possible ways to do this:

1. create XXXFactory singletons which can be extended by registering "XXXProducers" (e.g. ModelFactory with a MD3ModelProducer)At least TextureLoader follows this scheme... seems the most "service oriented" approach, but may be too J2EE style for games

2. create dedicated classes for each resource type which derive a special base class (e.g. MD3Model extends Model) and take the base name as constructor parameterI have seen several implementations like this and this seems fast and easy

I think solution 1 is oversized and 2 looks suspicious to have a catch (multiple inheritance perhaps). I would prefer something like solution 3. Don't know what you are doing with the new loader base, but it sounds to go into this direction.

Quote

I'm not sure, if all these locators and things actually make sense. I guess, it's not the most efficient way.

At least from the design perspective, they offer a good abstraction of resource loading. I guess with a little caching of valid stream locations they will be efficient enough. I think it is worth it, to have an abstracted access to different resources, but I would vote for the ResourceLoader to be just some sort of repository singleton where to register locators and move the createXXX methods to some other place (s.o.).

Quote

Maybe you want to write a wrapper class, that loads resources and makes use of TextureLoader and the model-/scene loaders.

I do not neccessarily need a central point of Texture/Model/Sound instanciation, I just like the idea of a central point to find resources, so TextureLoader looked like the right victim . Also I think it is substantial to have good support to load from the ClassLoader.

Hmm, so there should be dedicated Factories for textures, models and sound. I can think of three possible ways to do this:

1. create XXXFactory singletons which can be extended by registering "XXXProducers" (e.g. ModelFactory with a MD3ModelProducer)At least TextureLoader follows this scheme... seems the most "service oriented" approach, but may be too J2EE style for games

2. create dedicated classes for each resource type which derive a special base class (e.g. MD3Model extends Model) and take the base name as constructor parameterI have seen several implementations like this and this seems fast and easy

I think solution 1 is oversized and 2 looks suspicious to have a catch (multiple inheritance perhaps). I would prefer something like solution 3. Don't know what you are doing with the new loader base, but it sounds to go into this direction.

The loaders base does exactly what you describe in point (2.). And I definitely prefer this way. It is an advancement and generalization of the old / current org.xith3d.loaders.scene loaders base. This one is fine except that scenebase doesn't extend any Group type and the getters return arrays, which need to be created especially for the getters. And there's no difference between a model and a scene, which is a minor issue, but "solved" in my version.

Also I think it is substantial to have good support to load from the ClassLoader.

TextureLoader can theoretically load from an InputStream through TextureStreamLocator. But one had to write an implementation for it. Some time ago I wrote one for zip inputstreams, which is very similar. And org.xith3d.loaders.base.Loader has six methods to load. three to load the file as a Model and three to load it as a Scene. One of each three takes an InputStream, which enables you to easily load from classpath. It is up to the loader implementer to corretly implement these methods.

Marvin

btw. I don't like the naming of Factory or Producer or things like that for Loaders. They don't produce a model, but load it. As I mentioned above the TextureLoader has methods to create an empty texture, which is of course needed to load one. But these methods don't belong to the TextureLoader itself as I think, but to a separate class.

The loaders base does exactly what you describe in point (2.). And I definitely prefer this way. It is an advancement and generalization of the old / current org.xith3d.loaders.scene loaders base.

As I said this option is fast and simple. The only real advantage would be offered by option (1), where you can mix and match different Producers (or Builders ) without the user knowing anything about different model/texture/sound types. This would also prevent different inconsistent Loader classes, since the usage pattern is given by the API (the actual XXXFactory) and all concrete implementations are forced to use the interface offered by the SPI.

Quote

Quote

Also I think it is substantial to have good support to load from the ClassLoader.

TextureLoader can theoretically load from an InputStream through TextureStreamLocator. But one had to write an implementation for it. Some time ago I wrote one for zip inputstreams, which is very similar.

Yes, it's possible to use getResource() to retrieve an URL and pass it to TextureStreamLocatorURL, but this won't deal with the structure of the classpath (multiple jars/directories).Since it is easy to write an own TextureStreamLocatorClasspath, that overcomes this, I think it would be beneficial to adapt that scheme with other loaders, too.

Quote

And org.xith3d.loaders.base.Loader has six methods to load. three to load the file as a Model and three to load it as a Scene. One of each three takes an InputStream, which enables you to easily load from classpath. It is up to the loader implementer to corretly implement these methods.

At this point a general ResourceLocator could tighten the interface, since the InputStream retrieval is shifted to the ResourceLocator, so only resource names are needed to load a resource. Also it would allow for further optimization of the name<->stream mapping and resource access would be generalized for all kind of Loaders.

Quote

btw. I don't like the naming of Factory or Producer or things like that for Loaders. They don't produce a model, but load it

Yeah Producer is wrong, Builder would be better, since it would be an (simplistic) incarnation of the builder pattern. For me however everything that creates an Object is a Factory...

Anyway Loader is fine. They should just all behave the same and share as most base functionality as possible.

As I said this option is fast and simple. The only real advantage would be offered by option (1), where you can mix and match different Producers (or Builders ) without the user knowing anything about different model/texture/sound types.

Well, the user does know exactly what kind of data he is loading, since he'll have to handle the returned object corretly.

At this point a general ResourceLocator could tighten the interface, since the InputStream retrieval is shifted to the ResourceLocator, so only resource names are needed to load a resource. Also it would allow for further optimization of the name<->stream mapping and resource access would be generalized for all kind of Loaders.

Yeah Producer is wrong, Builder would be better, since it would be an (simplistic) incarnation of the builder pattern. For me however everything that creates an Object is a Factory...

Well, it is not simple object creation. Otherwise I would concede to you. Loader is just fine IMHO. Of course there're objects created, but in fact everyone will understand, what a loader does, when he expects it to load a model / texture / sound. And of course an object holding the model (e.g.) is the result.

The only things the "Model" (MD2Model, CalModel or whatever) should conform to is to :- Display the first frame of anim if that's an anim even if you haven't called any function after load- Extends BranchGroup or provide a branchgroup containing the data

And we should be able to load a "model" (huge abstraction here) of whatever type with a single generic instruction so a "basic" model loader is really straightforward.

I think we could provide a function which returns an icon of the 3D model file.

It would :- Load it- Compute its sphere bounding box- Create a scene with a Camera at the right distance so you see the whole model on a e.g. 48x48 canvas- Render an RGBA image of it

The only things the "Model" (MD2Model, CalModel or whatever) should conform to is to :- Display the first frame of anim if that's an anim even if you haven't called any function after load- Extends BranchGroup or provide a branchgroup containing the data

java-gaming.org is not responsible for the content posted by its members, including references to external websites,
and other references that may or may not have a relation with our primarily
gaming and game production oriented community.
inquiries and complaints can be sent via email to the info‑account of the
company managing the website of java‑gaming.org