ClippingNode and global Z order issue

The clipping node is behaving strangely when I use the setGlobalZOrder on nodes within the scene.

In order to get the clipping to work, the stencil and any child of the clipping node must be at the same global Z layer as the clipping node, which makes no sense.

From the CCNode.h file, I see this comment:

“if ClippingNode is one of the ancestors, then “global Z order” will be relative to the ClippingNode.”

Example:

cocos2d::Layer* layer = Layer::create();

auto visibleSize = Director::getInstance()->getVisibleSize(); // 1920 x 1080
auto origin = Director::getInstance()->getVisibleOrigin();

auto clipper = ClippingNode::create();
clipper->setPosition(0, 0);
clipper->setContentSize(Size(visibleSize.width, visibleSize.height));

DrawNode *groupStencil= DrawNode::create();

const auto windowHeight = 600;
const auto yStart = 100;

groupStencil->setAnchorPoint(Vec2(0, 0));
const auto boundingBox = clipper->getBoundingBox();
groupStencil->drawSolidRect(
    Vec2(0, boundingBox.size.height - yStart - windowHeight),
    Vec2(boundingBox.size.width, boundingBox.size.height - yStart),
    Color4F::MAGENTA);

// If this is set to 0, then it does not do any clipping. 
// If it is NOT set to 100 (same as clipper Z order), then it displays a MAGENTA colored box or does not clip anything depending on the child nodes of clipper
groupStencil->setGlobalZOrder(100); 

clipper->setStencil(groupStencil);
clipper->setInverted(true);
clipper->setGlobalZOrder(100);

layer->addChild(clipper);

// This background image is basically 'cut' out like a window.
auto clippedBgSprite = Sprite::create("Image_1920x1080.png");
clippedBgSprite->setPosition(Vec2(visibleSize.width / 2 + origin.x, visibleSize.height / 2 + origin.y));
// If it is NOT set to 100 (same as clipper Z order), then it displays a MAGENTA colored box or does not clip anything depending on the stencil global Z order
clippedBgSprite->setGlobalZOrder(100); // if this is NOT 100, it will NOT clip it
clipper->addChild(clippedBgSprite);

// This sprite should be visible within the stencil area of the clipper (the cut out window of the above background image),
// but it is not.  It is ONLY visible if the clipper, stencil AND the background image all use the same ZOrder value, 
// which makes no sense at all.
auto visibleSprite = Sprite::create("SmallSprite_50x50.png");
visibleSprite->setPosition(visibleSize.width / 2, visibleSize.height / 2);
visibleSprite->setGlobalZOrder(50); 
layer->addChild(visibleSprite);

EDIT:

Here is what I’ve discovered:

1 - In order for the clipper to work, any child node added to it must be at the same global Z order value in order for the clipping to work.
2 - If a child node of the clipper is at a greater Z order value than the clipper, it will display above the clipped window, and no clipping takes place.
3 - If a child node of the clipper is at a lower Z order value than the clipper, it will display below the clipper, and no clipping of that child takes place.
4 - To order the child items of the clipper, you can no longer use global Z, so local Z must be used, since they are now relative to the clipper global Z.