C2DGraphics creating multiple instances inside functions and issues with the DEPTH macro

[ArnoldUK]

Good morning, I've run into a couple of issues when creating instances of C2DGraphics from within a function (see the code block below). The function simply draws random circles on the screen which is called from the main kernel run loop which passes the ScreenDevice. This appears to work but any subsequent drawing calls to the ScreenDevice or the FrameBuffer fail to display anything as the last 2DGraphics draw is not cleared.

Also setting VSYNC to true locks up this function call and when setting the DEPTH macro to 8 (8bit) all calls to the ScreenDevice::SetPixel fail to compile.

void PixelRunTest2DGraphics(CScreenDevice *pScreenDevice) {
	uint8_t cRed;
	uint8_t cGreen;
	uint8_t cBlue;

	unsigned scrWidth = pScreenDevice->GetWidth();
	unsigned scrHeight =  pScreenDevice->GetHeight();
	unsigned nPixels = scrWidth * scrHeight;
	
	CBcmRandomNumberGenerator m_Random;
	u32 nNumber = m_Random.GetNumber();
	
	C2DGraphics my2DGraphics = C2DGraphics(scrWidth, scrHeight, false);
	my2DGraphics.Initialize();

	uint8_t nCount = 0;
	unsigned pixelY, pixelX;
	unsigned circle_x, circle_y, circle_r;

	for (nCount = 0; nCount < 100; nCount++) {
		nNumber = m_Random.GetNumber();
		nNumber %= nPixels;
		circle_r = nNumber % 25;
		circle_x = nNumber % scrWidth;
		if (nNumber > 0) { circle_y = nNumber / scrWidth; } else { circle_y = 0; }
		cRed = randomNumber() % 31;
		cGreen = randomNumber() % 31;
		cBlue = randomNumber() % 31;
		my2DGraphics.DrawCircle(circle_x, circle_y, circle_r, COLOR16(cRed, cGreen, cBlue));
	}
	
	my2DGraphics.UpdateDisplay();
	//my2DGraphics.ClearScreen(BLACK_COLOR);
}

Maybe i'm doing something incorrectly here but the above function works without any issues, if I create and initialize the C2DGraphics first inside the kernel.cpp and then pass it along with the CScreenDevice to the function. Instead of creating it inside the function like above. Is only a single instance of C2DGraphics allowed to be created and does that also apply to a CScreenDevice ? Can the 2 instances run alongside each other ?

[rsta2]

Hi, there can be only one instance of the classes CBcmFrameBuffer, C2DGraphics or CScreenDevice at a time in the system, because they all directly communicate with the firmware in the Initialize() method to setup the frame buffer hardware. If there would be multiple instances, they would disturb each other in this process. So you cannot use C2DGraphics and CScreenDevice together.

An exception from this rule is the Raspberry Pi 4, which has multiple HDMI connectors and thus multiple frame buffers. The nDisplay parameter can be used to select the HDMI connector to be used in this case.

Normally the instance of CBcmFrameBuffer, C2DGraphics or CScreenDevice should be managed as a member variable of CKernel and initialized in CKernel::Initialize(). Please have a look at the samples 03-screentext and 41-screenanimations for the latter two options.

With DEPTH == 8 the Color parameter of any function is an index into a color palette, which must be between and including 0 and 15. Only these colors are defined then:

BLACK_COLOR
RED_COLOR
GREEN_COLOR
YELLOW_COLOR
BLUE_COLOR
MAGENTA_COLOR
CYAN_COLOR
WHITE_COLOR
BRIGHT_BLACK_COLOR
BRIGHT_RED_COLOR
BRIGHT_GREEN_COLOR
BRIGHT_YELLOW_COLOR
BRIGHT_BLUE_COLOR
BRIGHT_MAGENTA_COLOR
BRIGHT_CYAN_COLOR
BRIGHT_WHITE_COLOR

[ArnoldUK]

Excellent explaination, thanks for clarifying this. I was suspecting this to be the case and it now clears up all the issues I've been encountering. Explains the reason why everything worked when I created and initialized the device in the kernel class. The DEPTH macro kind of makes sense also but didn't expect the function parameters to change when setting it to 8Bit.

From now on I will be intitializing all Cricle devices in the Kernel class similar to the samples and passing a pointer to each device to my functions instead. Yes, the samples are a great resource and so are the docs, but there seems to be alot hidden under hood that is not in the docs.

Thanks for your help again and I want to also add that your SDK is quite an achievement.

[rsta2]

Thank you for appreciating Circle.

[ArnoldUK]

You are welcome. Oh, and for the record, after some testing I found it is possible to initialize and use both the CScreenDevice and C2DGraphics together. Although, all the CScreenDevice.Write calls are only displayed on screen after calling C2DGraphics.UpdateDisplay().

So, in effect all the C2DGraphics calls can still be used for primitive drawing to the display along with text and ascii from the CScreenDevice.Write calls in the same kernel image.

I also managed to get around the DEPTH issue by using this small helper function to generate the random colors for each DEPTH macro setting. Although the CBcmRandomNumberGenerator is awful slow dropping my frames to 2 fps on each pixel call, I guess this is my error by creating an instance of CBcmRandomNumberGenerator on every pixel update!! (That's my C habit of seeing everything as a static structure and wrestling with C++ classes):

static unsigned g_seed;
static unsigned randomNumber() {
	g_seed = (214013*g_seed+2531011);
	return (g_seed>>16)&0x7fff;
}

TScreenColor GetRandomColor(void) {
	uint8_t cRed;
	uint8_t cGreen;
	uint8_t cBlue;
	uint8_t cAlpha;
	
	//CBcmRandomNumberGenerator m_Random;
	//u32 nNumber = m_Random.GetNumber();
	
	#if DEPTH == 8
		return randomNumber() % 16;
	#elif DEPTH == 16
		cRed = randomNumber() % 31; //m_Random.GetNumber() % 31;
		cGreen = randomNumber() % 31; //m_Random.GetNumber() % 31;
		cBlue = randomNumber() % 31; //m_Random.GetNumber() % 31;
		return COLOR16(cRed, cGreen, cBlue);
	#elif DEPTH == 32
		cRed = randomNumber() % 256; //m_Random.GetNumber() % 256;
		cGreen = randomNumber() % 256; //m_Random.GetNumber() % 256;
		cBlue = randomNumber() % 256; //m_Random.GetNumber() % 256;
		cAlpha = 255;
		return COLOR32(cRed, cGreen, cBlue, cAlpha);
	#else
		#error Screen DEPTH must be defined to 8, 16 or 32
	#endif
}

Have a good weekend!

[rsta2]

Interesting finding. I never tested this, because it is not recommended to use CScreenDevice and C2DGraphics together on the same frame buffer. Both classes implement very different display models (scrolling vs. fixed with two virtual planes). I understand, that it can be useful to be able to combine these models (e.g. to have a scrolling window on the C2DGraphics display), but unfortunately this is currently not officially implemented in Circle. Have a good weekend too!

[ArnoldUK]

I've been running this combination without any problems so far. Being able to use the writing features of the CScreenDevice on top of the C2DGraphics device is useful for log output and textual information. The only gotcha with this is that the DEPTH must be 16Bit as I was unable to compile my code with any other color bit depth.

I'm not quite sure if the Circle SDK requires recompiling after adding the DEFINE += -DDEPTH=16 in my make file or if a simple #define in the code can be used to set the DEPTH on the fly ?
The #define DEPTH=8 in code creates compile errors for all C2DGraphics.PixelDraw() calls with incompatible type for the TScreenColor parameter.

[rsta2]

I had a look into the class implementations, and the class CBcmFrameBuffer is initialized twice, when you call Initialize() for instances of CScreenDevice and of C2DGraphics. That works, if you use the same display dimensions in both cases. But it is not clean code and not recommended therefore. No question, you can use it, if you like, but there is no guarantee, if this will work in future versions.

Normally such configuration options are added to the file Config.mk like that:

DEFINE += -DDEPTH=8

You have to enter makeall clean and makeall after changing Config.mk to rebuild the whole code.

[ArnoldUK]

Thanks for that, makes sense to not use both the classes then as you said. I only porting an emulator so I guess I can add a few hacks here and there without bringing the internet to a crawl :)
The DEPTH macro was driving me nuts but I figured it out eventually, like you said, the circle sdk has to be re-compiled to pickup the new DEPTH setting.

I think it's time for long weekend of relaxing and beer supping for me now. Have a great day!