muPP API Reference
This reference describes the muPP image-processing APIs available in MUSA SDK 5.2. It explains the shared conventions and type system first, then groups the supported functions by image-processing task so you can find the APIs you need more quickly.
1. Introduction
1.1 What Is muPP
muPP is the MUSA library for GPU-accelerated image-processing and signal-processing primitives. It provides reusable operations for common pixel arithmetic, color conversion, data movement, filtering, geometry transforms, statistics, thresholding, and image memory-management workflows on MUSA devices.
Applications can use muPP as a standalone library from host code or combine muPP primitives with application-managed MUSA kernels in the same workflow. In both cases, the library provides prebuilt processing routines while the application retains control of buffer allocation, ROI selection, and stream usage.
The public interface is divided into image-processing APIs with the muppi* prefix and signal-processing APIs with the mupps* prefix.
1.2 Public Header Organization
The umbrella header mupp.h exposes the overall muPP interface. The image-processing declarations are grouped under muppi.h, the signal-processing declarations are grouped under mupps.h, and shared types, enums, constants, and common declarations are defined in muppdefs.h and muppcore.h.
This layout lets applications include the full umbrella header or work from the image and signal layers separately, depending on integration style and scope.
1.3 API Scope in MUSA SDK 5.2
The public headers contain both image-processing and signal-processing declarations. This reference describes the image-processing APIs in MUSA SDK 5.2. The documented entries use the muppi* prefix and cover arithmetic, color conversion, data exchange, filtering, geometry transforms, linear transforms, morphology, statistics, threshold and comparison operations, and image memory management.
Signal-processing declarations from mupps.h remain part of the public headers, but they are not described in this reference for MUSA SDK 5.2.
Use this reference to find the muPP functions, shared types, structures, enums, constants, parameters, and status values that are supported in MUSA SDK 5.2.
Note: Some muPP declarations may appear in the public headers but are not described in this reference. For MUSA SDK 5.2, rely on the APIs documented here when checking the supported muPP reference scope.
1.4 How to Use This Document
Start with Chapter 2 for naming, memory, scaling, and rounding rules. Use Chapter 3 for ROI, layout, in-place, context, and status conventions. Use Chapter 4 for the shared type layer used across the image APIs. Use Chapter 5 to navigate the exact function entries by image-processing domain.
2. General Conventions
2.1 Memory Management
The muPP image APIs in this reference operate on MUSA device memory. Source, destination, mask, and auxiliary pointers identify device-resident data unless an exact entry states otherwise. Line-step parameters such as nSrcStep, nDstStep, and nMaskStep are byte strides between consecutive image rows, not element counts.
Some families also require temporary device work buffers such as pDeviceBuffer, while companion helper routines with names such as GetBufferSize and GetBufferHostSize report the required workspace size through host output parameters. The image memory-management helpers in Chapter 5.10 allocate image storage and return the computed step size. Other APIs in this reference assume that the caller has already allocated valid device buffers and passes ROI and step values that match the selected image layout.
2.2 Function Naming
Most image APIs in this reference follow a pattern such as muppi<operation>_<data type or conversion>_<layout and access>[_Ctx]. The muppi prefix identifies the image-processing layer. The middle tokens describe the numeric type or conversion path, and the trailing tokens describe the channel layout, destination behavior, and optional execution-context form.
The API names therefore appear as forms such as muppiCopy_8u_C1R, muppiCopy_8u_C1R_Ctx, muppiSwapChannels_32f_C4IR, and muppiColorTwistBatch32f_8u_C3R.
Common suffix elements used throughout this reference include:
8u,16u,16s,32s,32f,32fc, and similar numeric tokens for operand or result data typesC1,C3, andC4for packed one-channel, three-channel, and four-channel imagesAC4for four-channel layouts in which the alpha channel is preserved but not processedP2,P3, andP4for planar two-plane, three-plane, and four-plane image layoutsRfor operations that write a separate destination imageIRfor in-place operations that overwrite the destination bufferMRfor masked variants_Ctxfor variants that take an application-managedMUppStreamContext
These suffixes are part of the API names. They are not shorthand in this document and should be read as part of the exact function identity.
2.3 Integer Result Scaling
Some muPP image APIs use scaled fixed-point or integer output conventions. In these routines, a parameter such as nScaleFactor controls how intermediate results are scaled before they are converted back to the destination integer type. This usually appears either as an explicit scale-factor parameter or as an Sfs marker in the function name, as in muppiRectStdDev_32s_C1RSfs.
When a family description or parameter list includes a scale factor, use the scaling rule documented by that exact API entry. Do not assume that floating-point and integer variants in the same family use identical rounding or saturation behavior.
2.4 Rounding Modes
Image APIs that convert or rescale numeric values can depend on the MUppRoundMode enum. The shared rounding modes in Chapter 4 include round-to-nearest-even, round-to-nearest-away-from-zero, and round-toward-zero semantics, together with the short legacy spellings and the longer IEEE-754-style alias names exposed by the public enum.
When an exact API family exposes a rounding-mode parameter, use the enum value defined in Chapter 4 and the specific conversion rule stated by that API entry.
3. Image Processing Conventions
3.1 ROI and Step Conventions
Most muPP image APIs operate on a rectangular region of interest described by MUppiSize, MUppiRect, or both. Common parameter names include oSizeROI for the active width and height, oSrcROI or oRect for a source rectangle, and oSrcSize when the full source image size is needed to interpret a sub-rectangle. The line-step parameters are byte strides, not element counts. They describe the distance from the first byte of one image row to the first byte of the next row.
For packed images, the ROI width and height describe the logical image extent while the step describes the physical storage stride. For planar images, each plane uses its own pointer and step, but the same ROI convention applies unless the exact API states otherwise. Batched geometry families can also carry ROI data through descriptor structures such as MUppiResizeBatchROI_Advanced.
3.2 Channel Layout and Packed or Planar Layout
Packed layouts store channel data interleaved in memory. Planar layouts store each channel in a separate plane. The channel suffixes in the function name identify which layout the API expects.
C1,C3,C4, andAC4indicate packed channel layoutsP2,P3, andP4indicate planar or semi-planar layouts with two, three, or four planesAC4means the alpha channel is preserved but not processed- mixed suffixes such as
C3P3R,P3C3R,C1C3R, andP2C3Rindicate conversion between different channel organizations
Use the exact name suffix to determine whether an API expects packed, planar, or mixed packed-planar input and output buffers.
3.3 Coefficient Matrix Formats
Some muPP image APIs and batch descriptors take coefficient arrays rather than pixel buffers. These coefficient arrays have fixed public shapes and should be passed in the exact format named by the API or structure field.
Affine transform utilities and batched affine descriptors use (2 \times 3) coefficient arrays such as aCoeffs[2][3], pCoeffs, and aTransformedCoeffs[2][3]:
Perspective transform utilities, perspective warp routines, and batched perspective descriptors use (3 \times 3) coefficient arrays such as aCoeffs[3][3], pCoeffs, and aTransformedCoeffs[3][3]:
Color-twist batch descriptors carry per-image twist matrices through MUppiColorTwistBatchCXR::pTwist. The 4-channel constant-vector variants use a (4 \times 5) matrix:
where (s_i) are source channels and (d_i) are destination channels. For lower-channel color-twist variants, the public descriptions state that the full twist matrix can still be supplied and the API uses the coefficients that match the corresponding pixel format.
3.4 In-Place and Masked Variants
Functions ending in IR update a destination image in place. Functions ending in MR apply the operation only where the mask condition is satisfied. When both source and destination pointers appear, use separate non-overlapping buffers unless the exact entry is explicitly an in-place variant.
Masked variants typically add a mask pointer and sometimes a mask step. The mask layout and ROI follow the same image and step conventions as the main image operands unless the exact API entry states a narrower rule.
3.5 Context Variants and Execution Context
Many muPP image APIs are available both as a base form and as a _Ctx form. The _Ctx form adds a MUppStreamContext argument so that the application can provide an explicit execution context.
When both variants are present, they describe the same operation. The _Ctx form simply makes the execution context explicit. The MUppStreamContext structure defined in Chapter 4 carries the stream handle, device identity, and device capability fields used to bind the call to the intended execution environment. Use the matching variant consistently within an application so that stream and device attributes remain aligned with the image buffers being processed.
3.6 Error Handling and Return Status
Most muPP image APIs in this reference return MUppStatus. A return value of MUPP_NO_ERROR indicates success. Other return values report invalid pointers, bad ROI or step information, unsupported modes, allocation failures, execution failures, and other image-processing errors defined by the shared MUppStatus enum in Chapter 4.
The image memory-management helpers are an exception because the muppiMalloc_* families return typed image pointers directly and report the computed line step through an output parameter.
Image Data Related Error Codes
This is a documentation category for common MUppStatus values related to image pointers, image storage, line steps, channel layout, data type, alignment, memory allocation, and image-kernel execution. It is not a separate enum. See the MUppStatus enum for the complete status list.
Common statuses in this category include MUPP_INVALID_HOST_POINTER_ERROR, MUPP_INVALID_DEVICE_POINTER_ERROR, MUPP_NULL_POINTER_ERROR, MUPP_STEP_ERROR, MUPP_STRIDE_ERROR, MUPP_ALIGNMENT_ERROR, MUPP_DATA_TYPE_ERROR, MUPP_CHANNEL_ERROR, MUPP_NUMBER_OF_CHANNELS_ERROR, MUPP_CHANNEL_ORDER_ERROR, MUPP_SIZE_ERROR, MUPP_MEMORY_ALLOCATION_ERR, MUPP_NO_MEMORY_ERROR, and MUPP_MUSA_KERNEL_EXECUTION_ERROR.
ROI Related Error Codes
This is a documentation category for common MUppStatus values related to region-of-interest sizes, rectangles, source/destination intersections, masks, anchors, and geometry extents. It is not a separate enum. See the MUppStatus enum for the complete status list.
Common statuses in this category include MUPP_SIZE_ERROR, MUPP_RECTANGLE_ERROR, MUPP_WRONG_INTERSECTION_ROI_ERROR, MUPP_RESIZE_NO_OPERATION_ERROR, MUPP_RESIZE_FACTOR_ERROR, MUPP_INTERPOLATION_ERROR, MUPP_ANCHOR_ERROR, MUPP_MASK_SIZE_ERROR, MUPP_WRONG_INTERSECTION_ROI_WARNING, and MUPP_MISALIGNED_DST_ROI_WARNING.
4. Data Types, Structs, Enums, and Constants
Use this chapter to decode the shared signature elements before you enter the long API reference. It groups the public muPP type layer into numeric types, ROI geometry, execution and batch descriptors, shared enums, and constants that recur throughout the muPP image APIs described in this reference.
4.1 Scalar and Packed Numeric Types
These scalar, packed, and complex numeric types appear directly in the muPP image API signatures described in this reference.
MUpp8u
- Kind:
typedef
typedef unsigned char MUpp8u
Details
- 8-bit unsigned chars
MUpp8s
- Kind:
typedef
typedef signed char MUpp8s
Details
- 8-bit signed chars
MUpp16u
- Kind:
typedef
typedef unsigned short MUpp16u
Details
- 16-bit unsigned integers
MUpp16s
- Kind:
typedef
typedef short MUpp16s
Details
- 16-bit signed integers
MUpp32u
- Kind:
typedef
typedef unsigned int MUpp32u
Details
- 32-bit unsigned integers
MUpp32s
- Kind:
typedef
typedef int MUpp32s
Details
- 32-bit signed integers
MUpp64u
- Kind:
typedef
typedef unsigned long long MUpp64u
Details
- 64-bit unsigned integers
MUpp64s
- Kind:
typedef
typedef long long MUpp64s
Details
- 64-bit signed integers
MUpp32f
- Kind:
typedef
typedef float MUpp32f
Details
- 32-bit (IEEE) floating-point numbers
MUpp64f
- Kind:
typedef
typedef double MUpp64f
Details
- 64-bit floating-point numbers
MUpp16f
- Compound name:
MUpp16f - Compound kind:
struct
Public Attrib
fp16
- Kind:
variable
short MUpp16f::fp16
MUpp16f_2
- Compound name:
MUpp16f_2 - Compound kind:
struct
Public Attrib
fp16_0
- Kind:
variable
short MUpp16f_2::fp16_0
fp16_1
- Kind:
variable
short MUpp16f_2::fp16_1
MUpp32uc
- Compound name:
MUpp32uc - Compound kind:
struct
Overview
- Complex Number This struct represents an unsigned int complex number.
Public Attrib
re
- Kind:
variable
MUpp32u MUpp32uc::re
Details
- Real part
im
- Kind:
variable
MUpp32u MUpp32uc::im
Details
- Imaginary part
MUpp32sc
- Compound name:
MUpp32sc - Compound kind:
struct
Overview
- Complex Number This struct represents a signed int complex number.
Public Attrib
re
- Kind:
variable
MUpp32s MUpp32sc::re
Details
- Real part
im
- Kind:
variable
MUpp32s MUpp32sc::im
Details
- Imaginary part
MUpp32fc
- Compound name:
MUpp32fc - Compound kind:
struct
Overview
- Complex Number This struct represents a single floating-point complex number.
Public Attrib
re
- Kind:
variable
MUpp32f MUpp32fc::re
Details
- Real part
im
- Kind:
variable
MUpp32f MUpp32fc::im
Details
- Imaginary part
MUpp64sc
- Compound name:
MUpp64sc - Compound kind:
struct
Overview
- Complex Number This struct represents a long long complex number.
Public Attrib
re
- Kind:
variable
MUpp64s MUpp64sc::re
Details
- Real part
im
- Kind:
variable
MUpp64s MUpp64sc::im
Details
- Imaginary part
MUpp64fc
- Compound name:
MUpp64fc - Compound kind:
struct
Overview
- Complex Number This struct represents a double floating-point complex number.
Public Attrib
re
- Kind:
variable
MUpp64f MUpp64fc::re
Details
- Real part
im
- Kind:
variable
MUpp64f MUpp64fc::im
Details
- Imaginary part
4.2 Geometry and ROI Structures
The following structures define points, sizes, and rectangles used across image ROI, geometry, and neighborhood-based APIs.
MUppiPoint
- Compound name:
MUppiPoint - Compound kind:
struct
Overview
- 2D Point
Public Attrib
x
- Kind:
variable
int MUppiPoint::x
Details
- x-coordinate.
y
- Kind:
variable
int MUppiPoint::y
Details
- y-coordinate.
MUppiSize
- Compound name:
MUppiSize - Compound kind:
struct
Overview
- 2D Size This struct typically represents the size of a a rectangular region in two space.
Public Attrib
width
- Kind:
variable
int MUppiSize::width
Details
- Rectangle width.
height
- Kind:
variable
int MUppiSize::height
Details
- Rectangle height.
MUppiRect
- Compound name:
MUppiRect - Compound kind:
struct
Overview
- 2D Rectangle This struct contains position and size information of a rectangle in two space. The rectangle's position is usually signified by the coordinate of its upper-left corner.
Public Attrib
x
- Kind:
variable
int MUppiRect::x
Details
- x-coordinate of upper left corner (lowest memory address).
y
- Kind:
variable
int MUppiRect::y
Details
- y-coordinate of upper left corner (lowest memory address).
width
- Kind:
variable
int MUppiRect::width
Details
- Rectangle width.
height
- Kind:
variable
int MUppiRect::height
Details
- Rectangle height.
4.3 Execution Context and Batch Descriptor Structures
The following structures appear in _Ctx variants, batched transforms, and image- or buffer-descriptor-based helpers.
MUppStreamContext
- Compound name:
MUppStreamContext - Compound kind:
struct
Overview
- MUPP stream context structure must be filled in by application. Application should not initialize or alter reserved fields.
Public Attrib
hStream
- Kind:
variable
musaStream_t MUppStreamContext::hStream
nMusaDeviceId
- Kind:
variable
int MUppStreamContext::nMusaDeviceId
nMultiProcessorCount
- Kind:
variable
int MUppStreamContext::nMultiProcessorCount
nMaxThreadsPerMultiProcessor
- Kind:
variable
int MUppStreamContext::nMaxThreadsPerMultiProcessor
nMaxThreadsPerBlock
- Kind:
variable
int MUppStreamContext::nMaxThreadsPerBlock
nSharedMemPerBlock
- Kind:
variable
size_t MUppStreamContext::nSharedMemPerBlock
nMusaDevAttrComputeCapabilityMajor
- Kind:
variable
int MUppStreamContext::nMusaDevAttrComputeCapabilityMajor
nMusaDevAttrComputeCapabilityMinor
- Kind:
variable
int MUppStreamContext::nMusaDevAttrComputeCapabilityMinor
nStreamFlags
- Kind:
variable
unsigned int MUppStreamContext::nStreamFlags
nReserved0
- Kind:
variable
int MUppStreamContext::nReserved0