! . */
| 11284 | |
| 11285 | /*! . */ |
| 11286 | void * GMT_Create_Data (void *V_API, unsigned int family, unsigned int geometry, unsigned int mode, uint64_t dim[], double *range, double *inc, unsigned int registration, int pad, void *data) { |
| 11287 | /* Create an empty container of the requested kind and allocate space for content. |
| 11288 | * The known families are GMT_IS_{DATASET,GRID,PALETTE,IMAGE,POSTSCRIPT}, but we |
| 11289 | * also allow for creation of the containers for GMT_IS_{VECTOR,MATRIX}. Note |
| 11290 | * that for VECTOR|MATRIX we don't allocate space to hold data as it is the users |
| 11291 | * responsibility to hook their data pointers in. The VECTOR allocates the array |
| 11292 | * of column vector type and data pointers. |
| 11293 | * Geometry should reflect the resource, e.g. GMT_IS_SURFACE for grid, etc. |
| 11294 | * There are two ways to define the dimensions needed to actually allocate memory: |
| 11295 | * (A) Via uint64_t dim[]: |
| 11296 | * The dim array contains up to 4 dimensions for: |
| 11297 | * 0: dim[GMT_TBL] = number of tables, |
| 11298 | * 1: dim[GMT_SEG] = number of segments per table |
| 11299 | * 2: dim[GMT_ROW] = number of rows per segment. |
| 11300 | * 3: dim[GMT_COL] = number of columns per row. |
| 11301 | * The dim array is ignored for CPTs. |
| 11302 | * For GMT_IS_IMAGE & GMT_IS_MATRIX, par[GMT_Z] = GMT[2] holds the number of bands or layers (dim == NULL means just 1). |
| 11303 | * For GMT_IS_GRID, GMT_IS_IMAGE, & GMT_IS_MATRIX: dim[0] holds the number of columns and dim[1] holds the number |
| 11304 | * of rows; this implies that wesn = 0-<dim-1>, inc = 1, and registration is pixel-registration. |
| 11305 | * For GMT_IS_VECTOR, dim[0] holds the number of columns, optionally dim[1] holds number of rows, if known, or 0. |
| 11306 | * dim[2] can hold the data type (GMT_DOUBLE, etc). If dim[1] > 0 then we allocate the rows. |
| 11307 | * (B) Via range, inc, registration: |
| 11308 | * Convert user domain range, increments, and registration into dimensions |
| 11309 | * for the container. For grids and images we fill out the GMT_GRID_HEADER; |
| 11310 | * for vectors and matrices we fill out their internal parameters. |
| 11311 | * For complex grids pass registration + GMT_GRID_IS_COMPLEX_{REAL|IMAG} |
| 11312 | * For GMT_IS_MATRIX and GMT_IS_IMAGE, dim[GMT_Z] = holds the number of layers or bands (dim == NULL means just 1), |
| 11313 | * and dim[3] holds the data type (dim == NULL means GMT_DOUBLE). |
| 11314 | * For GMT_IS_VECTOR, dim[GMT_Z] holds the data type (dim == NULL means GMT_DOUBLE). |
| 11315 | * pad sets the padding for grids and images, while for matrices it can be |
| 11316 | * 0 for the default row/col orientation |
| 11317 | * 1 for row-major format (C) |
| 11318 | * 2 for column major format (FORTRAN) |
| 11319 | pad is ignored for other resources. |
| 11320 | * Some default actions for grids: |
| 11321 | * range = NULL: Select current -R setting if present. |
| 11322 | * registration = GMT_NOTSET: Gridline unless -r is in effect. |
| 11323 | * Give -1 (GMT_NOTSET) to accept GMT default padding [2]. |
| 11324 | * |
| 11325 | * For creating grids and images you can do it in one or two steps: |
| 11326 | * (A) Pass mode = GMT_CONTAINER_AND_DATA; this creates both header and allocates grid|image; |
| 11327 | * (B) Call GMT_Create_Data twice: |
| 11328 | * 1. First with mode = GMT_CONTAINER_ONLY which creates header only |
| 11329 | * and computes the dimensions based on the other arguments. |
| 11330 | * 2. 2nd with mode = GMT_DATA_ONLY, which allocates the grid|image array |
| 11331 | * based on the dimensions already set. This time you pass NULL/0 |
| 11332 | * for dim, wesn, inc, registration, pad but let data be your grid|image |
| 11333 | * returned to you after step 1. |
| 11334 | * |
| 11335 | * By default, the created resource is consider an input resource (direction == GMT_IN). |
| 11336 | * However, for the interface containers GMT_VECTOR and GMT_MATRIX they will have their |
| 11337 | * direction set to GMT_OUT if the row-dimension is not set. |
| 11338 | * |
| 11339 | * For containers GMT_IS_DATASET, GMT_IS_MATRIX and GMT_IS VECTOR: If you add the constant |
| 11340 | * GMT_WITH_STRINGS to the mode it will allocate the corresponding arrays of string pointers. |
| 11341 | * You can then add actual strings in addition to data values. Note: GMT will assume |
| 11342 | * the individual strings was allocated using functions like malloc or strdup and will |
| 11343 | * free them when the container goes out of scope. If you don't want that to happen then |