|
*** very useful
A very useful and easy to use function.
The function returns a handle to a polygon which is the created layer.
After calling this function the created layer is immediately visible.
(no need to call STATE_engine_add_polygon() )
Using STATE_layer_create() one can easily create a square polygon
with a bitmap on it. The first four parameters define the layer size and position.
No matter what is the size of the window which you render on the
top left corner is always 0,0 and the bottom right corner is 100,100
For example if the four numbers 0,0,50,100 are given as the first 4 parameters
then the layer will occupied the half left of the rendered screen
If there are two or more polygon layers that overlap then the one which was
first created will be on top. Use STATE_layer_set_depth()to control the order and the depth in which the
layer are rendered.
Return value
The function returns a handle to a polygon which is used for the layer.
Parameters:
left_x, top_y:
The top left corner of the created layer.
Any number in range [0-100]. (0,0) is the top left corner
while (100,100) is the bottom right corner
right_x, bottom_y:
The bottom right corner of the created layer.
Any number in range [0-100]. (0,0) is the top left corner
while (100,100) is the bottom right corner
Note that after the a layer is created it is possible
to change/move the points using the Polygon and Point APIs
one can also call STATE_layer_set_shape() to change the shape of
the layer
bitmap_handle: A handle to a bitmap that will be used.
Give NULL if your layer will use color fill.
Note that after the layer is created, one can use STATE_polygon_set_bitmap_fill()
to change the bitmap.
glass_type:
Using this parameter one can determine if the layer will be
opaque or translucent. Use any of the values possible with
the STATE_polygon_set_translucent() function.
To precisely control the level of translucency
call STATE_polygon_set_light(layer_handle, translucent_level_rgb);
Remarks:
--------
A very convenient way to work with layer polygons is
to create them all at the beginning of the program and then to disable those
which should not be visible right away.
Then during the program run, enable layer polygons according to the need.
There is no time penalty for having many layer polygons which are disabled
Only those which are drawn consume time. Layers are very fast to draw since
they exploit the 3D card hardware. The time it takes to draw a layer
depends on its size. If the layer covers the whole rendering window\fullscreen
then the slowdown in FPS might be measurable.
Examples:
Example 1:
Creating a layer on the whole window
DWORD my_bitmap=STATE_bitmap_load("binocular", -1);
if(my_bitmap==NULL) return(VR_ERROR);
DWORD layer_polygon=STATE_layer_create(0,0, 100, 100, my_bitmap, FILTER_GLASS);
After the next render the layer will be shown on the screen
Example 2:
A more advanced example which show how to make a message
appearing on the screen and then fading away and disappearing.
This message could be something like "1000 points bonus"
"Extra life" etc. This example is quite important since once
you will understand it you will be able to create many more nice effects
that have nothing to do with layers.
The following example is comprised of 3 functions that together
create the mechanism.
Call this function at the beginning of the program
DWORD create_message_layer(void)
{
DWORD my_bitmap=STATE_bitmap_load("ExtraLife", -1);
if(my_bitmap==NULL) return(NULL);
Note that we have chosen LIGHT_SOURCE_GLASS below since
this type of blending will do 'add' between the layer_message polygon and the
rendered world below (new_pixel=src+dest). We need this adding for
doing the fade away effect. We will make the message_layer_polygon
darker and darker till it wont be seen (new_pixel= 0 + dest == dest)
DWORD message_layer_polygon=STATE_layer_create(20,15, 80,30, my_bitmap, LIGHT_SOURCE_GLASS);
if(message_layer_polygon==NULL) return(NULL);
disable the polygon since we dont want it to be seen now
STATE_polygon_disable(message_layer_polygon);
m_is_message_visible=NO; remember the status of the message in a global\class member variable.
return(message_layer_polygon);
}
Call this function when the message should be seen
void make_message_visible(DWORD message_polygon)
{
STATE_polygon_enable(message_polygon);
BYTE rgb[3]={255,255,255);
Show the message in full visibility
STATE_polygon_set_light(message_polygon, rgb); Set the rgb of all the points to 255,255,255
m_is_message_visible=YES;
}
Call this function before each render
void make_message_fade_away(DWORD message_polygon)
{
if(m_is_message_visible==NO) return; If the message is not visible then there is nothing to do
All the points have the same rgb so lets check the first one
DWORD point=STATE_polygon_get_first_point(message_polygon);
BYTE rgb[3];
STATE_point_get_rgb(point, rgb);
if(rgb[0]==0) {
STATE_polygon_disable(message_layer_polygon);
m_is_message_visible=NO;
return;
}
Reducing the rgb will make the message darker and because we use LIGHT_SOURCE_GLASS
The result will be fading away
rgb[0]--;
rgb[1]--;
rgb[2]--;
STATE_polygon_set_light(message_layer_polygon, rgb); Set the rgb of all the points of the polygon
}
|