Hi Dominik,
On Tue, 2003-10-21 at 07:20, Dominik Rau wrote:
> Hi.
>
> Well, there are some more of us - especially here at the University of
> Koblenz, where we've got some OpenSG-Hype. ; )
Dont' believe the hype! ;)
> >Could you give me an example (or more than one) about the techniques
> >you're thinking of that are not described well?
> >
> I don't think that the problem are the concepts and techniques in general,
> they are, as Pascal already said, described in the related pages / tutorials
> quite well. The problems occur with smaller, trivial things that are not
> documented at all. Here's an example:
>
> We're writing a Radiosity System that uses OpenSG mainly for the reading of
> the scene files and to display the results. Therefore, we also work on the
> OpenSG-Types like vec3f etc. that's all, no big deal so far. Now I have to
> write a paper about it (it's my Studienarbeit, sorry, I don't know the exact
> english term ) which needs some screenshots. Now follow me on my quest through
> the docs:
>
> * First I have a look at the related Pages Section, and find the
> filegrabforeground in the windows section. This looks like what I want, so I
> go on to
> the class description of it. What I know from here is that I have to set a
> filename. It's not mentioned anywhere, but I guess, that OSG will determine
> the image-type from the extension, so I hope that setName("output.png") works.
So far, so correct. Actually the PNG output was added today, but that's
a minor detail. ;)
> * Ok, there's a method called draw(), that I have to use (could someone
> explain me why this func is protected?!) to write the image and which needs a
> pointers to DrawAction and the Viewport as arguments.
Well, it's protected because you're not supposed to use it, and that's
what protected is supposed to tell you. At this point I would have hoped
you'd follow the link at the top of the page which says "See File Grab
Foreground for a description". The text there describes what the FGF can
do. It doesn't list the variable names and so on, these are on the doc
page. Admittedly they are a little hidden in the Base class, using the
Inheriting docs they would be on the doc page. But you found them
anyway, so that wasn't the problem.
Now you were lost what to do with an FGF. Well, the hope was that you
would look up the inheritance hierarchy or the documentation page to
find the base class Foreground. Which says that a foreground is used in
a Viewport. And the docs for the Viewport mention the foregrounds, and
the doc page for Viewport shows the _mfForegrounds field.
So at this point it should have been clear that you need to attach the
Foreground to a Viewport, which is a different story, but one that you
pretty much solved below.
> * What's a DrawAction?! I have a look at the RelatedPages again and find out
> (well, I knew it before...) that actions are used to traverse the
> scenegraph, but there's no word about DrawActions. Well, I guess that,
> because I want
> to draw the whole graph, I have to create that DrawAction Object with the
> root Node of my scenegraph, so I try the following:
> OSG::DrawActionBase *da=OSG::DrawAction::create();
> da->apply(m_sceneGraph);
> gcc stays silent, so I hope I'm on the right way although I don' t know what
> I'm doing anymore.
>
> * Ok, now I need the ViewPort of my Window. According to the Documentation
> (Ctrl+F in the CompoundMembers Section) I get a Ptr to the ViewPort by calling
> getPort( const UInt index ), although there again is not a single line of
> documentation.
>
> So in the end, I've got the following (not working, please help) code:
>
> OSG::FileGrabForegroundPtr fg=OSG::FileGrabForeground::create();
> fg->setName("ouput.png");
> OSG::DrawActionBase *da=OSG::DrawAction::create();
> da->apply(m_sceneGraph);
>
> fg->draw(da,(m_renderWidget.getManager()->getWindow()->getPort(0)));
>
> After 2 hours of trying some variants and reading empty doxygen created docs
> I give up and go on using ksnapshot and gimp to create my screenshots, which
> is frustrating too, but at least works...
Hm, too bad. You were on the right track, and you found the right
component, but then got lost. I'm not sure how to change the docs to
prevent that from happening. You got all the right info, you just
assumed that you could use the FileGrabForeground directly and that led
you astray.
> I have a dream of a fully, QT- or SWING-like documented OSG, where I don't
> have to be a ./src/*-reading template guru or clairvoyant to know what code I
> have to write. Where such easy things like taking a screenshot are mentioned
> in a little "Example" part of the class documentation and
The problem is that pretty much everything is just an easy thing, but
there are tons of them. And which class should this be part of? The FGF?
Possibly, but then we would have tons of repetitions for every
Foreground, as they all need very similar code for setup, and don't
really need much themselves.
We actually have a bunch of examples that are not in the Tutorials but
in the source, these are the test*.cpp programs that we use to test the
stuff. If there is no tutorial for something, these are always the next
best thing, and there are some for all the foregrounds, too. See
Source/WindowSystem/GLUT/testWindowGLUTFGF.cpp for an example for the
FileGrabForeground. I admit, this is an extremely unintuitive location,
and the name is strange, too. fgrep is your friend for now.
> every(!) method
> has at least one or two sentences about its functionality, documented
> parameters and return values.
I'm not sure that's the best way. I think there is no point in
documenting methods that are called setFileName(), because it's totally
obvious what it does: it sets the file name. I think it makes much more
sense to document the functionality of the class (that's what the
related pages are supposed to do) explaining that there is a file name
and what it's for, and only document the methods that actually do
something and especially mention conditions under which they don't do
what they're expected to do. Similarly the Related Pages don't mention
variable names, because it's not relevant to the functionality. These
are mentioned on the class's doc page, where people are expected to look
when implementing. Remember that the Related Pages also make up the
starter guide, so I don't want to clutter them with stuff that's not
relevant when you not sitting in front of the code.
I think the main point is what can we expect the user to know about the
general structure (e.g. Windows->Viewports->Foregrounds...), and how can
we make it easier for him to find these general parts/structures.
One option I could think of would be a section with essentials, but I'm
not sure how long that section can sensibly be before it turns into
another starter guide.
> So please: Stop implementing (for a little while) and
> start documenting! I know that this needs some efforts, but OSG is far too
> complicated to be self-explaining. With a documentation in the current form,
> OpenSG is hardly usable for beginners.
Documenting is a major pain and an enormous amount of work, and a little
while won't help much. We did a lot of documenting for 1.2, and right
now there are a couple major things in the code that need to be finished
before it makes sense to go back to documenting, IMHO.
I'm a big proponent of example code (which takes a lot of time to write,
too ;). In general I think a scenegraph is different from many other
libraries in the sense that there are far less directly usabale, active
components. You are much more likely to elaborately set up some
structures, call mgr->redraw() and watch the magic happen. That's why
examples are IMHO a much better way to document these things than
documenting functions/methods.
It would be nice to have a running example for every class. We made a
start with the Tutorials, but these take quite a bit of time to write,
too, time that we don't have right now.
But as this is Open Source, I'd be more than happy to add whatever
useful tutorials anybody comes up with to the Code. I know that OpenSG
looks pretty dangerous when you try to understand from the code what's
going on (it's not really that bad once you get past the initial steps
;). But I think the Tutorials are a reasonably good start, and I hope
they explain the aspect they're about well enough to make it
understandable.
So if every one who stumbled across a point that wasn't clear from the
documentation and that wasn't explained in the tutorials wrote a
tutorial about it or extended the documentation, it shouldn't take that
long to cover the really important and/or unclear points. I'd love to
see contributions in that area, even more than contributions in the code
(okay, maybe not as much as a fully integrated shader support, but close
;) (actually, I'd rather not see that, as I want to do that myself :)).
IMHO, open for comments
Dirk
--
-- Dirk Reiners Assistant Professor Iowa State University
-- Human-Computer Interaction, Computer Science
-- Snail mail: 1620f Howe Hall; Ames, Ia 50011
-- Email: [EMAIL PROTECTED], [EMAIL PROTECTED]
-- The OpenSG Open Source Scenegraph: http://www.opensg.org
-------------------------------------------------------
This SF.net email is sponsored by OSDN developer relations
Here's your chance to show off your extensive product knowledge
We want to know what you know. Tell us and you have a chance to win $100
http://www.zoomerang.com/survey.zgi?HRPT1X3RYQNC5V4MLNSV3E54
_______________________________________________
Opensg-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/opensg-users
