OGWMap Class Reference
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.
Tasks
Other Methods
-
world
property
Map Size
-
size
property -
elementSize
property -
elementCount
property
Map Memory
-
map
property -
elementBytes
property -
mapBytes
property
Map Type
-
type
property
Creating Maps
Modifying Map
Converting Coordinates
Accessing Elements
Enumerating Elements
-
– enumerateElementsUsingBlock:
-
– enumerateElementsIntersectingRect:usingBlock:
-
– enumerateElementsInRect:usingBlock:
Debug
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.
See Also
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)
.
See Also
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}.
See Also
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.
See Also
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)
.
See Also
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
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
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 passsizeof(GWInteger)
.
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 passsizeof(GWInteger)
.
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.
See Also
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