MbufChildColor2dClip

• See also
Reference:
MbufAllocColor MbufFree MbufSetRegion
Availability
Available in MIL-Lite
Available in MIL


Available on Windows
Available on Linux


Not supported on:
Not supported on Matrox Indio (Update 53 or Update 68) (w)
Not supported on Matrox Concord PoE with ToE (Update 82) (z)
Fully supported on:
Fully supported on Host system (a)
Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)
Fully supported on Matrox Morphis (g)
Fully supported on Matrox Morphis QxT (h)
Fully supported on Matrox Orion HD (i)
Fully supported on Matrox Radient eCL (j)
Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)
Fully supported on Matrox Solios eA/XA (l)
Fully supported on Matrox Solios ecl/xcl/ev-cl (m)
Fully supported on Matrox USB3 Vision driver (Update 19) (o)
Fully supported on Matrox RadientPro-CL (Update 7) (p)
Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)
Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)
Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)
Fully supported on Matrox GenTL driver (Update 34) (v)
Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)
Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)


* Refer to the MIL system-specific information
   in the MIL Reference for the minimum update required.


For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note


Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP/GPm
Available on Matrox Supersight
Function map
Examples
None.
MbufChildColor2d
MbufChildColor

Description

This function allocates a child data buffer within the specified, previously allocated, color parent data buffer. It selects a rectangular area in one or all of the color bands of the parent data buffer and allocates this area as a child of that buffer. If necessary, the specified rectangular area will be adjusted (clipped) to ensure it fits within the limits of the parent buffer. If the specified rectangular area is completely outside the limits of the parent buffer, the allocation fails and an error is reported.

The child buffer is not allocated in its own memory space; it remains part of the parent buffer. Therefore, any modification to the child buffer affects the parent and vice versa. Note, a parent buffer can have several child buffers.

A color child buffer is considered a data buffer in its own right. It can be used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.

If the child buffer is larger or positioned outside the parent buffer, the child buffer is clipped and the clipping status is returned using the StatusPtr parameter. In the following example, both the X-offset and the X/Y-size are clipped, so M_CLIPPED_OFFSET_X + M_CLIPPED_SIZE_X + M_CLIPPED_SIZE_Y is returned as the clipping status. If no clipping was necessary, M_NULL is returned as the clipping status.

If a child buffer is allocated using a parent buffer with an ROI, set using MbufSetRegion(), the child buffer inherits the parent buffer's ROI. You can also set an ROI in a child buffer directly. Note that the ROI of the child buffer is only accessible using the child buffer's MIL identifier.

When this buffer is no longer required, release it, using MbufFree().

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.

Parameters

ParentBufId

Specifies the identifier of the parent buffer.

The parent buffer cannot have an M_COMPRESS attribute unless the Band parameter is set to M_ALL_BANDS.

Band

Specifies the color band of the parent data buffer from which to allocate the child data buffer. The specified color band should be valid in the parent buffer.

The Band parameter can be set to one of the following values:

For specifying the color band
Value	Description
M_ALL_BANDS	Specifies all color bands (for RGB, HSL, HSV, and YUV buffers).
M_BLUE	Specifies the blue color band (for RGB buffers).
M_GREEN	Specifies the green color band (for RGB buffers).
M_HUE	Specifies the hue band (for HSL and HSV buffers).
M_LUMINANCE	Specifies the luminance band (for HSL buffers).
M_RED	Specifies the red color band (for RGB buffers).
M_SATURATION	Specifies the saturation band (for HSL and HSV buffers).
M_U	Specifies the U band (for YUV buffers).
M_V	Specifies the V band (for YUV and HSV buffers).
M_Y	Specifies the Y band (for YUV buffers).
0 <= Value <= 2	Specifies the index of the band to copy. The relationship between index value and band for RGB, HSL, HSV, and YUV buffers is the following: 0 Corresponds to the red band for RGB buffers, the hue band for HSL and HSV buffers, or the Y band for YUV buffers. 1 Corresponds to the green band for RGB buffers, or the saturation band for HSL and HSV buffers, or the U band for YUV buffers. 2 Corresponds to the blue band for RGB buffers, or the luminance band for HSL buffers, or the V band for YUV and HSV buffers. (summarize) Specifies the index of the band to copy. (more details...)

OffX

Specifies the horizontal offset of the child buffer, relative to the parent buffer's top-left pixel. If necessary, the given offset will be adjusted (clipped) to make sure that the top-left pixel of the child buffer is within the limits of the parent buffer.

OffY

Specifies the vertical offset of the child buffer, relative to the parent buffer's top-left pixel. If necessary, the given offset will be adjusted (clipped) to make sure that the top-left pixel of the child buffer is within the limits of the parent buffer.

SizeX

Specifies the width of the child buffer. If necessary, the given dimension will be adjusted (clipped) to make sure that the bottom-right pixel of the child buffer is within the limits of the parent buffer.

SizeY

Specifies the height of the child buffer. If necessary, the given dimension will be adjusted (clipped) to make sure that the bottom-right pixel of the child buffer is within the limits of the parent buffer.

StatusPtr

Specifies the address of the variable in which the clipping status is written. If no status is required, set this parameter to M_NULL.

One or more of the following values can be returned together to denote that the child buffer was clipped. For example, when both the X-offset and the X-size are clipped, then M_CLIPPED_OFFSET_X + M_CLIPPED_SIZE_X is returned as the clipping status.

For retrieving clipping results
Value	Description
M_NULL	Specifies that no clipping was necessary.
M_CLIPPED_OFFSET_X	Specifies that the horizontal offset of the child buffer was clipped to fit within the width of the parent buffer.
M_CLIPPED_OFFSET_Y	Specifies that the vertical offset of the child buffer was clipped to fit within the height of the parent buffer.
M_CLIPPED_SIZE_X	Specifies that the width of the child buffer was clipped to fit within the width of the parent buffer.
M_CLIPPED_SIZE_Y	Specifies that the height of the child buffer was clipped to fit within the height of the parent buffer.

BufIdPtr

Specifies the address of the variable in which the child buffer identifier is to be written. Since the MbufChildColor2dClip() function also returns the child buffer identifier, you can set this parameter to M_NULL.

Return value

The returned value is the child buffer identifier, if successful. If allocation fails, M_NULL is returned.