arUtil.c File Reference

#include <ARX/AR/ar.h>
#include <math.h>
#include <ctype.h>
#include <unistd.h>
#include <sys/param.h>
#include <pthread.h>
#include <ARX/ARUtil/file_utils.h>

Include dependency graph for arUtil.c:

Macros
#define	_GNU_SOURCE

Functions
ARUint32	arGetVersion (char **versionStringRef)
	Get the artoolkitX version information in numberic and string format. More...
int	arUtilGetSquareCenter (ARdouble vertex[4][2], ARdouble *x, ARdouble *y)
int	arUtilMatMul (const ARdouble s1[3][4], const ARdouble s2[3][4], ARdouble d[3][4])
int	arUtilMatMuldff (const ARdouble s1[3][4], const float s2[3][4], float d[3][4])
int	arUtilMatMulf (const float s1[3][4], const float s2[3][4], float d[3][4])
int	arUtilMatInv (const ARdouble s[3][4], ARdouble d[3][4])
int	arUtilMatInvf (const float s[3][4], float d[3][4])
int	arUtilMat2QuatPos (const ARdouble m[3][4], ARdouble q[4], ARdouble p[3])
int	arUtilQuatPos2Mat (const ARdouble q[4], const ARdouble p[3], ARdouble m[3][4])
int	arUtilQuatNorm (ARdouble q[4])
int	arUtilGetPixelSize (const AR_PIXEL_FORMAT arPixelFormat)
	Get the size in bytes of a single pixel for a given pixel format. More...
const char *	arUtilGetPixelFormatName (const AR_PIXEL_FORMAT arPixelFormat)
	Get a string holding a descriptive name for a given pixel format enumeration. More...
const char *	arUtilGetFileNameFromPath (const char *path)
char *	arUtilGetFileBasenameFromPath (const char *path, const int convertToLowercase)
	Get file base name from a path. More...
char *	arUtilGetFileExtensionFromPath (const char *path, const int convertToLowercase)
	Get file extension from a path. More...
char *	arUtilGetDirectoryNameFromPath (char *dir, const char *path, const size_t n, const int addSeparator)
char *	arUtilGetFileURI (const char *path)
	Get a path as a file URI. More...
char *	arUtilGetResourcesDirectoryPath (AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR behavior)
	Get the path to the resources directory using the specified behavior. More...
char *	arUtilGetAndCreateResourcesDirectoryPath (AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR behavior)
	Get the path to the resources directory using the specified behavior, creating the path if it doesn't already exist. More...
int	arUtilChangeToResourcesDirectory (AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR behavior, const char *path)
	Change to the resources directory using the specified behavior. More...
int	arUtilReplaceExt (char *filename, int n, char *ext)
int	arUtilRemoveExt (char *filename)
int	arUtilDivideExt (const char *filename, char *s1, char *s2)
void	arUtilPrintTransMat (const ARdouble trans[3][4])
	Prints a transformation matrix via ARPRINT(...). More...
void	arUtilPrintMtx16 (const ARdouble mtx16[16])
	Prints a 4x4 row-major matrix via ARPRINT(...). More...

Macro Definition Documentation

_GNU_SOURCE

#define _GNU_SOURCE

Function Documentation

arGetVersion()

ARUint32 arGetVersion

(

char **

versionStringRef

)

Get the artoolkitX version information in numberic and string format.

@functiongroup "Utility".

As of version 2.72, ARToolKit now allows querying of the version number of the toolkit available at runtime. It is highly recommended that any calling program that depends on features in a certain artoolkitX version, check at runtime that it is linked to a version of artoolkitX that can supply those features. It is NOT sufficient to check the artoolkitX SDK header versions, since with artoolkitX implemented in dynamically-loaded libraries, there is no guarantee that the version of artoolkitX installed on the machine at run-time will be as recent as the version of the artoolkitX SDK which the host program was compiled against.

The version information is reported in binary-coded decimal format, and optionally in an ASCII string.

A increase in the major version number indicates the removal of functionality previously provided in the API. An increase in the minor version number indicates that new functionality has been added. A change in the tiny version number indicates changes (e.g. bug fixes) which do not affect the API. See the comments in the config.h header for more discussion of the definition of major, minor, tiny and build version numbers.

Parameters

versionStringRef

If non-NULL, the location pointed to will be filled with a pointer to a string containing the version information. Fields in the version string are separated by spaces. As of version 2.72.0, there is only one field implemented, and this field contains the major, minor and tiny version numbers in dotted-decimal format. The string is guaranteed to contain at least this field in all future versions of the toolkit. Later versions of the toolkit may add other fields to this string to report other types of version information. The storage for the string is malloc'ed inside the function. The caller is responsible for free'ing the string.

Returns

Returns the full version number of the artoolkitX in binary coded decimal (BCD) format. BCD format allows simple tests of version number in the caller e.g. if ((arGetVersion(NULL) >> 16) > 0x0272) printf("This release is later than 2.72\n"); The major version number is encoded in the most-significant byte (bits 31-24), the minor version number in the second-most-significant byte (bits 23-16), the tiny version number in the third-most-significant byte (bits 15-8), and the build version number in the least-significant byte (bits 7-0).

arUtilChangeToResourcesDirectory()

int arUtilChangeToResourcesDirectory	(	AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR	behavior,
		const char *	path
	)

Change to the resources directory using the specified behavior.

artoolkitX uses relative paths to locate several types of resources, including camera parameter files, pattern files, multimarker files and others. This function provides the convenience of setting the current process working directory to the appropriate value for your application.

On Android only, the function has an optional parameter 'instanceOfAndroidContext'. If behavior is AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_APP_CACHE_DIR, this parameter must be an instance of a class derived from android/content/Context. In all other cases, pass NULL for this parameter.

Parameters

behavior	See AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR type for allowed values.
path	When behavior is AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_SUPPLIED_PATH, the path to change to (absolute or relative to current working directory). In all other cases, if this parameter is non-NULL, it will be taken as a subdirectory of the desired path and to which the working directory should be changed.

Returns

-1 in the case of error, or 0 otherwise.

Since

Not available on Windows Runtime (WinRT).

Here is the call graph for this function:

arUtilDivideExt()

int arUtilDivideExt	(	const char *	filename,
		char *	s1,
		char *	s2
	)

arUtilGetAndCreateResourcesDirectoryPath()

char * arUtilGetAndCreateResourcesDirectoryPath

(

AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR

behavior

)

Get the path to the resources directory using the specified behavior, creating the path if it doesn't already exist.

artoolkitX uses relative paths to locate several types of resources, including camera parameter files, pattern files, multimarker files and others. This function provides the convenience of finding an appropriate value for your application.

On Android only, the function has an optional parameter 'instanceOfAndroidContext'. If behavior is AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_APP_CACHE_DIR, this parameter must be an instance of a class derived from android/content/Context. In all other cases, pass NULL for this parameter.

Parameters

behavior

See AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR type for allowed values.

Returns

NULL in the case of error, or the path otherwise. Must be free()d by the caller.

Here is the call graph for this function:

arUtilGetDirectoryNameFromPath()

char * arUtilGetDirectoryNameFromPath	(	char *	dir,
		const char *	path,
		const size_t	n,
		const int	addSeparator
	)

arUtilGetFileBasenameFromPath()

char * arUtilGetFileBasenameFromPath	(	const char *	path,
		const int	convertToLowercase
	)

Get file base name from a path.

Given a full or partial pathname passed in string path, returns a string with the base name portion of path, i.e. the text between the rightmost path separator and the the rightmost '.' character, if any. If the filename contains no '.', returns the filename.

Parameters

path	Full or partial pathname.
convertToLowercase	If convertToLowercase is TRUE, uppercase ASCII characters in the basename will be converted to lowercase.

Returns

A string with the basename portion of path. NB: The returned string must be freed by the caller.

Here is the call graph for this function:

arUtilGetFileExtensionFromPath()

char * arUtilGetFileExtensionFromPath	(	const char *	path,
		const int	convertToLowercase
	)

Get file extension from a path.

Given a full or partial pathname passed in string path, returns a string with the extension portion of path, i.e. the text after the rightmost '.' character, if any. If the filename contains no '.', NULL is returned.

Parameters

path	Full or partial pathname.
convertToLowercase	If convertToLowercase is TRUE, uppercase ASCII characters in the extension will be converted to lowercase.

Returns

A string with the extension portion of path. NB: The returned string must be freed by the caller.

Here is the call graph for this function:

arUtilGetFileNameFromPath()

const char * arUtilGetFileNameFromPath

(

const char *

path

)

arUtilGetFileURI()

char * arUtilGetFileURI

(

const char *

path

)

Get a path as a file URI.

Given a full or partial pathname passed in string path, returns a string with the file URI for that path.

Partial pathnames are handled by concatening with the process's current working directory.

Parameters

path	Full or partial pathname. On Windows, both partial pathnames, full pathnames including the drive letter, or UNC pathnames (beginning with "\\" are all OK.

Returns

A string with the the file URI for that path, or NULL in the case of error. NB: The returned string must be freed by the caller (by calling free() once its use is complete).

arUtilGetPixelFormatName()

const char * arUtilGetPixelFormatName

(

const AR_PIXEL_FORMAT

arPixelFormat

)

Get a string holding a descriptive name for a given pixel format enumeration.

On occasions it can be useful to display to the user the format of the pixels which artoolkitX is processing. This funtion converts a pixel-format number into a human-readable string description.

Parameters

arPixelFormat

Enumerated pixel format number for which to retrieve a name.

Returns

A constant c-string holding a descriptive name for the pixel format. The string returned matches the constants used in the definition of the type AR_PIXEL_FORMAT, e.g. "AR_PIXEL_FORMAT_RGB".

arUtilGetPixelSize()

int arUtilGetPixelSize

(

const AR_PIXEL_FORMAT

arPixelFormat

)

Get the size in bytes of a single pixel for a given pixel format.

Different pixel formats have different sizes in bytes, and therefore different storage requirements per row of pixels. Use this function to calculate the number of bytes required to store a single pixel of the given type.

Parameters

arPixelFormat

The pixel type whose size is to be measured.

Returns

Number of bytes required to store 1 pixel of the given type.

arUtilGetResourcesDirectoryPath()

char * arUtilGetResourcesDirectoryPath

(

AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR

behavior

)

Get the path to the resources directory using the specified behavior.

artoolkitX uses relative paths to locate several types of resources, including camera parameter files, pattern files, multimarker files and others. This function provides the convenience of finding an appropriate value for your application.

On Android only, the function has an optional parameter 'instanceOfAndroidContext'. If behavior is AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_APP_CACHE_DIR, this parameter must be an instance of a class derived from android/content/Context. In all other cases, pass NULL for this parameter.

Parameters

behavior

See AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR type for allowed values.

Returns

NULL in the case of error, or the path otherwise. Must be free()d by the caller.

Here is the call graph for this function:

arUtilGetSquareCenter()

int arUtilGetSquareCenter	(	ARdouble	vertex[4][2],
		ARdouble *	x,
		ARdouble *	y
	)

arUtilMat2QuatPos()

int arUtilMat2QuatPos	(	const ARdouble	m[3][4],
		ARdouble	q[4],
		ARdouble	p[3]
	)

arUtilMatInv()

int arUtilMatInv	(	const ARdouble	s[3][4],
		ARdouble	d[3][4]
	)

Here is the call graph for this function:

arUtilMatInvf()

int arUtilMatInvf	(	const float	s[3][4],
		float	d[3][4]
	)

Here is the call graph for this function:

arUtilMatMul()

int arUtilMatMul	(	const ARdouble	s1[3][4],
		const ARdouble	s2[3][4],
		ARdouble	d[3][4]
	)

arUtilMatMuldff()

int arUtilMatMuldff	(	const ARdouble	s1[3][4],
		const float	s2[3][4],
		float	d[3][4]
	)

arUtilMatMulf()

int arUtilMatMulf	(	const float	s1[3][4],
		const float	s2[3][4],
		float	d[3][4]
	)

arUtilPrintMtx16()

void arUtilPrintMtx16

(

const ARdouble

mtx16[16]

)

Prints a 4x4 row-major matrix via ARPRINT(...).

Parameters

mtx16

The matrix to print.

arUtilPrintTransMat()

void arUtilPrintTransMat

(

const ARdouble

trans[3][4]

)

Prints a transformation matrix via ARPRINT(...).

Parameters

trans

The transformation matrix to print.

arUtilQuatNorm()

int arUtilQuatNorm

(

ARdouble

q[4]

)

arUtilQuatPos2Mat()

int arUtilQuatPos2Mat	(	const ARdouble	q[4],
		const ARdouble	p[3],
		ARdouble	m[3][4]
	)

arUtilRemoveExt()

int arUtilRemoveExt

(

char *

filename

)

arUtilReplaceExt()

int arUtilReplaceExt	(	char *	filename,
		int	n,
		char *	ext
	)