Reorders the channels and overwrites the pixels of one or more planes of an ARGB8888 image.


vImage_Error vImagePermuteChannelsWithMaskedInsert_ARGB8888(const vImage_Buffer *src, const vImage_Buffer *dest, const uint8_t permuteMap[4], uint8_t copyMask, const Pixel_8888 backgroundColor, vImage_Flags flags);



A pointer to a vImage buffer structure that contains the source image whose data you want to permute.


A pointer to a vImage buffer data structure. You're responsible for filling out the height, width, and rowBytes fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer this structure points to contains the destination image data. When you no longer need the data buffer, you must deallocate the memory.


An array of four 8-bit integers with the values 0, 1, 2, and 3, in some order. Each value specifies a plane from the source image that should be copied to that plane in the destination image. 0 denotes the alpha channel, 1 the red channel, 2 the green channel, and 3 the blue channel.


An output value that selects the plane (or planes) from the ARGB8888 source buffer that you want replaced with the scalar value. The value 0x8 selects the alpha channel, 0x4 the red channel, 0x2 the green channel, and 0x1 the blue channel. You can add these values together to select multiple channels.


A pointer to 8-bit ARGB values that replace the result pixels based on the copyMask value.


The options to use when performing the operation. If you plan to perform your own tiling or use multithreading, pass kvImageDoNotTile.

Return Value

kvImageNoError; otherwise, one of the error codes described in Data Types and Constants.


This function is, in principle, the same as vImagePermuteChannels_ARGB8888, followed by vImageOverwriteChannelsWithScalar_ARGB8888. The fused operation is provided because it allows you to set different channels to different values. Also, because neither the permute nor the overwrite functions alone saturate the vector ALU on most architectures, the function gets the extra work done in the compound operation for free.

This function can work in place provided the following are true:

  • For each buffer, buf, that overlaps with dest, buf->data is equal to dest->data and buf->rowBytes >= dest->rowBytes

  • If an overlapping buffer has a different rowBytes from dest, kvImageDoNotTile is also passed in the flags

See Also

Permuting Channels with Masked Insert


Reorders the channels and overwrites the pixels of one or more planes of an ARGBFFFF image.


Reorders the channels and overwrites the pixels of one or more planes of an ARGB16U image.