78 lines
2.0 KiB
Groff
78 lines
2.0 KiB
Groff
.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
|