even more refractoring and documentation

bpre.sym

 memcpy = 0x081E5E78|1;
 obj_template_instanciate_forward_search = 0x08006F8D;
 gpu_copy_to_vram_by_bgid = 0x08001298|1;
-bg_set_tilemap = 0x08001FA0|1;
-bg_nullify_tilemap = 0x08001FD4|1;
-bg_get_tilemap = 0x08002008|1;
-bg_send_tilemap = 0x080020BC|1;
+virtual_bg_set_tilemap = 0x08001FA0|1;
+virtual_bg_nullify_tilemap = 0x08001FD4|1;
+virtual_bg_get_tilemap = 0x08002008|1;
+virtual_bg_send_tilemap = 0x080020BC|1;
 gpu_init_bgs = 0x08001028|1;
 gpu_tile_bg_drop_all_sets = 0x08001618|1;
-bg_vram_setup = 0x08001658|1;
+gpu_bg_vram_setup = 0x08001658|1;
 gpu_bg_show = 0x08001320|1;
 gpu_bg_hide = 0x0800139C|1;
 gpu_sync_bg_visibility_and_mode = 0x080013D0|1;
 objc_exec = 0x08006B5D;
 obj_sync = 0x08006BA9;
 
-clear_flag = 0x0806E6A9;
+flag_clear = 0x0806E6A9;
 
 divide = 0x081E4018;
 
 party_player = 0x02024284;
 party_opponent = 0x0202402C;
 
-get_attributes = 0x0803FBE8|1;
-set_attributes = 0x0804037C|1;
+pokemon_get_attribute = 0x0803FBE8|1;
+pokemon_set_attribute = 0x0804037C|1;
 
 
 battle_status3_bits_pbs = 0x02023DFC;

nbproject/configurations.xml

           <in>battle_test.h</in>
           <in>debug.h</in>
           <in>dns_core.h</in>
+          <in>game_engine.h</in>
           <in>item_effects.h</in>
           <in>items.h</in>
+          <in>math.h</in>
           <in>memory.h</in>
           <in>oe_animation.h</in>
           <in>pkmn_attributes.h</in>
       </item>
       <item path="src/include/dns_core.h" ex="false" tool="3" flavor2="0">
       </item>
+      <item path="src/include/game_engine.h" ex="false" tool="3" flavor2="0">
+      </item>
       <item path="src/include/item_effects.h" ex="false" tool="3" flavor2="0">
       </item>
       <item path="src/include/items.h" ex="false" tool="3" flavor2="0">
       </item>
+      <item path="src/include/math.h" ex="false" tool="3" flavor2="0">
+      </item>
       <item path="src/include/memory.h" ex="false" tool="3" flavor2="0">
       </item>
       <item path="src/include/oe_animation.h" ex="false" tool="3" flavor2="0">

nbproject/private/configurations.xml

           <in>debug.h</in>
           <in>dns_core.h</in>
           <in>fade.h</in>
+          <in>game_engine.h</in>
           <in>item_effects.h</in>
           <in>items.h</in>
           <in>lcd.h</in>
+          <in>math.h</in>
           <in>memory.h</in>
           <in>moves.h</in>
           <in>objects.h</in>

src/battle_engine/battle_help.c

     u8 usable_pokes = 0;
     for (u8 i = 0; i < 6; i ++)
     {
-        if (get_attributes(&poke[i], ATTR_CURRENT_HP, 0) != 0 && get_attributes(&poke[i], ATTR_IS_EGG, 0) != 1 && get_attributes(&poke[i], ATTR_SPECIES, 0) != 0)
+        if (pokemon_get_attribute(&poke[i], ATTR_CURRENT_HP, 0) != 0 && pokemon_get_attribute(&poke[i], ATTR_IS_EGG, 0) != 1 && pokemon_get_attribute(&poke[i], ATTR_SPECIES, 0) != 0)
             usable_pokes++;
     }
     return usable_pokes;

src/debug/debug.c

         gpu_tile_bg_drop_all_sets(2);
         gpu_tile_bg_drop_all_sets(3);
 
-        bg_vram_setup(0, standard_bg, 4);
+        gpu_bg_vram_setup(0, standard_bg, 4);
 
         gpu_bg_show(0);
         gpu_bg_show(1);

src/include/bpre.h

 #include <pkmn_attributes.h>
 #include <battle_structs.h>
 
-u32 __aeabi_uidivmod(u32 a, u32 b);
-u16 *var_access(int index);
-u8 flag_check(int flag);
-void clear_flag(u16 flag);
-u16 random();
-void* malloc(int size);
-void free(void* address);
-void* memcpy (void * destination, const void* source, size_t num);
-void* memset (void* dst, int value, size_t size);
-
 //debug
 /*void agbprintf(const char* pBuf, ...);
 void agbprint_flush();
 
 
 //attribute setter and getter
-u8 get_attributes(struct pokemon* poke_address, u8 request, void* destination);
-void set_attributes(struct pokemon* poke_address, u8 request, void* new_value);
+
 
 #endif

src/include/game_engine.h

+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
+/**
+ * @file game_engine.h
+ * @author Sturmvogel
+ * @date 15 dec 2016
+ * @brief Game Environment
+ * 
+ * This header file contains methods to interact with the game environment,
+ * misc. functions i.e. access to flags / variables and (encrypted) pokémon
+ * data.
+ */
+
+#ifndef GAME_ENGINE_H
+#define GAME_ENGINE_H
+
+/* === INCLUDE === */
+#include <types.h>
+
+/* === EXTERN METHODS === */
+
+/**
+ * @brief get pointer of var
+ * @param index variable to access
+ * @return pointer to given variable storage
+ */
+extern u16 *var_access(u32 index);
+
+/**
+ * @brief checks if flag is set
+ * @param flag index of flag to check
+ * @return flag status (bool)
+ */
+extern u8 flag_check(u32 flag);
+
+/**
+ * @brief clears a flag
+ * @param flag flag index to clear
+ */
+extern void flag_clear(u16 flag);
+
+/**
+ * @brief gets attribute of pokémon
+ * @param poke_address address to pokémon structure
+ * @param request request from the attribute request table
+ * @param destination destination to write to (if not returned directly)
+ * @return requested value (if not too big)
+ */
+extern u32 pokemon_get_attribute(struct pokemon* poke_address, u8 request, void* destination);
+
+/**
+ * @brief sets attribute of pokémon
+ * @param poke_address address to pokémon structure
+ * @param request request from the attribute request table
+ * @param new_value pointer to new value
+ */
+void pokemon_set_attribute(struct pokemon* poke_address, u8 request, void* new_value);
+
+#endif /* GAME_ENGINE_H */
+

src/include/lcd.h

+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
+/**
+ * @file lcd.h
+ * @author Sturmvogel
+ * @date 15 dec 2016
+ * @brief Operations on the GBA Screen
+ * 
+ * This header contains methods to manipulate and update the lcd screen,
+ * for interacting with the object entity engine
+ * @see objects.h
+ */
+
+
 #ifndef LCD_H_
 #define LCD_H_
 
-#include "objects.h"
+/* === STRUCTURES === */
 
 struct bg_config {
     u32 id : 2;
     u16 b : 5;
 };
 
+/* === STATIC STRUCTURES === */
+
 static struct bg_config standard_bg[4] = {
     {0, 0, 0x19, 0, 0, 0},
     {1, 1, 0x1A, 0, 0, 1},
     {3, 3, 0x1C, 0, 0, 3}
 };
 
-u8 gpu_copy_to_vram_by_bgid(u8 bg_id, void* source, u16 byte_size, u16 start_tile, u8 mode);
-void gpu_init_bgs();
-void gpu_tile_bg_drop_all_sets(u8 bg);
-void bg_vram_setup(u8 mirror, struct bg_config* configs, u8 count);
-void bg_set_tilemap(u8 bg_id, void* tilemap);
-void bg_nullify_tilemap(u8 bg_id);
-void* bg_get_tilemap(u8 bg_id);
-void bg_send_tilemap(u8 bg_id);
-void wram_decompress(void* src, void* dst);
-void vram_decompress(void* src, void* dst);
+/* === EXTERN METHODS === */
+
+/**
+ * @brief copy tileset or tilemap to bg
+ * @param bg_id bg id to copy tileset to
+ * @param source tileset source
+ * @param byte_size tileset size
+ * @param start_tile start tile to copy to
+ * @param mode 1 = copy tileset 2 = copy tilemap
+ * @return 
+ */
+extern u8 gpu_copy_to_vram_by_bgid(u8 bg_id, void* source, u16 byte_size, u16 start_tile, u8 mode);
+
+/**
+ * @brief reset bg configs and init bgs
+ */
+extern void gpu_init_bgs();
+
+/**
+ * @brief drop all tilesets from bg ( ? )
+ * @param bg background to drop tilesets from
+ */
+extern void gpu_tile_bg_drop_all_sets(u8 bg);
+
+/**
+ * @setup bg vram
+ * @param mirror not so sure about that
+ * @param configs pointer to config array (4 entries)
+ * @param count number of entries
+ */
+extern void gpu_bg_vram_setup(u8 mirror, struct bg_config* configs, u8 count);
+
+/**
+ * @brief set tilemap of bg in the bg structure
+ * @param bg_id bg to set tilemap for
+ * @param tilemap pointer to tilemap
+ */
+extern void virtual_bg_set_tilemap(u8 bg_id, void* tilemap);
+
+/**
+ * @brief set tilemap of bg to NULL in bg structure
+ * @param bg_id bg to set tilemap for
+ */
+extern void virtual_bg_nullify_tilemap(u8 bg_id);
+
+/**
+ * @brief get tilemap of bg in bg structure
+ * @param bg_id bg to get tilemap for
+ * @return pointer to tilemap, might be null
+ */
+extern void* virtual_bg_get_tilemap(u8 bg_id);
+
+/**
+ * @brief sends virtual tilemap to vram
+ * @param bg_id bg id to send tilemap for
+ */
+extern void virtual_bg_send_tilemap(u8 bg_id);
+
+
+/**
+ * @brief decompress palette and copy to f/u buffers
+ * @param src palette source (lz compressed)
+ * @param start palette start (in bytes)
+ * @param end palette count (in entries, I think)
+ */
 void pal_decompress_slice_to_faded_and_unfaded(void* src, u16 start, u16 end);
+
+/**
+ * @brief show bg
+ * @param id bg id
+ */
 void gpu_bg_show(u8 id);
+
+/**
+ * @brief hide bg
+ * @param id bg id
+ */
 void gpu_bg_hide(u8 id);
+
+/**
+ * @brief sync bg visibility and mode, execute during vblank to avoid artifacts
+ */
 void gpu_sync_bg_visibility_and_mode();
+
+/**
+ * @brief set I/O
+ * @param id device ID
+ * @param value value to set I/O device to
+ */
 void lcd_io_set_func(u8 id, u16 value);
+
+/**
+ * @brief upload palettes from buffer to palette memory
+ */
 void gpu_pal_upload();
+
+/**
+ * @brief free pal tag
+ * @param tag tag to free
+ */
 void gpu_pal_free_by_tag(u16 tag);
 
+/**
+ * @brief get from I/O
+ * @param id device ID
+ * @return I/O value
+ */
 u16 lcd_io_get(u8 id);
 
+/* === MACROS AND DEFINES === */
+
+/* TODO: Implement without macros */
 #define palette_faded_buffer ((struct color*) 0x020375F8)
 #define palette_unfaded_buffer ((struct color*) 0x020371F8)
 

src/include/math.h

+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
+/**
+ * @file math.h
+ * @author Sturmvogel
+ * @date 15 dec 2016
+ * @brief Math Environment
+ * 
+ * This header file contains methods to interact with the math engine,
+ * i.e. the division / mod methods and the PRNG
+ */
+
+#ifndef MATH_H
+#define MATH_H
+
+/* === INCLUDE === */
+
+#include <types.h>
+
+/* === EXTERN METHODS === */
+
+/**
+ * @brief gets the a mod b
+ * @param a dividend
+ * @param b divisor
+ * @return a % b
+ */
+u32 __aeabi_uidivmod(u32 a, u32 b);
+
+u16 random();
+
+#endif /* MATH_H */
+

src/include/memory.h

  */
 extern void* memset (void* dst, int value, size_t size);
 
+/**
+ * @brief decompress data into wram using interrupt
+ * @param src data source
+ * @param dst data destination (must be in wram)
+ */
+extern void wram_decompress(void* src, void* dst);
+
+/**
+ * @brief decompress data into vram using interrupt
+ * @param src data source
+ * @param dst data destination (must be in vram)
+ */
+extern void vram_decompress(void* src, void* dst);
+
 #endif /* MEMORY_H */
 

src/include/types.h

 
 #define NULL 0
 
-#define		rgb5(r,g,b)				(u16)( r | ( g << 5) | ( b << 10) )
+#define rgb5(r,g,b)                 (u16)( r | ( g << 5) | ( b << 10) )
 
 #endif

src/specials/custom_specials.c

 {
   for(u16 i = 0x1000; i < 0x1800; ++i)
   {
-    clear_flag(i);
+    flag_clear(i);
   }
 }
 

src/specials/cutscene_meteor.c

 	gpu_tile_bg_drop_all_sets(2);
 	gpu_tile_bg_drop_all_sets(3);
 
-	bg_vram_setup(0, standard_bg, 4);
+	gpu_bg_vram_setup(0, standard_bg, 4);
 
 	gpu_bg_show(0);
 	gpu_bg_show(1);