/usr/include/openslide/openslide.h is in libopenslide-dev 3.2.5-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 | /*
* OpenSlide, a library for reading whole slide image files
*
* Copyright (c) 2007-2010 Carnegie Mellon University
* All rights reserved.
*
* OpenSlide is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation, version 2.1.
*
* OpenSlide is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with OpenSlide. If not, see
* <http://www.gnu.org/licenses/>.
*
*/
/**
* @file openslide.h
* The API for the OpenSlide library.
*/
#ifndef OPENSLIDE_OPENSLIDE_H_
#define OPENSLIDE_OPENSLIDE_H_
#include <openslide-features.h>
#include <stdio.h>
#include <stdint.h>
/**
* The main OpenSlide type.
*/
typedef struct _openslide openslide_t;
/**
* @name Basic Usage
* Opening, reading, and closing. Note that the terminology used by
* OpenSlide is slightly different from DICOM and others: notably,
* a DICOM "level" is known as a "layer" in OpenSlide.
*/
//@{
/**
* Do a quick check to see if a whole slide image is valid.
*
* @param filename The filename to check.
* @return If openslide_open() will succeed.
*/
OPENSLIDE_PUBLIC()
bool openslide_can_open(const char *filename);
/**
* Open a whole slide image.
*
* @param filename The filename to open.
* @return A new OpenSlide object, or NULL if an error occurred.
*/
OPENSLIDE_PUBLIC()
openslide_t *openslide_open(const char *filename);
/**
* Get the number of layers in the whole slide image.
*
* @param osr The OpenSlide object.
* @return The number of layers, or -1 if an error occurred.
*/
OPENSLIDE_PUBLIC()
int32_t openslide_get_layer_count(openslide_t *osr);
/**
* Get the dimensions of layer 0 (the largest layer). Exactly
* equivalent to calling openslide_get_layer_dimensions(osr, 0, w, h).
*
* @param osr The OpenSlide object.
* @param[out] w The width of the image, or -1 if an error occurred.
* @param[out] h The height of the image, or -1 if an error occurred.
*/
OPENSLIDE_PUBLIC()
void openslide_get_layer0_dimensions(openslide_t *osr, int64_t *w, int64_t *h);
/**
* Get the dimensions of a layer.
*
* @param osr The OpenSlide object.
* @param layer The desired layer.
* @param[out] w The width of the image, or -1 if an error occurred
* or the layer was out of range.
* @param[out] h The height of the image, or -1 if an error occurred
* or the layer was out of range.
*/
OPENSLIDE_PUBLIC()
void openslide_get_layer_dimensions(openslide_t *osr, int32_t layer,
int64_t *w, int64_t *h);
/**
* Get the downsampling factor of a given layer.
*
* @param osr The OpenSlide object.
* @param layer The desired layer.
* @return The downsampling factor for this layer, or -1.0 if an error occurred
* or the layer was out of range.
*/
OPENSLIDE_PUBLIC()
double openslide_get_layer_downsample(openslide_t *osr, int32_t layer);
/**
* Get the best layer to use for displaying the given downsample.
*
* @param osr The OpenSlide object.
* @param downsample The downsample factor.
* @return The layer identifier, or -1 if an error occurred.
*/
OPENSLIDE_PUBLIC()
int32_t openslide_get_best_layer_for_downsample(openslide_t *osr,
double downsample);
/**
* Copy pre-multiplied ARGB data from a whole slide image.
*
* This function reads and decompresses a region of a whole slide
* image into the specified memory location. @p dest must be a valid
* pointer to enough memory to hold the region, at least (@p w * @p h * 4)
* bytes in length. If an error occurs or has occurred, then the memory
* pointed to by @p dest will be cleared.
*
* @param osr The OpenSlide object.
* @param dest The destination buffer for the ARGB data.
* @param x The top left x-coordinate, in the layer 0 reference frame.
* @param y The top left y-coordinate, in the layer 0 reference frame.
* @param layer The desired layer.
* @param w The width of the region. Must be non-negative.
* @param h The height of the region. Must be non-negative.
*/
OPENSLIDE_PUBLIC()
void openslide_read_region(openslide_t *osr,
uint32_t *dest,
int64_t x, int64_t y,
int32_t layer,
int64_t w, int64_t h);
/**
* Close an OpenSlide object. After this call returns, the object cannot
* be used anymore.
*
* @param osr The OpenSlide object.
*/
OPENSLIDE_PUBLIC()
void openslide_close(openslide_t *osr);
//@}
/**
* @name Error Handling
* A simple mechanism for detecting errors.
*
* Sometimes an unrecoverable error can occur that will invalidate the
* OpenSlide object. (This is typically something like an I/O error or
* data corruption.) When such an error happens in an OpenSlide
* object, the object will move terminally into an error state.
*
* While an object is in an error state, no OpenSlide functions will
* have any effect on it except for openslide_close(). Functions
* that are expected to return values will instead return an error
* value, typically something like NULL or -1. openslide_read_region()
* will clear its destination buffer instead of painting into
* it. openslide_get_error() will return a non-NULL string containing
* an error message. See the documentation for each function for
* details on what is returned in case of error.
*
* This style of error handling allows programs written in C to check
* for errors only when convenient, because the error state is
* terminal and the OpenSlide functions return harmlessly when there
* has been an error.
*
* If writing wrappers for OpenSlide in languages that support
* exceptions, it is recommended that the error state be checked after
* each call and converted into an exception for that language.
*/
//@{
/**
* Get the current error string.
*
* For a given OpenSlide object, once this function returns a non-NULL
* value, the only useful operation on the object is to call
* openslide_close() to free its resources.
*
* @param osr The OpenSlide object.
* @return A string describing the original error that caused
* the problem, or NULL if no error has occurred.
*
*/
OPENSLIDE_PUBLIC()
const char *openslide_get_error(openslide_t *osr);
//@}
/**
* @name Predefined Properties
* Some predefined properties.
*/
//@{
/**
* The name of the property containing a slide's comment, if any.
*/
#define OPENSLIDE_PROPERTY_NAME_COMMENT "openslide.comment"
/**
* The name of the property containing an identification of the vendor.
*/
#define OPENSLIDE_PROPERTY_NAME_VENDOR "openslide.vendor"
/**
* The name of the property containing the "quickhash-1" sum.
*/
#define OPENSLIDE_PROPERTY_NAME_QUICKHASH1 "openslide.quickhash-1"
/**
* The name of the property containing a slide's background color, if any.
* It is represented as an RGB hex triplet.
*/
#define OPENSLIDE_PROPERTY_NAME_BACKGROUND_COLOR "openslide.background-color"
//@}
/**
* @name Properties
* Querying properties.
*/
//@{
/**
* Get the NULL-terminated array of property names.
*
* Certain vendor-specific metadata properties may exist
* within a whole slide image. They are encoded as key-value
* pairs. This call provides a list of names as strings
* that can be used to read properties with openslide_get_property_value().
*
* @param osr The OpenSlide object.
* @return A NULL-terminated string array of property names, or
* an empty array if an error occurred.
*/
OPENSLIDE_PUBLIC()
const char * const *openslide_get_property_names(openslide_t *osr);
/**
* Get the value of a single property.
*
* Certain vendor-specific metadata properties may exist
* within a whole slide image. They are encoded as key-value
* pairs. This call provides the value of the property given
* by @p name.
*
* @param osr The OpenSlide object.
* @param name The name of the desired property. Must be
a valid name as given by openslide_get_property_names().
* @return The value of the named property, or NULL if the property
* doesn't exist or an error occurred.
*/
OPENSLIDE_PUBLIC()
const char *openslide_get_property_value(openslide_t *osr, const char *name);
/**
* Get the comment (if any) for this image. Exactly equivalent to calling
* openslide_get_property_value() with #OPENSLIDE_PROPERTY_NAME_COMMENT.
*
* @param osr The OpenSlide object.
* @return The comment for this image, or NULL if an error occurred.
*/
OPENSLIDE_PUBLIC()
const char *openslide_get_comment(openslide_t *osr);
//@}
/**
* @name Associated Images
* Reading associated images.
*/
//@{
/**
* Get the NULL-terminated array of associated image names.
*
* Certain vendor-specific associated images may exist
* within a whole slide image. They are encoded as key-value
* pairs. This call provides a list of names as strings
* that can be used to read associated images with
* openslide_get_associated_image_dimensions() and
* openslide_read_associated_image().
*
* @param osr The OpenSlide object.
* @return A NULL-terminated string array of associated image names, or
an empty array if an error occurred.
*/
OPENSLIDE_PUBLIC()
const char * const *openslide_get_associated_image_names(openslide_t *osr);
/**
* Get the dimensions of an associated image.
*
* This function returns the width and height of an associated image
* associated with a whole slide image. Once the dimensions are known,
* use openslide_read_associated_image() to read the image.
*
* @param osr The OpenSlide object.
* @param name The name of the desired associated image. Must be
* a valid name as given by openslide_get_associated_image_names().
* @param[out] w The width of the associated image, or -1 if an error occurred.
* @param[out] h The height of the associated image, or -1 if an error occurred.
*/
OPENSLIDE_PUBLIC()
void openslide_get_associated_image_dimensions(openslide_t *osr,
const char *name,
int64_t *w, int64_t *h);
/**
* Copy pre-multiplied ARGB data from an associated image.
*
* This function reads and decompresses an associated image associated
* with a whole slide image. @p dest must be a valid pointer to enough
* memory to hold the image, at least (width * height * 4) bytes in
* length. Get the width and height with
* openslide_get_associated_image_dimensions(). This call does nothing
* if an error occurred.
*
* @param osr The OpenSlide object.
* @param dest The destination buffer for the ARGB data.
* @param name The name of the desired associated image. Must be
* a valid name as given by openslide_get_associated_image_names().
*/
OPENSLIDE_PUBLIC()
void openslide_read_associated_image(openslide_t *osr,
const char *name,
uint32_t *dest);
//@}
// these are meant to throw compile- and link-time errors,
// since the functions they replace were never implemented
int _openslide_give_prefetch_hint_UNIMPLEMENTED(void);
void _openslide_cancel_prefetch_hint_UNIMPLEMENTED(void);
#define openslide_give_prefetch_hint(osr, x, y, layer, w, h) \
_openslide_give_prefetch_hint_UNIMPLEMENTED(-1);
#define openslide_cancel_prefetch_hint(osr, prefetch_id) \
_openslide_cancel_prefetch_hint_UNIMPLEMENTED(-1)
/**
* @mainpage OpenSlide
*
* OpenSlide is a C library that provides a simple interface to read
* whole-slide images (also known as virtual slides). See
* http://openslide.org/ for more details.
*/
#endif
|