| 36 | | * blocks or a mix of both. |
| 37 | | * |
| 38 | | * Empty blocks are blocks that contain only pixels whose value is the nodata value when it |
| 39 | | * is set, or whose value is 0 when the nodata value is not set. |
| | 37 | * blocks or a mix of both. This function can be used to determine quickly |
| | 38 | * if it is worth issuing RasterIO / ReadBlock requests in datasets that may |
| | 39 | * be sparse. |
| | 40 | * |
| | 41 | * Empty blocks are blocks that contain only pixels whose value is the nodata |
| | 42 | * value when it is set, or whose value is 0 when the nodata value is not set. |
| 42 | | * values. If not possible, GDAL_DATA_COVERAGE_STATUS_UNIMPLEMENTED will be |
| 43 | | * returned. |
| | 45 | * values. If not possible, or not implemented at all by the driver, |
| | 46 | * GDAL_DATA_COVERAGE_STATUS_UNIMPLEMENTED | GDAL_DATA_COVERAGE_STATUS_DATA will |
| | 47 | * be returned. |
| | 48 | * |
| | 49 | * The values that can be returned by the function are the following, |
| | 50 | * potentially combined with the binary or operator : |
| | 51 | * <ul> |
| | 52 | * <li>GDAL_DATA_COVERAGE_STATUS_UNIMPLEMENTED : the driver does not implement |
| | 53 | * GetDataCoverageStatus(). This flag should be returned together with |
| | 54 | * GDAL_DATA_COVERAGE_STATUS_DATA.</li> |
| | 55 | * <li>GDAL_DATA_COVERAGE_STATUS_DATA: There is (potentially) data in the queried |
| | 56 | * window.</li> |
| | 57 | * <li>GDAL_DATA_COVERAGE_STATUS_EMPTY: There is nodata in the queried window. |
| | 58 | * This is typically identified by the concept of missing block in formats that |
| | 59 | * supports it. |
| | 60 | * </li> |
| | 61 | * </ul> |
| | 62 | * |
| | 63 | * Note that GDAL_DATA_COVERAGE_STATUS_DATA might have false positives and |
| | 64 | * should be interpreted more as hint of potential presence of data. For example |
| | 65 | * if a GeoTIFF file is created with blocks filled with zeroes (or set to the |
| | 66 | * nodata value), instead of using the missing block mechanism, |
| | 67 | * GDAL_DATA_COVERAGE_STATUS_DATA will be returned. On the contrary, |
| | 68 | * GDAL_DATA_COVERAGE_STATUS_EMPTY should have no false positives. |
| | 69 | * |
| | 70 | * The nMaskFlagStop should be generally set to 0. It can be set to a |
| | 71 | * binary-or'ed mask of the above mentioned values to enable a quick exiting of |
| | 72 | * the function as soon as the computed mask matches the nMaskFlagStop. For |
| | 73 | * example, you can issue a request on the whole raster with nMaskFlagStop = |
| | 74 | * GDAL_DATA_COVERAGE_STATUS_EMPTY. As soon as one missing block is encountered, |
| | 75 | * the function will exit, so that you can potentially refine the requested area |
| | 76 | * to find which particular region(s) have missing blocks. |
| 64 | | * to the (approximate) percentage in [0,100] of pixels in the queried sub-window that have |
| 65 | | * valid values. The implementation might not always be able to compute it, in |
| 66 | | * |
| | 97 | * to the (approximate) percentage in [0,100] of pixels in the queried |
| | 98 | * sub-window that have valid values. The implementation might not always be |
| | 99 | * able to compute it, in which case it will be set to a negative value. |
| | 114 | |
| | 115 | /** Flag returned by GDALGetDataCoverageStatus() when the driver does not |
| | 116 | * implement GetDataCoverageStatus(). This flag should be returned together |
| | 117 | * with GDAL_DATA_COVERAGE_STATUS_DATA */ |
| | 118 | #define GDAL_DATA_COVERAGE_STATUS_UNIMPLEMENTED 0x01 |
| | 119 | |
| | 120 | /** Flag returned by GDALGetDataCoverageStatus() when there is (potentially) |
| | 121 | * data in the queried window. Can be combined with the binary or operator |
| | 122 | * with GDAL_DATA_COVERAGE_STATUS_UNIMPLEMENTED or |
| | 123 | * GDAL_DATA_COVERAGE_STATUS_EMPTY */ |
| | 124 | #define GDAL_DATA_COVERAGE_STATUS_DATA 0x02 |
| | 125 | |
| | 126 | /** Flag returned by GDALGetDataCoverageStatus() when there is nodata in the |
| | 127 | * queried window. This is typically identified by the concept of missing block |
| | 128 | * in formats that supports it. |
| | 129 | * Can be combined with the binary or operator with |
| | 130 | * GDAL_DATA_COVERAGE_STATUS_DATA */ |
| | 131 | #define GDAL_DATA_COVERAGE_STATUS_EMPTY 0x04 |
| | 132 | |
| | 133 | |
