simage.h File Reference

Windows specific information. More...

Go to the source code of this file.

Data Structures
struct	simage_plugin

Macros
#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

Typedefs
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_image *	s_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)

Enumerations
enum	{   S_INTEGER_PARAM_TYPE, S_BOOL_PARAM_TYPE = S_INTEGER_PARAM_TYPE, S_FLOAT_PARAM_TYPE, S_DOUBLE_PARAM_TYPE,   S_STRING_PARAM_TYPE, S_POINTER_PARAM_TYPE, S_FUNCTION_PARAM_TYPE }
enum	{ SIMAGE_SEEK_SET = 0, SIMAGE_SEEK_CUR = 1, SIMAGE_SEEK_END = 2 }
enum	{ SIMAGE_ORDER_RGB = 0, SIMAGE_ORDER_BGR }

Functions
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_image *	s_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_image *	s_image_load (const char *filename, s_image *prealloc)
int	s_image_save (const char *filename, s_image *image, s_params *params)
s_movie *	s_movie_open (const char *filename)
s_movie *	s_movie_create (const char *filename, s_params *params)
s_image *	s_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_params *	s_params_create (void)
s_params *	s_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_stream *	s_stream_open (const char *filename, s_params *params)
s_stream *	s_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_params *	s_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_image *	s_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 configure.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 MSWindows 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 MSWindows platforms, or else the #error statement will 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 dropdown 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 sourcecode whether or not this file is included.

SIMAGE_VERSION_1_1

#define SIMAGE_VERSION_1_1

Version 1.1 introduced saving

SIMAGE_VERSION_1_2

#define SIMAGE_VERSION_1_2

Version 1.2 added a new API, and support for movies

SIMAGE_VERSION_1_3

#define SIMAGE_VERSION_1_3

Version 1.3 added simage_resize3d

SIMAGE_VERSION_1_4

#define SIMAGE_VERSION_1_4

Version 1.4 added API for stream I/O

SIMAGE_VERSION_1_5

#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

SIMAGE_VERSION_1_6

#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

Enumerator
S_INTEGER_PARAM_TYPE
S_BOOL_PARAM_TYPE
S_FLOAT_PARAM_TYPE
S_DOUBLE_PARAM_TYPE
S_STRING_PARAM_TYPE
S_POINTER_PARAM_TYPE
S_FUNCTION_PARAM_TYPE

anonymous enum

anonymous enum

Enumerator
SIMAGE_SEEK_SET
SIMAGE_SEEK_CUR
SIMAGE_SEEK_END

anonymous enum

anonymous enum

Enumerator
SIMAGE_ORDER_RGB
SIMAGE_ORDER_BGR

Function Documentation

simage_version()

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

Note specifically for MSWindows 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 run-time: when using the wrong calling convention, obscure errors due to stack corruption can occur under certain (possibly rare) conditions.

Returns run-time 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 filetype. 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();
s_params_set(imgparams,
             "allow image modification", S_INTEGER_PARAM_TYPE, 1,
             NULL);
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);
}
s_params_destroy(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
	)