Inherits from NSObject
Declared in OGWMap.h

Overview

An arbitrary map represented by a memory buffer. Can be used for collision, heat, surface and other map types as you see fit.

Maps should be stored in OGWWorldMaps, which you can access through OGWWorld.

Though the map is merely a memory buffer, the map has a 2D size (number of rows/columns) associated with it as well as the elementSize (arbitrary size of each element). This gives you the spatial information often needed for maps. With elementBytes and the map being void* you can use any data type within the map, be it char or integer or double or even (custom) structs.

Properties

elementBytes

The elementBytes determine the integral byte size of each element in the map. No assumption is made how many bytes each element in the map occupies, hence the map is a void* type and can be used for any element types like char, integer or double.

@property (readonly) size_t elementBytes

Return Value

The size in bytes of each element. Typically either 1 (char), 2 (short), 4 (int, float) or 8 (long, double) bytes.

Declared In

OGWMap.h

elementCount

The number of elements in the map. This is equal to (size.width * size.height).

@property (readonly) GWUInteger elementCount

Return Value

The number of elements in the map. This is equal to (size.width * size.height).

Declared In

OGWMap.h

elementSize

How you interpret the size of an element is up to you. Most often it would be used to indicate the spacing between two elements in world coordinates, respectively the area each element occupies in the world.

@property GWSize elementSize

Return Value

The size of individual elements in the map, in arbitrary units (typically world coordinates). Defaults to {1, 1}.

Declared In

OGWMap.h

map

Gives you low-level access to the map data (elements). In most cases you’re bette off to use the enumeration methods.

@property (readonly) void *map

Return Value

Pointer to the start of the map’s memory buffer.

Discussion

Warning: The map pointer must not be freed. Its memory is managed by OGWMap.

Declared In

OGWMap.h

mapBytes

How much memory (in bytes) the map occupies. This is equal to (elementCount * elementBytes).

@property (readonly) size_t mapBytes

Return Value

How much memory (in bytes) the map occupies. This is equal to (elementCount * elementBytes).

Declared In

OGWMap.h

size

The size makes the map a 2D buffer, determining how many elements per row and column exist.

@property (readonly) GWIntSize size

Return Value

The size of the map, in map (integer) coordinates.

Declared In

OGWMap.h

type

You can optionally assign a map a type from the OGWMapType list or your own. This allows you to get a map based on its type instead of by name.

@property OGWMapType type

Return Value

The map’s predefined type.

See Also

Declared In

OGWMap.h

world

@property (weak) OGWWorld *world

Class Methods

mapWithBytes:elementBytes:size:

Copies the contents of the buffer. This is slower and allocated another buffer of the same size, which doubles memory usage until you free the buffer. If this concerns you, use the no-copy initializer..

+ (id)mapWithBytes:(const void *const)buffer elementBytes:(size_t)elementBytes size:(GWIntSize)size

Parameters

buffer

An allocated memory buffer.

elementBytes

The size of each element, in bytes. For example for a GWInteger* buffer you would pass sizeof(GWInteger).

size

The size of the map, ie how many elements per row and column.

Return Value

A new map instance.

Discussion

Warning: It is your responsibility to free the buffer afterwards.

Warning: Size of elements times width times height must equal the buffer’s length. There are no buffer overflow checks in place!

Declared In

OGWMap.h

mapWithBytesNoCopy:elementBytes:size:

Takes ownership of the buffer without copying it. This is faster and more memory efficient.

+ (id)mapWithBytesNoCopy:(void *const)buffer elementBytes:(size_t)elementBytes size:(GWIntSize)size

Parameters

buffer

An allocated memory buffer.

elementBytes

The size of each element, in bytes. For example for a GWInteger* buffer you would pass sizeof(GWInteger).

size

The size of the map, ie how many elements per row and column.

Return Value

A new map instance.

Discussion

Warning: You must not free the buffer when using this initializer!

Warning: Size of elements times width times height must equal the buffer’s length. There are no buffer overflow checks in place!

Declared In

OGWMap.h

Instance Methods

debugDumpMap

The map as string with coordinate markers. Mainly for printing to the console and further analysis.

- (NSString *)debugDumpMap

Return Value

The map as string with coordinate markers. Mainly for printing to the console and further analysis.

Declared In

OGWMap.h

elementAt:

A position in element coordinates.

- (void *const)elementAt:(GWIntPoint)position

Parameters

position

A position in element coordinates.

Return Value

The element at the given position. Returns NULL if the position was outside the map’s boundaries.

Declared In

OGWMap.h

elementAtPoint:

This considers the elementSize of elements to determine which element to return.

- (void *const)elementAtPoint:(GWPoint)point

Parameters

point

A point in world coordinates.

Return Value

The element at the given point. Returns NULL if the point was outside the map’s boundaries.

See Also

Declared In

OGWMap.h

enumerateElementsInRect:usingBlock:

Enumerates the elements at the coordinates given by the rect (in element coordinates).

- (void)enumerateElementsInRect:(GWIntRect)rect usingBlock:(OGWMapElementEnumerationBlock)block

Parameters

rect

A rectangle in element coordinates. The rect may be partially or completely outside the map’s boundaries, it will be adjusted accordingly and return only elements within the map’s boundaries, if any.

block

The block to run for each intersecting element.

Declared In

OGWMap.h

enumerateElementsIntersectingRect:usingBlock:

Enumerates the elements intersecting the rect (in world coordinates).

- (void)enumerateElementsIntersectingRect:(GWRect)rect usingBlock:(OGWMapElementEnumerationBlock)block

Parameters

rect

A rectangle in world coordinates. The rect may be partially or completely outside the map’s boundaries, it will be adjusted accordingly and return only elements within the map’s boundaries, if any.

block

The block to run for each intersecting element.

Declared In

OGWMap.h

enumerateElementsUsingBlock:

Enumerates all elements.

- (void)enumerateElementsUsingBlock:(OGWMapElementEnumerationBlock)block

Parameters

block

The block to run for each element.

Declared In

OGWMap.h

mapCoordFromPoint:inBounds:

A point in world coordinates.

- (GWIntPoint)mapCoordFromPoint:(GWPoint)point inBounds:(BOOL *const)inBounds

Parameters

point

A point in world coordinates.

inBounds

Pass nil if you don’t want to perform bounds checking (faster). Pass a pointer to a BOOL if you want to perform bounds checking. The inBounds parameter will be YES if the returned coordinate is within the map’s boundaries, NO if it is outside the map’s boundaries - in that case the returned coordinates can not be used to access the map’s elements.

Return Value

The corresponding point in map coordinates, taking elementSize into account. The point may lie outside the bounds of the map.

Declared In

OGWMap.h

mapCoordRectFromPointRect:inBounds:

A rect in world coordinates.

- (GWIntRect)mapCoordRectFromPointRect:(GWRect)rect inBounds:(BOOL *const)inBounds

Parameters

rect

A rect in world coordinates.

inBounds

Pass nil if you don’t want to perform bounds checking (faster). Pass a pointer to a BOOL if you want to perform bounds checking. The inBounds parameter will be YES if the returned rectangle is entirely within the map’s boundaries, NO if the rectangle is at least partially outside the map’s boundaries - in that case the returned rectangle can not be used to access the map’s elements.

Return Value

The corresponding rect in map coordinates, taking elementSize into account. The rectangle may lie (partially or completely) outside the bounds of the map.

Declared In

OGWMap.h

reverseRows

Flips the map’s rows by copying them into a new buffer and releasing the old buffer. This is a slow operation, run this only when your buffer’s positive Y coordinates extend downwards (origin at upper left) instead of the OpenGW (OpenGL) coordinate system where positive Y coordinates extend upwards (origin at lower left).

- (void)reverseRows

Discussion

If, for some reason, you need the map both flipped and unflipped frequently, then it’s better to create two OGWMap instances with one copying the buffer on init and reversing the map’s rows on one map.

Declared In

OGWMap.h