[Clanlib-devel] question regarding surfaces..

[Thomi Richards]

Hi guys,


I have a few questions regarding the CL_Surface class. I tried asking
in IRC, but everyone was AFK - I'm hoping I get a better responce
here.


I'm making a tilemap editor for a game - I want to create a surface
and draw all the tiles onto that surface, then render the entire large
surface to the screen at once.

I'm having problems because I can't figure out how to create a
CL_Surface with a fixed size. It has get_width() and get_height()
methods, but no set_width() and set_height() methods. How can I set
the size of a surface!??

I guess what I'm after is a generic "graphic surface" class - one that
will let me set it's size, copy things to and from it in an easy
manner...

Am I using the right class? I also investigated CL_Canvas and
CL_PixelBuffer, but they didn't seem to be what I want..

I'm very impressed with ClanLib in general, but the docs *really* need
updating. There are so many classes with little or no documentation...
The output format of the docs are also really strange... For example,
CL_Keyboard::get_keycode() is a static method, but it doesn't say that
in the API reference *anywhere*... You have to guess. Same goes for
CL_Display and CL_Mouse and probably more that I have yet to "guess".

ClanLib has some great functionality, but without the documentation to
back it up it's very hard to learn and use.

I'm more than willing to work on improving the documentation - I've
already submitted a few patches to that effect - but I'll need help -
I don't know the ClanLib internals (hell, I don't even know the
externals)...


So... whadaya say?


Thanks,

[Magnus Norddahl]

Hi Thomi,

In ClanLib 0.8.0 you have the following imaging classes at your disposal:

1. CL_Surface

Represents an image placed in the graphics card memory. The name surface is
a bit misleading, since you do not actually have direct memory access to the
image as you did in DirectDraw. It is currently implemented as a texture in
clanGL.

2. CL_Canvas

Off-screen rendering context. Allows you to use hardware accelerated
rendering methods to draw something to be stored in a surface afterwards.
The 0.8 series implementation is a bid oddly designed since you need to
select a surface into the canvas to permit drawing.

3. CL_PixelBuffer

Image stored in system memory.

4. CL_Sprite

Higher level class that makes it easier to draw a lot of smaller images and
use them in animations.

To do the thing you want, you need to create a surface and a canvas. Then
select the surface into the canvas and draw all the tiles there.
Unfortunately, as you noticed yourself, CL_Surface is missing a constructor
that allows you to create an empty surface. You can workaround this by
creating an empty CL_PixelBuffer with the right dimensions, or you can fix
the code and add another constructor.

Post by Thomi Richards
I'm very impressed with ClanLib in general, but the docs *really* need
updating. There are so many classes with little or no documentation...
The output format of the docs are also really strange... For example,
CL_Keyboard::get_keycode() is a static method, but it doesn't say that
in the API reference *anywhere*... You have to guess. Same goes for
CL_Display and CL_Mouse and probably more that I have yet to "guess".

The problem is partly that most devs are currently coding on the ClanLib 0.9
branch, which differs somewhat from how 0.8 worked. For example, the legacy
surface concepts that haunt you above has been removed. Instead the classes
in 0.9 are CL_Texture, CL_TextureGroup, CL_Subtexture, CL_Canvas,
CL_PixelBuffer and CL_Sprite. These fundamental changes make it difficult
for us to want write further documentation for the older 0.8 version,
because for us it would seem deprecated before even published on the
website.

All the missing information in the 0.8 reference documentation is caused by
using an old documentation system called pce2. It was chosen in the days
before doxygen had XML output capabilities and because its filtering model
allowed a very great amount of freedom for formatting the HTML as I wanted
it. The main problems are that it is not really able to parse and
understand all parts of C++ and the filters has to be written in perl. The
long term intention is to move away from pce2 and instead use doxygen to
generate XML descriptions of each class. This is then parsed by a small
utility program called ReferenceDocs, which then currently generates the
following output:

http://esoteric.clanlib.org/~mbn/temp/reftest/modules.html

I never completed this utility, though. It generates a fair amount of the
documentation, but still doesn't parse all the elements made available from
the doxygen XML files.

The 0.8 branch is currently maintained by mrfun and I'm sure he'd welcome
documentation updates for the branch, but personally my focus is 100% on
0.9. If you have any questions about 0.8 I'll gladly answer it, but I'd
rather spend my own limited spare time on getting 0.9 ready for an official
release.

--
Magnus Norddahl

[Thomi Richards]

Thanks for that Magnus,

I sent this email a full 2 days before it got to the mailing list - I
guess sourceforge is having a few problems..

Anyway, i did work out how to do hat I want. I have a few questions
about the 0.9 branch:

1) is it stable / usable?

2) Since it seems that it won't be backwards compatible with 0.8, is
it worth writing new ClanLib applications with 0.8 or 0.9?

3) I assume that 0.9 will have the same level of platform independence as 0.8?

Thanks,

Post by Magnus Norddahl
Hi Thomi,
1. CL_Surface
Represents an image placed in the graphics card memory. The name surface is
a bit misleading, since you do not actually have direct memory access to the
image as you did in DirectDraw. It is currently implemented as a texture in
clanGL.
2. CL_Canvas
Off-screen rendering context. Allows you to use hardware accelerated
rendering methods to draw something to be stored in a surface afterwards.
The 0.8 series implementation is a bid oddly designed since you need to
select a surface into the canvas to permit drawing.
3. CL_PixelBuffer
Image stored in system memory.
4. CL_Sprite
Higher level class that makes it easier to draw a lot of smaller images and
use them in animations.
To do the thing you want, you need to create a surface and a canvas. Then
select the surface into the canvas and draw all the tiles there.
Unfortunately, as you noticed yourself, CL_Surface is missing a constructor
that allows you to create an empty surface. You can workaround this by
creating an empty CL_PixelBuffer with the right dimensions, or you can fix
the code and add another constructor.

Post by Thomi Richards
I'm very impressed with ClanLib in general, but the docs *really* need
updating. There are so many classes with little or no documentation...
The output format of the docs are also really strange... For example,
CL_Keyboard::get_keycode() is a static method, but it doesn't say that
in the API reference *anywhere*... You have to guess. Same goes for
CL_Display and CL_Mouse and probably more that I have yet to "guess".

The problem is partly that most devs are currently coding on the ClanLib 0.9
branch, which differs somewhat from how 0.8 worked. For example, the legacy
surface concepts that haunt you above has been removed. Instead the classes
in 0.9 are CL_Texture, CL_TextureGroup, CL_Subtexture, CL_Canvas,
CL_PixelBuffer and CL_Sprite. These fundamental changes make it difficult
for us to want write further documentation for the older 0.8 version,
because for us it would seem deprecated before even published on the
website.
All the missing information in the 0.8 reference documentation is caused by
using an old documentation system called pce2. It was chosen in the days
before doxygen had XML output capabilities and because its filtering model
allowed a very great amount of freedom for formatting the HTML as I wanted
it. The main problems are that it is not really able to parse and
understand all parts of C++ and the filters has to be written in perl. The
long term intention is to move away from pce2 and instead use doxygen to
generate XML descriptions of each class. This is then parsed by a small
utility program called ReferenceDocs, which then currently generates the
http://esoteric.clanlib.org/~mbn/temp/reftest/modules.html
I never completed this utility, though. It generates a fair amount of the
documentation, but still doesn't parse all the elements made available from
the doxygen XML files.
The 0.8 branch is currently maintained by mrfun and I'm sure he'd welcome
documentation updates for the branch, but personally my focus is 100% on
0.9. If you have any questions about 0.8 I'll gladly answer it, but I'd
rather spend my own limited spare time on getting 0.9 ready for an official
release.
--
Magnus Norddahl
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys -- and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
clanlib-devel mailing list
https://lists.sourceforge.net/lists/listinfo/clanlib-devel

[Magnus Norddahl]

Post by Thomi Richards
Anyway, i did work out how to do hat I want. I have a few questions
1) is it stable / usable?

Mostly, yes. clanApp, clanCore, clanDatabase, clanMikMod, clanNetwork,
clanRegExp, clanSound, clanSqlite and clanVorbis are all working pretty much
as adverticed. The only exception is the net-session classes in network,
which are completely unimplemented - pending for a redesign.

clanDisplay, clanGL and clanGUI are the modules that need most the work.
All three modules have been completely rewritten since 0.8, making the API
more loyal to the way OpenGL and the GPU operates. Essentially the new
display is far more state oriented and attempts to standardize how you
supply vertex data to rendering both 2D and 3D things. It also offers a
more natural relationship between CL_PixelBuffer, CL_Texture, CL_Canvas and
CL_Sprite.

Most of the lower level APIs are complete in clanDisplay/GL, while the
higher level classes (CL_Sprite and such) are not. In clanGUI most of the
component management stuff is complete, but none of the stock components
has been implemented.

Post by Thomi Richards
2) Since it seems that it won't be backwards compatible with 0.8, is
it worth writing new ClanLib applications with 0.8 or 0.9?

This is difficult for me to answer. ClanLib suffers from the same problem
that most framework libraries suffer from. Essentially because they try to
cover a range of different application usages, as opposed to specializing in
a specific purpose, small errors in design can cause huge disadvantages.
Although normal libraries aren't excluded from this, the difference is that
you (as a user) normally can stay on an older design for a long time without
switching to a new one. With a framework library, if you want one of the
new features from clanNetwork, you have to update to the same clanDisplay as
well.

To my knowledge all framework libraries suffer from this. At the place I
work we are still using Qt 3.3, because upgrading to Qt 4 would require us
to completely port all our GUI - code that took us literally years to write.
Even if the better thread handling of QString is a feature we want, we have
to wait with upgrading until the amount of improvements in Qt 4+ can justify
the work required to do the porting. Likewise, if you used the .net
framework 1.0 and tries to move to 2.0, there is a risk you may have to port
a portion of your code.

One of the reasons I've kept 0.9 pretty much "below radar" has been to avoid
people starting to use 0.9 while I still make significant changes to the
API. ClanLib has had many significant changes to the API since the first
versions, mainly because my skills as an API designer and understanding of
base technologies has improved. The changes I've made has been neccessary
to get ClanLib to the place I want it, but I can very well understand why it
has frustrated many people that tried to use it.

The current goal is that the 0.9 branch will become ClanLib 1.0.0 and then
any subsequent 1.x.x releases should avoid breaking API for the users. But
this of course assumes that I will get 0.9 finished one day. :)

Post by Thomi Richards
3) I assume that 0.9 will have the same level of platform independence as 0.8?

Yes, that is the intent. Currently, however, only the WGL clanGL target has
been implemented. Adding support for GLX and AGL is fairly simpel and
straightforward, but I personally find it very difficult to find the
motivation to do it. Eventually I will, unless someone does it for me. :)

--
Magnus Norddahl

[Thomi Richards]

Thanks a lot for youir reply Magnus,

I'm very keen to help out in any way I can. Unfortunately, I'm not sure how
much use I can be; I don't know OpenGL, or the internals of ClanLib at all.

I'm developing in a Linux environment, so if you need compile tests under
Linux I could do that.. My english is reasonably good, so I could write
documentation.. I also teach web design / construction. If you want I could
start working on a prototype website for you...

Please let me know what you need, and I'll get on to it as soon as possible.


As far as my application is concerned, I think I'll stick with 0.8
until 0.9becomes more complete - I need the OpenGL / DIsplay things
anyway.


Please let me know what i can do to help out..

Thanks,

Post by Magnus Norddahl

Post by Thomi Richards
Anyway, i did work out how to do hat I want. I have a few questions
1) is it stable / usable?

Mostly, yes. clanApp, clanCore, clanDatabase, clanMikMod, clanNetwork,
clanRegExp, clanSound, clanSqlite and clanVorbis are all working pretty much
as adverticed. The only exception is the net-session classes in network,
which are completely unimplemented - pending for a redesign.
clanDisplay, clanGL and clanGUI are the modules that need most the work.
All three modules have been completely rewritten since 0.8, making the API
more loyal to the way OpenGL and the GPU operates. Essentially the new
display is far more state oriented and attempts to standardize how you
supply vertex data to rendering both 2D and 3D things. It also offers a
more natural relationship between CL_PixelBuffer, CL_Texture, CL_Canvas and
CL_Sprite.
Most of the lower level APIs are complete in clanDisplay/GL, while the
higher level classes (CL_Sprite and such) are not. In clanGUI most of the
component management stuff is complete, but none of the stock components
has been implemented.

Post by Thomi Richards
2) Since it seems that it won't be backwards compatible with 0.8, is
it worth writing new ClanLib applications with 0.8 or 0.9?

This is difficult for me to answer. ClanLib suffers from the same problem
that most framework libraries suffer from. Essentially because they try to
cover a range of different application usages, as opposed to specializing in
a specific purpose, small errors in design can cause huge disadvantages.
Although normal libraries aren't excluded from this, the difference is that
you (as a user) normally can stay on an older design for a long time without
switching to a new one. With a framework library, if you want one of the
new features from clanNetwork, you have to update to the same clanDisplay as
well.
To my knowledge all framework libraries suffer from this. At the place I
work we are still using Qt 3.3, because upgrading to Qt 4 would require us
to completely port all our GUI - code that took us literally years to write.
Even if the better thread handling of QString is a feature we want, we have
to wait with upgrading until the amount of improvements in Qt 4+ can justify
the work required to do the porting. Likewise, if you used the .net
framework 1.0 and tries to move to 2.0, there is a risk you may have to port
a portion of your code.
One of the reasons I've kept 0.9 pretty much "below radar" has been to avoid
people starting to use 0.9 while I still make significant changes to the
API. ClanLib has had many significant changes to the API since the first
versions, mainly because my skills as an API designer and understanding of
base technologies has improved. The changes I've made has been neccessary
to get ClanLib to the place I want it, but I can very well understand why it
has frustrated many people that tried to use it.
The current goal is that the 0.9 branch will become ClanLib 1.0.0 and then
any subsequent 1.x.x releases should avoid breaking API for the users. But
this of course assumes that I will get 0.9 finished one day. :)

Post by Thomi Richards
3) I assume that 0.9 will have the same level of platform independence

as 0.8?
Yes, that is the intent. Currently, however, only the WGL clanGL target has
been implemented. Adding support for GLX and AGL is fairly simpel and
straightforward, but I personally find it very difficult to find the
motivation to do it. Eventually I will, unless someone does it for me. :)
--
Magnus Norddahl
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys -- and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
clanlib-devel mailing list
https://lists.sourceforge.net/lists/listinfo/clanlib-devel

[Magnus Norddahl]

Post by Thomi Richards
Thanks a lot for youir reply Magnus,
I'm very keen to help out in any way I can. Unfortunately, I'm not sure how
much use I can be; I don't know OpenGL, or the internals of ClanLib at all.
I'm developing in a Linux environment, so if you need compile tests under
Linux I could do that.. My english is reasonably good, so I could write
documentation.. I also teach web design / construction. If you want I could
start working on a prototype website for you...

I guess getting the website shined up wouldn't be that bad. Adding
documentation for 0.9 would be really nice, but some of the things may still
be bit too incomplete for you to write it. Especially the fact that you use
Linux and the GLX support missing is bit of a show stopper. :)

--
Magnus Norddahl

[Thomi Richards]

Well, here's what I'll do:

I'll start designing / creating a new website for you.. I'll host it myself.
If you like it, we can talk about replacing the old clanlib website..

I'm assuming that there are no features you really really want in a website
that aren't already implemented in the current clanlib site?


Thanks,

Post by Thomi Richards

Post by Thomi Richards
Thanks a lot for youir reply Magnus,
I'm very keen to help out in any way I can. Unfortunately, I'm not

sure how

Post by Thomi Richards
much use I can be; I don't know OpenGL, or the internals of ClanLib

at all.

Post by Thomi Richards
I'm developing in a Linux environment, so if you need compile tests

under

Post by Thomi Richards
Linux I could do that.. My english is reasonably good, so I could

write

Post by Thomi Richards
documentation.. I also teach web design / construction. If you want I

could

Post by Thomi Richards
start working on a prototype website for you...

I guess getting the website shined up wouldn't be that bad. Adding
documentation for 0.9 would be really nice, but some of the things may still
be bit too incomplete for you to write it. Especially the fact that you use
Linux and the GLX support missing is bit of a show stopper. :)
--
Magnus Norddahl

[Magnus Norddahl]

Post by Thomi Richards
I'll start designing / creating a new website for you.. I'll host it myself.
If you like it, we can talk about replacing the old clanlib website..
I'm assuming that there are no features you really really want in a website
that aren't already implemented in the current clanlib site?

Just a build and release automation site. :D

--
Magnus Norddahl

[Thomi Richards]

We'll see about that...

Post by Thomi Richards

Post by Thomi Richards
I'll start designing / creating a new website for you.. I'll host it

myself.

Post by Thomi Richards
If you like it, we can talk about replacing the old clanlib website..
I'm assuming that there are no features you really really want in a

website

Post by Thomi Richards
that aren't already implemented in the current clanlib site?

Just a build and release automation site. :D
--
Magnus Norddahl
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys -- and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
clanlib-devel mailing list
https://lists.sourceforge.net/lists/listinfo/clanlib-devel

[Thomi Richards]

Another quick question: are you guys really passionate about keeping
the current clanlib title logo / graphics? Is it worth me trying to
come up with something better?

I'd enjoy doing it, but if you're really keen on keeping the current
graphics I won;t bother..


Thanks,

Post by Thomi Richards
We'll see about that...

Post by Magnus Norddahl

Post by Thomi Richards
I'll start designing / creating a new website for you.. I'll host it

myself.

Post by Magnus Norddahl

Post by Thomi Richards
If you like it, we can talk about replacing the old clanlib website..
I'm assuming that there are no features you really really want in a

website

Post by Magnus Norddahl

Post by Thomi Richards
that aren't already implemented in the current clanlib site?

Just a build and release automation site. :D
--
Magnus Norddahl

-------------------------------------------------------------------------

Post by Magnus Norddahl
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share

your

Post by Magnus Norddahl
opinions on IT & business topics through brief surveys -- and earn cash

http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV

Post by Magnus Norddahl
_______________________________________________
clanlib-devel mailing list

https://lists.sourceforge.net/lists/listinfo/clanlib-devel

[Magnus Norddahl]

Post by Thomi Richards
Another quick question: are you guys really passionate about keeping
the current clanlib title logo / graphics? Is it worth me trying to
come up with something better?
I'd enjoy doing it, but if you're really keen on keeping the current
graphics I won;t bother..

You are welcome to make a new logo. :)

--
Magnus Norddahl

[Ben Chambers]

Post by Magnus Norddahl
The current goal is that the 0.9 branch will become ClanLib 1.0.0 and then
any subsequent 1.x.x releases should avoid breaking API for the users. But
this of course assumes that I will get 0.9 finished one day. :)

In fact, I'd love it if you could put out an announcement of when the
API for 0.9 is reasonably stable. I'd love to work on it myself, but I
don't have the time to put into something that's going to change
completely in a few weeks anyway. When the API is stable, then I could
help filling in the implementations.

...Chambers

[Magnus Norddahl]

Post by Ben Chambers
In fact, I'd love it if you could put out an announcement of when the
API for 0.9 is reasonably stable. I'd love to work on it myself, but I
don't have the time to put into something that's going to change
completely in a few weeks anyway. When the API is stable, then I could
help filling in the implementations.

I'll do that. :)

--
Magnus Norddahl

[Jonathan Royalty]

Post by Magnus Norddahl
To do the thing you want, you need to create a surface and a canvas. Then
select the surface into the canvas and draw all the tiles there.
Unfortunately, as you noticed yourself, CL_Surface is missing a constructor
that allows you to create an empty surface. You can workaround this by
creating an empty CL_PixelBuffer with the right dimensions, or you can fix
the code and add another constructor.

I have tried to do this myself, but the data I put onto the canvas after
was corrupt (Take a square, and divide it into 10 sections. Take every
third section and shift it left by a width of the square. Take every
second third section and shift it right by twice the width of the
square. That's the image I saw). Is there some trick to creating the
CL_PixelBuffer or CL_Canvas to ensure compatability?

[Thomi Richards]

I don't know about that kind of data corruption, but I had other problems....

I could draw other surfaces to my canvas, but as soon as I wanted to
use any of the draw_* methods of the canvas's graphics context the
following happened:

1) First time through the render loop everything worked perfectly.
2) second time through the render loop the entire canvas was filled with white.

I tested this with mrfun, and it appears to only happen on my system
(Kubuntu dapper, running custom 2.6.12 kernel with an nVidia Geforce4
MX440). I made a few tests in case anyone's interested:

This is a small test app that displays a screen of pure white:
http://www.rafb.net/paste/results/D03De239.html

If you step through that application you'll see that everything works
perfectly on the first loop, but breaks on the second. UNLESS you
re-create the surface and the canvas for every render loop:
http://www.rafb.net/paste/results/vBh3g150.html

Anyway, I fixed the problem by avoiding it. It would be really nice to
be able to use the canvas & surface functions properly however....


Thanks,

Post by Jonathan Royalty

Post by Magnus Norddahl
To do the thing you want, you need to create a surface and a canvas. Then
select the surface into the canvas and draw all the tiles there.
Unfortunately, as you noticed yourself, CL_Surface is missing a constructor
that allows you to create an empty surface. You can workaround this by
creating an empty CL_PixelBuffer with the right dimensions, or you can fix
the code and add another constructor.

I have tried to do this myself, but the data I put onto the canvas after
was corrupt (Take a square, and divide it into 10 sections. Take every
third section and shift it left by a width of the square. Take every
second third section and shift it right by twice the width of the
square. That's the image I saw). Is there some trick to creating the
CL_PixelBuffer or CL_Canvas to ensure compatability?
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys -- and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
clanlib-devel mailing list
https://lists.sourceforge.net/lists/listinfo/clanlib-devel