Introduction

Framewave (FW) is a collection of libraries that contain highly-optimized functions for use in a variety of programming domains. All implementations of the libraries provide C and C++ programmers ANSI C style interfaces.

Framewave consists of the following libraries:

Framewave functions are geared to yield maximum performance on the x86 and the AMD64 hardware architectures. Current implementations exploit multicore architecture and single instruction multiple data (SIMD) instructions. Specifically, streaming SIMD extensions and AMD® family 10h technologies are used to optimize for speed. Programmers can concentrate on task functionality because Framewave handles performance. Many of the functions are threaded internally; the programmer has the flexibility of controlling the number of threads and of turning off threading. As architecture changes and new instructions are added, new code paths to take advantage of extensions can be added to Framewave without changing the programming interface and existing functionality.

About This Manual

This documentation is intended for experienced software developers. To understand the functional descriptions, a developer must be reasonably proficient in the C programming language, and must have a working knowledge of application-specific terminology and techniques.

The documentation is divided into sections for each library. Within the sections, Basic Concepts chapters provide overview information related to the library and subsequent chapters provide detailed descriptions of the library functions.

Each detailed description consists of a Function Name followed by a short description, a Synopsis of the function syntax, a list of function Parameters, a detailed Description of the function, and a list of Return Values.

When a function is optimized for one or more technologies, a list of Supported Technologies is provided after the short description. Most function groups are optimized for the same technologies, but the lists are function-specific; the use of a particular optimization in a single function does not indicate that all the functions in the group are optimized for that technology. When no list of optimizations is present, a function has only reference code. Absence of optimizations does not mean that a function runs more slowly -- use of a particular optimization may not increase the performance of the function.

The Function Quick Reference provides an index and snapshot view of function optimizations.

Data Types

Framewave function definitions use the following data types.

Fw16s   16-bit signed integer
Fw16sc   16-bit signed complex number
Fw16u   16-bit unsigned integer
Fw32f   32-bit floating-point number
Fw32fc   32-bit floating-point complex number
Fw32s   32-bit signed integer
Fw32sc   32-bit signed complex number
Fw32u   32-bit unsigned integer
Fw64f   64-bit floating-point number
Fw64fc   64-bit floating-point complex number
Fw64s   64-bit signed integer
Fw64sc   64-bit signed complex number
Fw64u   64-bit unsigned integer
Fw8s   8-bit signed integer
Fw8u   8-bit unsigned integer

Return Value Glossary

All Framewave functions return the enumerated integer value FwStatus, which precisely reports the result of execution. The following return value definitions are used.

fwStsAnchorErr   The anchor is located outside the mask.
fwStsBadArgErr   Some argument is invalid.
fwStsBorderErr   The morphology borderType is an invalid value.
fwStsChannelOrderErr   The given destination order is not valid (contains values other than 0,1,2).
fwStsCoeffErr   The coefficient values have errors.
fwStsContextMatchErr   The specification struture does not match the function or is invalid.
fwStsCpuMismatch   The specified CPU type cannot be assigned.
fwStsDivByZeroErr   The divisor is zero.
fwStsDivisorErr   The divisor is zero.
fwStsDomain   Argument out of function domain warning status code.
fwStsDoubleSize   Image height and/or width is not a multiple of two warning status code.
fwStsEpsValErr   Eps is a negative value.
fwStsH263VLCCodeErr   Illegal Huffman code encountered during VLC stream processing.
fwStsInterpolationErr   The interpolation value is incorrect or unsupported for the specified function.
fwStsLengthErr   Invalid string length.
fwStsLnNegArg   Negative input buffer element warning status code.
fwStsLnZeroArg   Zero-valued input buffer element warning status code.
fwStsMaskErr   The mask size is invalid.
fwStsMaskSizeErr   The mask has an invalid value.
fwStsMemAllocErr   The function failed to allocate memory.
fwStsMirrorFlipErr   The mirror flip value is invalid.
fwStsNoErr   No error detected.
fwStsNotEvenStepErr   A step value for a floating point image is not divisible by four.
fwStsNullPtrErr   A pointer passed to the function is null.
fwStsNumChannelErr   The number of channels is incorrect.
fwStsOutOfRangeErr   An a rgument is out of range or a point is outside an image.
fwStsOverflow   Overflow in operation warning status code.
fwStsQuadErr   The source or destination quadrangle degenerates into a triangle, line, or points; or the destination quadrangle has conflicted vertex coordinates.
fwStsRectErr   The width or height of the source ROI has a value less than or equal to one.
fwStsResFloor   All result values are floored.
fwStsResizeFactorErr   The resize factor is less than or equal to zero.
fwStsResizeNoOperationErr   A destination image dimension is less than one pixel.
fwStsSingularity   Singularity in operation warning status code.
fwStsSizeErr   The size is invalid (usually indicates negative or zero size).
fwStsStepErr   The step value for the buffer is invalid.
fwStsThresholdErr   The less-than threshold is greater than the greater-than threshold.
fwStsUnderflow   Underflow in operation warning status code.
fwStsWrongIntersectQuad   The quadrangle does not intersect the source or destination image (no operation is performed).
fwStsWrongIntersectROI   The ROI does not intersect the source or destination image (no operation is performed).
fwStsZeroMaskValuesErr   All mask values are equal to zero.

Refer to individual function descriptions for detailed information about return values.

Processing Operators

Framewave function definitions use the following notation to indicate specific operations.

I   Function operates in-place (source and destination locations are the same)
R   Function operates on an ROI (iterative, used only in the Image Processing library)
M   Function performs a masking operation
Sfs   Function performs a scaled integer calculation

References

AMD64 Architecture Programmers Manual:

Volume 1, Application Programming, Order Number 24592

Volume 2, System Programming, Order Number 24593

Volume 3, General-Purpose and System Instructions, Order Number 24594

Volume 4, 128-Bit Media Instructions, Order Number 26568

Volume 5, 64-Bit Media and x87 Floating-Point Instructions, Order Number 26569