glsdk-devel

[Glsdk-devel] checking in

[Rob B. <rb...@bl...>]

	Hello Henri , yep I'm still here..

	I think the #1 goal has to be "walk developers step by step through  
use of the API".  I think to keep focus that we may need to set some  
explicit *non*-goals for a period of time, and here are a few I would  
suggest, since they don't help teach the API.

	a) SIMD optimization for the math lib.  <- fun, but off course.
	b) anything that would tip the balance towards "web site authoring  
and maint" and away from making code.
	c) 3D geometry/math tutorials - we can link to any number of books/ 
sites for this stuff
	d) anything else that consumes calendar time at the expense of demo  
code.

	One class of example that might be interesting would be a Rosetta  
stone, where several ways to accomplish the same goal are shown.  For  
example, simplest thing I can think of, a tumbling triangle.  You can  
do it with all the math on the CPU and push finished verts to the  
GPU.  You can then say "maybe I should do the rotation in the shader"  
and demonstrate how to hoist code from CPU to GPU and have it run in  
the shader.  You could show one version where we compute the rotation  
matrix on the CPU and pass that as a uniform to be used trivially in  
the shader, then you could do one where (just for kicks) we pass Euler  
angles as uniforms and let the shader generate the matrix itself.  We  
could do one where we pass non-Cartesian verts (azimuth/elevation and  
radius) and let the shader do polar-to-cartesian conversion.  By the  
end of it you've learned a few different ways to push data from CPU to  
GPU and have it acted on.

	stops on the API-learning road.. please add some stops here

	- how do I establish a context and put it on the screen
		- make a window, init context, clear, swap

	- how do I put data in a buffer so GPU can see it
		- no drawing - just demonstrate the buffer API's
		- perhaps BufferData some floats into a buffer, then map it and  
print the values seen

	- how do I draw the simplest possible triangle
		- pass-through shader for vert position
		- "write red" for pixel
		- constant verts for geometry in a VBO

	- how can I change the color of the triangle
		- introduce per vertex color attribute
		- vertex shader passes it through
		- alter pixel shader to read it and emit it

		- introduction to uniforms - communicate to shaders
		- show color change using uniform (several ways to do this)

	- how can I move the triangle
		- see above

	that's a lot of good tutorial steps before we even start talking  
about more than one triangle.  Ideally you get to the end of this  
phase and you have an idea of how to put data in a buffer, how to lay  
out some vertex data, how to draw a triangle, and how to communicate  
on a very basic level with the shaders, and no usage of deprecated APIs.

Rob

Re: [Glsdk-devel] checking in

[Jason M. <ko...@gm...>]

I like this. It puts into contrast what separates tutorials from examples
from demos.

A *demo *is just a program with documentation that shows how to do
something. The code itself may not be well formatted, but you can learn some
effect by reading the demo's docs.

An *example *is a well-documented program. That is, the documentation
actually walks you, step-by-step, through the relevant parts of code.
Examples can often skip initialization or so forth, but they need to explain
in detail the code relevant to the purpose of the example.

A *tutorial *is a teaching aid. It is important for tutorials to have a
sequence (one tutorial teaches things that are used in the next), and it is
important for them to engage the reader. The code listing for the tutorial
isn't nearly as important as how the tutorial itself is written. And as you
point out, a tutorial doesn't even need to have a functional codelist; it
exists to help the reader learn the concepts involved.

This tells me that tutorials need to be something we do "in-house," rather
than commissioning people to provide them. Or, at the very least, we should
provide the actual subject for each tutorial. A certain standard level of
quality needs to exist for them, and it will take concerted effort to
maintain that level of quality.

As for the "stops on the road", the main problem is the dramatic jump
between "I've got a GL window" and "render something". It requires
introducing VBOs and shaders. The VBO stuff is fairly simple; it's much like
a form of malloc. The problem comes with shaders, which are incredibly
complicated. I suppose in a tutorial, you can just handwave it as "magical
setup work that we'll detail later," but I'd be at least a little concerned
about how that would read to a user.

To expand on your list a bit:

  - How do I have a camera independent of the transform for the object?
    - Requires multiple objects
    - Introduces multiple sequential transforms
    - Concatenates them into one matrix for ease-of-use

  - How do I map textures?
    - Introduces passing of texture coordinates
    - Introduces texture mapping fragment operations

  - How do I introduce lighting?
    - Needs to be after the camera one.
    - Start with directional lights and a semi-complicated object (sphere).
    - Introduce normals and the diffuse lighting equation
    - Do per-vertex lighting, passing a color value.
    - Deal with normal transforms as separate from position transforms.
    - Interactions with textures.

  - What about better lighting?
    - Introduce a specular term.
    - Use it per-vertex. Show why this is bad.
    - Move to per-fragment lighting.
    - Different interactions with textures.


On Fri, Aug 29, 2008 at 9:41 AM, Rob Barris <rb...@bl...> wrote:
>
>        Hello Henri , yep I'm still here..
>
>        I think the #1 goal has to be "walk developers step by step through
> use of the API".  I think to keep focus that we may need to set some
> explicit *non*-goals for a period of time, and here are a few I would
> suggest, since they don't help teach the API.
>
>        a) SIMD optimization for the math lib.  <- fun, but off course.
>        b) anything that would tip the balance towards "web site authoring
> and maint" and away from making code.
>        c) 3D geometry/math tutorials - we can link to any number of books/
> sites for this stuff
>        d) anything else that consumes calendar time at the expense of demo
> code.
>
>        One class of example that might be interesting would be a Rosetta
> stone, where several ways to accomplish the same goal are shown.  For
> example, simplest thing I can think of, a tumbling triangle.  You can
> do it with all the math on the CPU and push finished verts to the
> GPU.  You can then say "maybe I should do the rotation in the shader"
> and demonstrate how to hoist code from CPU to GPU and have it run in
> the shader.  You could show one version where we compute the rotation
> matrix on the CPU and pass that as a uniform to be used trivially in
> the shader, then you could do one where (just for kicks) we pass Euler
> angles as uniforms and let the shader generate the matrix itself.  We
> could do one where we pass non-Cartesian verts (azimuth/elevation and
> radius) and let the shader do polar-to-cartesian conversion.  By the
> end of it you've learned a few different ways to push data from CPU to
> GPU and have it acted on.
>
>        stops on the API-learning road.. please add some stops here
>
>        - how do I establish a context and put it on the screen
>                - make a window, init context, clear, swap
>
>        - how do I put data in a buffer so GPU can see it
>                - no drawing - just demonstrate the buffer API's
>                - perhaps BufferData some floats into a buffer, then map it
and
> print the values seen
>
>        - how do I draw the simplest possible triangle
>                - pass-through shader for vert position
>                - "write red" for pixel
>                - constant verts for geometry in a VBO
>
>        - how can I change the color of the triangle
>                - introduce per vertex color attribute
>                - vertex shader passes it through
>                - alter pixel shader to read it and emit it
>
>                - introduction to uniforms - communicate to shaders
>                - show color change using uniform (several ways to do this)
>
>        - how can I move the triangle
>                - see above
>
>        that's a lot of good tutorial steps before we even start talking
> about more than one triangle.  Ideally you get to the end of this
> phase and you have an idea of how to put data in a buffer, how to lay
> out some vertex data, how to draw a triangle, and how to communicate
> on a very basic level with the shaders, and no usage of deprecated APIs.
>
> Rob
>
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
challenge
> Build the coolest Linux based applications with Moblin SDK & win great
prizes
> Grand prize is a trip for two to an Open Source event anywhere in the
world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Glsdk-devel mailing list
> Gls...@li...
> https://lists.sourceforge.net/lists/listinfo/glsdk-devel
>

Re: [Glsdk-devel] checking in

[Andrew G. <and...@gm...>]

These are all great, and given their granularity it allows someone to skip
around a bit to focus on exactly what they need.

That said, the more granular the tutorials, the more work! :-)

The tutorial format will have to be played with, and I'm sure people will
probably be very opinionated on what constitutes a clear and readable
tutorial that "engages" the user.

So, chicken or egg?  Does someone create a simple triangle demo or context
creation and then we (or one person) takes a stab at presenting a tutorial
based on it?  Or should a tutorial format be tested covering the basics of
context creation (without necessarily full code included in the tutorial)?

Hopefully in the coming weeks I'll have a chance to actually submit
something, whether code, tutorial/documentation, or other, so I won't just
be an opinionated voice on this list.

Re: [Glsdk-devel] checking in

[H. H. <hen...@gm...>]

On Fri, Aug 29, 2008 at 7:41 PM, Rob Barris <rb...@bl...> wrote:

>
>        Hello Henri , yep I'm still here..
>
>        I think the #1 goal has to be "walk developers step by step through
> use of the API".  I think to keep focus that we may need to set some
> explicit *non*-goals for a period of time, and here are a few I would
> suggest, since they don't help teach the API.
>
>        a) SIMD optimization for the math lib.  <- fun, but off course.
>        b) anything that would tip the balance towards "web site authoring
> and maint" and away from making code.
>        c) 3D geometry/math tutorials - we can link to any number of books/
> sites for this stuff
>        d) anything else that consumes calendar time at the expense of demo
> code.
>

Yes I generally agree on these points. At this moment I am writing the GLM
API reference which I consider to be important to the SDK (a library is not
usable unless it has documentation). I am not sure do we need a separate
programming guides and/or tutorials for the mathlib and other baselibs at
all, but either way, these can wait.

DirectX SDK does not have a programming guide as far as I know for their
D3DX library either.

-- 
Henri 'henux' Häkkinen