GUI design guidelines

Last update: 2018-07-30 by EGE3D


managing textures handy

As described in previous document - creating a graphic context , textures can be loaded from files on disks, or can be dynamically created on CPU side.
We describe here how to look at textures in EGE2D gui in order to use them as are designed but also more deeply how to manage them to extend functionallity of the library itself or also to use them as a basis for some other project.

Source code: You can DOWNLOAD source code from Github following the links on this page and looking for download. On the same page there are also some Video tutorial on YouTube sections that explanes how to download, prepare the system and compile the library and the samples for different destination platforms.

Basic usage

Tutorial 02: we suggest to open tutorial code to look into while reading. this paragraph concernes [Sample 1 : Texture from file] in comments

getpathonly(): the function preceding jpeg filename to open return the proper path according with actual toolchain. ie:path when compile with g++ differs from Emscripten path to browser

To just use pictures, it's enough to instanciate a class object and call the method load() with filename and EGE_ENU_TEXTURE_ROLE::None whenever required. After this, if you want to play to the screen is necessary to load to GPU with "loadGPU()" method. At the end with "draw(pointerToPIcture)" method the gui shows the picture to screen.
Draw picture method belongs to the graphic context that is infact the owner of the display.
It's quite obvious that at the end of usage a texture has to be released from GPU memory with releaseGPU() method. The method frees GPU for the relevant image.

Empty textures

Tutorial 02: we suggest to open tutorial code to look into while reading. this paragraph concernes [Sample 2 : Memory allocated texture] in comments

The second method to threat a texture is to instanciate it and, instead to load from file, to make an empty memory area that holds our pixel informations. This is achieved by function "texture->loadempty(width, height, EGE_FORMAT_RGBA);".
In this case the texture has a specific size and is uninitialized. We can write any pixel colours into accessing the memory buffer that's accessible for direct memory access to keep the process fast.It's up to the programmer to keep memory consistent avoiding to overvrite exceeding memory areas. The memory buffer where pixels in RGBA format are located is accessible starting from "texture->getTextureData()->p_image_data8[0]" and for a size equal to image_width*image_height*4 bytes in RGBA (multiply by 3 in case of RGB). In "texture->getTextureData()" there are usefull informations about memory buffer and are generally used internally in code. There is a helper function, that we suggest to look into "texture->initialize(color);" because makes the idea concerning the steps to follow to write into the texture. The sample is easy because it writes a single color but should be enough clear to explane the concept and give an overall idea on how to write pixels directly to memory.
Just for knowledge, after memory modification the jpeg could also be saved by calling "pObject->save("myModifiedJpeg");"

I want to write here a short description concerning image class getTextureData(). Underneath data are from Jpeglib code. In there are present data fields necessary to describe image informations about size and format. Here is a brief summary of the meaning of them:

  • EGEint uncomp_width = 0; --> rappresents the Image width in pixels
  • EGEint uncomp_height = 0; --> rappresents the Image height in pixels
  • EGEint uncomp_actual_comps = 0; --> rappresents the Actual image format : if RGB==3 / if RGBA==4
  • EGEint uncomp_req_comps = 4; --> internal data that holds the format of the image that has to be allocated dynamically according with construct method that can switch beetween RGB==3 or RGBA==4
  • EGEuchar *p_image_data8=NULL; --> unsigned char single dimension array for RGB/RGBA colors, actual pixel colors in summary

Textures handling with classes

Tutorial 02: we suggest to open tutorial code to look into while reading. this paragraph concernes [Sample 3 : Image copy operator] in comments

Tip: This, more than a tutorial on how to interact with EGE2D GUI is a proposal on how to implements image handler classes because we have tryed to abstract operations into classes that acts at runtime. The idea behind is to have an operation class (scale/sum/divide etc.. in relation to pixel array (rgb/rgba) ) that takes a source image and apply the operation over a destination image in the pseudo-code format : classOperator(sourceImage)->doOperationWith(otherOrDestinationImage) to achive a uniform method signature/layout for a group of different actions on data pixels. At the end the operation class acts like as Strategy pattern do.

Still from user side view, there are some functions that helps in images handling. Are presented proceding in Tutorial-02. Suppose you want to have a composed image that's from a source as basis and also you want another piece for the image has to be loaded from a subregion of another image. Simply speaking, is like to have a picture and paste on it another picture bringed from another source picture as a rectangle.
This is exactly what Totorial-02 makes in second section with:

pCopyImage=new egeTexOpSubCopy(pTextureFile, startPosition); // Texture arg. is SOURCE
pCopyImage->execute(pTextureComposition,destPosition,size); // Texture arg. is DESTINATION

in the first line of code we instanciate an object that's capable to copy a subregion from a source and place it into the destination image. Once instanciated, egeTexOpSubCopy wants the start position as lower left pixel to start to copy from. In the case we specify (0,0) then the origin is bottom left corner of the image.
the second instruction we command to execute the copy of the source area to the destination texture, also here we control the destination position as lower left start coordinate for a specific size as width, height.
As you can imagine egeTexOpSubCopy class is designed to be a prototype for lots functions that makes operations over images. Just for example there will be a scale, rotate, draw line, draw ellipse, color operarion functions like as Gimp for example do (sum,sub,divide,multiply etc..) for it's layers and so on.

Use cases

In EGE2D gui project we have used all of the above mothods. We load pictures from disk like for example for background images and also for widget controls like switches. We have also dynamic textures for example to create pushbuttons widget controls aspect as procedural texturing. Also fonts are threated as images and threated procedurally starting from the freetype generator library