| .TH IM_ARRAY 3 "11 April 1993" |
| .SH NAME |
| IM_ARRAY, IM_NEW, IM_NUMBER \- memory allocation macros |
| .SH SYNOPSIS |
| |
| #include <vips/vips.h> |
| |
| type-name *IM_NEW( IMAGE *im, type-name ) |
| .br |
| type-name *IM_ARRAY( IMAGE *im, int number, type-name ) |
| .br |
| int IM_NUMBER( array ) |
| |
| .SH DESCRIPTION |
| |
| NEW, NUMBER and ARRAY are macros built on im_malloc(3) which make memory |
| allocation slightly easier. Given a type name, NEW returns a pointer to a |
| piece of memory large enough to hold an object of that type. ARRAY works as |
| NEW, but allocates space for a number of objects. Given an array, NUMBER |
| returns the number of elements in that array. |
| |
| #define IM_NEW(IM,A) ((A *)im_malloc((IM),sizeof(A))) |
| #define IM_NUMBER(R) (sizeof(R)/sizeof(R[0])) |
| #define IM_ARRAY(IM,N,T) ((T *)im_malloc((IM),(N) * sizeof(T))) |
| |
| Both IM_ARRAY and IM_NEW take an image descriptor as their first |
| parameter. Memory is allocated local to this descriptor, that is, when the |
| descriptor is closed, the memory is automatically freed for you. If you |
| pass NULL instead of an image descriptor, memory is allocated globally and |
| is not automatically freed. |
| |
| (NOTE: in versions of VIPS before 7.3, NEW(3) and ARRAY(3) did not have the |
| initial IMAGE parameter. If you are converting an old VIPS7.2 program, you |
| will need to add a NULL parameter to the start of all NEW(3) and ARRAY(3) |
| parameter lists.) |
| |
| Both functions return NULL on error, setting im_errorstring. |
| |
| Example: |
| |
| #include <vips/vips.h> |
| |
| /* A structure we want to carry about. |
| */ |
| typedef struct { |
| ... |
| } Wombat; |
| |
| /* A static array of them. |
| */ |
| static Wombat swarm[] = { |
| { ... }, |
| { ... }, |
| { ... } |
| }; |
| static int swarm_size = IM_NUMBER( swarm ); |
| |
| int |
| transform_wombat( IMAGE *in, IMAGE *out ) |
| { |
| /* Allocate space for a Wombat. |
| */ |
| Wombat *mar = IM_NEW( out, Wombat ); |
| |
| /* Allocate space for a copy of swarm. |
| */ |
| Wombat *mar = IM_ARRAY( out, swarm_size, Wombat ); |
| |
| .... |
| } |
| |
| .SH COPYRIGHT |
| National Gallery, 1993 |
| .SH SEE ALSO |
| im_malloc(3), im_open_local(3). |
| .SH AUTHOR |
| J. Cupitt \- 23/7/93 |