TivaWare™ Graphics Library Display Drivers - TI.com

1 ApplicationReportSPMA055 July 2013 TivaWare GraphicsLibraryDisplayDriversDaveWilsonA BSTRACTTheTivaWareGraphicsLibrary( grlib ) offersa compactyet powerfulcollectionof graphicsfunctionsallowingthe developmentof compellinguserinterfaceson smallmonochromeor colordisplaysattachedto applicationreportdescribeshow to supporta new displaydevicein TivaWareGraphicsLibrary( grlib )is includedin all TivaWarefirmwaredevelopmentpackagessuppo rtingevaluationor developmentkits that Graphicslibraryprovidesacollectionof graphicsfunctionsthat allowyou to developuserinterfaceson smallmonochromeor colordisplaysattachedto Tiva microcontrollers,includingthe thesekits canbe downloadedfromTools& Softwarefor yourTivaWarepackage,the graphicslibrarysourcecan be foundin theC:\ti\TivaWare_C_Series-<version>\grlibdirectory(assumingyou installedin the defaultlocation)andvariousexampleapplica tionsusingthe librarycan be foundin the C:\ti\TivaWare_C_Series-<version>\examples\boards\<yourboardname> exampleapplicationsprovidedvary fromboardto board,but a versionof grlib_demo is includedin all kits supportingthe applicationreportprovidesinformationon the lowestlayerof the TivaWareGraphicsLibraryarchitecture:the layeracts as the interfacebetweenthe commoncodeof the graphicslibraryand the displaycontrollerin use on a new or modifieddisplaydriveris requiredto supportthe TivaWareGraphicsLibraryon a new boarddesignor whenusinga graphicsdisplaycontrollerotherthanthoses upportedon the displaydriverfor eachsupportedboardcan be foundin the C.

2 \ti\TivaWare_C_Series-<version>\examples\boards\<yourboardname>\ a trademarkof othertrademarksare the propertyof July 2013 TivaWare GraphicsLibraryDisplayDriversSubmitDocum entationFeedbackCopyright 2013,TexasInstrumentsIncorporatedWidget ManagerInput Driver(for example, buttonsor touchscreen)ApplicationWidget ClassesGraphics FunctionsDisplay DriverDisplay HardwareInput TivaWareGraphicsLibraryis a layeredlibraryofferingfour mainapplicationprogramminginterfaces(API s)for the applicationdeveloperto showsthe organizationof the Organizationof TivaWareGraphicsLibraryThe rightside of the figureshowsthe layersof the providedat the widgetlevel(the WidgetAPI),the graphicsfunctionlevel(the Low-LevelGraphicsAPI)and at the displaydriverlevel(the DisplayDriverAPI).Additionally,a standarduser-inputdriverinterface(the InputDriverAPI)is requirementsof a givenapplication,someportionsof the librarycan beomittedif theirfunctionsare not type definitions,labels,macros,and functionprototypesforthe graphicsfunctionsand displaydriverlayerscan be foundin the Definitionsrelatingto thehigherlevelwidgetlibrarycan be foundin individualheaderssuchas ,containdefinitionsfor displaydriverlayerprovidesa standardprogramminginterfaceto the graphicslibrarycodeallowingitto drawactualpixelson the API is very simple(drawhorizontaland verticallines,copya lineof pixelsto a positionon the screen,plot a singlepixel)

3 And is not typicallyaccesseddirectlyby theapplicationsinceit is missingmanyof the graphicsprimitivesthat an applicationis likelyto requiresuchas slantedlines,rectangles,circles,text, and applicationreportprovidesadditionalinfor mationon the displaydriverAPI and offerssuggestionsonhow to developa new displaydriverfor yourparticularboardand OverviewThe first API that is intendedfor applicationuse is the low-levelgraphicsAPI. This givesaccesstofunctionsthat drawthe majorgraphicsprimitives:lines,rectangles ,circles,text, and addition,functionsand macrosare providedto performcoordinatecheckingand rectangleprocessing(for example,checkingfor intersectionand overlap,determiningwhethera pointlies withina rectangle,and so on).The low-levelgraphicsAPI is concernedonly with drawingto the displayand has no knowledgeof userinputor any OverviewAbovethe low-levelgraphicsAPI and the inputdriver,the widgetAPI offersa high-levelinterfacethatallowsyou to builda complexuserinterfacethat includesindividualcontrolssuchas buttons,sliders,checkboxes,and otherhigh-levelwidgets(controls).

4 2 TivaWare GraphicsLibraryDisplayDriversSPMA055 July 2013 SubmitDocumentationFeedbackCopyright 2013, layerties the graphicaldisplayto managesthe inputand updatesthe displayedwidgetsaccordingto buttonor touchscreenpressesmadeby you. Applicationinteractionwith widgetsisvia specificto the type of widgetbutwouldincludefunctionscalledwhen a buttonis pressedor a slideris inputdriver,like the displaydriver,is responsiblefor managinga blockof hardwareand translatinguserinteractioninto a standardformatthat the widgetmanagercan applicationwill nottypicallycall the inputdriverotherthanduringstartupwhena call is madeto initializethe includetouchscreensor lowestlevelof the graphicslibrarystackis the displaydriverAPI isspecifiedby the graphicslibrary,the sourceis specificto the boardand displayhardwareand can befoundin the C:\ti\TivaWare_C_Series-<version>\examples\boards\<yourboardname>\ driversourcefile nameis typicallyderivedfromthe displaymanufacturer,displayresolution,an d example,the displaydriverfor the dk-tm4c123gis supportsaCrystalfontzCFAL9664-F-B1 OLED displayand offers96x64resolutionat 16 bits per displaydriver s responsibilityis to translatecallsmadeto the standarddisplaydriverAPI into ordersto drawpixelsor lineson the interfaceto the driveris intendedto offerthe absoluteminimumsubsetof drawingordersrequiredto supportthe maingraphicslibraryand,as a result,makeit extremelystraightforwardto developa driverfor a new displayvery displaydriverAPI includesthe followingbasicfunctionsthat mustbe supportedby everydisplaydriver:voidPixelDraw(void*pv DisplayData,int32_ti32X,int32_ti32Y,uint 32_tui32ulValue);voidPixelDrawMultiple(v oid*pvDisplayData,int32_ti32X,int32_ti32 Y,int32_ti32X0,int32_ti32 Count,int32_ti32 BPP,constuint8_t*pui8 Data,constuint8_t*pui8 Palette).

5 VoidLineDrawH(void*pvDisplayData,int32_t i32X1,int32_ti32X2,int32_ti32Y,uint32_tu i32ulValue);voidLineDrawV(void*pvDisplay Data,int32_ti32X,int32_ti32Y1,int32_ti32 Y2,uint32_tui32ulValue);voidRectFill(voi d*pvDisplayData,consttRectangle*psRect,u int32_tui32ulValue);uint32_tColorTransla te(void*pvDisplayData,uint32_tui32ulValu e);voidFlush(void*pvDisplayData);The actualnamesof thesefunctionsare not importantsincethey are providedto the graphicslibrarybymeansof a tablecan be foundin the tDisplaystructurethat the displaydriverexportsand whichthe applicationuseswhencallingthe graphicsAPI GrContextInit() definedin ,the displaydrivertypicallyprovidesan initializationfunctionthat the applicationis expectedtocall priorto initializingthe call is usedto initializethe underlyinggraphicshardwareand clearthe July 2013 TivaWare GraphicsLibraryDisplayDriversSubmitDocum entationFeedbackCopyright 2013, the driverAPI containssignificantlyfewergraphicsprimit ivesthanthe brokendownby the higherlevelcodeand passedto the driverin ,an unfilledrectangleis drawnusingtwo callsto the LineDrawVfunctionand two callsto ,text is renderedusingmultiplecallsto the PixelDrawand modelworkswell with small,low-costdisplayswhichdo not typicallyincludeany graphicsaccelerationhardwarebut do oftenincludethe abilityto choosedrawingdirectionand copylinesof otherhigherlevelfeaturecarriedout by the low-levelgraphicslayeron behalfof the coordinatesthat are outsidethe boundsof the displayare everpassedto the displaydriversincethis is checkedfor and handledin the approach.

6 It becomesquickand easyto producea new graphicsdriversinceonly a smallnumberof simplefunctionsneedto be intendedto allowspecifichardwaredisplaysto be usedwith theTivaWareGraphicsLibrary,threespeciald riversare includedwithinthe off-screengraphicsrenderingin 1 bpp (bit per pixel),4 bpp,and 8 bpp formatsand aretypicallyusedin combinationwith a driverwhichsupportsthe may be mainuse for an off-screendisplaydriveris to supportapplicationswhichrequiresmoothani mationorwhichrenderan thesecases,an imageis drawninto a memorybufferusingthe off-screendisplaydriverand,oncethe imageis completed,it is transferredto the physicaldisplayin renderingof the imagetakesmanystepsand may includeerasingthe entirebufferbeforestartingto redraw,usingan physicaldisplaycontinuesto showthe previousimageuntil a new one is readyfor Display ,at whichpointtheimageis updatedso quicklythat you do not see any of the interveninggraphicoperationsthat wererequiredto generatethe new an exampleof the use of the off-screendisplaydriver,see the sourcefor the qs-loggerexampleapplicationfromthe applicationimplementsa simplesensordataloggerand renderssensorreadingwaveformsinto an off-screenbufferbeforeupdatingthe actualdisplay,resultingin smooth.

7 The off-screendisplaydriverscan be foundin the , ,and in the C:\ti\TivaWare_C_Series-<version>\ sectiondescribesthe individualdisplaydriverfunctionsin the first parameterto eachfunction,pvDisplayData,is a pointerthat the driveritselfprovidesin the tDisplaystructureit needto use this parameter,but it is providedto prototypefor the driverinitializationfunctionis applicationcallsthis functiondirectlypriorto initializingthe low-levelgraphicsAPI layerand the functiontheninitializesthe displayhardwareand blanksthe screenin preparationfor (void*pvDisplayData,uint32_tui32 RGBC olor);The higherlevelgraphicsdriverAPIsmakeuse of a standard24-bitRGBcolordescriptionwith the colordescribedin a single,unsignedlong valuewith the red componentin bits 16 to 23, greenin bits 8 to 15,and blue in bits 0 to 7. Differentdisplays,however,describecolori n differentwaysso the ColorTranslatefunctionallowsthe graphicslibraryto obtaina representationof a givenRGB24colorin the nativeformatsupportedby the GraphicsLibraryDisplayDriversSPMA055 July 2013 SubmitDocumentationFeedbackCopyright 2013, monochromedisplays,the returnedvalueshouldrepresentthe brightnessof the colordisplays,the returnedvalueshouldrepresentthe originalcoloras closelyas possiblegiventheconstraintsof the the displaysupports16-bitRGB,for example,the returnedcolorvaluetruncates,masks,and shiftsthe supplied8-bitR,G,and B samplesinto a othercallsto the displaydriverwill be passedpre-translatedcolors(thatis, colorsthat havebeenreturnedfroma previouscall to this ColorTranslatefunction),so the overheadof colortranslationis kept toa (void*pvDisplayData,int32_ti32X,int32_ti 32Y,uint32_tui32 DispColor).

8 The simplestfunctionthat a displaydrivermustsupportis the abilityto plot a singlepixelat a givenpositionon the functionplotsa pixelusingcolorui32 DispColorat position(i32X,i32Y)on the colorpassedhas alreadybeentranslatedinto the Display -dependentformatusingapreviouscal l to the (void*pvDisplayData,int32_ti32X,int32_ti 32Y,int32_ti32X0,int32_ti32 Count,int32_ti32 BPP,constuint8_t*pui8 Data,constuint8_t*pui8 Palette);The PixelDrawMultiplefunctionis blockof pixeldatarepresentinga givenhorizontalspanis passedto the displaydriver,whichrendersthe pixeldataontothe displayat this case,the drivermustsupport1 bpp,4 bpp,and 8 bpp bpp formatsmay also supportnative16 bpp formatis not currentlyusedby the graphicslibrary,it can be usefulto applicationswishingto displayJPEGor ui32 Bppparameterprovidesthe numberof bits per pixelin the sourcepixeldataas well as flagsintendedto providehintsto allowcolormanagementoptimizationin the numberof bits perpixelis storedin the bottom8 bits of the parameterso driversmusttake careto maskoff the top 24 bits toextractthis the first call to PixelDrawMultipleas a resultof a call to GrImageDraw.

9 The flagGRLIB_DRIVER_FLAG_NEW_IMAGEis set in the flag may be usedby thedriverto constructany colorlookuptablerequiredto mapthe sourceimagepaletteto the driver' is safe to assumethat the colorpalettehas not changedand that any previouslycalculatedlookuptablemay be reusedif GRLIB_DRIVER_FLAG_NEW_IMAGEis not the 1 bpp pixelformat,the pui8 Palettepointsto a 2-entryarraycontainingpre-translatedcolo rsforbackgroundand 4 bpp and 8 bpp formats,the pui8 Paletteparameterpointsto a colortablecontainingRGB24colorswhichthe drivermusttranslateto the nativecolorformatduringthe paletteis ignoredfor the 16 bpp formatssinceit is assumedthat the pixelspassedare in the nativecolorformatof the bpp and 4 bpp formats,the i32X0parameterindicateswherethe first pixelto drawis withinthe first byte of 1 bpp,validvaluesare 0 through7 and for 4 bpp,values0 or 1may be eachcase,pixelsare packedwith the leftmostpixelin the mostsignificantbit or nibbleofthe an example,if i32X0is 5 this indicatesthat we skip the 5 leftmostpixelsin thefirst byte passedand will draw3 pixelsfromthat be takenfrombits 2 , 1 and 0 of the July 2013 TivaWare GraphicsLibraryDisplayDriversSubmitDocum entationFeedbackCopyright 2013, (void*pvDisplayData,int32_ti32X1,int32_t i32X2int32_ti32Y,uint32_tui32 DispColor);This functiondrawshorizontallinesusingthe supplied, the line drawnincludesboththe first and last pixelsspecifiedby parametersi32X1and i32X2,whichmeansthat thenumberof pixelswrittenis ((i32X2 i32X1)+ 1).

10 The graphicslibraryensuresthat i32X2is alwaysgreaterthani32X1,so no parametersortingis requiredin the (void*pvDisplayData,int32_ti32X,int32_ti 32Y1,int32_ti32Y2,uint32_tui32 DispColor);This functiondrawsverticallinesusingthe supplied, for LineDrawH,the linedrawnincludesboththe first and last pixelsspecifiedby parametersi32Y1and i32Y2meaningthat thenumberof pixelswrittenis ((i32Y2 i32Y1)+ 1). The graphicslibraryensuresthat i32Y2is alwaysgreaterthani32Y1so no parametersortingis requiredin the (void*pvDisplayData,consttRectangle*psRe ct,uint32_tui32 DispColor);This functionfills a rectangleon the displaywith the solidcolorprovidedin the the tRectangletype usesa bottom-rightinclusivedefinitionso the widthof the rectangleto drawis givenby ((psRect->i16 XMax psRect->i16 XMin)+ 1) and the heightis ((psRect->i16 YMax psRect->i16 YMin)+ 1). This is differentfromWindowsand variousothergraphicslibrariesthat use a (void* pvDisplayData);The flushfunctionis providedto supportdisplayhardwarethat doesnot containan integratedframebufferand wherethe displaydrivermustkeepthe displaycontentsin a this model,thedrawingfunctionsprovidedby the driverupdatethe contentsof the RAMbufferinsteadof flushedto the actualdisplayusingthe driversthat updatethe displayon eachcall to any of the driverdrawingAPIs,this call can be a stub thatreturnswithoutperformingany the widgetclassesdo not currentlymakeuse of the Flush()driverAPI so, if you plan to use adriverthat performsoff-screenrenderingwith the widgetlayer,you mustupdatethe widgetclassesyouare usingto call Flush()at appropriatepointsin GraphicsLibraryDisplayDriversSPMA055 July 2013 SubmitDocumentationFeedbackCopyright 2013, showsa list of the graphicslibrary-compatibledisplaydrivers provi