include/neuro/graphics.h

   1
   2 /*
   3  * libneuro, a light weight abstraction of high or lower libraries
   4  * and toolkit for applications.
   5  * Copyright (C) 2005-2006  Nicholas Niro, Robert Lemay
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  20  */
  21
  22 /*! \file graphics.h
  23  * \brief graphics engine header
  24  *
  25  * The graphic engine is part of the most important engines in a game.
  26  * It provides function to draw images on the screen.
  27  */
  28
  29 #ifndef __GRAPHICS_H
  30 #define __GRAPHICS_H
  31
  32 #include "neuro_engine.h"
  33 #include "other.h"
  34
  35 #include <stdlib.h>
  36
  37 /*! default : 60
  38  * the maximum amount of frames per seconds -deprecated-
  39  */
  40 #define FRAMES_PER_SECOND 60
  41
  42 /*! default : 2
  43  * how many time the computer has to check
  44  * out which one of the image has the lowest
  45  * layer(to be placed in the instruction
  46  * buffer).
  47  */
  48 #define LAYER_CHECK_PER_FRAMES 2
  49
  50 /*! The Total screen width (can be changed before compile time to set the new size) */
  51 #define SCREEN_X 800
  52 /*! The Total screen height (can be changed before compile time to set the new size) */
  53 #define SCREEN_Y 600
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 typedef struct INSTRUCTION_ENGINE INSTRUCTION_ENGINE;
  60
  61 typedef INSTRUCTION_ENGINE v_elem;
  62
  63 /** Neuro_GetScreenBuffer - returns the variable containing the screen buffer.
  64  */
  65 extern void *Neuro_GetScreenBuffer();
  66
  67 /** Neuro_PushStaticDraw
  68  * @sdecri
  69  * Add a static drawing instruction to the gfx loop.
  70  *
  71  * @param[in]
  72  * layer the drawing order by which the frame needs to be drawn on screen
  73  *
  74  * @param[in]
  75  * src the image rectangle to draw (to select different parts of a single image)
  76  *
  77  * @param[in]
  78  * dst the coordinate where the image must be drawn to.
  79  *
  80  * @param[in]
  81  * surface the pointer to the image itself.
  82  *
  83  * @description
  84  * Add a Static Drawing Instruction to the graphics loop. This function will
  85  * put take the image, place it in a special buffer and then draw the image
  86  * with the desired draw time(in comparison with other to draw images : layer) and
  87  * place it on the screen depending on the given coordinates (also draws the portion
  88  * of the image that you set). This function is in general meant to be inside a function
  89  * that has a pointer callback set in Neuro_AddDrawingElement().
  90  *
  91  * @related
  92  * Neuro_PushDynamicDraw(3), Neuro_PushDraw(3)
  93  *
  94  */
  95 extern void Neuro_PushStaticDraw(u32 layer, Rectan *src, Rectan *dst, void *surface);
  96
  97 /*! Add a Dynamic Drawing Instruction to the graphics loop. This function will
  98  * put take the image, place it in a special buffer and then draw the image
  99  * with the desired draw time(in comparison with other to draw images : layer) and
 100  * place it on the screen depending on the given coordinates (also draws the portion
 101  * of the image that you set). This function is in general meant to be inside a function
 102  * that has a pointer callback set in Neuro_AddDrawingElement().
 103  * @param [in] layer the drawing order by which the frame needs to be drawn on screen
 104  * @param [in] src the image rectangle to draw (to select different parts of a single image)
 105  * @param [in] dst the coordinate where the image must be drawn to.
 106  * @param [in] surface the pointer to the image itself.
 107  */
 108 extern void Neuro_PushDynamicDraw(u32 layer, Rectan *src, Rectan *dst, void *surface);
 109
 110 /* push a drawing instruction that will be deleted from the queue and raw
 111  * after being drawn. This replaces the hackish override method with an
 112  * ultra versatile one and much less costy ;P.
 113  * same use as with the Dynamic and Static
 114  * functions above.
 115  */
 116 extern void Neuro_PushVolatileDraw(u32 layer, Rectan *isrc, Rectan *idst, v_object *isurface);
 117
 118 /* this is the new generation of the drawing push functions, this will
 119  * replace completely the current drawing system method if it presents
 120  * better performances than the old (dynamic, static and volatile) system.
 121  *
 122  * the "older" system is however kept for backward compatibility and this
 123  * function uses the same algorithm so it would be unwise to remove the
 124  * other functions.
 125  */
 126 extern v_elem *Neuro_PushDraw(u32 layer, Rectan *isrc, Rectan *idst, v_object *isurface);
 127
 128 /* outputs all the core informations about an image element
 129  * in the buffer.
 130  *
 131  * psrc the rectangle position of the source image.
 132  * px the X axis position of the image on the screen.
 133  * py the Y axis position of the image on the screen.
 134  * osurface outputs the pointer of the image.
 135  *
 136  * returns 0 if all is ok and 1 on error
 137  */
 138 extern int Neuro_FetchDraw(v_elem *eng, Rectan *psrc, u16 *px, u16 *py, v_object **osurface);
 139
 140 /* TODO */
 141 extern int Neuro_SetImgPos(v_elem *eng, u16 px, u16 py);
 142
 143 /* TODO */
 144 extern int Neuro_SetImgSrcPos(v_elem *eng, Rectan *psrc);
 145
 146
 147 /* this function's sole purpose is the input of a new surface for the
 148  * element.
 149  */
 150 extern int Neuro_SetDraw(v_elem *eng, v_object *isurface);
 151
 152 /* cleans the drawn element on screen so it is no longer visible, this
 153  * action should be taken before touching the element's source
 154  * or destination variables or else undesirable trails will subsist
 155  * because no buffer is kept for the coordinates to clean.
 156  */
 157 extern int Neuro_CleanDraw(v_elem *eng);
 158
 159 /* set the layer of a drawn element. */
 160 extern int Neuro_SetImgLayer(v_elem *eng, u32 layer);
 161
 162
 163 /* tags the element to be redrawn by the engine, without this functions,
 164  * changes made with the Neuro_FetchDraw function would not be applied to
 165  * the element.
 166  */
 167 extern int Neuro_FlushDraw(v_elem *eng);
 168
 169 /* destroys the element */
 170 extern int Neuro_DestroyDraw(v_elem *eng);
 171
 172 /*! This function is used to add a callback function in a buffer. This buffer is looped and
 173  * the callback functions(which are added using this function) are ran one by one every cycles.
 174  * @param [in] func this is the callback function that the graphics engine will loop and
 175  * run every cycles
 176  */
 177 extern void Neuro_AddDrawingElement(void (*func)());
 178
 179 /* directly draw a surface on the screen without
 180  * the layering feature and without the cleaning feature either (no feature actually :) ).
 181  */
 182 extern void Neuro_AddDirectDrawing(Rectan *src, Rectan *dst, void *surface);
 183
 184 /** use this function to set the background
 185  * @param [in] the pointer to an image.
 186  */
 187 extern void Neuro_AddBackground(void *isurface);
 188
 189 /* refreshes the screen nicely also support backgrounds */
 190 extern void Neuro_RefreshScreen();
 191
 192 /* tells neuro to redraw the screen
 193  * might not work if the screen is not
 194  * buffered but it could work anyway.
 195  */
 196 extern void Neuro_RedrawScreen();
 197
 198 /*! give the current fps */
 199 extern void Neuro_GiveFPS(t_tick *output);
 200
 201 /* the u32 pointers will be given the current screen size in pixels */
 202 extern void Neuro_GiveScreenSize(u32 *width, u32 *height);
 203
 204 /* draw a pixel on the screen */
 205 extern void Neuro_PutPixel(v_object *vobj, u32 x, u32 y, u32 pixel);
 206
 207 /* get the color of a pixel on the screen */
 208 extern u32 Neuro_GetPixel(v_object *vobj, u32 x, u32 y);
 209
 210 /* clean all the pixels that were drawn using the handled pixel drawer in this module */
 211 extern void Neuro_CleanPixels();
 212
 213 /*! internal use Initialisation of the Graphics Engine */
 214 extern int Graphics_Init(void);
 215 /*! Poll of the Graphics Engine */
 216 extern void Graphics_Poll(void);
 217 /*! Cleaning of the Graphics Engine */
 218 extern void Graphics_Clean(void);
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* __GRAPHICS_H */