ClanLib Surface/Sprite Cleanup RFC
==================================

This RFC will address some problems with the current Sprite and
Surface infrastructure and will provide some ways to make them more
flexible and more powerfull.
  

Inconsistency in the Resource Handling:
=======================================
Surfaces resources are declared via:

 <surface file="../images/core/editor/weather_rain.png" name="weather_rain" />

While sprites are declared via:
     
 <sprite name="light">
   <image file="images/light.png" />
   <translation origin="bottom_center" />
 </sprite>

You see that one time 'surface' tag is used and another time the
'image' tag, while really they have the same purpose. This
inconsistency doesn't have much of a reason and I don't consider it
necessary. So I propose simple:

 <sprite name="light">
   <surface file="images/light.png" />
   <translation origin="bottom_center" />
 </sprite>

as a solution.


Filter Support:
===============

In games it is often usefull to manipulate graphics to form new
graphics at runtime, be it simple things like merging two images to
add a player-color to a sprite or bluring or coloring effects to add
some athmosphere, adding a custom text to some image or simple things
like rotating or mirroring graphics. Currently ClanLib doesn't provide
any way help of doing these things. I propose to add a system of
filters to ClanLib which should address this problem.

A filter would be a little function that takes a CL_PixelBuffer and/or
additional arguments and returns a new CL_PixelBuffer, a simple filter
could look like:

CL_PixelBuffer blur_filter(CL_PixelBuffer buffer) 
{
  ...
  // blur the image
  ...
  return new_buffer;
}

Filters could also take multilpe arguments to combine images such as:

CL_PixelBuffer blit_filter(CL_PixelBuffer target, CL_PixelBuffer source, x, y) 

which would blit the given 'source' image onto the 'target' one.

Filters should both be able to be used at runtime and via the resource
mechanism, ie. after registering a filter one should be able to use it
like:

 <surface name="foobar">
   <blur-filter>
      <value>50</value>
       <surface file="images/button.png" />
   </blur-filter>
 </surface>

 <surface name="foobar">
   <blit-filter>
     <x>5</x>
     <y>10</y>
     <surface file="images/background.png" />
     <surface file="images/button.png" />
   <blit-filter>
 </surface>

Filtered surfaces should be useable like normal ones, ie. they should
be addable to CL_Sprite and the like.


Pixelbuffer vs. Surface
========================

The filter system above might already solve this problem, however I am
not so sure on this issue, ie. currently CL_PixelBuffer and CL_Surface
are quite seperate, one cannot draw a CL_Surface to a pixelbuffer or
visa verse. For OpenGL this should be ok, since the hardware doesn't
allow it in a fast way, but for the SDL target, where CL_Surfaces are
often completly keep in system memory, this limitation is quite
anoying, since it 'steals' a lot of freedom which one would have when
using raw SDL. In addition to the filter system described above a
simple and non-memory copying way to convert a CL_Surface to a
CL_PixelBuffer and the other way around might help for the SDL target.

Surface is not abstruct
=======================

CL_Surface currently doesn't allow to inherit from it easily, this
restricts its use in several places quite a bit. Neither sprite nor
the GUI can take custom drawing commands via CL_Surface, so everything
that is not expressable via a pixel-image that can be loaded into a
CL_Surface won't be combinable with functions that are applied to a
CL_Surface. I propose to move CL_Surface_Generic into the API space,
so that the user can inherit from it, add the resulting object into a
CL_Surface and use that in places where a normal CL_Surface would be
used.

# EOF #