Coin Logo Coin3D is Free Software,
published under the BSD 3-clause license.
simage.h File Reference

Windows specific information. More...

Go to the source code of this file.

Data Structures

struct  simage_plugin


#define __SIMAGE__
#define SIMAGE_VERSION_1_1
#define SIMAGE_VERSION_1_2
#define SIMAGE_VERSION_1_3
#define SIMAGE_VERSION_1_4
#define SIMAGE_VERSION_1_5
#define SIMAGE_VERSION_1_6


typedef struct simage_image_s s_image
typedef struct simage_movie_s s_movie
typedef struct simage_parameters_s s_params
typedef int s_movie_open_func(const char *, s_movie *)
typedef int s_movie_create_func(const char *, s_movie *, s_params *)
typedef s_images_movie_get_func(s_movie *, s_image *, s_params *)
typedef int s_movie_put_func(s_movie *, s_image *, s_params *)
typedef void s_movie_close_func(s_movie *)
typedef struct simage_stream_s s_stream
typedef int s_stream_open_func(const char *, s_stream *, s_params *)
typedef int s_stream_create_func(const char *, s_stream *, s_params *)
typedef void * s_stream_get_func(s_stream *, void *, int *, s_params *)
typedef int s_stream_put_func(s_stream *, void *, int, s_params *)
typedef void s_stream_close_func(s_stream *)
typedef int s_stream_seek_func(s_stream *, int, int, s_params *)
typedef int s_stream_tell_func(s_stream *, s_params *)
typedef void * s_dlopen_func(const char *filename)
typedef void * s_dlsym_func(void *handle, const char *symbolname)
typedef void s_dlclose_func(void *handle)


enum  {


void simage_version (int *major, int *minor, int *micro)
int simage_check_supported (const char *filename)
unsigned char * simage_read_image (const char *filename, int *width, int *height, int *numcomponents)
const char * simage_get_last_error (void)
void simage_free_image (unsigned char *imagedata)
int simage_next_power_of_two (int val)
unsigned char * simage_resize (unsigned char *imagedata, int width, int height, int numcomponents, int newwidth, int newheight)
void * simage_add_loader (const struct simage_plugin *l, int addbefore)
void simage_remove_loader (void *handle)
int simage_check_save_supported (const char *filenameextension)
int simage_save_image (const char *filename, const unsigned char *bytes, int w, int h, int numcomponents, const char *filenameextension)
void * simage_add_saver (int(*save_func)(const char *name, const unsigned char *bytes, int width, int height, int nc), int(*error_func)(char *textbuffer, int bufferlen), const char *extensions, const char *fullname, const char *description, int addbefore)
void simage_remove_saver (void *handle)
int simage_get_num_savers (void)
void * simage_get_saver_handle (int idx)
const char * simage_get_saver_extensions (void *handle)
const char * simage_get_saver_fullname (void *handle)
const char * simage_get_saver_description (void *handle)
s_images_image_create (int w, int h, int components, unsigned char *prealloc)
void s_image_destroy (s_image *image)
int s_image_width (s_image *image)
int s_image_height (s_image *image)
int s_image_components (s_image *image)
unsigned char * s_image_data (s_image *image)
void s_image_set (s_image *image, int w, int h, int components, unsigned char *data, int copydata)
s_images_image_load (const char *filename, s_image *prealloc)
int s_image_save (const char *filename, s_image *image, s_params *params)
s_movies_movie_open (const char *filename)
s_movies_movie_create (const char *filename, s_params *params)
s_images_movie_get_image (s_movie *movie, s_image *prealloc, s_params *params)
int s_movie_put_image (s_movie *movie, s_image *image, s_params *params)
void s_movie_close (s_movie *movie)
void s_movie_destroy (s_movie *movie)
void s_movie_importer_add (s_movie_open_func *open, s_movie_get_func *get, s_movie_close_func *close)
void s_movie_exporter_add (s_movie_create_func *create, s_movie_put_func *put, s_movie_close_func *close)
s_paramss_params_create (void)
s_paramss_params_copy (s_params *params)
void s_params_destroy (s_params *params)
void s_params_set (s_params *params,...)
int s_params_get (s_params *params,...)
unsigned char * simage_resize3d (unsigned char *imagedata, int width, int height, int numcomponents, int layers, int newwidth, int newheight, int newlayers)
s_streams_stream_open (const char *filename, s_params *params)
s_streams_stream_create (const char *filename, s_params *params)
void * s_stream_get_buffer (s_stream *stream, void *prealloc, int *size, s_params *params)
int s_stream_put_buffer (s_stream *stream, void *buffer, int size, s_params *params)
void s_stream_close (s_stream *stream)
void s_stream_destroy (s_stream *stream)
s_paramss_stream_params (s_stream *stream)
void s_stream_importer_add (s_stream_open_func *open, s_stream_get_func *get, s_stream_close_func *close)
void s_stream_exporter_add (s_stream_create_func *create, s_stream_put_func *put, s_stream_close_func *close)
int s_stream_seek (s_stream *stream, int offset, int whence, s_params *params)
int s_stream_tell (s_stream *stream, s_params *params)
void s_stream_importer_add_ex (s_stream_open_func *open, s_stream_get_func *get, s_stream_seek_func *seek, s_stream_tell_func *tell, s_stream_close_func *close)
void s_stream_exporter_add_ex (s_stream_create_func *create, s_stream_put_func *put, s_stream_seek_func *seek, s_stream_tell_func *tell, s_stream_close_func *close)
int s_image_set_component_order (s_image *image, int order)
int s_image_get_component_order (s_image *image)
s_images_image_open (const char *file, int oktoreadall)
int s_image_read_line (s_image *image, int line, unsigned char *buf)
void s_set_dynamic_loader_interface (s_dlopen_func *dlopen, s_dlsym_func *dlsym, s_dlclose_func *dlclose)

Detailed Description

Windows specific information.

These are available for adding or omitting features based on simage version numbers in "client" sources. NB: they are automatically synchronized with the settings in when configure is run. The #ifndefs are necessary because during development, these are also defined in the config.h file generated by configure.

On Microsoft Windows platforms, one of these defines must always be set when building application programs:

  • "SIMAGE_DLL", when the application programmer is using the library in the form of a dynamic link library (DLL)
  • "SIMAGE_NOT_DLL", when the application programmer is using the library in the form of a static object library (LIB)

Note that either SIMAGE_DLL or SIMAGE_NOT_DLL must be defined by the application programmer on Microsoft Windows platforms, or else the #error statement will be hit. Set up one or the other of these two defines in your compiler environment according to how the library was built – as a DLL (use "SIMAGE_DLL") or as a LIB (use "SIMAGE_NOT_DLL").

(Setting up defines for the compiler is typically done by either adding something like "/DSIMAGE_DLL" to the compiler's argument line (for command-line build processes), or by adding the define to the list of preprocessor symbols in your IDE GUI (in the MSVC IDE, this is done from the "Project"->"Settings" menu, choose the "C/C++" tab, then "Preprocessor" from the drop-down box and add the appropriate define)).

It is extremely important that the application programmer uses the correct define, as using "SIMAGE_NOT_DLL" when "SIMAGE_DLL" is correct will cause mysterious crashes.

Macro Definition Documentation

◆ __SIMAGE__

#define __SIMAGE__

A unique identifier to recognize in source code whether or not this file is included.


#define SIMAGE_VERSION_1_1

Version 1.1 introduced saving


#define SIMAGE_VERSION_1_2

Version 1.2 added a new API, and support for movies


#define SIMAGE_VERSION_1_3

Version 1.3 added simage_resize3d


#define SIMAGE_VERSION_1_4

Version 1.4 added API for stream I/O


#define SIMAGE_VERSION_1_5

Version 1.5 added API for seeking and getting ("telling") the current position in a stream added API for setting and getting component order of an image


#define SIMAGE_VERSION_1_6

Version 1.6 added API for reading images line-by-line added API for loading dynamic libraries at run-time

Typedef Documentation

◆ s_image

typedef struct simage_image_s s_image

◆ s_movie

typedef struct simage_movie_s s_movie

◆ s_params

typedef struct simage_parameters_s s_params

◆ s_movie_open_func

typedef int s_movie_open_func(const char *, s_movie *)

◆ s_movie_create_func

typedef int s_movie_create_func(const char *, s_movie *, s_params *)

◆ s_movie_get_func

typedef s_image* s_movie_get_func(s_movie *, s_image *, s_params *)

◆ s_movie_put_func

typedef int s_movie_put_func(s_movie *, s_image *, s_params *)

◆ s_movie_close_func

typedef void s_movie_close_func(s_movie *)

◆ s_stream

typedef struct simage_stream_s s_stream

◆ s_stream_open_func

typedef int s_stream_open_func(const char *, s_stream *, s_params *)

◆ s_stream_create_func

typedef int s_stream_create_func(const char *, s_stream *, s_params *)

◆ s_stream_get_func

typedef void* s_stream_get_func(s_stream *, void *, int *, s_params *)

◆ s_stream_put_func

typedef int s_stream_put_func(s_stream *, void *, int, s_params *)

◆ s_stream_close_func

typedef void s_stream_close_func(s_stream *)

◆ s_stream_seek_func

typedef int s_stream_seek_func(s_stream *, int, int, s_params *)

◆ s_stream_tell_func

typedef int s_stream_tell_func(s_stream *, s_params *)

◆ s_dlopen_func

typedef void* s_dlopen_func(const char *filename)

◆ s_dlsym_func

typedef void* s_dlsym_func(void *handle, const char *symbolname)

◆ s_dlclose_func

typedef void s_dlclose_func(void *handle)

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

◆ anonymous enum

anonymous enum

◆ anonymous enum

anonymous enum

Function Documentation

◆ simage_version()

void simage_version ( int *  major,
int *  minor,
int *  micro 

Note specifically for Microsoft Windows that by leaving out the APIENTRY keyword for the function definitions, we default to the __cdecl calling convention. This is important to take into consideration when explicitly linking to the library at runtime: when using the wrong calling convention, obscure errors due to stack corruption can occur under certain (possibly rare) conditions.

Returns runtime version for simage.

◆ simage_check_supported()

int simage_check_supported ( const char *  filename)

Checks if image file format is supported. Returns 1 if filename can be loaded, 0 otherwise.

◆ simage_read_image()

unsigned char* simage_read_image ( const char *  filename,
int *  width,
int *  height,
int *  numcomponents 

Attempts to read filename, and return a pointer to the image data. NULL is returned if the image could not be loaded. The memory is allocated using malloc(), and it is the callers responsibility to free the memory (using free()) width and height contains the width and height of the image, and numcomponents is a number indicating the following:

1 : Grayscale image (GL_LUMINANCE) 2 : Grayscale with alpha channel (GL_LUMINANCE_ALPHA) 3 : RGB data (GL_RGB) 4 : RGB data with alpha component (GL_RGBA)

Returned image buffer must be freed by simage_free_image()

◆ simage_get_last_error()

const char* simage_get_last_error ( void  )

Returns error message, which is set when simage_read_image returned NULL or simage_write_image returns 0.

◆ simage_free_image()

void simage_free_image ( unsigned char *  imagedata)

Free resources allocated by either simage_read_image() or simage_resize() (Windows goes berzerk if you call free() from the client application)

◆ simage_next_power_of_two()

int simage_next_power_of_two ( int  val)

Returns the first 2^n bigger or equal to val. If simage_next_power_of_two(size) != size, you'll typically need to resize your image to be able to use it in an OpenGL app.

◆ simage_resize()

unsigned char* simage_resize ( unsigned char *  imagedata,
int  width,
int  height,
int  numcomponents,
int  newwidth,
int  newheight 

Since OpenGL textures must have width and height equal to 2^n, this is often needed. A pointer to the new image data is returned. imagedata is not freed. Uses the algorithm "Filtered Image Rescaling" by Dale Schumacher, from GGems III.

Scales the input imagedata and return a new image with the given dimensions returned image buffer must be freed by simage_free_image()

◆ simage_add_loader()

void* simage_add_loader ( const struct simage_plugin l,
int  addbefore 

◆ simage_remove_loader()

void simage_remove_loader ( void *  handle)

◆ simage_check_save_supported()

int simage_check_save_supported ( const char *  filenameextension)

Checks if export is available for a file type. Returns 1 if a saver of type filenameextension is supported, 0 otherwise. The built-in savers are gif, jpg/jpeg, png, tif/tiff and rgb.

◆ simage_save_image()

int simage_save_image ( const char *  filename,
const unsigned char *  bytes,
int  w,
int  h,
int  numcomponents,
const char *  filenameextension 

Saves image in the format specified in filenameextension. Use simage_check_write_supported first to verify that the file format is supported.

◆ simage_add_saver()

void* simage_add_saver ( int(*)(const char *name, const unsigned char *bytes, int width, int height, int nc)  save_func,
int(*)(char *textbuffer, int bufferlen)  error_func,
const char *  extensions,
const char *  fullname,
const char *  description,
int  addbefore 

◆ simage_remove_saver()

void simage_remove_saver ( void *  handle)

◆ simage_get_num_savers()

int simage_get_num_savers ( void  )

◆ simage_get_saver_handle()

void* simage_get_saver_handle ( int  idx)

◆ simage_get_saver_extensions()

const char* simage_get_saver_extensions ( void *  handle)

◆ simage_get_saver_fullname()

const char* simage_get_saver_fullname ( void *  handle)

◆ simage_get_saver_description()

const char* simage_get_saver_description ( void *  handle)

◆ s_image_create()

s_image* s_image_create ( int  w,
int  h,
int  components,
unsigned char *  prealloc 

◆ s_image_destroy()

void s_image_destroy ( s_image image)

◆ s_image_width()

int s_image_width ( s_image image)

◆ s_image_height()

int s_image_height ( s_image image)

◆ s_image_components()

int s_image_components ( s_image image)

◆ s_image_data()

unsigned char* s_image_data ( s_image image)

◆ s_image_set()

void s_image_set ( s_image image,
int  w,
int  h,
int  components,
unsigned char *  data,
int  copydata 

◆ s_image_load()

s_image* s_image_load ( const char *  filename,
s_image prealloc 

◆ s_image_save()

int s_image_save ( const char *  filename,
s_image image,
s_params params 

◆ s_movie_open()

s_movie* s_movie_open ( const char *  filename)

◆ s_movie_create()

s_movie* s_movie_create ( const char *  filename,
s_params params 

Will create a new move file named filename and attempt to locate a suitable encoder based on the parameters ( params ) supplied.

Returns a pointer to the opened movie on success, NULL on failure

Common parameters:

  • "mime-type" <string> : The requested encoder type. There are currently 2 encoders available, with mime-types "video/mpeg" and "video/avi".
  • width <int> : Frame width (all input images must have this width)
  • height <int> : Frame height (all input images must have this height)

Parameters specific for the AVI encoder

  • fps <int> : Number of frames per second in output file
  • parameter file <int> : If this parameter is missing (or empty ""), a GUI will pop up each time this functions is run, asking the user to specify compression settings. If a filename is specified and the file doesn't exist, a GUI pops up, and the compression settings are saved in a new file with the specified filename. If the file exists, no GUI pops up, and the compression settings are read from the file. The format of the file is unspecified, and copying such a file between different computers probably won't work.
  • width and height must be divisible by 4

◆ s_movie_get_image()

s_image* s_movie_get_image ( s_movie movie,
s_image prealloc,
s_params params 

◆ s_movie_put_image()

int s_movie_put_image ( s_movie movie,
s_image image,
s_params params 

Adds (encodes) the image as one frame to the movie. params is currently used only for optimizing AVI encoding: - "allow image modification" <int> : Set to "1" to allow the encoder to modify the image buffer. If this parameter is not set, the encoder will make a local copy of the image before it is encoded.

Example code:

s_params *imgparams = s_params_create();
"allow image modification", S_INTEGER_PARAM_TYPE, 1,
for(;;) {
s_image_set(image, width, height, 1, <get image from somewhere>);
for (int i=0; i<repeatCount;i++)
s_movie_put_image(movie, image, imgparams);

Returns 1 on success, 0 on failure

◆ s_movie_close()

void s_movie_close ( s_movie movie)

Closes the newly created movie file.

◆ s_movie_destroy()

void s_movie_destroy ( s_movie movie)

Cleans up all resources allocated by "<s_movie_create>"(...)

◆ s_movie_importer_add()

void s_movie_importer_add ( s_movie_open_func open,
s_movie_get_func get,
s_movie_close_func close 

◆ s_movie_exporter_add()

void s_movie_exporter_add ( s_movie_create_func create,
s_movie_put_func put,
s_movie_close_func close 

◆ s_params_create()

s_params* s_params_create ( void  )

◆ s_params_copy()

s_params* s_params_copy ( s_params params)

◆ s_params_destroy()

void s_params_destroy ( s_params params)

◆ s_params_set()

void s_params_set ( s_params params,

◆ s_params_get()

int s_params_get ( s_params params,

◆ simage_resize3d()

unsigned char* simage_resize3d ( unsigned char *  imagedata,
int  width,
int  height,
int  numcomponents,
int  layers,
int  newwidth,
int  newheight,
int  newlayers 

Returned image buffer must be freed by simage_free_image()

◆ s_stream_open()

s_stream* s_stream_open ( const char *  filename,
s_params params 

◆ s_stream_create()

s_stream* s_stream_create ( const char *  filename,
s_params params 

◆ s_stream_get_buffer()

void* s_stream_get_buffer ( s_stream stream,
void *  prealloc,
int *  size,
s_params params 

◆ s_stream_put_buffer()

int s_stream_put_buffer ( s_stream stream,
void *  buffer,
int  size,
s_params params 

◆ s_stream_close()

void s_stream_close ( s_stream stream)

◆ s_stream_destroy()

void s_stream_destroy ( s_stream stream)

◆ s_stream_params()

s_params* s_stream_params ( s_stream stream)

◆ s_stream_importer_add()

void s_stream_importer_add ( s_stream_open_func open,
s_stream_get_func get,
s_stream_close_func close 

◆ s_stream_exporter_add()

void s_stream_exporter_add ( s_stream_create_func create,
s_stream_put_func put,
s_stream_close_func close 

◆ s_stream_seek()

int s_stream_seek ( s_stream stream,
int  offset,
int  whence,
s_params params 

◆ s_stream_tell()

int s_stream_tell ( s_stream stream,
s_params params 

◆ s_stream_importer_add_ex()

void s_stream_importer_add_ex ( s_stream_open_func open,
s_stream_get_func get,
s_stream_seek_func seek,
s_stream_tell_func tell,
s_stream_close_func close 

◆ s_stream_exporter_add_ex()

void s_stream_exporter_add_ex ( s_stream_create_func create,
s_stream_put_func put,
s_stream_seek_func seek,
s_stream_tell_func tell,
s_stream_close_func close 

◆ s_image_set_component_order()

int s_image_set_component_order ( s_image image,
int  order 

◆ s_image_get_component_order()

int s_image_get_component_order ( s_image image)

◆ s_image_open()

s_image* s_image_open ( const char *  file,
int  oktoreadall 

◆ s_image_read_line()

int s_image_read_line ( s_image image,
int  line,
unsigned char *  buf 

◆ s_set_dynamic_loader_interface()

void s_set_dynamic_loader_interface ( s_dlopen_func dlopen,
s_dlsym_func dlsym,
s_dlclose_func dlclose