Home

PVRTrace User Manual - Imagination Technologies

1. Note Backing up the original libraries is extremely recommended A good backup location is data local tmp e Option 1 Use mv to move the files adb shell mv system vendor lib egl lt LIBRARY gt so system lib egl lt LIBRARY gt so Note In case mv is not available in the system do a cp and then rm the source file PVRTrace 51 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination 4 Copy the recording libraries to system vendor 1lib egl1 The libraries to copy are 1ibEGL PVRTRACE so libGLESv1 CM PVRTRACE so and libGLESv2_ PVRTRACE so e Option 1 Using adb push directly requires root shell i e option 1 in step 1 adb push path to PVRTrace Recorder Android lt ABI gt lt LIBRARY gt so system vendor lib egl e Option 2 Use cp to copy the file from an SD card on the device adb push path to PVRTrace Recorder Android lt ABI gt lt LIBRARY gt so sdcard adb shell cp sdcard lt LIBRARY gt so system vendor 1lib lt LIBRARY gt so 5 Create the pvrtraceconfig json see Section 2 4 and place it in the SD card Make sure that TraceFile points to a writable location The TraceFile variable must be set accurately with an absolute path If it is not correctly set no file will be output It is suggested that write permissions for the app be checked before setting this As all subsequent processes will be t
2. X Y X followed by Y xX Y Either X or Y Qua 5 x Match 0 or more X Match 1 or more X Match 0 or 1 X Match 0 or more X n Match n times X m Match no more than m times X n Match n or more X n m Match at least n but no more than m times Boundary matching Note These quantifiers are greedy By following them with it becomes possible to turn them into lazy quantifiers or follow them with for possessive non backtracking quantifiers d Match begin of line if at begin of pattern Match end of line if at end of pattern lt Begin of word gt End of word b Word boundary B Word interior Revision PowerVR SDK REL_3 5 3523383a 56 User Manual Kn imagination Public Imagination Technologies A Match only beginning of file Z Character classes Match only end of file abc Match a b orc abc Match any but a b orc a zA Z Match upper or lower case a through z Matches Matches Predefined character classes Match any character d Digit 0 9 D Non digit s Space s Non space w Word character a zA Z_0 9 W Non word character l Letter a zA Z L Non letter h Hex digit 0 9a fA F H Non hex digit u Single uppercase character U Single lowercase character p Punctuation not including _ P Non punctuation
3. config lt ATTRIBUTE gt lt VALUE gt lt ATT Overrides the specified configuration attributes with the defined values Example config 0x3025 0 PVRTrace 45 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Option Description config lt N gt lt ATTRIBUTE gt lt VALUE gt lt A Performs the same function as config but replaces config with ID N s attributes Example config26 0x3025 0 fake egl client buffers Makes PVRTracePlayback use textures to fake the egl client buffers if their data matches a GL ES texture format 4 3 2 Advanced Command Line O ptions Table 8 lists the advanced command line options and their description Note The advanced command line options are incompatible with the optimised memory option Table 8 Advanced command line options and their description Option Description range RANGE Renders a specified value of frames Example range 1 10 15 random Sets PVRTracePlayback to play frames from the trace ina random order Revision PowerVR SDK REL_3 5 3523383a 46 User Manual og Imagination Public Imagination Technologies 5 Troubleshooting Table 9 lists some of the common general and recording issues that may be encountered The table also identifies how to troubleshoot these issues Table 9 Troubleshooting issues The target device or
4. cp src path lt LIBRARY gt so dst path lt LIBRARY gt so Can be exchanged by cat src path lt LIBRARY gt so gt dst path lt LIBRARY gt so chmod 0644 dst path lt LIBRARY gt so A 1 1 Installation on Android 4 3 or Older Version To manually install PVRTrace on a device with Android 4 3 Jelly Bean or older version 1 Make the Android system directory writable e Option 1 Using ADB adb root adb remount e Option 2 Using the command line adb shell mount o rw remount system 2 Copy libPVRTrace so to system vendor 1lib e Option 1 Using adb push directly requires root shell i e option 1 in step 1 PVRTrace 49 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination adb push path to PVRTrace Recorder Android lt ABI gt libPVRTrace so system vendor lib libPVRTrace so e Option 2 Use cp to copy the file from an SD card on the device adb push path to PVRTrace Recorder Android lt ABI gt libPVRTrace so sdcard libPVRTrace so adb shell cp sdcard libPVRTrace so system vendor lib libPVRTrace so 3 Copy the recording libraries to system vendor 1lib egl or system 1lib egl The libraries to copy are libEGL_ PVRTRACE so libGLESv1l_ CM PVRTRACE so and libGLESv2_PVRTRACE so Note The location of the OpenGL ES driver is preferred which in the example here is assumed to be system vendor 1lib the default location in And
5. og Imagination Public Imagination Technologies Option Description Es2LibraryPath Type String Default Nu11 On Android the Recording Libraries will automatically attempt to populate this with the system s graphics libraries Es2LibraryPath refers to the location of the original OpenGL ES 2 0 3 0 3 1 driver on the host system This is usually found in system lib eg1 or system vendor lib egl1 if running an Android device On Linux the path will usually be usr lib 2 4 5 Profiling Options Table 5 lists profiling options and their description Table 5 Profiling options and their description Option Description Enabled Type Boolean Default false If set to true this sets the Recording Libraries to profiling mode disabling recording When used in conjunction with PVRPerfServer and PVRTune this enables PVRTune s Renderstate override capabilities software statistics and driver timing data SoftwareCounters Type Boolean Default true If this option is set to true it enables API counters to be displayed in PVRTune FunctionTimelineLevel Type Integer Default 1 This option will specify the amount of calls that will be displayed in the PVRTune timeline If set to 0 no calls will be displayed If set to 1 then a selection of calls will be displayed and if set to 2 all calls will be displayed It is important to remember that using the last option may slow down the applicatio
6. a F ES Objects and selecting a program number Then in the Shaders tab in the Object Data Viewer click the desired vertex or fragment shader to open it PVRTrace 39 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Object Data Viewer Gx Shader 350005 Call 424077 Information Source 1 2 3 4 5 7 odelViewProjec e matrix up 8 glstate_matrix 3 10 varying highp vec2 xlv_TEXCOORDO 11 varying lowp vec4 xlv_COLOR 12 d 13 uniform highp vec4 _HaloFalloff_ST 14 attribute vec4 _glesMultiTexCoord0 15 attribute vec4 _glesColor 16 attribute vec4 _glesVertex 17 void main 18 19 10 gl_Position gl_ModelViewProjectionMatrix _glesVertex 20 4 xlv_COLOR _glesColor vo 2 xlv_TEXCOORDO _glesMultiTexCoord0 xy HaloFalloff_ST xy _HaloFalloff_ST zw 22 23 24 Vertex Shader Compile succeeded Performance estimate Cycle count 15 0 E Temporary registers used o Primary attributes used 10 Non dependent texture reads 0 b Reset Original Source Apply a Figure 34 Inspecting a shader 3 10 2 Shader Modification When analysing a trace it may be required to modify a shader program in order to test new behaviour in image output and performance To modify a shader perform the following 1 Repeat the procedure for shader inspection see Section 3 10 1 2 Make modifications to the shader program If the
7. 3 5 1 Gall Statistics iieiea asea a th coed deka wee aeaaeai ei aeniea 28 3 5 2 REENEN 29 3 5 3 Graphical Representation of Statistics cccccesseeeeeeceeeeeseaeeeeeeeseeeeescaeeesaeeeenees 29 3 5 4 Other Forms of Statistical Analyse 31 3 6 Een 31 3 7 Inspection Of Draw Cales 32 3 8 Current Call Inspection cceceeeeeeeeeceneeeeeeeeeeeeeeeaeeecaaeeeeaeeseaeeeseaeessaaeseeeeeseaeeesaeeeeaaeeeenees 33 3 8 1 STEET 33 3 8 2 ERD o e EE 34 3 8 3 OpenGL ES ET 35 3 8 4 OpenGL ES Oblects Aua 36 Revision PowerVR SDK REL_3 5 3523383a 2 User Manual og Imagination Public Imagination Technologies 3 9 Texture INS POCTION crcire ianea pata ne EEEn hat AEAEE UE EEA AE EAS 37 3 10 Shader Inspection Modification and Analysis cccsceeeeeeeeeeeeeeeeeeeeeeceeeeeseaeeeeaeeeenees 38 3 10 1 Shader NSPS COM 2 ices cvee sagen weeaeedate eens th cocepaccen eee eaaa arana aiii Ea 38 3 10 2 Shader Modticaton A0 3 10 3 Shader ET 41 3 11 LOG gle teure 42 3 12 Recorded Framebuffer cccccccccccccscececcssseeeceesseeeueeeeccesaueueeeeaeeeueeeeeesauaeeeeuauseusenaaeeeeans 43 4 PVR TracePlaybatk eseu EAR EEEEEERE 44 4 1 EINEN eeben eebe a a OP re 44 4 2 St AN ATION DEE 44 4 3 Using PVRTracePlayback on Android 44 4 3 1 General Command Line Options ccceccceceeeeeeeeeeeeeeeceeeesaaeeseneeseeeeesaeeeenaeeeenees 45 4 3 2 Advanced Command Line Options essssssesesessesiesiestnestissrnstrnns
8. In order to access that information perform the following die Click the desired error or warning displayed in the Static Analysis window This will open an information box an example of which is shown in Figure 23 Function Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable IO wO wO wO wO wO wO 0 wO 0 wo wo Frame Call UID 3626 3778 3970 4277 4562 4633 4838 4909 5114 5185 5390 EI a aa Face culling is disabled 1010 counts If possible prefer face culling to reduce vertex data processing as polygons will a gt be rejected early in the pipeline Figure 23 Viewing suggestions for resolving an issue 2 It is then possible to read the suggestion message displayed at the bottom of the information box Figure 23a The information box also lists occurrences of the function which caused the issue together with their associated frame and call numbers Note Suggestion messages are hardware specific 3 7 Inspection of Draw Calls A summary of draw calls is displayed in the Draw Calls window Figure 24 which details the number of vertices processed by each entry in the list Draw Calls Gx E Call Mode 0 glDrawElements GL_TRIANGLE_STRIP 586 1 glDrawElements GL_TRIANGLE STRIP 41 l 2 glDrawElements GL_TRIANGLE_STRIP 38 l 3 glDrawElements GL_TRIANGLE_STRIP 106 Lu glDrawElements GL_TRIANGLE_STRIP 1602 5 glDrawElement
9. and select the required listed thread value option Remove Filters In order to remove the filters that have been applied to particular calls perform the following 1 Toggle the filter icon Figure 9c to reveal any previously filtered and hidden calls 2 Right click the call for which the filter is to be removed This will reveal an action menu 3 Select the Remove Filter option from the menu to unmark the call for filtering Note All applied filters can be removed by right clicking anywhere in the Function call list area and selecting the Remove All Filters option 3 3 4 Highlight Options The PVRTrace GUI enables the user to apply highlighting to the calls displayed in the Function call list area This is a useful feature that provides a visual way of quickly differentiating between API calls through the use of colour Quick Highlighting To quickly add highlight to a call perform the following 1 Right click a call in the Function call list area This will reveal an action menu Revision PowerVR SDK REL_3 5 3523383a 22 User Manual og Imagination Public Imagination Technologies 2 Select the Add Highlight option from the menu This will then highlight the row corresponding to the chosen call as well as all occurrences of the call in the Function call list area Note It is also possible to add highlight to a given call by identifying the call in the Calls Summary tab of the Statistics window see Section 3 5 1 right c
10. data data com powervr PVRHub bin PVRTraceInstaller u PVRTrace 47 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination 6 Contact Details For further support visit our forum http forum imgtec com Or file a ticket in our Support system https ovrsupport imgtec com To learn more about our PowerVR Graphics SDK and Insider programme please visit http www powervrinsider com For general enquiries please visit our website http imgtec com corporate contactus asp Revision PowerVR SDK REL_3 5 3523383a 48 User Manual og Imagination Public Imagination Technologies Appendix A Manual Android installation A 1 Installation with Root Permission PVRTrace can be installed manually on an Android device This section captures the necessary steps for achieving manual installation on Android devices with root permission available Warning Incorrectly installing PVRTrace on a device may damage it to the point where it is necessary to re flash the device s firmware The following provides some necessary information to get started with the manual installation procedure Commands means command from a user shell means command from a root shell This requires Android Superuser su to be ran from the shell cp vs cat Some Android devices may not have the cp utility used in the instructions provided next If that is the case then use cat instead For example
11. v GL_FRAGMENT_SHADER Linked 12110173 Attached 12110173 Recorded Information log Figure 29 Viewing OpenGL ES state variables in the Object Data Viewer window 3 8 4 OpenGL ES Objects The OpenGL ES Objects tab inthe Current Call window provides a summary of the OpenGL ES objects that are currently active up to the selected call Figure 30 The information is listed and grouped under collapsible sections per object type Current Call Gx giDrawElements Call UID 177927 EGL State EGL Objects OpenGLESState OpenGL ES Objects Object Created at call Destroyed at call 2 v Textures gt GL_TEXTURE_2D Is GL_TEXTURE_CUBE_MAP Texture 21 1162 BR Texture 283 46887 v Shaders GL_VERTEX_SHADER GL_FRAGMENT_SHADER Programs v Framebuffers Framebuffer 140002 2144 gt Buffers LI a p Hide currently uncreated objects Figure 30 OpenGL ES Objects tab in the Current Call window To view further details about the participating OpenGL ES objects perform the following 7 v v 1 Select an item in the list This loads additional details in the Object Data Viewer window 2 Depending on the chosen item tabs are displayed in the Object Data Viewer for browsing the information Note It is possible to toggle between showing and hiding the currently uncreated OpenGL ES objects by using the provided checkbox Figure 30a Revision PowerVR SDK REL_3 5 3523383a 36 User Manual og Imagination Public Ima
12. zoom in and out view the entire graph centre the view on the active frame and view the start or end portion of the graph To navigate through the timeline click an area of the graph and drag horizontally to the right hand side Also use the scroll bar in the graph area as appropriate An alternative way to zoom in and out of the graph is by hovering the cursor over the graph area and scrolling up or down using the mouse wheel It is also possible to specify the zoom amount in the zoom level counter shown in Figure 20 To display thread activity on a per frame basis in the case of multi threaded applications click the Thread Usage tab Figure 21 The thin bar at the top of the graph indicates the primary thread which called egl1SwapBuf fers for each frame Each row illustrates a thread which has submitted calls for every frame Note that it is not possible to save data to CSV files when viewing the thread usage graph Revision PowerVR SDK REL_3 5 3523383a 30 User Manual Kn imagination Public Imagination Technologies OO ii ws File View Per Frame Statistics Thread Usage Zoom 0 Figure 21 Statistics Graph dialog box displaying thread usage 3 5 4 Other Forms of Statistical Analysis The PVRTrace GUI displays other forms of statistical information notably Draw calls statistics The number of vertices for each draw call in a particular frame is available from the Draw
13. EGL objects perform the following 1 Select an item in the list This loads additional details in the Object Data Viewer window similar to the example shown in Figure 26 2 Depending on the chosen item tabs are displayed in the Object Data Viewer for browsing the information Note It is possible to toggle between showing and hiding the currently uncreated EGL objects by using the provided checkbox Figure 27a Current Call ax glDrawElements Call UID 177927 EGL State EGL Objects OpenGLES State OpenGL ES Objects Object Created at call Destroyed at call v EGLContexts Context 0x6d063ef0 941 v EGLSurfaces Window Surfaces Surface 0x70c7d298 945 632982 a gt Hide currently uncreated objects Revision PowerVR SDK REL_3 5 3523383a 34 User Manual og Imagination Public Imagination Technologies 3 8 3 OpenGL ES State The ability to view changes in OpenGL ES renderstate is an important aspect of current call analysis since by minimising renderstate changes it becomes possible to boost performance The renderstate for the selected call is displayed in the OpenGL ES State tab in the Current Call window Figure 28 Current Call Gx giDrawElements Call UID 177927 EGL State EGLObjects OpenGLESState OpenGL ES Objects Variable Value a v Program GL_CURRENT_PROGRAM 11970171 b Textures v Framebuffers GL_FRAMEBUFFER_BINDING 70001 b Renderbuffers v Buffers GL_ARRAY_B
14. GL_TRIANGLE STRIP 422 otenable p zeen mer ls gldrawelements GL_TRIANGLE_STRIP 374 Jotscissor 0 0 1920 1080 La nineantlamante GI TRIANGLE STRID 1788 XJ Jotcolorttask GL_TRUE GL_TRUE GL_TRUE GL_TRUE Current Call E X JJolclearCotor 0 000000 0 000000 0 000000 0 000000 eee DrawElements Call UID 424077 Jotepthrtask a RUE E me g EGL State EGL Objects OpenGL ES State OpenGL ES Objects Lateartesgg 1 000000 Variable Value Y Pll foictearstencit o Levet Size Internal Format Type XP HI v GL TEXTURE 2D GL CURRENT PROGRAM 11970171 Jaen pen am pr e ae Sr e rom BUFFER IT m Level 1024x1024 GL_RGB GL_UNSIGNED_BYTE f Textures otpisable a _sc ssor rest B ea 512x512 GL RGB GL_UNSIGNED_BYTE GL_ACTIVE_TEXTURE GL_TEXTUREL otoisable _s1eN0 B tevez 256x256 GL_RGB GLUNSIGNED_BYTE v GL_TEXTURED Jotcutrace sace B ea 128x128 GLRGB GL_UNSIGNED_BYTE GL_TEXTURE_BINDING_2D 17 i B eves 64x64 GL_RGB GL_UNSIGNED_BYTE EE LEI UE E eas 32x32 GLRGB GL_UNSIGNED BYTE v J oteindButfer 9 DEET A5 J JESSE lee Cem Cem Object Data Viewer Shader Analysis Modifications Recorded Framebuffer Frame672 804 AN zl SS J Figure 2 General layout of the PVRTrace GUI 3 2 Menu Bar 3 2 1 File Menu Figure 3 illustrates the File menu The menu provides options for opening files exporting data viewing trace information and exiting the PVRTrace application Tools View Help
15. Open Ctrl O Open Recent File gt Export Data gt Save As Trace Info Exit Figure 3 File menu Open a File To open a pvrtrace file click File gt Open Figure 3 This will open a dialog box for browsing to the required file Alternatively keyboard shortcuts can be used to open files Open a Recent File To open a recently accessed file click File gt Open Recent File Figure 3 This will display a list of the recently accessed files from which the desired file can then be selected for opening Revision PowerVR SDK REL_3 5 3523383a 14 User Manual og Imagination Public Imagination Technologies Clear Recent Files To clear the list of recently accessed files click File gt Open Recent File Figure 3 An option called Clear recent files will become available to use Export Data Exporting data is essential for saving information in formats that can then be interpreted and used by external applications for subsequent analysis or for performing other tasks outside of the PVRTrace environment By clicking File gt Export Data Figure 3 it becomes possible to achieve the following To export the contents in the Function call list area for the current frame to a TXT file select the option called Current Frame txt e To export the contents in the Function call list area for all frames broken down frame by frame to a TXT file select the option called All Frames txt e To export shaders as V
16. Option 1 Using adb push directly requires root shell i e option 1 in step 1 adb push path to PVRTrace Recorder Android lt ABI gt lt LIBRARY gt so system vendor lib egl e Option 2 Use cp to copy the file from an SD card on the device adb push path to PVRTrace Recorder Android lt ABI gt lt LIBRARY gt so sdcard adb shell cp sdcard lt LIBRARY gt so system vendor 1ib64 lt LIBRARY gt so 4 Create the pvrtraceconfig json see Section 2 4 and place it in the SD card Make sure that TraceFile points to a writable location The TraceFile variable must be set accurately with an absolute path If it is not correctly set no file will be output It is suggested that write permissions for the app be checked before setting this As all subsequent processes will be traced after installation it is recommended to use an output folder that allows write access for all processes so that PVRTrace output does not fail and potentially threaten the stability of the device 5 Rename the copied files using mv to remove the PVRTRACE suffix mv libEGL PVRTRACE so libEGL so mv libGLESv1_CM_PVRTRACE so libGLESv1_CM so mv libGLESv2_PVRTRACE so libGLESv2 so 6 Reboot the device Note A hot reboot will work as well Option 1 Normal device reboot PVRTrace 53 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination adb shell reboot e Option 2 Hot reboot only the Android runtime
17. Output Mode There are several visualization modes that can be used to view different types of render outputs To select a specific render output mode perform the following 1 Click the dropdown menu provided in the Image Analysis window Figure 17c This will display several options from which the required one can then be chosen The following options are available e Normal This option displays a standard image output which is rendered coloured shaded etc e Wireframe This option displays the wireframe of each object within the scene being rendered The wireframe of each object is shaded e Wireframe No Shaders This option displays unshaded wireframes for each object in the scene e Depth Complexity This option displays a standard depth complexity render with each object being drawn with varying transparency where brighter areas are used to signal greater depth complexity e PowerVR Depth Complexity This option displays a standard depth complexity render indicating the depth complexity of pixels rendered by PowerVR hardware Note Selecting the Depth Complexity orPowerVR Depth Complexity options will display a value selector control inthe Image analysis window which allows the depth complexity value to be adjusted This has the effect of increasing or decreasing the brightness and contrast of the depth complexity render and is a useful feature in very complex scenes PVRTrace 27 Revision PowerVR SDK REL_3 5 3523383a I
18. State The state of EGL API for the selected call is displayed inthe EGL State tab inthe Current Call window Figure 25 To view further details about the participating EGL state objects for that call perform the following 1 Select an item in the list This loads additional details in the Object Data Viewer window Figure 26 2 Depending on the chosen item tabs are displayed in the Object Data Viewer for browsing the information PVRTrace 33 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Object Data Viewer Gx Context 0x6d063ef0 Call UID 177927 Information State Objects Variable Value v Information Config 0x00000014 Shared Context EGL_NO_CONTEXT v Context Attributes EGL_CONTEXT_CLIENT_VERSION 2 v Config Attributes EGL_BUFFER_SIZE 16 EGL_ALPHA_SIZE 0 EGL_BLUE_SIZE 5 EGL_GREEN_SIZE 6 EGL_RED_SIZE 5 EGL_DEPTH_SIZE 24 EGL_STENCIL_SIZE 8 EGL_CONFIG_CAVEAT EGL_NONE EGL_LEVEL 0 EGL_MAX_PBUFFER_HEIGHT 4096 EGL_MAX_PBUFFER_PIXELS 16777216 EGL_MAX_PBUFFER_WIDTH 4096 EGL_NATIVE_RENDERABLE EGL_FALSE EGL_NATIVE_VISUAL_ID 4 EGL_NATIVE_VISUAL_TYPE 0 EGL_SAMPLES 0 z Figure 26 Viewing EGL state objects in the Object Data Viewer window 3 8 2 EGL Objects The EGL Objects tab in the Current Call window provides a summary of the EGL objects that are currently active up to the selected call Figure 27 To view further details about the participating
19. action menu with several options allowing the user to adjust its display size and orientation as well as providing the ability to save the image for a given frame 3 5 Statistical Analysis Statistical information is important when analysing a trace Statistical analysis is supported in the PVRTrace GUI and is intended for providing a digest of the fundamental metrics for calls and frames as well as supporting the user with interactive graphical information for inspection 3 5 1 Call Statistics The Calls Summary tab inthe Statistics window provides a list of all the function calls within the currently selected frame and the number of times each function has been called within that frame Figure 18 The function calls are normally arranged in descending order of frequency Statistics ax Calls Summary Frame Summary gt attert glVertexAttribPointer 452 glUniform4fy 379 g BindBuffer 333 glUniformMatrixdfy 268 glBindTexture 131 glActiveTexture 129 glDrawElements 129 glUniform3fv 104 glBlendFuncSeparate 156 vi Graph Figure 18 Viewing API call statistics Revision PowerVR SDK REL_3 5 3523383a 28 User Manual og Imagination Public Imagination Technologies Watch a Call Any call listed in the Calls Summary tab can be marked for watch purposes The ability to watch a call facilitates the task of analysing a trace To watch a listed call 1 Right click the desired call in the Calls Summary tab to o
20. compatibility information installation instructions a guide to the functionality of the application and a complete listing of all interface options and preferences 1 2 Software Overview PVRTrace is a recording and analysis utility which captures all the API calls made by an OpenGL ES application as it is running and records the data for subsequent analysis It consists of three main components Recording Libraries These are shim libraries that sit between an OpenGL ES application and the platform s native graphics libraries capturing the API calls These calls are captured and written into a pvrtrace file for reading back by the PVRTrace GUI and PVRTracePlayback e PVRTrace GUI This serves as the analysis interface of PVRTrace allowing user friendly access to the contents of pre recorded pvrtrace files e PVRTracePlayback This tool is used to play back pvrtrace files on various platforms This enables accurate debugging of multiple runs of a program across multiple platforms PVRTrace 5 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination 2 Recording Libraries 2 1 Overview The recording of a trace is performed by multiple libraries notably shim libraries for each API and one core recording library Figure 1 Once on a platform the shim libraries intercept graphics API calls and send them to the recording library to write them to a file The calls are then passed on to the host libra
21. exist create it Also if PVRHub is being used it will automatically generate and modify this file in data data com powervr PVRHub so that the user does not have to edit the file by hand Note If working on an Android device please refer to the PVRTrace Quick Start Guide for Android Rooted Unrooted depending on the specifics of your device Note For illustration purposes an example of a complete configuration file is provided in Appendix B 2 4 1 Tracing Options Table 1 lists tracing options and their description Table 1 Tracing options and their description Option Description OutputFilename Type String Default spname pvrtrace This sets the name and location of the trace file that is output by the Recording Libraries The process ID of an application can be used as part of its trace file name by using pid in this field Likewise the application name can be employed by using spname It should be noted that the output filename must be set to a writeable location or no trace file will be output RecordData Type Boolean Default true This option states whether the trace libraries should record the data associated with each call or not With this option set to true texture information and buffer data etc are recorded along with the graphics API calls With RecordData set to false only the graphics API calls are recorded In general this option should be set to true unless file size is a problem Note P
22. is restarted adb shell stop start A 2 Installation without Root Permission For full instructions on how to perform manual installation without root permission please refer to the PVRTrace Quick Start Guide for Unrooted Android Devices Revision PowerVR SDK REL_3 5 3523383a 54 User Manual og Imagination Public Imagination Technologies Appendix B Complete Configuration File The following example shows a standard trace config which will apply to all applications The last lines of this example show how to override the options per process in this case our OpenGL ES 2 Water demo Miso Jf Enabled false ATRICIO OutputFilename sdcard pname pvrtrace RecordData true StartFrame D AppendTraceVersion true EndFrame 100 OptimizeRS false ExitOnLastFrame true ClientBufferRecordFrequency 1 SaveFrameBuffer false UseCompression false Ihe Debug Level 1 Ihe Network Ware Erue Enabled false BufferSize 256 Ir EE Es2LibraryPath system lib 1libGLESv2 so EslLibraryPath system lib libGLESv1l_CM so EglLibraryPath system lib 1ibEGL so Ir Z nse latinos A FunctionTimelineLevel 1 Enabled false RenderstateOverride true SoftwareCounters true Overrides WieqoUl il atieveMlexskes 2 0 DisableStencilTest false DisableAlphaTest false ForceFlatColourFrag false DisableDrawCal
23. 383a Imagination Technologies Public og imagination 3 3 5 Search Options Search by Criteria In the PVRTrace GUI the user is able to search for call information To use the search functionality 1 In the Function call list area select the icon identified in Figure 9f This will open the Find dialog box with options to specify the search criteria Figure 14 Q Fina Find what i a Look in All Threads H Whole Trace GG Start Frame 0 End Frame 804 Options Method b Match case Textual Regular Expression Figure 14 Find dialog box 2 Type into the provided text box the required string of characters for searching Recent search terms are stored and can be retrieved by using the dropdown arrow Figure 14a 3 In order to refine the search criteria use the various options provided in the dialog box Figure 14b For example in the case of multi threaded applications specific threads can be selected Also search can be applied to the current selected frame the entire trace or for a specific user defined frame range Additional options are present for searching by matching case and by using a search method which can be of two types namely textual or by regular expression 4 After the search criteria have been specified click the Find button to retrieve the search results The results are displayed in the Find Results window An example of retrieved search results is illu
24. Calls window see Section 3 7 e Shader analysis statistics It is possible to visualize the result of automated shader analysis from the Shader Analysis window see Section 0 3 6 Static Analysis Static analysis is a crucial part of automated inspection of a trace as it helps identify a list of issues in the form of errors and warnings which may affect performance This subsequently allows the user to focus on rectifying the issues to improve an application In the PVRTrace GUI the results of static analysis are summarised in the Static Analysis window Figure 22 The column labelled as Level depicts the severity of an issue in descending order starting from the top of the list and the Title column contains a brief description of an issue The Count column indicates the number of times that an issue has occurred Static Analysis ax Level Title Count OO Error eglGetConfigAttrib 17 A WI Possible VBO modification whilst in use 7355 A w2 Redundant glScissor call 1588 A w2 Redundant glViewport call 4276 A w2 Face culling is disabled 1010 A w3 Uncompressed texture used 226 A w3 Non existent shader uniform 132 Figure 22 Viewing the results of static analysis PVRTrace 31 Revision PowerVR SDK REL_3 5 3523383a Public og imagination Imagination Technologies View Suggestions to Resolve an Issue The static analysis feature of PVRTrace allows the user to view suggestions on how to resolve certain issues
25. Characters Back slash character 033 Octal x1lb Hex t Tab n Newline Back references 1 to 9 Reference to 17 to 9 capturing group PVRTrace 57 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Imagination Technologies the Imagination Technologies logo AMA Codescape Ensigma IMGworks 12P PowerVR PURE PURE Digital MeOS Meta MBX MTX PDP SGX UCC USSE VXD and VXE are trademarks or registered trademarks of Imagination Technologies Limited All other logos products trademarks and registered trademarks are the property of their respective owners Revision PowerVR SDK REL_3 5 3523383a 58 User Manual
26. EL_3 5 3523383a Imagination Technologies Public og imagination 3 2 3 View Menu Figure 7 illustrates the View menu The menu provides options for showing or hiding the various windows present in the PVRTrace GUI allowing for workspace customisation Note The workspace can also be customised by dragging and dropping the individual dockable windows to either the right or left hand sides of the interface or as standalone windows View Help Show Statistics Show Draw Calls Show Current Call Show Find Results Show Shader Analysis Show Image Analysis Show Log Show Modifications Show Recorded Framebuffer Show Object Data Viewer me ll En aes Sse E E E Sst Pe Show Static Analysis Figure 7 View menu Show or Hide Statistics Window To show or hide the Statistics window toggle View gt Show Statistics Figure 7 Show or Hide Draw Calls Window To show or hide the Draw Calls window toggle View gt Show Draw Calls Figure 7 Show or Hide Current Call Window To show or hide the Current Call window toggle View gt Show Current Call Figure 7 Show or Hide Find Results Window To show or hide the Find Results window toggle View gt Show Find Results Figure 7 Show or Hide Shader Analysis Window To show or hide the Shader Analysis window toggle View gt Show Shader Analysis Figure 7 Show or Hide Image Analysis Window To show or hide the Image Analysis window toggle View gt Show Im
27. ORM gt 3 1 3 User Interface Layout Figure 2 illustrates the general layout of the PVRTrace GUI The interface consists of the following sections e Menu bar Figure 2a This section enables access to several options related to file tools view and help e Function call list area Figure 2b This section lists all function calls that have been recorded e Image Analysis window Figure 2c This section allows the user to interact with several visualisation modes for a render output e The section identified in Figure 2d provides multiple windows organised as tabs for performing static analysis viewing statistics about function calls and frame information viewing the standard log output from the PVRTrace GUI and viewing search results e Draw Calls window Figure 2e This section lists all draw calls for the current frame e Current Call window Figure 2f This section allows viewing information regarding EGL state EGL objects OpenGL ES state and OpenGL ES objects on the currently selected call e The section identified in Figure 2g provides multiple windows organised as tabs for viewing object data performing shader analysis viewing modifications and recorded framebuffer information PVRTrace 13 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination File Tools View Help e
28. PVRTrace keeps crashing D KL E S 5 The library path s that are configured in the configuration file may be incorrect Check the file 9 8 for errors Also check there is enough disk space on the target device Network connection is not working Check the target device and the host machine are both on the same subnet If running Android also ensure that the AndroidManifest xml of the application being recorded contains internet permissions similar to the following lt uses permission android name android permission INTERNET gt lt uses permission gt D S Unexpected behaviour while recording O Ensure that the target device has enough disk space available to store a trace file Network x recording requires a good network connection Consider recording a trace locally and pushing the file to the host machine if the network connection is poor Z USB connection is not working Android In order to connect a target device to a host machine using USB the adb forward method must be used to open a TCP port on the host machine For example using the default TCP port 54321 adb forward tcp 54321 tcp 54321 No graphical output on target Android device after reboot This requires system recovery PVRTracelnstaller can also be used to restore the system in case the trace libraries were wrongly installed By executing with u it will restore the system 2 and terminate For example O
29. SH and FSH files select the option called Shaders e To export saved framebuffers as TGA file select the option called Saved Framebuffers tga e To export the contents of the Frame Summary tab in the Statistics window see Section 3 5 2 for all frames to a CSV file select the option called Frame Statistics csv e To export the contents of the Calls Summary tab of the Statistics window see Section 3 5 1 for all frames to a CSV file select the option called Call Statistics csv Save pvrtrace File To save a trace to the pvrtrace file format click File gt Save As Figure 3 This will open a dialog box which allows all or a set number of user specified frames to be saved View Trace Information To display a listing of trace information about the loaded trace file click File gt Trace Info Figure 3 This will open a dialog box containing the information which includes details such as the trace version file version and platform Exit PVRTrace To close the PVRTrace GUI click File gt Exit 3 2 2 Tools Menu Figure 4 illustrates the Tools menu The menu provides options for using the Remote Controller Statistics Graph and also enables preferences to be set Tools View Help Remote Controller Statistics Graph Preferences Figure 4 Tools menu Remote Controller The Remote Controller dialog box Figure 5 is used to connect to an application whose Recording Libraries are set up f
30. UFFER_BINDING 20580294 GL_ELEMENT_ARRAY_BUFFER_BINDING 7560108 b Blending b Colour gt Culling H a gt F Hide unchanging state Figure 28 OpenGL ES State tab in the Current Call window During renderstate inspection any state change that occurred since the previous call is highlighted in red The information is listed and grouped under collapsible sections such as program textures framebuffers colour polygon offset values scissoring details etc These groupings are visible depending on the OpenGL ES version of the current EGL context for the current call To view further details about the participating OpenGL ES variables perform the following 1 Select an item in the list This loads additional details inthe Object Data Viewer window an example of which is shown in Figure 29 2 Depending on the chosen item tabs are displayed in the Object Data Viewer for browsing the information Note It is possible to toggle between showing and hiding unchanging OpenGL ES states by using the provided checkbox Figure 28a PVRTrace 35 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Object Data Viewer Gx Program 11970171 Call UID 177927 Information GL_VERTEX_SHADER GL_FRAGMENT_SHADER Parameter Value GL_ATTACHED_SHADERS 2 GL_DELETE_STATUS GL_FALSE GL_LINK_STATUS GL_TRUE GL_LINFO_LOG_LENGTH 0 Shaders Attachment Shader wv GL VERT SHADER Linked 12040172 Attached 12040172
31. VRTracePlayback and the PVRTrace GUI can only play back traces recorded with RecordData set to true StartFrame Type Integer Default 0 This states the frame at which recording should begin EndFrame Type Integer Default 0 This states the last frame to be recorded ExitOnLastFrame Type Boolean Default false If set to true the application will quit after the last frame has been recorded Revision PowerVR SDK REL_3 5 3523383a 8 User Manual og Imagination Public Imagination Technologies Option Description ClientBufferRecordFrequency Type Integer Default 0 This option is used to control when an EGLClientBuffer which is the backing store of an EGLImage is sampled for recording 0 means that client buffers will not be recorded 1 means that the client buffer will be sampled once each frame and 2 means that it will be sampled after each draw call 3 is used to only sample the client buffer once for recording at the time the EGLImage Is created It is important to remember that the more samples PVRTrace performs the larger the output file will be and also may affect the application s performance SaveFrameBuffer Type Boolean Default false If this option is set to true the application will save the framebuffer each frame effectively taking a screenshot of the application running on the device It is important to remember that this option will significantly increa
32. ae ax Level Title Count YBa Eror egiGetConfigAttrib 17 _ Jleaiceterror 19 ae AX Wi Possible VBO modification whilst in use 7355 E Jeaiceterror a success W2 Redundant glScissor call 1588 e A WC Redundant glViewport call 4206 Jeotcet rror e ams d W2 Face culling is disabled 1010 JJeaiceterror 6a_success A W3 Uncompressed texture used 226 Jeolceterror 9 ass A W3 Non existent shader uniform 132 I cart sent aie c Jlealcet rror a1_suCCESS Jleaiceterror E amp _suc ss JotwindBuffer GL _ARRAY_BUFFER 27720396 i m me JJotttapBufferoes GL_ARRAY_BUFFER GL_WRITE_ONLY Static Analysis Find Results E olBindBuffer 9 Assa pen 27720396 x Fe oh z otunmapsufferoes GL_ARRAY_BUFFER GL_TRUE Render Resolution 1920x1080 2 ca Mode Vertices jal lBindBuffer GL_ARRAY_BUFFER 0 Object x ln gldrawelements GL_TRIANGLESTRIP 474 I Dea ene SG oiviewport 0 1920 1080 Texture 225 Call UID 424077 1 idrewelements GL_TRIANGLE STRIP 958 Jotviewport 0 0 1920 1080 Faces Parameters 2 gldrawelements GL_TRIANGLE STRIP 2062 j C SRE A jolGetintegery c RED Ss 3 oldrewElements GL_TRIANGLE STRIP 7582 otc e jetIntegerv GL_GREEN_BITS 6 e Ia giDrawElements GL_TRIANGLE STRIP 538 SES GetIntegerv GL_BLUE_BITS 5 5 albrewelements GL_TRIANGLE STRIP 38 Is rv GL_BLUE BITS an le gldrewelements GL_TRIANGLE STRIP 2749 Joicetintegery pa erts 0 7 gldrawelements
33. age Analysis Figure 7 Show or Hide Log Window To show or hide the Log window toggle View gt Log Figure 7 Show or Hide Modifications Window To show or hide the Modifications window toggle View gt Show Modifications Figure 7 Show or Hide Recorded Framebuffer Window To show or hide the Recorded Framebuffer window toggle View gt Show Recorded Framebuffer Figure 7 Revision PowerVR SDK REL_3 5 3523383a 18 User Manual og Imagination Public Imagination Technologies Show or Hide Object Data Viewer Window To show or hide the Object Data Viewer window toggle View gt Show Object Data Viewer Figure 7 Show or Hide Static Analysis Window To show or hide the Static Analysis window toggle View gt Show Static Analysis Figure 7 3 2 4 Help Menu Figure 8 illustrates the Help menu The menu provides options for accessing PVRTrace help assets sending feedback viewing general PVRTrace release information and checking for software updates PVRTrace Help Feedback About Check for Updates View PVRTrace User Manual To view the PVRTrace User Manual click Help gt PVRTrace Help Figure 8 Submit Feedback To provide feedback click Help gt Feedback This will open a dialog box where instructions are displayed on how to post feedback and request for support Figure 8 About PVRTrace To view basic information about PVRTrace release information such as versioning and contact d
34. be installed from the PowerVR SDK installer 1 Navigate to the PowerVR Insider SDK webpage powervrinsider com and download the SDK 2 Launch the installer and follow the on screen instructions Once the SDK has been successfully installed the Recording Libraries can be found within the PVRTrace folder in the install directory lt InstallDir gt PVRTrace Recorder lt PLATFORM gt 2 3 2 Windows For installation on Windows perform the following steps 1 Copy LibEGL d11 libGLESv2 d11l OpenGL ES 2 0 and 3 0 libGLES CM d1l 1libGLESv1_CM d1l1 OpenGL ES 1 1 and PVRTrace d11 to the executable folder 2 If a PVRTrace configuration file does not exist make one manually see Section 2 4 Place pvrtraceconfig json into the executable folder Get 4 Update pvrtraceconfig json so that EglLibraryPath EslLibraryPath and Es2LibraryPath are set to the location of the system s graphics libraries see Section 2 4 2 3 3 Linux For manual installation on Linux perform the following steps 1 Copy LibEGL so libGLESv2 so OpenGL ES 2 0 3 0 and 3 1 LibGLES CH so libGLESv1_CM so OpenGL ES 1 1 and 1ibPVRTrace so to any folder 2 Set the LD LIBRARY PATH to the folder containing the new libraries This can be set using export LD LIBRARY PATH and reverted once the trace is complete Alternatively this can be set by using LD LIBRARY PATH lt APPLICATION_ NAME gt as part o
35. cissor to fit screen resolution delay lt NUM gt Forces PVRTracePlayback to wait a specified number of milliseconds between rendering frames skip failed calls Makes PVRTracePlayback skip calls that failed during recording ignore thread lt THREADS gt Makes PVRTracePlayback not play the specified threads Example ignore thread 1 5 ignore window lt WINDOWS gt Forces PVRTracePlayback to not play the specified windows Example ignore window 6 8 window lt WINDOW gt Only render the specified window save frame buffer lt FOLDER gt Saves a tga file of the frame at the eglSwapBuffer call in specified folder If this is not specified the file will be saved in the same folder as the pvrt pvrtrace file run lt NUM gt Perform the specified value number of runs of the trace verbose Makes PVRTravePlayback display more information when playing back traces info Prints out the file information such as a list of windows and threads help Displays this list and exits the utility version Prints version information and exits the utility robust Forces PVRTracePlayback to use EGL EXT create context robustness and GL EXT Robustness disable api checks Disables the checks to ensure the context supports the API of the call being played khrdebug Enables the use of GL_KHR_ debug for every context
36. ct eos iE i EEE E E REEE AE S ER 18 Figure 8 Fel Ru E 19 Fours 9 Function call liSt area siestan AE ARA KAARE 20 Figure 10 Action menu displayed on right clicking a function call 20 Figure 11 Selecting a frame sisi sirina i A AE A AN A 21 Figure 12 Advanced filtering using the Filter Highlight Functions dialog Dos 22 Figure 13 Advanced highlighting using the Filter Highlight Functions dialog Dos 23 Foue T4 Fndadialog DOs bbseric hos daa cee og duteheneanae dudes ene ates de Severe deamndead pidetaeden dad he foeteeia tad 24 Figure 15 Viewing search results cceecccceceecccceeeseceeeeeeeceeeeeeeaeeeeaeaaeeeeseaaeeesaeeaaeeseeaaenseeeaseeseeeaseneeees 25 Figure 16 Viewing disabled calls in the Modifications ab 26 Figure 17 Image Analysis WiINGOW c cccceeeeeeeeeeeeneee eee ae eset teases ee eaaeeeeeeaaeeeeeeaaeeeeeeaaeeeeeeaeeeeeeaeeeeneaa 27 Figure T8 Viewing API Call Statistics vic cciiecesccedatencetdicaceetiieesevientneereeateneenscaaeeteltaaesiieeaertateen EES 28 Foure 19 VIEWING Weu Ee 29 Figure 20 Statistics Graph dialog box displaying per frame statistics ccceeseeeeeeeeteeeeeteeeeneeteaes 30 Figure 21 Statistics Graph dialog box displaying thread usage 31 Figure 22 Viewing the results of static ANALYSIS 0 0 0 eee eeeee ee eene ee ee eeee ee eee ae ee ee eaae ee ee taaeeeeeeaaeeeeetaeeeeeeea 31 Figure 23 Viewing suggestions for resolving AN Iesue ssssssssssrrssssrrssrrrrssrirrssirnsst
37. e by the PVRTrace GUI 6 Run the PVRTrace GUI and open the output file to begin analysis 2 5 3 Recording on Android Recording on Android can be performed using PVRHub For more information refer to the PVRHub User Manual The user manual can also be accessed from the PVRHub application Note It is important to remember that on unrooted Android devices OpenGL ES 1 1 and OpenGL ES 2 0 3 0 3 1 cannot be mixed Revision PowerVR SDK REL_3 5 3523383a 12 User Manual og Imagination Public Imagination Technologies 3 PVRTrace GUI 3 1 The Basics 3 1 1 Overview The PVRTrace GUI is the graphical user interface of PVRTrace It opens pvrtrace files created with the PVRTrace Recording Libraries and displays them in a user friendly format A wealth of information is displayed in the user interface and that information is broken down frame by frame including details such as the number of times a given call occurs in a trace to the exact values of a specific matrix PVRTrace currently supports the following APIs e EGL e OpenGL ES 1 1 e OpenGL ES 2 0 3 0 and 3 1 3 1 2 Installation The PVRTrace GUI can be installed from the PowerVR SDK installer 1 Navigate to the PowerVR Insider SDK webpage powervrinsider com and download the SDK 2 Launch the installer and follow the on screen instructions 3 Once the SDK has been successfully installed the PVRTrace GUI will be available in lt InstallDir gt PVRTrace GUI lt PLATF
38. e number of fragments multiplied by the number of cycles per fragment e Fragment Count This option displays the number of fragments per frame output by each fragment shader e Fragment Tex Reads This option displays the number of texture reads performed per fragment shader e Vertex Cost This option displays the cost of vertices output by each primitive which is the number of vertices multiplied by the number of cycles per vertex e Vertex Count This option displays the number of vertices per primitive per frame Shader Analysis a x Selected Pixel a gt coordinates 865 657 Fragment Shader IDs 12110173 Lie b Frame Summary Total Fragments 2 739 752 Total Vertices 62 024 Average Overdraw 1 32125 pen Fragment cost lt ID Count Cycles Tex Reads B 2321 18 097 2 E 3673 50 415 8 E 4362 307 812 3 E 47822 178 540 26 E 48097 114 135 1 E 48848 21 382 5 E 48953 177 856 3 E 50275 37 623 10 E 50315 1 776 093 7 ES 50362 12 044 3 ES 50432 3 504 e E 50479 627 6 Figure 37 Viewing the Shader Analysis tab 3 11 Log Information Any error from the application or from playing back a trace is reported in the PVRTrace GUI and to access this information select the Log window Figure 38 fom c N N Fa NUWE ba GO Wo Be Note Any output not from the current frame is greyed out Revision PowerVR SDK REL_3 5 3523383a 42 User Manual En imagination Public Imagination T
39. e trace select the option Find all in Whole Trace This will display the search results in the Find Results window Figure 15 Note The Find all in frame option is also accessible from the Calls Summary tab of the Statistics window see Section 3 5 1 by right clicking a call and selecting that option 3 3 6 Disable or Enable Calls During the analysis of calls in the Function call list area itis sometimes required to disable certain calls to facilitate the identification of problems in a trace To disable a call perform the following 1 Inthe Function call list area identify the call that is of interest 2 Right click the call to reveal an action menu 3 Select the Disable Call option from the menu The call will be disabled and greyed out If the trace was recorded with data and therefore viewable in the Image Analysis window then disabling a call causes it not to be processed when determining the image output Furthermore all disabled calls will be summarised in the Modifications window where for a given call the call number is also shown Figure 16 PVRTrace 25 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Modifications ax Enable Disable modifications v Disable calls Call UID 424055 glBindBuffer Call UID 424058 glVertexAttribPointer Call UID 424060 glEnableVertexAttribArray Call UID 424072 glBindTexture Call UID 424090 glUniform3fv Call UID 424096 g
40. echnologies Log Analyzing Image Render Scene F 672 PixelAnalysis in progress FB 1 5 FB 2 5 FB 5 5 PixelAnalysis in progress Done Analyzing Image Render Scene F 672 Done Analyzing Image Render Scene F 672 Analyzing Image Render Scene F 672 Done Formatting Final Image ImageAnalysis Image 1920x1080 3 12 Recorded Framebuffer The Recorded Framebuffer window is active if the trace was recorded with the SaveFrameBuf fer parameter enabled see Section 2 4 1 The window displays the contents of the final framebuffer from the original device PVRTrace 43 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination 4 PVRTracePlayback 4 1 Overview PVRTracePlayback is a tool for playing back a pre recorded pvrtrace file It does this by reading the pvrtrace file and repeating each function call from the file As this requires the pvrtrace file to contain information pertaining to the textures vertex buffers etc from the original recording it is required that the recording be performed with RecordData set to true in the configuration file see Section 2 4 4 2 Installation PVRTracePlayback takes the form of a native executable on most operating systems and thus requires no installation On some operating systems e g Android PVRTracePlayback takes the form of a native package e g Android application package APK These native packages should be installed
41. eeed eet aaide iaaa aaae daa deeg aaae aaaea ug des 10 2 4 4 Roettgers aa e aaa enaa a a a aea ae e deg 10 2 4 5 Steidltrleb its IN 11 2 5 Recording wih PYRT ACE sessin s EN AAE S S 12 2 5 1 Remote Network Recording s ssssssirisessarivisenissi rresia iaaa 12 2 5 2 On Device Recording cccccececcceeeeeeeeeeeceeeeeceaeeeeaaesaeeecaeeeeaaeseeaeesseeeeseaeeneaaeeninees 12 2 5 3 Recording on ANdIOld DT 12 3 Nr 13 3 1 The BASICS cnnan hited adie ati eateees nideds arable adel adie shatn 13 3 1 1 OVEIVIOW geg EEN Ges ee deans nies 13 3 1 2 STAM AON WEE 13 3 1 3 User Interface Layout tics useterget stet geed 13 3 2 leng Ball asarria iann Edge 14 3 2 1 Pile MO E 14 3 2 2 TOOIS MON esasa aaa A AAAA SEREA S 15 3 2 3 VUEN 18 3 2 4 Help Menura nananana A AA EEA 19 3 3 Working with the Function Call List ccccecccceceeeceeeeeeeeeeeeeeeeeeaeeeeeeeseeeeeseaeeesaeeseaeeenaes 20 3 3 1 View Calls by TE 21 3 3 2 Expand or Collapse Draw Calls c cccccceeceeceeseeeeeeeceaeeeeaaeeseeeeseeeeesaeeetaeeeeneeees 21 3 3 3 SIE 21 3 3 4 Highlight gl el 22 3 3 5 SEACH OPTIONS ET 24 3 3 6 Disable or Enable Cales 25 3 3 7 Function Call Documentation 26 3 4 le TN 26 3 4 1 Select a Render Output Mode 27 3 4 2 View Image Output by Draw Call Type 28 3 4 3 Other ACTIONS occ sticsciie ences cack eege keE E ceeds deka wes E geed ee 28 3 5 Statistical Analyse 2xzeecueee dkseegeueeROEERe E ee ENEEEESEE SSES AE 28
42. eneaa 43 List of Tables Table 1 Tracing options and their description sssesesssssssssrernesssttttntnnsttstttnnnnnnnrsttnnn nannan nnnn nnne annene nenn 8 Table 2 Debug options and their description ccccccceeeeeeeeeeeceeeeeeeeeeeaeaeeeeeeesesnaaeaeeeeeeeseeenneaeeeeeess 9 Table 3 Network options and their description 10 Table 4 Host options and their descrptton ce eececeeeeeteeeeeenneeeeeeeaeeeeeeaaeeeseeaaeeeeeeaaeeeessaaeeeeseaeeeeneaaes 10 Table 5 Profiling options and their description ssssssssssssssssrrnnsssstttnnnnnsststttnnnnnsstntnnnnnnnsnnnnnn annene nnt 11 Table 6 Renderstate Overrides ccccsccccesssececeesneeececaeeeeeceaeeecscaaeeesecsaeeesesaeeeeseaaeeeesesaeeessesaeeeesnaaes 11 Table 7 General command line options and their description cccecececeteeeeeeeeeeeeeseeeeeseaeeeeeeeeeeees 45 Table 8 Advanced command line options and their description 0 eeeeeeeeeeeeeeeeneeeeeeeaeeeeeenaeeeetenaes 46 Table 9 Troubleshooting ISSUES aces cece eeseeaaeaeeeeeeeecaaaaeaeceseesadeaaeaeseeeedseeeeneeeeeeeess 47 Table 10 Regular expression syntax and description 56 Revision PowerVR SDK REL_3 5 3523383a 4 User Manual og Imagination Public Imagination Technologies 1 Introduction 1 1 Document Overview The purpose of this document is to serve as a complete user manual for the PVRTrace analysis tool and its associated libraries as well as PVRTracePlayback It includes
43. etails click Help gt About Figure 8 Check for Updates As of SDK release 3 0 PVRTrace is able to auto update However to force check for software updates click Help gt Check for Updates Figure 8 PVRTrace 19 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination 3 3 Working with the Function Call List Upon loading a pvrtrace file the Function call list area ofthe PVRTrace GUI is populated with all the function calls that have been recorded for a particular frame Part of the Function call list area is illustrated in Figure 9 a c d f e Y Y Q Thread ID all fi Jealceterror BGL_SUCCESS glDrawelements GL_TRIANGLE_STRIP 474 GL_UNSIGNED_SHORT NULL a olsindBuffer GL_ELEMENT_ARRAY_BUFFER 8750125 olbuffersubpata GL_ELEMENT_ARRAY_BUFFER 0 1916 Data 1916 bytes olsindButfer GL_ELEMENT_ARRAY_BUFFER 0 olpindBuffer GL_ELEMENT_ARRAY_BUFFER 8750125 ei b olpindBuffer GL_ARRAY_BUFFER 20580294 JolvertexattribPointer 0 3 GL_FLOAT GL_FALSE 60 0x20 glvertexattribPointer 2 3 GL_FLOAT GL_FALSE 60 Ox2c JolvertexattribPointer 3 2 GL_FLOAT GL_FALSE 60 0x3c Figure 9 Function call list area In the Functional call list area for individual calls listed it is possible to perform the following basic actions e Hover over a given call to display a toolt
44. example if the original file stated 0 0 android 0 1 POWERVR_SGX_540 120 Edit to Revision PowerVR SDK REL_3 5 3523383a 50 User Manual og Imagination Public Imagination Technologies 0 0 android 0O 1 PVRTRACE 6 Once a trace is complete the changes to eg1 cfg must be reverted to avoid any undesired behaviour This should be done before a reboot to avoid the need for flashing the device s firmware A 1 2 Installation on Android 4 4 or Newer Version To manually install PVRTrace on a device with Android 4 4 KitKat or newer version 1 Make the Android system directory writable e Option 1 Using ADB adb root adb remount e Option 2 Using the command line adb shell mount o rw remount system 2 Copy libPVRTrace so to system vendor 1lib Option 1 Using adb push directly requires root shell i e option 1 in step 1 adb push path to PVRTrace Recorder Android lt ABI gt libPVRTrace so system vendor lib libPVRTrace so Option 2 Use cp to copy the file from an SD card on the device adb push path to PVRTrace Recorder Android lt ABI gt libPVRTrace so sdcard libPVRTrace so adb shell cp sdcard libPVRTrace so system vendor lib libPVRTrace so 3 Move the original EGL and OpenGL ES driver libraries from system vendor 1lib egl to system lib egl The libraries to copy are libEGL_ lt DRIVER_NAME gt so libGLESv1 CM lt DRIVER NAME gt so and 1ibGLESv2_ lt DRIVER NAME gt so
45. f running the trace 3 If pvrtraceconfig json does not exist make one manually see Section 2 4 4 Place pvrtraceconfig 4json into the executable folder 5 Update pvrtraceconfig json so that EglLibraryPath EslLibraryPath and Es2LibraryPath are set to the location of the system s graphics libraries see Section 2 4 Note In addition to the manual approach installation on Linux can also be made using PVRHub For more information on using PVRHub on Linux see the PVRHub User Manual 2 3 4 Android Installation on Android can be done using PVRHub which is the preferred method of controlling the Android Recording Libraries The PVRHub APK can be found in the folder lt InstallDir gt PVRHub Once this APK has been installed on a rooted device it can be used to control and setup the Recording Libraries with no manual editing of the PVRTrace config file or file system For more information on PVRHub see the PVRHub User Manual Note PVRTrace can also be manually installed on Android For further details see Appendix A PVRTrace 7 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination 2 4 Configuration The PVRTrace Recording Libraries require a configuration file named pvrtraceconfig json This file should be located in the working directory of the application you are tracing on Android devices the file can also be found in data data com powervr PVRHub If the file does not
46. ffers etc Figure 33 2 In the list of objects scroll to the Shaders section The shaders are arranged as vertex and fragment shaders where each shader is given a unique identifier Revision PowerVR SDK REL_3 5 3523383a 38 User Manual og Imagination Public Imagination Technologies Current Call x glDrawElements Call UID 177927 EGL State EL Objects OpenGL ES State OpenGL ES Objects Object Created at call Destroyed at call 4 v Textures b GL_TEXTURE_ 2D p GL_TEXTURE_CUBE_MAP v Shaders v GL_VERTEX_SHADER Shader 70001 958 Shader 350005 1183 Shader 560008 2112 Shader 770011 2234 Shader 910013 2299 Shader 2240032 3497 Shader 2380034 3651 pd v Hide currently uncreated objects 3 Select the required vertex or fragment shader by clicking it This will then display the contents of the shader program in the Source tab of the Object Data Viewer Figure 34 Note The editor present in the PVRTrace GUI is a built in instance of PVRShaderEditor which is also available as a separate utility in the PowerVR Graphics Tools amp SDK For more information see the PVRShaderEditor User Manual 4 Once opened inspect the shader program as appropriate There are alternative methods which can be used to open a shader program These are e Pick a shader from the relevant call in the Function call list area e A shader can be opened by looking in the Programs section of the list of OpenGL
47. following the operating systems standard installation procedure e g Android Debug Bridge ADB install 4 3 Using PVRTracePlayback on Android On Android the PVRTracePlayback app loads one of the following specific files in order sdcard PVRTrace trace pvrtrace tmp trace pvrtrace If neither of these files exists the application will quit To use PVRTracePlayback on Android copy an existing trace file to one of these locations ensuring the file is called trace pvrtrace The following identifies usage instructions for PVRTracePlayback PVRTracePlayback optimised memory vsync dont resize delay lt NUM gt skip failed calls ignore thread lt THREADS gt ignore window lt WINDOWS gt window lt WINDOW gt save frame buffer lt FOLDER gt Note PVRVFrame will be required on systems that do not natively support OpenGL ES Revision PowerVR SDK REL_3 5 3523383a 44 User Manual Kn imagination 4 3 1 Public Imagination Technologies General Command Line Options Table 7 lists the general command line options and their description Table 7 General command line options and their description Description optimised memory Forces PVRTracePlayback to use a fixed amount of memory 20MB This is done avoiding loading the whole trace in memory vsync lt NUM gt Overrides v sync to a specified value NUM dont resize Forces PVRTracePlayback to not resize the viewport s
48. gination Technologies 3 9 Texture Inspection The textures recorded in a trace can be inspected using the PVRTrace GUI This allows the user to visualize textures and cross reference them to the calls that have participating textures In order to view a list of recorded textures select the OpenGL ES Objects tab inthe Current Call window Figure 31 By default all the textures active at the currently selected call are listed Textures are usually shown with thumbnails and hold a GLES handle name of the object ID Details are also provided for the calls at which they were created and or destroyed Current Call x glDrawElements Call UID 177927 EGL State EGL Objects OpenGLESState OpenGL ES Objects Object Created at call Destroyed at call S v Textures v GL_TEXTURE_2D D lecture 70001 950 Texture 1 1078 Texture 3 1085 Texture 5 1092 B Texture 7 1099 Texture 9 1106 Texture 11 1115 Texture 13 1122 DI Texture 15 1133 BB tecture 17 1144 z H V Hide currently uncreated objects Figure 31 Inspecting textures To inspect a texture perform the following 1 Select the OpenGL ES Objects tab inthe Current Call window and go to the Textures section of the list Figure 31 2 Select the desired texture This will then display the texture in the Object Data Viewer window Figure 32 Alternatively a texture can be picked from the relevant call in the Function call list area Note The size of the disp
49. he frames is taking too long and the user is only interested in the Revision PowerVR SDK REL_3 5 3523383a 16 User Manual og Imagination Public Imagination Technologies function calls Deselecting the checkbox prompts for reloading the pvrtrace file after which the image analysis functionality is disabled e Enable Primitive Highlighting This option is available under the Image Analysis section of the Preferences dialog box Figure 6 The option when ticked will highlight the currently selected primitive in the Image Analysis window see Section 3 4 drawing it as an overlay wireframe with the selected colour e Play calls that failed during recording This option is available under the Image Analysis section of the Preferences dialog box Figure 6 The option when ticked allows replaying failed calls that occurred during the recording of the trace file see Section 3 4 e Highlight Colour This option is available under the Image Analysis section of the Preferences dialog box Figure 6 The colour that the primitive highlight is displayed in can be specified by clicking the corresponding button This will open a colour picker from which the required colour can be selected e Heatmap Colouration This option is available under the Image Analysis section of the Preferences dialog box Figure 6 Heatmap colouration can be set by selecting either the Chromatic of Acrochromatic radio buttons e Wireframe Effect Colour This opti
50. ip which identifies both its contents and its data type e g Stride size pointer etc Each function call can be clicked on This updates the renderstate to illustrate the actual state after the function call has completed Moreover clicking a texture or shader function call in the Function call list area displays these textures and shaders in the Object Data Viewer window e Individual calls can be right clicked to reveal an action menu as shown in Figure 10 This menu provides options for performing filtering and highlighting tasks amongst others and is explained in subsequent subsections of this user manual Add Filter Add Highlight Disable Call Clear Disabled Calls Function Quick Help Find all in Frame Find all in Whole Trace View Object gt Figure 10 Action menu displayed on right clicking a function call Note Any function call that has spawned an error is highlighted with red text after the function parameter in the Function call list area Revision PowerVR SDK REL_3 5 3523383a 20 User Manual og Imagination Public Imagination Technologies 3 3 1 View Calls by Frame For a given pvrtrace file the PVRTrace GUI can be used to analyse calls frame by frame Every time a frame is selected the contents of Function call list area are updated to show the calls that have been traced at the chosen frame In order to view the calls for a specific frame perform the following 1 Use the frame scrubbe
51. lActiveTexture Call UID 424131 glUniformlfv Call UID 424144 glBindBuffer Call UID 424164 glUniformMatrix4fy Call UID 424170 glActiveTexture v Modify shader source calls SS S S S S S S S S Figure 16 Viewing disabled calls in the Modifications tab Note To re enable all the previously disabled calls uncheck the disabled call from the Modifications window and apply changes Alternatively right click anywhere in the Function call list area and select the Clear Disabled Calls option 3 3 7 Function Call Documentation In most cases the documentation for function calls can be accessed by performing the following i Identify the desired function call and right click it in the Function Call List area to reveal an action menu 2 Select the option called Function Quick Help This will open the documentation page for the function call on the Khronos website 3 4 Image Analysis By default if a trace being analysed was recorded with data the Image Analysis window would display the overall render output of the current frame from the first draw call to last Figure 17 The image analysis capability supported in the PVRTrace GUI provides access to various means of visualizing an image output The following basic actions can be accomplished during image analysis e Zoom in and out Use the zoom menu provided to magnify or decrease the size of the displayed image Figure 17a e Select a frame Use the f
52. layed texture image can be adjusted by using the zoom feature provided Figure 32a PVRTrace 37 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Object Data Viewer ax Texture 215 Call UID 177927 Faces Parameters tevalo ep ie a Level Size Internal Format Type Ge v GL TETURE 2D 9 Level 0 1024x1024 GL_COMPRESSED_RGBA_PVRTC_4BPPVL_IMG ki Level 1 512x512 GL COMPRESSED_RGBA_PVRTC_4BPPV1_IMG bes Level 2 256x256 GL_COMPRESSED_RGBA_PVRTC_4BPPV1_IMG E Level3 128x128 GL_COMPRESSED_RGBA_PVRTC_4BPPV1_IMG be Level 4 64 x 64 GL_COMPRESSED_RGBA_PVRTC_4BPPVL_IMG a Level 5 32x32 GL_COMPRESSED_RGBA_PVRTC_4BPPV1_IMG E Level 6 16x16 GL_COMPRESSED_RGBA_PVRTC_4BPPV1IMG x Figure 32 Viewing a texture in the Data Viewer 3 Further inspection of a texture can be done by viewing the data associated with it such as any mip map levels parameters etc 3 10 Shader Inspection Modification and Analysis 3 10 1 Shader Inspection The PVRTrace GUI supports the inspection of vertex fragment and compute shaders This is facilitated through the use of an editor which supports syntax highlighting and displays approximate per line cycle counts and register information To inspect a shader perform the following 1 Select the OpenGL ES Objects tab inthe Current Call window This will display the loaded OpenGL ES objects including any textures shaders programs framebu
53. licking the call and selecting the Ada Highlight option Advanced Highlighting Options for advanced highlighting are accessed by selecting the icon identified in Figure 9d This opens the Filter Highlight Functions dialog box which provides further options to achieve a finer level of highlighting Figure 13 E E Filter Highlight Functions 2 mo Function Name Highlight Hide EGL OpenGL ES d Figure 13 Advanced highlighting using the Filter Highlight Functions dialog box To use advanced highlighting 1 Open the Filter Highlight Functions dialog box 2 Under the Highlight column tick the checkbox for the desired API Finer highlighting can be applied by expanding an API name and selecting the required function groups for that API 3 Click the Accept button to apply the highlighting settings Remove Highlights In order to remove the highlights that have been applied to particular calls perform the following 1 Right click a highlighted callin the Function call list area This will reveal an action menu 2 Select the Remove Highlight option from the menu This will clear any highlight that has been applied to the call as well as all occurrences of the highlighted call in the Function call list area Note All highlights can be cleared by right clicking anywhere in the Function call list area and selecting the Remove All Highlights option PVRTrace 23 Revision PowerVR SDK REL_3 5 3523
54. ling as defined in the user application 2 5 Recording with PVRTrace 2 5 1 Remote Network Recording The following steps highlight the procedure for local recording with the PVRTrace GUI 1 Install the recording libraries on the target device as per the installation instructions see Section 2 3 2 Ensure that pvrtraceconfig json is set correctly for network recording see Section 2 4 3 If required set Network Wait to 1 This allows the initial setup calls of the application to be remotely recorded and the app will start playing upon connection 4 Run the PVRTrace GUI and launch the Remote Controller by clicking Tools gt Remote Controller see Section Remote Controller 5 Run through the steps identified in Section Remote Controller for recording and opening a trace file 2 5 2 On Device Recording The following steps highlight the procedure for on device recording with PVRTrace 1 Install the PVRTrace libraries on the target device as per the installation instructions see Section 2 3 2 Ensure that pvrtraceconfig json is set correctly See Section 2 4 and that the application has permission to write to the output location set under Tracing OutputFilename in pvrtraceconfig json 3 Ensure that pvrtraceconfig json has Network Enabled set to false 4 Run the application to be traced 5 Once the application has exited copy the output file into a location on a computer accessibl
55. ls false DisableDepthTest false DisableBlending false Force2x2Textures false DisableTextureModifications false DisableScissorTest false DisableFBAccess false ForceViewport false DisableFlushNFinish false DisableTextureFiltering false Ihe SwapiInterval 0 Ihe com powervr OGLES2Water Enabled true Nopeecalng ts 2 StartFrame 100 EndFrame 200 SaveFrameBuffer true UseCompression true PVRTrace 55 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public Appendix C Regular Expression Syntax og imagination Table 10 provides a list of regular expression syntax and description which includes details for special constructs logical operators quantifiers boundary matching character classes predefined character classes characters and back references Table 10 Regular expression syntax and description Special constructs i X Match sub pattern case insensitive I X Match sub pattern case sensitive n X Match sub pattern with newlines N X Match sub pattern with no newlines X Capturing parentheses use with back references X Non capturing parentheses X Zero width positive look ahead X Zero width negative look ahead lt X Zero width positive look behind lt X Zero width negative look behind gt X Atomic grouping possessive match Logical operators
56. magination Technologies Public og imagination Note Tiling and Hidden Surface Removal are not simulated in image analysis so the output should not be considered indicative of how PowerVR hardware performs rendering This information is given for debugging purposes only 3 4 2 View Image Output by Draw Call Type The Draw Call View Type dropdown menu identified in Figure 17b can be used to select how the draw calls are displayed in the Image Analysis window To view the image output by draw call type use the dropdown menu and select the required mode The available modes are explained next Scrubber This option displays all rendered draw calls up to the draw call value specified in the upper value selector box e Single Primitive This option displays the result of a single draw call value specified in the upper value selector box e Range All This option displays image analysis for the whole range of draw calls Lower and upper value selection is disabled with this option e Range This option displays a range of draw calls selected from the lower and upper value selector boxes which are activated upon choosing the option e Range FBO lt numbers This option displays a range of draw calls for different Frame Buffer Objects if available in a trace The draw calls can be selected from the lower and upper value selector boxes which are activated upon choosing the option 3 4 3 Other Actions Right clicking an image reveals an
57. n RenderstateOverrid Type Boolean Default true If set to true this will enable PVRTune capabilities to toggle different selections of renderstates Refer to the PVRTune User Manual for further details In addition to profiling options there is also an Overrides subsection which contains the options listed in Table 6 Table 6 Renderstate Overrides ForceViewport Modifies the viewport to have zero sized dimensions DisableBlending Disables alpha blending Force2x2Textures Forces textures to be 2 pixels by 2 pixels in size ForceFlatColourFrag Forces the fragment shader to output a single colour DisableStencilTest Disables the stencil test DisableDepthTest Disables the depth test PVRTrace 11 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Option Description DisableScissorTest Disables the scissor test DisableDrawCalls Disables all g1Draw function calls DisableFlushNFinish Disables all glLFlush and glFinish function calls DisableTextureModifications Disables g1TexSubImage2D and glTexSubImage3D This disables the updating of texture sub regions DisableTextureFiltering Disables texture filters All texture filters are set to the nearest point DisableAlphaTest Disables the alpha test DisableFBAccess Disables glReadPixels function calls CullingMode Forces the culling mode to perform cul
58. n trace file after download checkbox is ticked then this will open the trace in the PVRTrace GUI immediately after the download Statistics Graph When a pvrtrace file has been loaded the Statistics Graph dialog box can be used to visualize software counters in the traced application on a per frame basis as well as thread activity on a per frame basis in multi threaded applications if applicable To open the dialog box click Tools gt Statistics Graph For more information on the Statistics Graph see Section 3 5 Preferences User preferences are set by clicking Tools gt Preferences in the Menu bar This opens the Preferences dialog box Figure 6 which displays various options to enable the customisation of the PVRTrace GUI The Preferences dialog box can be used to achieve the following Max number of returned search results This option is available under the General section of the Preferences dialog box Figure 6 To specify the maximum number of hits returned during a search activity change the value in the field provided This is a handy feature because the number of hits returned during a search activity can be quite lengthy and controlling this number enables the time taken for performing a search to be reduced e Enable Image Analysis This option is available under the Image Analysis section of the Preferences dialog box Figure 6 This option should be used when there are issues with image analysis or resolving t
59. og Imagination Public Imagination Technologies PowerVR by imagination PVRTrace User Manual Copyright Imagination Technologies Limited All Rights Reserved This publication contains proprietary information which is subject to change without notice and is supplied as is without warranty of any kind Imagination Technologies and the Imagination Technologies logo are trademarks or registered trademarks of Imagination Technologies Limited All other logos products trademarks and registered trademarks are the property of their respective owners Filename PVRTrace User Manual4 Version PowerVR SDK REL_3 5 3523383a External Issue Issue Date 17 Apr 2015 Author Imagination Technologies Limited PVRTrace 1 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Contents 1 Ge TT e M ness a cinch ce cece detec ced shee enh donee eb ch cece done caed doebesevobedeneeboncesviebedests 5 1 1 Document OVEIVICW ccececeeececeneeeeeaeeeeaae cence ceaeeecaaeeeeaaeseeeeesaaeeeseaeedeaeeseeeeessaeeesaeeseneeteaes 5 1 2 Software Cvermlew ttnan tutt nntt tnt nnntnn Atna nn ntun nn nen nsen nenna nnn 5 2 Recording LIDlANleS E 6 2 1 STE A A E 6 2 2 elle NEE 6 2 3 ET Le TEE 7 2 3 1 Package Installation EE 7 2 3 2 lee 7 2 3 3 Bi UE 7 2 3 4 alle Lee EE 7 2 4 elle Che WEE 8 2 4 1 Tracing OptioNS EE 8 2 4 2 DEBUG Options ynhieren ea ea e a aaa aeaa Saia nanai 9 2 4 3 NetWork OPTIONS enger d
60. on is available under the Image Analysis section of the Preferences dialog box Figure 6 The option enables a colour to be specified for the wireframe effects displayed in the Image Analysis window see Section 3 4 To specify the colour click the corresponding button This will open a colour picker from which the required colour can be selected e Compiler This option is available under the Shader Compiler section of the Preferences dialog box Figure 6 A dropdown menu enables a PowerVR compiler to be chosen to verify and profile shaders The choice of compiler should reflect the platform that is being targeted e Custom Compiler Path This option is available under the Shader Compiler section of the Preferences dialog box Figure 6 The option is enabled when the Custom Compiler value is chosen for the Compiler field Once enabled it becomes possible to select the path for pointing to a custom compiler supplied by Imagination Technologies a SY Preferences General Max number of returned search results 500 Image Analysis V Enable Image Analysis Play calls that failed during recording V Enable Primitive Highlighting Highlight Colour Heatmap Colouration Chromatic Acrochromatic Wireframe Effect Colour L Shader Compiler Compiler PowerVR GLSLES Series6 z Custom Compiler Path Lox cancel Figure 6 Preferences dialog box PVRTrace 17 Revision PowerVR SDK R
61. on of the pixel will be marked with horizontal and vertical lines through the pixel coordinates Image Analysis Gx Normal X Range All y Jo si Move your finger in left portion of screen to control player movement D Eni O ee M A jae pai A CG S ge E d Se CH Render Resolution 1920x1080 40 Fit e Figure 36 Selecting a pixel in the Image Analysis window 3 Refer back to the Shader Analysis window which now displays a range of information including e Coordinates of the selected pixel Figure 37a e Fragment shader s used when shading the selected pixel Figure 37b Double clicking a listed fragment shader opens it in the Object Data Viewer window e Summarized frame information about fragment counts clock cycles in the shader compiler and texture reads for each fragment shader Figure 37c Several graphs are available for display 4 Select the desired graph from the Graph dropdown menu Figure 37d This will display a pie chart summarizing frame information High count items accounting for larger segments of the pie chart are generally a good indication of areas of concern that require addressing There are 5 types of charts that can be viewed namely PVRTrace 41 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination e Fragment Cost This option displays a pie chart representing the cost of each fragment shader as th
62. or remote recording To open the dialog box click Tools gt Remote Controller PVRTrace 15 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination E i Remote Controller Enter a server name or IP address Start recording on connection V Open trace file after download Figure 5 Remote Controller dialog box To use the Remote Controller dialog box for recording purposes 1 In the Remote Controller dialog box Figure 5 enter the IP address of the target device in the Connect to box The box also has a dropdown menu which lists recently used IP connections 2 Click the Go button to establish the connection 3 Run the application to be traced If the application is already running and is waiting for the network connecting will start the application 4 Click the Start Recording button to start recording the trace Once the recording has started the button will then display the Stop Recording option Notice that the Start recording on connection checkbox should be ticked if it is desired to start recording from frame 0 when the application starts running after the connection is established although a later frame to start from may be picked if necessary 5 To stop recording the trace click the Stop Recording button 6 Once the trace has been recorded it becomes possible to open and save the recording by clicking the Download button Notice that ifthe Ope
63. orded pauses during the first API call until an instance of the PVRTrace GUI has connected and sent the command to continue playing With this flag set to false the application being recorded continues to play regardless of whether a client has connected or not BufferSize Type Integer Default 256 Network BufferSize sets the volume of data that is sent from the Recording Libraries to the PVRTrace GUI in each packet 2 4 4 Host Options Table 4 lists host options and their description Table 4 Host options and their description Option Description EglLibraryPath Type String Default Null On Android the Recording Libraries will automatically attempt to populate this with the system s graphics libraries EglLibraryPath refers to the location of the original EGL driver on the host system This is usually found in system 1lib egl or system vendor 1lib egl if running an Android device On Linux the path will usually be usr 1lib EslLibraryPath Type String Default Null On Android the Recording Libraries will automatically attempt to populate this with the system s graphics libraries Es1LibraryPath refers to the location of the original OpenGL ES 1 1 driver on the host system This is usually found in system 1lib egl or system vendor 1lib egl if running an Android device On Linux the path will usually be usr 1lib Revision PowerVR SDK REL_3 5 3523383a 10 User Manual
64. pen an action menu 2 Select the Add Watch option from the menu This will not only highlight the call in the Calls Summary tab but also places it at the top of the list for easy identification Figure 18a Remove Watch Calls that are being watched can be unmarked by performing the following 1 Right click the watched call in the Calls Summary tab to open an action menu 2 Select the Remove Watch option from the menu This will unmark the call If multiple calls are being watched then it is possible to unmark all the calls by selecting the Remove A11 Watches option from the action menu 3 5 2 Frame Statistics The Frames Summary tab in the Statistics window provides an overall summary of the currently selected frame by listing the frequency of each listed item Figure 19 Note The statistics for the total number of triangles and lines correspond to the number sent to the API before any Hidden Surface Removal or culling Statistics Gx Calls Summary Frame Summary Function Calls 519 Draw Calls 24 Triangles 18412 Lines 0 Texture Loads 0 Shader Loads 0 Imb Figure 19 Viewing frame statistics 3 5 3 Graphical Representation of Statistics The PVRTrace GUI provides a graphical representation of per frame statistics Figure 20 as well as thread usage statistics in the case of multi threaded applications Figure 21 To view the graph of statistics from the Menu bar click Tools gt Statistics Graph Alternativel
65. program compiles successfully the Apply button Figure 34a will become active to allow saving changes made to the shader 3 Save changes by clicking the Apply button For tracking purposes the modified shader program is displayed in the Modifications window Figure 35 Note Shader modification can be removed by unchecking the modified shader and clicking on Apply Changes from the Modifications window Figure 35 Alternatively use the Reset button in the Source tab of the Object Data Viewer window Figure 34b Modifications ag x Enable Disable modifications Disable calls Modify shader source calls Call 1187 glShaderSource Shader 350005 GL_VERTEX_SHADER SIS Revision PowerVR SDK REL_3 5 3523383a 40 User Manual og imagination Public Imagination Technologies 3 10 3 Shader Analysis The PVRTrace GUI supports automated shader analysis through the provision of statistical information about a pixel s contribution to the rendering of a given frame This is a useful feature which allows the user to quickly interpret the impact of fragment and vertex shaders as well as fragment texture reads in order to identify areas of concern that should be addressed To use the shader analysis feature perform the following Te Select the Shader Analysis window This will enable pixel selection in image analysis 2 In the Image Analysis window select the desired pixel by clicking the image Figure 36 The positi
66. r to select a frame Figure 11a Alternatively double click the frame selector area Figure 11b to open a dialog box in which a frame value can be typed in a o fee ou 11 yo Figure 11 Selecting a frame 2 Selecting a frame will then display the calls for that frame in the Function call list area If image analysis is enabled then the image output will also be updated in the Image Analysis window see Section 3 4 3 3 2 Expand or Collapse Draw Calls Draw calls inthe Function call list area can be expanded or collapsed in one mouse click to either show or hide the functions between the draw calls respectively To expand or collapse all draw calls use the icon identified in Figure 9a Alternatively to expand or collapse a specific draw call use the expand collapse icon for that call Figure 9b 3 3 3 Filter Options The ability to effectively filter calls in the PVRTrace GUI is a key part of working with the contents in the Function call list area By filtering the displayed information the user is able to hide or reveal certain calls as appropriate Quick Filtering To quickly apply a filter to the desired listed calls perform the following 1 Mark the desired call for filtering by right clicking the call and selecting the Add Filter option from the action menu Figure 10 This will filter all calls of the same type e g ifa glBindBuf fer call is marked for filtering then all occurrences of the callin the Func
67. raced after installation it is recommended to use an output folder that allows write access for all processes so that PVRTrace output does not fail and potentially threaten the stability of the device 6 Reboot the device Note A hot reboot will work as well e Option 1 Normal device reboot e Option 2 Hot reboot only the Android runtime is restarted adb shell stop start A 1 3 Installation on 64 bit Android To manually install PVRTrace on a 64 bit Android device 1 Make the Android system directory writable e Option 1 Using ADB 9 adb root adb remount e Option 2 Using the command line Revision PowerVR SDK REL_3 5 3523383a 52 User Manual og Imagination Public Imagination Technologies adb shell mount o rw remount system 2 Copy libPVRTrace so to system vendor lib64 Option 1 Using adb push directly requires root shell i e option 1 in step 1 adb push path to PVRTrace Recorder Android lt ABI gt libPVRTrace so system vendor lib64 libPVRTrace so Option 2 Use cp to copy the file from an SD card on the device adb push path to PVRTrace Recorder Android lt ABI gt libPVRTrace so sdcard libPVRTrace so adb shell cp sdcard libPVRTrace so system vendor lib64 libPVRTrace so 3 Copy the recording libraries to system vendor lib64 eg1 The libraries to copy are 1ibEGL PVRTRACE so libGLESv1 CM PVRTRACE so and libGLESv2_ PVRTRACE so e
68. rame scrubber located at the bottom right hand side of the PVRTrace GUI to choose the desired frame to display see Section 3 3 1 e Select a draw call It is possible using the Draw Call View Type to draw only a subset of the overall draw calls down to a single draw call if required Figure 17b Use the arrows provided in the lower and upper value selector box to change the draw call value or alternatively with the cursor positioned over the box scroll up or down as appropriate e Select a pixel A pixel can be selected by clicking a point in the displayed image This functionality only works during shader analysis see Section 0 The position of the pixel is marked with horizontal and vertical lines through the pixel coordinates Note When jumping frames content that uses framebuffer objects or compute shaders may not render correctly If this occurs right click the image and select Re Evaluate Revision PowerVR SDK REL_3 5 3523383a 26 User Manual QF imagination Public Imagination Technologies Note To remove the marking for a selected pixel zoom out of the image click hold and drag outside the picture in the image analysis window c b Image Analysis fx SS z Range Al Move your finger in left portion of screen to control player movement mz i TE ee f Render Resolution 1920x1080 40 fit y A a Figure 17 Image Analysis window 3 4 1 Select a Render
69. ries as defined in the PVRTrace configuration file see Section 2 4 Calls are streamed to the pvrtrace file during runtime so that even if an application crashes data is recorded Platform Trace Libraries Host Emulation Libraries i libEGL pvrtraceconfig json libEGL libGLES_CM libGLES_CM Pena ES i Recording Library Screen as normal pplication R libGLESv1_CM libGLESv1_CM libGLESv2 PVRT File libGLESv2 PVRTrace Playback PVRTraceGUI Analysis Playback PVRTrace Analysis amp Playback Figure 1 Overview of Recording Library Note This diagram changes when using an Android target device without root permission For more information on using a device without root permission see the PVRTrace Quick Start Guide for Android Unrooted 2 2 Compatibility The following compatibility information is relevant to PVRTrace Recording Libraries API compatibility PVRTrace Recording Libraries are compatible with EGL OpenGL ES 1 1 OpenGL ES 2 0 OpenGL ES 3 0 and OpenGL ES 3 1 e Supported extensions PVRTrace only supports extensions supported by PowerVR devices Revision PowerVR SDK REL_3 5 3523383a 6 User Manual og Imagination Public Imagination Technologies 2 3 Installation This section identifies the various methods of installing PVRTrace 2 3 1 Package Installation PVRTrace can
70. roid 4 0 and newer e Option 1 Using adb push directly requires root shell i e option 1 in step 1 adb push path to PVRTrace Recorder Android lt ABI gt lt LIBRARY gt so system vendor lib egl Option 2 Use cp to copy the file from an SD card on the device adb push path to PVRTrace Recorder Android lt ABI gt lt LIBRARY gt so sdcard adb shell cp sdcard lt LIBRARY gt so system vendor lib egl lt LIBRARY gt so 4 Create the pvrtraceconfig json see Section 2 4 and place it in the SD card Make sure that TraceFile points to a writable location The TraceFile variable must be set accurately with an absolute path If it is not correctly set no file will be output It is suggested that write permissions for the app be checked before setting this As all subsequent processes will be traced after installation it is recommended to use an output folder that allows write access for all processes so that PVRTrace output does not fail and potentially threaten the stability of the device 5 Edit egl cfg in system 1ib egl1 to use PVRTrace instead of the original driver Note This change can be done at any time and will only affect new processes that are launched after the change It is recommended that two copies of eg1 cfg be used one referencing the PVR Trace libraries and the other referencing the default libraries Each file should be named separately and copied over the original egl cfg as required For
71. s GL_TRIANGLE_STRIP 4994 6 glDrawElements GL_TRIANGLE_STRIP 514 7 glDrawElements GL_TRIANGLE_STRIP 1509 e glDrawElements GL_TRIANGLE_STRIP 939 Vertices X Figure 24 Viewing the Draws Calls window Revision PowerVR SDK REL_3 5 3523383a 32 User Manual Qg Imagination Public Imagination Technologies To view the effect of a draw call for a given frame perform the following 1 Go to the desired frame by using the frame scrubber or frame selector This will populate the Draw Calls window with a list of draw calls for that frame 2 Click the required draw call in the list This highlights the draw call in the Function Call List area Information is also updated in the various windows of the PVRTrace GUI e g the Image Analysis window will be updated as appropriate with the draw highlighted in the image 3 8 Current Call Inspection The PVRTrace GUI facilitates the inspection of EGL and OpenGL ES states and objects at any point in a frame This can be achieved by selecting a call in the Function Call List area Upon selection the Current Call window Figure 25 will be updated with the relevant information for the call Current Call Gx glDrawElements Call UID 177927 EGL State EGL Objects OpenGL ES State OpenGL ES Objects Object Name Current Display 0x00000001 Current Draw Surface 0x70c7d298 Current Read Surface 0x70c7d298 Current Context Ox6d063ef0 Figure 25 Current Call window 3 8 1 EGL
72. se the file size UseCompression Type Boolean Default false Enables compression of the trace data to reduce output file size AppendTraceVersion Type Boolean Default true Adds the PVRTrace version to the results of eglQueryString display EGL VERSION glGetString GL_RENDERER 2 4 2 Debug Options Table 2 lists debug options and their description Table 2 Debug options and their description Description Level Type Integer Default 0 This option will set the level of verbosity of the debug output 0 means disabled resulting in no output 1 means only the most important data is displayed and 2 means all data is displayed PVRTrace 9 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination 2 4 3 Network Options Table 3 lists network options and their description Table 3 Network options and their description Option Description Enabled Type Boolean Default false With this flag set to true the PVRTrace GUI is able to connect to the application over a network allowing for remote recording It should be noted that while this flag is set to true the StartFrame and EndFrame flags are ignored With this flag set to false on device recording is performed and the Network Wait and Network BufferSize flags are ignored Wait Type Boolean Default false With this flag set to true the application being rec
73. strated in Figure 15 Note The syntax used in regular expression searching is documented in Appendix B Note Clicking a call from the retrieved search results updates the currently selected call in the function call list and if required the current frame Revision PowerVR SDK REL_3 5 3523383a 24 User Manual og Imagination Public Imagination Technologies Find Results a x 4 Search glBind 500 hits in 7 frames Incomplete a 4 Frame 0 13 hits l Thread 7183 Call UID 23 eglGetProcAddress glBindAttribLo l Thread 7183 Call UID 24 eglGetProcAddress glBindFramebu l Thread 7183 Call UID 25 eglGetProcAddress glBindFramebu Thread 7183 Call UID 26 eglGetProcAddress glBindProgram Thread 7183 Call UID 27 eglGetProcAddress glBindRenderb Thread 7183 Call UID 28 eglGetProcAddress glBindRenderb Thread 7183 Call UID 29 eglGetProcAddress glBindVertexArr Thread 7183 Call UID 316 eglGetProcAddress glBindFrameb l Thread 7183 Call UID 317 eglGetProcAddress glBindProgra Find Calls Occurrences of a call can be quickly narrowed down for inspection by performing the following 1 Identify the desired callin the Function call list area and right click it to reveal an action menu 2 To search for all occurrences of the call in the current frame select the option Find all in frame Otherwise if it is required to search for all occurrences of the call in the entir
74. tion call list area are marked 2 Click the filter icon identified in Figure 9c to apply the filter This will then hide all the calls that have been marked for filtering Advanced Filtering Options for advanced filtering are accessed by selecting the icon identified in Figure 9d This opens the Filter Highlight Functions dialog box which provides further options to achieve a finer level of filtering Figure 12 PVRTrace 21 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination rn E Filter Highlight Functions 2 mon Function Name Highlight Hide EGL OpenGL ES 7 Figure 12 Advanced filtering using the Filter Highlight Functions dialog box To use advanced filtering 1 Open the Filter Highlight Functions dialog box 2 Under the Hide column tick the checkbox for the desired API Finer filtering can be achieved by expanding an API name and selecting the required function groups for that API 3 Click the Accept button to mark the calls present in the Function call list area for filtering 4 Click the filter icon identified in Figure 9c to apply the filter This will then hide all the calls that have been marked for filtering Filter by Thread ID In the case of multi threaded applications it is possible to filter the contents in Function call list area to only show functions called in a certain thread To use this filter open the Thread ID dropdown menu Figure 9e
75. tnnnnttnnnatennnntnn nnani 32 PVRTrace 3 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination Figure 24 Viewing the Draws Calls WINdOW ssssseessesssesssssisssissttntttnstnnttnntttnuttntnnnnnnnstnnsnnnssnnsnnnnnn 32 Figure eren e EE 33 Figure 26 Viewing EGL state objects in the Object Data Viewer window 34 Figure 27 EGL Objects tab in the Current Call Window cccccceceeeeeeeceeeeeseeeeeeaeeseeeeeseaeeeseaeeneaeeeeaes 34 Figure 28 OpenGL ES State tab in the Current Call window ssssseessessseesseessnessrnesrrssrnssnnnsnnsrnssrnnens 35 Figure 29 Viewing OpenGL ES state variables in the Object Data Viewer window sesssesesee 36 Figure 30 OpenGL ES Objects tab in the Current Call WINdOW c cceecceceeeeeeteeceeeeeeeeeeenaeeteneeteaes 36 Figure 31 INSpecting textures REENEN 37 Figure 32 Viewing a texture in the Data Viewer 38 Figure 33 Viewing loaded ahaderg AA 39 Figure 34 Inspecting a SMA ee cccceeccceeeeeceeeeeeeceeeeeaeeessseaeeeeaeaaaeeeseaaaaesaeeaaeessaeaeeeseeeaseeseeeaseneeees 40 Figure 35 Viewing modified shaders in the Modifications wimdow 40 Figure 36 Selecting a pixel in the Image Analysis WiINGOW cccccesececeeeeeeeeeeeeeeeeeeeeseaeeeseaeeneneeeeaes 41 Figure 37 Viewing the Shader Analysis ab 42 Figure 38 Viewing the Log WiINKOW eeccceeeesteeeeeenne cece eae ee ee ea ae ee ee Enni ee eaaeeeeeeaaeeeeeeaaeeeeeeaeeeeeeaeee
76. tnnntnnntnnnnn nentet 46 5 Ftrotibleeleottg sees aa aaaea aaea eege Ee Seeded 47 6 Contact D tail S vissiscccccivcccccecitvecceataveccunvawic ccd savevcuavavassudsadeeduuvavasdddsavenduavavassuusivudduunavecuuisatvavuusiuvedd 48 Appendix A Manual Android Installation cccccccssssssseeeececeeenesneneeeeeeceennssaeeeeseeneeaesneneeenaes 49 A 1 Installation with Root PBermission 49 A 1 1 Installation on Android 4 3 or Older Version 49 A 1 2 Installation on Android 4 4 or Newer Version 51 A 1 3 Installation on 64 bit Android 52 A 2 Installation without Root Permlseion 54 Appendix B Complete Configuration File c cccssseceeessseeeenseeeeeenseeeeeseseeeeeseseeeeneesseeenees 55 Appendix C Regular Expression Syntax sscccsscesseeesseesesneeenseeeeseeeeseaesesneeeneeeeseeeseseaeseseeenenees 56 List of Figures Figure 1 Overview of Recording Library ccccccccseeeeeeeceeeeeceeeeeaeeseaeeceeeeseaeeeeaaeeeeeeeseaeeescaeeseaeseneees 6 Figure 2 General layout of the PVRTrace GU 14 bere FING TVG IMU seen eege E egeeg 14 Figure TOOR MEN egeieeegeeeeee eege ee eege a 15 Figure 5 Remote Controller dialog DOX ccccccceeeceeeeeeeeceeeeeeeceaeeeeeaeeeeneeseeeeeseaesesaaeseeeeeseaeeeseaeeseeeeeaes 16 Figure 6 Preferences dialog DOX cccsccccecesccceeeeeeceeeeeeeceeeeseeaeeesaeeaeeeesaeaaeesaeaaeesaeaaenseeeaeeeseeeaseneeees 17 Figure 7 View MEMI asices cethncedevssnccetetancasevesha
77. y in the Statistics window use the Graph button to view the graph see Figure 18 and Figure 19 The horizontal axis provides a timeline corresponding to the recorded frames and double clicking at a particular frame will load the associated data in the PVRTrace GUI The Per Frame Statistics tab displays software counters in the traced application on a per frame basis Figure 20 To add or remove graphs of specific statistics and or function calls use their corresponding checkboxes Values can be made to display on the graph by ticking the required checkbox under the Label column PVRTrace 29 Revision PowerVR SDK REL_3 5 3523383a Imagination Technologies Public og imagination P lul Statistics Graph File View Per Frame Statistics Thread Usage Statistic Graph Label Line H Function Calls d BB Draw Calls v RB Triangles v H Lines d BB Tetture Uploads d DW Shader Compilations E Function Call Graph Label Line S BW egiChooseConfig BB egiCreateContext BW egiCreateWindowSurface gt Zoom 0 Figure 20 Statistics Graph dialog box displaying per frame statistics A number of options are provided in the dialog e From the File menu in the Statistics Graph dialog it is possible to save the graph as an image export the data as CSV files or close the window e Use the View menu to access various options to show or hide data labels hide all statistics

PVRTrace User Manual - Imagination Technologies

Contents

Download Pdf Manuals

Related Search

Related Contents