manpagez: man pages & more
man im_format_for_file(3)
Home | html | info | man
im_format(3)                                                      im_format(3)




NAME

       im_format_register,    im_format_set_priority,    im_format_unregister,
       im_format_map, im_format_for_file, im_format_for_name,  im_format_write
       - load and search image formats


SYNOPSIS

       #include <vips/vips.h>

       typedef enum {
         IM_FORMAT_FLAG_NONE = 0,
         IM_FORMAT_FLAG_PARTIAL = 1
       } im_format_flags;

       typedef gboolean (*im_format_is_a_fn)( const char * );
       typedef int (*im_format_header_fn)( const char *, IMAGE * );
       typedef int (*im_format_load_fn)( const char *, IMAGE * );
       typedef int (*im_format_save_fn)( IMAGE *, const char * );
       typedef im_format_flags (*im_format_flags_fn)( const char * );

       typedef struct im__format_t {
         const char *name;
         const char *name_user;
         int priority;
         const char **suffs;
         im_format_is_a_fn is_a;
         im_format_header_fn header;
         im_format_load_fn load;
         im_format_save_fn save;
         im_format_flags_fn flags;
       } im_format_t;

       im_format_t *im_format_register(
         const char *name, const char *name_user, const char **suffs,
         im_format_is_a_fn is_a, im_format_header_fn header,
         im_format_load_fn load, im_format_save_fn save,
         im_format_flags_fn flags );
       void im_format_set_priority( im_format_t *format, int priority );
       void im_format_unregister( im_format_t *format );

       void *im_format_map( VSListMap2Fn fn, void *a, void *b );
       im_format_t *im_format_for_file( const char *filename );
       im_format_t *im_format_for_name( const char *filename );

       int im_format_write( IMAGE *im, const char *filename );

       int im_format_read( const char *filename, IMAGE *out );



DESCRIPTION

       These  functions  register and unregister image formats, and search the
       table of available image formats to find one suitable  for  loading  or
       saving a file.

       im_open(3)  will do something similar, but that returns a descriptor to
       the file rather than copying to a descriptor you supply.

       The two APIs are useful in different circumstances: im_open(3) is  good
       if you want to directly manipulate a file on disc, for example with the
       paintbox functions. The format API is  useful  for  controlling  how  a
       image is unpacked, since you can specify a destination for the copy.

       im_format_register(3)  registers  an image format with vips. This might
       typically be called during module load, see the documentation for GMod-
       ule.

       An image format has a number of components:

       name  The  internal name by which the format should be known. For exam-
       ple, the OpenEXR image format is known within vips as  "exr".  You  can
       identify formats by testing this field with strcmp(3).

       name_user  The  name  as  it should be displayed to the user. It can be
       internationalised.  For example, in English, the  "analyze"  format  is
       shown as "Analyze 6.0".

       suffs  A  NULL-terminated array of possible file-name suffixes for this
       format. This list is used to filter filenames when they  are  shown  to
       the  user,  and  to help select a format to sav a file as. For example,
       the JPEG format has the suffixes: { .jpg , .jpeg , .jpe , NULL }

       is_a A function which tests whether a file is of the specified  format.
       This is useful if you can guess a file type from the first few bytes in
       the file. If you leave this function NULL, vips  will  guess  from  the
       filename suffix for you.

       header  Load  only  the image header, not any of the image pixels. vips
       will call this first on  im_open(3)  and  delay  loading  pixels  until
       asked. If you leave this NULL, vips will just use the load function.

       load  Load  the  image from the file into the IMAGE. You can leave this
       function NULL if you only have a save method implemented.

       save Write from the IMAGE to the file in this  format.  You  can  leave
       this function NULL if you only have a lload method implemented.

       flags  A  function  which  examines  the file and sets various flags to
       indicated properties of the image. The only  flag  implemented  at  the
       moment  is IM_FORMAT_FLAG_PARTIAL which may be set to indicate that the
       file can be read lazily.

       vips registers the format and returns a pointer to the  im_format_t  it
       created. This may later be used to unregister the format.

       im_format_set_priority(3)  sets  a  priority for the format. Priorities
       for formats default to zero: you mmay set a lower or higher  number  to
       set where in the format table your format is positioned.

       im_format_unregister(3) removes a format from vips. It mmight typically
       be called during module unload, see the documentation for GModule.

       im_format_map(3) maps a function over the list of loaded  formats.  See
       im_slist_map(3).

       im_format_for_file(3)  looks  at  a file on disc and selects the 'best'
       format to use to load that file. If no suitable  format  is  found,  it
       returns NULL and sets an error message.

       im_format_for_name(3)  looks at a filename and picks a format to use to
       save that file based on the file extension. If no  suitable  format  is
       found, it returns NULL and sets an error message.

       im_format_read(3) is a convenience function which copies the image from
       the file into the IMAGE.  error, it returns non-zero and sets an  error
       message.

       im_format_write(3)  is a convenience function which copies the image to
       the file in the appropriate format. On error, it returns  non-zero  and
       sets an error message.



RETURN VALUE

       The functions return 0 success and -1 on error.


SEE ALSO

       im_tiff2vips(3), im_open(3).


AUTHOR

       Jesper Friis and John Cupitt



                                16 August 2008                    im_format(3)

vips 7.16.2 - Generated Sun Sep 28 18:43:04 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.