sgdk: vram.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Functions
vram.h File Reference

SGDK VRAM (Video Memory) management unit. More...

Go to the source code of this file.

## Classes

struct | VRAMRegion
| VRAM region structure. More...

## Functions

void | VRAM_createRegion (VRAMRegion *region, u16 startIndex, u16 size)
| Initialize a new VRAM region structure.
void | VRAM_releaseRegion (VRAMRegion *region)
| Release the VRAM region structure.
void | VRAM_clearRegion (VRAMRegion *region)
| Release all allocations from specified VRAM region.
u16 | VRAM_getFree (VRAMRegion *region)
| Return the number of free tile remaining in the specified VRAM region.
u16 | VRAM_getAllocated (VRAMRegion *region)
| Return the number of allocated tile in the specified VRAM region.
u16 | VRAM_getLargestFreeBlock (VRAMRegion *region)
| Return the largest free block index in the specified VRAM region.
s16 | VRAM_alloc (VRAMRegion *region, u16 size)
| Try to allocate the specified number of tile in the given VRAM region and return its index.
void | VRAM_free (VRAMRegion *region, u16 index)
| Release the previously allocated VRAM block at specified index in the given VRAM region.

## Detailed Description

SGDK VRAM (Video Memory) management unit.

Author:
  Stephane Dallongeville

Date:
  11/2015

Video Memory management unit.
It offerts methods to manage dynamic VRAM allocation for tile data.
Tile data should always be located before tilemap in VRAM (0000-XXXX = tile data, XXXX-FFFF = tilemaps).

     VRAMRegion structure define a VRAM region where we want to use dynamic allocation.
     'vram' field is a buffer representing the VRAM region usage. For each entry:
      b14-b0 = size of the bloc (in tile)
      b15    = 1:used, 0:free

      address           value

                      +-------------------+
      free = 0        | cacheSize  (free) |
                      |                   |
                      |                   |
      cacheSize - 1   |                   |
                      +-------------------+
      cacheSize       | 0                 |
                      +-------------------+

      1. Before allocation (with cacheSize = 1000)

                      +-------------------+
      free = 0        | 1000       (free) |
                      |                   |
                      |                   |
      999             |                   |
                      +-------------------+
      1000            | 0                 |
                      +-------------------+

      cache = ???
      free = cache            *free = cacheSize
      end = cache+cacheSize   *end = 0

      2. After allocation of 32 tiles

                      +------------------------+
      0               | 32              (used) |
      free = 32       | 968             (free) |
                      |                        |
                      |                        |
      999             |                        |
                      +------------------------+
      1000            | 0                      |
                      +------------------------+

      cache = ???
      free = cache + 32       *free = cacheSize - 32

      3. After allocation of 128 tiles

                      +------------------------+
      0               | 32              (used) |
      32              | 128             (used) |
      free = 32+128   | 840             (free) |
                      |                        |
                      |                        |
      999             |                        |
                      +------------------------+
      1000            | 0                      |
                      +------------------------+

      4. After allocation of 64, 500, 100 tiles

                      +------------------------+
      0               | 32              (used) |
      32              | 128             (used) |
      160             | 64              (used) |
      224             | 500             (used) |
      724             | 100             (used) |
      free = 824      | 176             (free) |
                      |                        |
                      |                        |
      999             |                        |
                      +------------------------+
      1000            | 0                      |
                      +------------------------+

      5. After release of allocation #3 (64 tiles)

                      +------------------------+
      0               | 32              (used) |
      32              | 128             (used) |
      160             | 64              (free) |
      224             | 500             (used) |
      724             | 100             (used) |
      free = 824      | 176             (free) |
                      |                        |
                      |                        |
      999             |                        |
                      +------------------------+
      1000            | 0                      |
                      +------------------------+

      6. After release of allocation #4 (500 tiles)

                      +------------------------+
      0               | 32              (used) |
      32              | 128             (used) |
      160             | 64              (free) |
      224             | 500             (free) |
      724             | 100             (used) |
      free = 824      | 176             (free) |
                      |                        |
                      |                        |
      999             |                        |
                      +------------------------+
      1000            | 0                      |
                      +------------------------+

      7. After allocation of 400 tiles

                      +------------------------+
      0               | 32              (used) |
      32              | 128             (used) |
      160             | 400             (used) |
      560             | 164             (free) |
      724             | 100             (used) |
      free = 824      | 176             (free) |
                      |                        |
                      |                        |
      999             |                        |
                      +------------------------+
      1000            | 0                      |
                      +------------------------+
     *

## Function Documentation

s16 VRAM_alloc | ( | VRAMRegion * | region,
|  | u16 | size
| ) |  |

Try to allocate the specified number of tile in the given VRAM region and return its index.

Parameters:

  region | VRAM region
  size | Number of tile we want to allocate in VRAM (need to be > 0).

Returns:
  the index in VRAM where we allocated the bloc of tile.
  -1 if there is no enough available VRAM in the region.

See also:
  VRAM_free(..)

void VRAM_clearRegion | ( | VRAMRegion * | region | ) |

Release all allocations from specified VRAM region.

Parameters:

  region | VRAM region we want to clear.

void VRAM_createRegion | ( | VRAMRegion * | region,
|  | u16 | startIndex,
|  | u16 | size
| ) |  |

Initialize a new VRAM region structure.

Parameters:

  region | Region to initialize.
  startIndex | Tile start index in VRAM.
  size | Size in tile of the region.

Set parameters and allocate memory for the VRAM region structure.

See also:
  VRAM_releaseRegion(..)

void VRAM_free | ( | VRAMRegion * | region,
|  | u16 | index
| ) |  |

Release the previously allocated VRAM block at specified index in the given VRAM region.

Parameters:

  region | VRAM region
  index | The index of the VRAM block we want to release

See also:
  VRAM_alloc(..)

u16 VRAM_getAllocated | ( | VRAMRegion * | region | ) |

Return the number of allocated tile in the specified VRAM region.

Parameters:

  region | VRAM region

Returns:
  the number of allocated tile in the specified VRAM region.

u16 VRAM_getFree | ( | VRAMRegion * | region | ) |

Return the number of free tile remaining in the specified VRAM region.

Parameters:

  region | VRAM region

Returns:
  the number of free tile in the specified VRAM region

u16 VRAM_getLargestFreeBlock | ( | VRAMRegion * | region | ) |

Return the largest free block index in the specified VRAM region.

Parameters:

  region | VRAM region

Returns:
  the largest free block index in the specified VRAM region.

void VRAM_releaseRegion | ( | VRAMRegion * | region | ) |

Release the VRAM region structure.

Parameters:

  region | VRAMRegion we want to release.

Release memory used by the VRAM region structure.

See also:
  VRAM_createRegion(..)

All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines