diff --git a/docs/python_api/index.rst b/docs/python_api/index.rst index a9cf6f22c..aaf794d4b 100644 --- a/docs/python_api/index.rst +++ b/docs/python_api/index.rst @@ -6,4 +6,4 @@ Python API funcs enums_data pipelines/index - qrenderdoc + qrenderdoc/index diff --git a/docs/python_api/qrenderdoc.rst b/docs/python_api/qrenderdoc.rst deleted file mode 100644 index cc5d6908f..000000000 --- a/docs/python_api/qrenderdoc.rst +++ /dev/null @@ -1,8 +0,0 @@ -QRenderDoc -========== - -.. automodule:: qrenderdoc - :members: - :undoc-members: - :imported-members: - diff --git a/docs/python_api/qrenderdoc/config.rst b/docs/python_api/qrenderdoc/config.rst new file mode 100644 index 000000000..ef9a88dde --- /dev/null +++ b/docs/python_api/qrenderdoc/config.rst @@ -0,0 +1,22 @@ +Persistant Config +================= + +.. contents:: + +.. module:: qrenderdoc + +Config +------ + +.. autoclass:: qrenderdoc.PersistantConfig + +.. autoclass:: qrenderdoc.SPIRVDisassembler + :members: + :undoc-members: + +Remote Host +----------- + +.. autoclass:: qrenderdoc.RemoteHost + :members: + :undoc-members: diff --git a/docs/python_api/qrenderdoc/index.rst b/docs/python_api/qrenderdoc/index.rst new file mode 100644 index 000000000..3b2393252 --- /dev/null +++ b/docs/python_api/qrenderdoc/index.rst @@ -0,0 +1,8 @@ +QRenderDoc +========== + +.. toctree:: + main + windows + config + pipeline diff --git a/docs/python_api/qrenderdoc/main.rst b/docs/python_api/qrenderdoc/main.rst new file mode 100644 index 000000000..6eb3fc455 --- /dev/null +++ b/docs/python_api/qrenderdoc/main.rst @@ -0,0 +1,40 @@ +Main Interfaces +=============== + +.. contents:: + +.. module:: qrenderdoc + +Context +------- + +.. autoclass:: qrenderdoc.CaptureContext + :members: + :undoc-members: + +Replay Manager +-------------- + +.. autoclass:: qrenderdoc.ReplayManager + :members: + :undoc-members: + +LogViewer Interface +------------------- + +.. autoclass:: qrenderdoc.LogViewer + :members: + :undoc-members: + +Utilities +--------- + +.. autoclass:: qrenderdoc.DockReference + :members: + :undoc-members: + :exclude-members: enum_constants__, + +.. autoclass:: qrenderdoc.CaptureSettings + :members: + :undoc-members: + diff --git a/docs/python_api/qrenderdoc/pipeline.rst b/docs/python_api/qrenderdoc/pipeline.rst new file mode 100644 index 000000000..64e70ccce --- /dev/null +++ b/docs/python_api/qrenderdoc/pipeline.rst @@ -0,0 +1,37 @@ +Pipeline Abstraction +==================== + +.. contents:: + +.. module:: qrenderdoc + +Pipeline +-------- + +.. autoclass:: qrenderdoc.CommonPipelineState + :members: + :undoc-members: + +Bindings +-------- + +.. autoclass:: qrenderdoc.BoundResource + :members: + :undoc-members: + +.. autoclass:: qrenderdoc.BoundVBuffer + :members: + :undoc-members: + +.. autoclass:: qrenderdoc.BoundCBuffer + :members: + :undoc-members: + +.. autoclass:: qrenderdoc.VertexInputAttribute + :members: + :undoc-members: + +.. autoclass:: qrenderdoc.Viewport + :members: + :undoc-members: + diff --git a/docs/python_api/qrenderdoc/windows.rst b/docs/python_api/qrenderdoc/windows.rst new file mode 100644 index 000000000..100c283a5 --- /dev/null +++ b/docs/python_api/qrenderdoc/windows.rst @@ -0,0 +1,91 @@ +Windows +======= + +.. contents:: + +.. module:: qrenderdoc + +MainWindow +---------- + +.. autoclass:: qrenderdoc.MainWindow + :members: + :undoc-members: + +EventBrowser +------------ + +.. autoclass:: qrenderdoc.EventBrowser + :members: + :undoc-members: + +APIInspector +------------ + +.. autoclass:: qrenderdoc.APIInspector + :members: + :undoc-members: + +PipelineStateViewer +------------------- + +.. autoclass:: qrenderdoc.PipelineStateViewer + :members: + :undoc-members: + +TextureViewer +------------- + +.. autoclass:: qrenderdoc.TextureViewer + :members: + :undoc-members: + +BufferViewer +------------ + +.. autoclass:: qrenderdoc.BufferViewer + :members: + :undoc-members: + +CaptureDialog +------------- + +.. autoclass:: qrenderdoc.CaptureDialog + :members: + :undoc-members: + +DebugMessageView +---------------- + +.. autoclass:: qrenderdoc.DebugMessageView + :members: + :undoc-members: + +StatisticsViewer +---------------- + +.. autoclass:: qrenderdoc.StatisticsViewer + :members: + :undoc-members: + +ShaderViewer +------------ + +.. autoclass:: qrenderdoc.ShaderViewer + :members: + :undoc-members: + +ConstantBufferPreviewer +----------------------- + +.. autoclass:: qrenderdoc.ConstantBufferPreviewer + :members: + :undoc-members: + +PixelHistoryView +---------------- + +.. autoclass:: qrenderdoc.PixelHistoryView + :members: + :undoc-members: + diff --git a/docs/window/options_window.rst b/docs/window/options_window.rst index 14e8ae1dd..6e7907b1e 100644 --- a/docs/window/options_window.rst +++ b/docs/window/options_window.rst @@ -1,6 +1,8 @@ Options Window ============== +.. _settings-window: + The options window contains various advanced or niche settings that configure the analysis UI. Options diff --git a/qrenderdoc/Code/Interface/CommonPipelineState.h b/qrenderdoc/Code/Interface/CommonPipelineState.h index 9f57bb0fe..6f9972c36 100644 --- a/qrenderdoc/Code/Interface/CommonPipelineState.h +++ b/qrenderdoc/Code/Interface/CommonPipelineState.h @@ -27,6 +27,7 @@ // do not include any headers here, they must all be in QRDInterface.h #include "QRDInterface.h" +DOCUMENT("Information about a single resource bound to a slot in an API-specific way."); struct BoundResource { BoundResource() @@ -44,57 +45,106 @@ struct BoundResource typeHint = CompType::Typeless; } + DOCUMENT("A :class:`~renderdoc.ResourceId` identifying the bound resource."); ResourceId Id; + DOCUMENT("For textures, the highest mip level available on this binding, or -1 for all mips"); int HighestMip; + DOCUMENT("For textures, the first array slice available on this binding. or -1 for all slices."); int FirstSlice; + DOCUMENT( + "For textures, a :class:`~renderdoc.CompType` hint for how to interpret typeless textures."); CompType typeHint; }; DECLARE_REFLECTION_STRUCT(BoundResource); +DOCUMENT("Information about a single vertex buffer binding."); struct BoundVBuffer { + DOCUMENT("A :class:`~renderdoc.ResourceId` identifying the buffer."); ResourceId Buffer; - uint64_t ByteOffset; - uint32_t ByteStride; + DOCUMENT("The offset in bytes from the start of the buffer to the vertex data."); + uint64_t ByteOffset = 0; + DOCUMENT("The stride in bytes between the start of one vertex and the start of the next."); + uint32_t ByteStride = 0; }; DECLARE_REFLECTION_STRUCT(BoundVBuffer); +DOCUMENT("Information about a single constant buffer binding."); struct BoundCBuffer { + DOCUMENT("A :class:`~renderdoc.ResourceId` identifying the buffer."); ResourceId Buffer; + DOCUMENT("The offset in bytes from the start of the buffer to the constant data."); uint64_t ByteOffset = 0; + DOCUMENT("The size in bytes for the constant buffer. Access outside this size returns 0."); uint32_t ByteSize = 0; }; DECLARE_REFLECTION_STRUCT(BoundCBuffer); +DOCUMENT("Information about a vertex input attribute feeding the vertex shader."); struct VertexInputAttribute { + DOCUMENT("The name of this input. This may be a variable name or a semantic name."); QString Name; + DOCUMENT("The index of the vertex buffer used to provide this attribute."); int VertexBuffer; + DOCUMENT("The byte offset from the start of the vertex data for this VB to this attribute."); uint32_t RelativeByteOffset; + DOCUMENT("``True`` if this attribute runs at instance rate."); bool PerInstance; + DOCUMENT(R"(If :data:`PerInstance` is ``True``, the number of instances that source the same value +from the vertex buffer before advancing to the next value. +)"); int InstanceRate; + DOCUMENT("A :class:`~renderdoc.ResourceFormat` with the interpreted format of this attribute."); ResourceFormat Format; + DOCUMENT(R"(A :class:`~renderdoc.PixelValue` with the generic value for this attribute if it has +no VB bound. +)"); PixelValue GenericValue; + DOCUMENT("``True`` if this attribute is enabled and used by the vertex shader."); bool Used; }; DECLARE_REFLECTION_STRUCT(VertexInputAttribute); +DOCUMENT("Information about a viewport."); struct Viewport { - float x, y, width, height; + DOCUMENT("The X co-ordinate of the viewport."); + float x; + DOCUMENT("The Y co-ordinate of the viewport."); + float y; + DOCUMENT("The width of the viewport."); + float width; + DOCUMENT("The height of the viewport."); + float height; }; DECLARE_REFLECTION_STRUCT(Viewport); +DOCUMENT(R"(An API-agnostic view of the common aspects of the pipeline state. This allows simple +access to e.g. find out the bound resources or vertex buffers, or certain pipeline state which is +available on all APIs. + +For more detailed or precise information without abstraction, access the specific pipeline state +for the capture that's open. +)"); class CommonPipelineState { public: CommonPipelineState() {} + DOCUMENT(R"(Set the source API-specific states to read data from. + +:param ~renderdoc.APIProperties props: The properties of the current capture. +:param ~renderdoc.D3D11_State d3d11: The D3D11 state. +:param ~renderdoc.D3D12_State d3d12: The D3D11 state. +:param ~renderdoc.GL_State gl: The OpenGL state. +:param ~renderdoc.VK_State vk: The Vulkan state. +)"); void SetStates(APIProperties props, D3D11Pipe::State *d3d11, D3D12Pipe::State *d3d12, GLPipe::State *gl, VKPipe::State *vk) { @@ -105,36 +155,68 @@ public: m_Vulkan = vk; } + DOCUMENT( + "The default :class:`~renderdoc.GraphicsAPI` to pretend to contain, if no capture is " + "loaded."); GraphicsAPI DefaultType = GraphicsAPI::D3D11; + DOCUMENT(R"(Determines whether or not a capture is currently loaded. + +:return: A boolean indicating if a capture is currently loaded. +:rtype: ``bool`` +)"); bool LogLoaded() { return m_D3D11 != NULL || m_D3D12 != NULL || m_GL != NULL || m_Vulkan != NULL; } + DOCUMENT(R"(Determines whether or not a D3D11 capture is currently loaded. + +:return: A boolean indicating if a D3D11 capture is currently loaded. +:rtype: ``bool`` +)"); bool IsLogD3D11() { return LogLoaded() && m_APIProps.pipelineType == GraphicsAPI::D3D11 && m_D3D11 != NULL; } + DOCUMENT(R"(Determines whether or not a D3D12 capture is currently loaded. + +:return: A boolean indicating if a D3D12 capture is currently loaded. +:rtype: ``bool`` +)"); bool IsLogD3D12() { return LogLoaded() && m_APIProps.pipelineType == GraphicsAPI::D3D12 && m_D3D12 != NULL; } + DOCUMENT(R"(Determines whether or not an OpenGL capture is currently loaded. + +:return: A boolean indicating if an OpenGL capture is currently loaded. +:rtype: ``bool`` +)"); bool IsLogGL() { return LogLoaded() && m_APIProps.pipelineType == GraphicsAPI::OpenGL && m_GL != NULL; } + DOCUMENT(R"(Determines whether or not a Vulkan capture is currently loaded. + +:return: A boolean indicating if a Vulkan capture is currently loaded. +:rtype: ``bool`` +)"); bool IsLogVK() { return LogLoaded() && m_APIProps.pipelineType == GraphicsAPI::Vulkan && m_Vulkan != NULL; } // add a bunch of generic properties that people can check to save having to see which pipeline - // state - // is valid and look at the appropriate part of it + // state is valid and look at the appropriate part of it + DOCUMENT(R"(Determines whether or not tessellation is currently enabled. + +:return: A boolean indicating if tessellation is currently enabled. +:rtype: ``bool`` +)"); bool IsTessellationEnabled() { if(LogLoaded()) @@ -155,33 +237,188 @@ public: return false; } + DOCUMENT(R"(Determines whether or not the current capture supports binding arrays of resources. + +:return: A boolean indicating if binding arrays of resources is supported. +:rtype: ``bool`` +)"); bool SupportsResourceArrays() { return LogLoaded() && IsLogVK(); } + DOCUMENT(R"(Determines whether or not the current capture uses explicit barriers. + +:return: A boolean indicating if explicit barriers are used. +:rtype: ``bool`` +)"); bool SupportsBarriers() { return LogLoaded() && (IsLogVK() || IsLogD3D12()); } - // whether or not the PostVS data is aligned in the typical fashion - // ie. vectors not crossing float4 boundaries). APIs that use stream-out - // or transform feedback have tightly packed data, but APIs that rewrite - // shaders to dump data might have these alignment requirements + DOCUMENT(R"(Determines whether or not the PostVS data is aligned in the typical fashion (ie. +vectors not crossing ``float4`` boundaries). APIs that use stream-out or transform feedback have +tightly packed data, but APIs that rewrite shaders to dump data might have these alignment +requirements. + +:return: A boolean indicating if post-VS data is aligned. +:rtype: ``bool`` +)"); bool HasAlignedPostVSData() { return LogLoaded() && IsLogVK(); } + DOCUMENT(R"(For APIs that have explicit barriers, retrieves the current layout of a resource. + +:return: The name of the current resource layout. +:rtype: ``str`` +)"); QString GetResourceLayout(ResourceId id); + + DOCUMENT(R"(Retrieves a suitable two or three letter abbreviation of the given shader stage. + +:param ~renderdoc.ShaderStage stage: The shader stage to abbreviate. +:return: The abbreviation of the stage. +:rtype: ``str`` +)"); QString Abbrev(ShaderStage stage); + DOCUMENT(R"(Retrieves a suitable two or three letter abbreviation of the output stage. Typically +'OM' or 'FBO'. + +:return: The abbreviation of the output stage. +:rtype: ``str`` +)"); QString OutputAbbrev(); + DOCUMENT(R"(Retrieves the viewport for a given index. + +:param int index: The viewport index to retrieve. +:return: The viewport for the given index. +:rtype: Viewport +)"); Viewport GetViewport(int index); + + DOCUMENT(R"(Retrieves the current bindpoint mapping for a shader stage. + +This returns an empty bindpoint mapping if no shader is bound. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch. +:return: The bindpoint mapping for the given shader. +:rtype: ~renderdoc.ShaderBindpointMapping +)"); const ShaderBindpointMapping &GetBindpointMapping(ShaderStage stage); + + DOCUMENT(R"(Retrieves the shader reflection information for a shader stage. + +This returns ``None`` if no shader is bound. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch. +:return: The reflection data for the given shader. +:rtype: :class:`~renderdoc.ShaderBindpointMapping` or ``None`` +)"); const ShaderReflection *GetShaderReflection(ShaderStage stage); + + DOCUMENT(R"(Retrieves the name of the entry point function for a shader stage. + +For some APIs that don't distinguish by entry point, this may be empty. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch. +:return: The entry point name for the given shader. +:rtype: ``str`` +)"); QString GetShaderEntryPoint(ShaderStage stage); + + DOCUMENT(R"(Retrieves the object ID of the shader bound at a shader stage. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch. +:return: The object ID for the given shader. +:rtype: ~renderdoc.ResourceId +)"); ResourceId GetShader(ShaderStage stage); + + DOCUMENT(R"(Retrieves the name of the shader object at a shader stage. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch. +:return: The object name for the given shader. +:rtype: ``str`` +)"); QString GetShaderName(ShaderStage stage); + + DOCUMENT(R"(Retrieves the common file extension for high level shaders in the current API. + +Typically this is ``glsl`` or ``hlsl``. + +:return: The file extension with no ``.``. +:rtype: ``str`` +)"); QString GetShaderExtension(); + + DOCUMENT(R"(Retrieves the current index buffer binding. + +:return: A tuple with the buffer object bound to the index buffer slot, and the byte offset to the + start of the index data. +:rtype: ``tuple`` of :class:`~renderdoc.ResourceId` and ``int`` +)"); QPair GetIBuffer(); + + DOCUMENT(R"(Determines whether or not primitive restart is enabled. + +:return: A boolean indicating if primitive restart is enabled. +:rtype: ``bool`` +)"); bool IsStripRestartEnabled(); + + DOCUMENT(R"(Retrieves the primitive restart index. + +:param int indexByteWidth: The width in bytes of the indices. +:return: The index value that represents a strip restart not a real index. +:rtype: ``int`` +)"); uint32_t GetStripRestartIndex(uint32_t indexByteWidth); + + DOCUMENT(R"(Retrieves the currently bound vertex buffers. + +:return: The list of bound vertex buffers. +:rtype: ``list`` of :class:`BoundVBuffer`. +)"); QVector GetVBuffers(); + + DOCUMENT(R"(Retrieves the currently specified vertex attributes. + +:return: The list of current vertex attributes. +:rtype: ``list`` of :class:`VertexInputAttribute`. +)"); QVector GetVertexInputs(); + + DOCUMENT(R"(Retrieves the constant buffer at a given binding. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch from. +:param int BufIdx: The index in the shader's ConstantBlocks array to look up. +:param int ArrayIdx: For APIs that support arrays of constant buffers in a single binding, the index + in that array to look up. +:return: The constant buffer at the specified binding. +:rtype: BoundCBuffer +)"); BoundCBuffer GetConstantBuffer(ShaderStage stage, uint32_t BufIdx, uint32_t ArrayIdx); + + DOCUMENT(R"(Retrieves the read-only resources bound to a particular shader stage. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch from. +:return: The currently bound read-only resoruces. +:rtype: ``dict`` with :class:`~renderdoc.BindpointMap` keys, to lists of :class:`BoundResource`. +)"); QMap> GetReadOnlyResources(ShaderStage stage); + + DOCUMENT(R"(Retrieves the read/write resources bound to a particular shader stage. + +:param ~renderdoc.ShaderStage stage: The shader stage to fetch from. +:return: The currently bound read/write resoruces. +:rtype: ``dict`` with :class:`~renderdoc.BindpointMap` keys, to lists of :class:`BoundResource`. +)"); QMap> GetReadWriteResources(ShaderStage stage); + + DOCUMENT(R"(Retrieves the read/write resources bound to the depth-stencil output. + +:return: The currently bound depth-stencil resource. +:rtype: BoundResource +)"); BoundResource GetDepthTarget(); + + DOCUMENT(R"(Retrieves the resources bound to the colour outputs. + +:return: The currently bound output targets. +:rtype: ``list`` of :class:`BoundResource`. +)"); QVector GetOutputTargets(); private: diff --git a/qrenderdoc/Code/Interface/PersistantConfig.h b/qrenderdoc/Code/Interface/PersistantConfig.h index ffe3a0350..70ba57b4d 100644 --- a/qrenderdoc/Code/Interface/PersistantConfig.h +++ b/qrenderdoc/Code/Interface/PersistantConfig.h @@ -30,13 +30,17 @@ typedef QMap QStringMap; +DOCUMENT("Describes an external program that can be used to disassemble SPIR-V."); struct SPIRVDisassembler { SPIRVDisassembler() {} VARIANT_CAST(SPIRVDisassembler); + DOCUMENT("The human-readable name of the program."); QString name; + DOCUMENT("The path to the executable to run for this program."); QString executable; + DOCUMENT("The command line argmuents to pass to the program."); QString args; }; @@ -49,6 +53,10 @@ DECLARE_REFLECTION_STRUCT(SPIRVDisassembler); access: \ type name; +// Since this macro is already complex enough, the documentation for each of these members is +// in the docstring for PersistantConfig as :data: members. +// Please keep that docstring up to date when you add/remove/change these config settings. +// Note that only public properties should be documented. #define CONFIG_SETTINGS() \ \ CONFIG_SETTING_VAL(public, QString, QString, LastLogPath, "") \ @@ -121,6 +129,24 @@ DECLARE_REFLECTION_STRUCT(SPIRVDisassembler); \ CONFIG_SETTING(private, QVariantList, QList, RemoteHostList) +DOCUMENT(R"(The unit that GPU durations are displayed in. + +.. data:: Seconds + + The durations are displayed as seconds (s). + +.. data:: Milliseconds + + The durations are displayed as milliseconds (ms). + +.. data:: Microseconds + + The durations are displayed as microseconds (µs). + +.. data:: Nanoseconds + + The durations are displayed as nanoseconds (ns). +)"); enum class TimeUnit : int { Seconds = 0, @@ -130,6 +156,11 @@ enum class TimeUnit : int Count, }; +DOCUMENT(R"(Gets the suffix for a time unit. + +:return: The one or two character suffix. +:rtype: ``str`` +)"); inline QString UnitSuffix(TimeUnit unit) { if(unit == TimeUnit::Seconds) @@ -144,27 +175,268 @@ inline QString UnitSuffix(TimeUnit unit) return "s"; } +DOCUMENT(R"(Checks if a given file is in a list. If it is, then it's shuffled to the end. If it's +not then it's added to the end and an item is dropped from the front of the list if necessary to +stay within a given maximum + +As the name suggests, this is used for tracking a 'recent file' list. + +:param list recentList: A ``list`` of ``str`` that is mutated by the function. +:param str file: The file to add to the list. +:param int maxItems: The maximum allowed length of the list. +)"); void AddRecentFile(QList &recentList, const QString &file, int maxItems); +DOCUMENT(R"(A persistant config file that is automatically loaded and saved, which contains any +settings and information that needs to be preserved from one run to the next. + +For more information about some of these settings that are user-facing see +:ref:`the documentation for the settings window `. + +.. data:: LastLogPath + + The path to the last capture to be opened, which is useful as a default location for browsing. + +.. data:: RecentLogFiles + + A ``list`` of ``str`` with the recently opened capture files. + +.. data:: LastCapturePath + + The path containing the last executable that was captured, which is useful as a default location + for browsing. + +.. data:: LastCaptureExe + + The path to the last executable that was captured, inside :data:`LastCapturePath`. + +.. data:: RecentCaptureSettings + + A ``list`` of ``str`` with the recently opened capture settings files. + +.. data:: TemporaryCaptureDirectory + + The path to where temporary capture files should be stored until they're saved permanently. + +.. data:: DefaultCaptureSaveDirectory + + The default path to save captures in, when browsing to save a temporary capture somewhere. + +.. data:: TextureViewer_ResetRange + + ``True`` if the :class:`TextureViewer` should reset the visible range when a new texture is + selected. + + Defaults to ``False``. + +.. data:: TextureViewer_PerTexSettings + + ``True`` if the :class:`TextureViewer` should store most visualisation settings on a per-texture + basis instead of keeping it persistent across different textures. + + Defaults to ``True``. + +.. data:: ShaderViewer_FriendlyNaming + + ``True`` if the :class:`ShaderViewer` should replace register names with the high-level language + variable names where possible. + + Defaults to ``True``. + +.. data:: AlwaysReplayLocally + + ``True`` if when loading a capture that was originally captured on a remote device but uses an + API that can be supported locally, should be loaded locally without prompting to switch to a + remote context. + + Defaults to ``False``. + +.. data:: LocalProxyAPI + + The index of the local proxy API to use when using remote context replay. ``-1`` if the default + proxy should be used. + + Defaults to ``-1``. + +.. data:: EventBrowser_TimeUnit + + The :class:`TimeUnit` to use to display the duration column in the :class:`EventBrowser`. + + Defaults to microseconds. + +.. data:: EventBrowser_HideEmpty + + ``True`` if the :class:`EventBrowser` should hide marker regions that don't contain any actual + non-marker events. + + Defaults to ``False``. + +.. data:: EventBrowser_HideAPICalls + + ``True`` if the :class:`EventBrowser` should hide marker regions that don't contain any events + that aren't just drawcalls (this will hide events under "API Events" faux-markers). + + Defaults to ``False``. + +.. data:: EventBrowser_ApplyColors + + ``True`` if the :class:`EventBrowser` should apply any colours specified with API marker regions. + + Defaults to ``True``. + +.. data:: EventBrowser_ColorEventRow + + ``True`` if when colouring marker regions in the :class:`EventBrowser`, the whole row should be + coloured instead of just a side-bar. + + Defaults to ``True``. + +.. data:: Formatter_MinFigures + + The minimum number of significant figures to show in formatted floating point values. + + Defaults to ``2``. + +.. data:: Formatter_MaxFigures + + The maximum number of significant figures to show in formatted floating point values. + + Defaults to ``5``. + +.. data:: Formatter_NegExp + + The cut-off on negative exponents of a normalised values to display using scientific notation. + + E.g. for a value of 5, anything below 1.0e-5 will be displayed using scientific notation. + + Defaults to ``5``. + +.. data:: Formatter_PosExp + + The cut-off on the exponent of a normalised values to display using scientific notation. + + E.g. for a value of 7, anything above 1.0e+7 will be displayed using scientific notation. + + Defaults to ``7``. + +.. data:: Font_PreferMonospaced + + ``True`` if a monospaced font should be used in all places where data is displayed, even if the + data is not tabular such as names. + + Defaults to ``False``. + +.. data:: Android_AdbExecutablePath + + The path to the ``adb`` executable to use for Android interaction. + +.. data:: Android_MaxConnectTimeout + + The maximum timeout in seconds to wait when launching an Android package. + + Defaults to ``30``. + +.. data:: CheckUpdate_AllowChecks + + ``True`` if when colouring marker regions in the :class:`EventBrowser`, the whole row should be + coloured instead of just a side-bar. + + Defaults to ``True``. + +.. data:: CheckUpdate_UpdateAvailable + + ``True`` if an update to a newer version is currently available. + + Defaults to ``False``. + +.. data:: CheckUpdate_UpdateResponse + + Contains the response from the update server from the last update check, with any release notes + for the new version. + +.. data:: CheckUpdate_LastUpdate + + A date containing the last time that update checks happened. + +.. data:: DegradedLog_LastUpdate + + A date containing the last time that the user was warned about captures being loaded in degraded + support. This prevents the user being spammed if their hardware is low spec. + +.. data:: Tips_HasSeenFirst + + ``True`` if the user has seen the first tip, which should always be shown first before + randomising. + + Defaults to ``False``. + +.. data:: AllowGlobalHook + + ``True`` if global hooking is enabled. Since it has potentially problematic side-effects and is + dangerous, it requires explicit opt-in. + + Defaults to ``False``. + +.. data:: SPIRVDisassemblers + + A list of :class:`SPIRVDisassembler` detailing the potential disassembler programs. The first one + in the list is the default. + +.. data:: RemoteHosts + + A ``list`` of :class:`RemoteHost` handles to the currently configured remote hosts. +)"); class PersistantConfig { public: // Runtime list of dynamically allocated hosts. // Saved to/from private RemoteHostList in CONFIG_SETTINGS() + // This is documented above in the docstring, similar to the values in CONFIG_SETTINGS() + DOCUMENT(""); QList RemoteHosts; + + DOCUMENT("If configured, queries ``adb`` to add android hosts to :data:`RemoteHosts`."); void AddAndroidHosts(); + DOCUMENT(""); CONFIG_SETTINGS() public: PersistantConfig() {} ~PersistantConfig(); + + DOCUMENT(R"(Loads the config from a given filename. This happens automatically on startup, so it's +not recommended thattyou call this function manually. + +:return: A boolean status if the load was successful. +:rtype: ``bool`` +)"); bool Load(const QString &filename); + + DOCUMENT(R"(Saves the config to disk. This can happen if you want to be sure a setting has been +propagated and will not be forgotten in the case of crash or otherwise unexpected exit. + +:return: A boolean status if the save was successful. +:rtype: ``bool`` +)"); bool Save(); + DOCUMENT("Configures the :class:`Formatter` class with the settings from this config."); void SetupFormatting(); + DOCUMENT(R"(Sets an arbitrary dynamic setting similar to a key-value store. This can be used for +storing custom settings to be persisted without needing to modify code. + +:param str name: The name of the setting. Any existing setting will be overwritten. +:param str value: The contents of the setting. +)"); void SetConfigSetting(const QString &name, const QString &value); + DOCUMENT(R"(Retrieves an arbitrary dynamic setting. See :meth:`SetConfigSetting`. + +:param str name: The name of the setting. +:return: The value of the setting, or the empty string if the setting did not exist. +:rtype: ``str`` +)"); QString GetConfigSetting(const QString &name); private: diff --git a/qrenderdoc/Code/Interface/QRDInterface.h b/qrenderdoc/Code/Interface/QRDInterface.h index fcfd31b3a..a55dee86d 100644 --- a/qrenderdoc/Code/Interface/QRDInterface.h +++ b/qrenderdoc/Code/Interface/QRDInterface.h @@ -43,25 +43,40 @@ class QWidget; struct ICaptureContext; +DOCUMENT("Contains all of the settings that control how to capture an executable."); struct CaptureSettings { CaptureSettings(); VARIANT_CAST(CaptureSettings); + DOCUMENT("The :class:`~renderdoc.CaptureOptions` with fine-tuned settings for the capture."); CaptureOptions Options; + DOCUMENT( + "``True`` if the described capture is an inject-into-process instead of a launched " + "executable."); bool Inject; + DOCUMENT("``True`` if this capture settings object should be immediately executed upon load."); bool AutoStart; + DOCUMENT("The path to the executable to run."); QString Executable; + DOCUMENT("The path to the working directory to run in, or blank for the executable's directory."); QString WorkingDir; + DOCUMENT("The command line to pass when running :data:`Exectuable`."); QString CmdLine; + DOCUMENT( + "A ``list`` of :class:`~renderdoc.EnvironmentModification` with environment changes to " + "apply."); QList Environment; }; DECLARE_REFLECTION_STRUCT(CaptureSettings); +DOCUMENT("The main parent window of the application."); struct IMainWindow { + DOCUMENT( + "Retrieves the QWidget for this :class:`MainWindow` if PySide2 is available, or ``None``."); virtual QWidget *Widget() = 0; protected: @@ -71,8 +86,11 @@ protected: DECLARE_REFLECTION_STRUCT(IMainWindow); +DOCUMENT("The event browser window."); struct IEventBrowser { + DOCUMENT( + "Retrieves the QWidget for this :class:`EventBrowser` if PySide2 is available, or ``None``."); virtual QWidget *Widget() = 0; protected: @@ -82,10 +100,14 @@ protected: DECLARE_REFLECTION_STRUCT(IEventBrowser); +DOCUMENT("The API inspector window."); struct IAPIInspector { + DOCUMENT( + "Retrieves the QWidget for this :class:`APIInspector` if PySide2 is available, or ``None``."); virtual QWidget *Widget() = 0; + DOCUMENT("Refresh the current API view - useful if callstacks are now available."); virtual void Refresh() = 0; protected: @@ -95,10 +117,18 @@ protected: DECLARE_REFLECTION_STRUCT(IAPIInspector); +DOCUMENT("The pipeline state viewer window."); struct IPipelineStateViewer { + DOCUMENT( + "Retrieves the QWidget for this :class:`PipelineStateViewer` if PySide2 is available, or " + "``None``."); virtual QWidget *Widget() = 0; + DOCUMENT(R"(Prompt the user to save the binary form of the given shader to disk. + +:param ~renderdoc.ShaderReflection shader: The shader reflection data to save. +)"); virtual bool SaveShaderFile(const ShaderReflection *shader) = 0; protected: @@ -108,11 +138,25 @@ protected: DECLARE_REFLECTION_STRUCT(IPipelineStateViewer); +DOCUMENT("The texture viewer window."); struct ITextureViewer { + DOCUMENT( + "Retrieves the QWidget for this :class:`TextureViewer` if PySide2 is available, or " + "``None``."); virtual QWidget *Widget() = 0; + DOCUMENT(R"(Open a texture view, optionally raising this window to the foreground. + +:param ~renderdoc.ResourceId ID: The ID of the texture to view. +:param bool focus: ``True`` if the :class:`TextureViewer` should be raised. +)"); virtual void ViewTexture(ResourceId ID, bool focus) = 0; + DOCUMENT(R"(Highlights the given pixel location in the current texture. + +:param int x: The X co-ordinate. +:param int y: The Y co-ordinate. +)"); virtual void GotoLocation(int x, int y) = 0; protected: @@ -122,13 +166,36 @@ protected: DECLARE_REFLECTION_STRUCT(ITextureViewer); +DOCUMENT("The buffer viewer window, either a raw buffer or the geometry pipeline."); struct IBufferViewer { + DOCUMENT( + "Retrieves the QWidget for this :class:`BufferViewer` if PySide2 is available, or ``None``."); virtual QWidget *Widget() = 0; + DOCUMENT(R"(Scroll to the given row in the given stage's data. + +:param int row: the row to scroll to. +:param ~renderdoc.MeshDataStage stage: The stage of the geometry pipeline to scroll within. +)"); virtual void ScrollToRow(int row, MeshDataStage stage = MeshDataStage::VSIn) = 0; + + DOCUMENT(R"(In a raw buffer viewer, load the contents from a particular buffer resource. + +:param int byteOffset: The offset in bytes to the start of the data. +:param int byteSize: The number of bytes to read out. +:param ~renderdoc.ResourceId id: The ID of the buffer itself. +:param str format: Optionally a HLSL/GLSL style formatting string. +)"); virtual void ViewBuffer(uint64_t byteOffset, uint64_t byteSize, ResourceId id, const QString &format = "") = 0; + DOCUMENT(R"(In a raw buffer viewer, load the contents from a particular texture resource. + +:param int arrayIdx: The array slice to load from. +:param int mip: The mip level to load from. +:param ~renderdoc.ResourceId id: The ID of the texture itself. +:param str format: Optionally a HLSL/GLSL style formatting string. +)"); virtual void ViewTexture(uint32_t arrayIdx, uint32_t mip, ResourceId id, const QString &format = "") = 0; @@ -139,25 +206,79 @@ protected: DECLARE_REFLECTION_STRUCT(IBufferViewer); +DOCUMENT("The executable capture window."); struct ICaptureDialog { + DOCUMENT( + "Retrieves the QWidget for this :class:`CaptureDialog` if PySide2 is available, or " + "``None``."); virtual QWidget *Widget() = 0; + DOCUMENT(R"(Determines if the window is in inject or launch mode. + +:return: ``True`` if the window is set up for injecting. +:rtype: ``bool`` +)"); virtual bool IsInjectMode() = 0; + DOCUMENT(R"(Switches the window to or from inject mode. + +:param bool inject: ``True`` if the window should configure for injecting into processes. +)"); virtual void SetInjectMode(bool inject) = 0; + DOCUMENT(R"(Sets the executable filename to capture. + +:param str filename: The filename to execute. +)"); virtual void SetExecutableFilename(const QString &filename) = 0; + + DOCUMENT(R"(Sets the working directory for capture. + +:param str dir: The directory to use. +)"); virtual void SetWorkingDirectory(const QString &dir) = 0; + + DOCUMENT(R"(Sets the command line string to use when launching an executable. + +:param str cmd: The command line to use. +)"); virtual void SetCommandLine(const QString &cmd) = 0; + + DOCUMENT(R"(Sets the list of environment modifications to apply when launching. + +:param list modifications: The list of :class:`~renderdoc.EnvironmentModification` to apply. +)"); virtual void SetEnvironmentModifications(const QList &modifications) = 0; + DOCUMENT(R"(Configures the window based on a bulk structure of settings. + +:param CaptureSettings settings: The settings to apply. +)"); virtual void SetSettings(CaptureSettings settings) = 0; + + DOCUMENT(R"(Retrieves the current state of the window as a structure of settings. + +:return: The settings describing the current window state. +:rtype: CaptureSettings +)"); virtual CaptureSettings Settings() = 0; + DOCUMENT("Launches a capture of the current executable."); virtual void TriggerCapture() = 0; + DOCUMENT(R"(Loads settings from a file and applies them. See :meth:`SetSettings`. + +:param str filename: The filename to load the settings from. +)"); virtual void LoadSettings(QString filename) = 0; + + DOCUMENT(R"(Saves the current settings to a file. See :meth:`Settings`. + +:param str filename: The filename to save the settings to. +)"); virtual void SaveSettings(QString filename) = 0; + + DOCUMENT("Update the current state of the global hook, e.g. if it has been enabled."); virtual void UpdateGlobalHook() = 0; protected: @@ -167,8 +288,12 @@ protected: DECLARE_REFLECTION_STRUCT(ICaptureDialog); +DOCUMENT("The debug warnings and errors window."); struct IDebugMessageView { + DOCUMENT( + "Retrieves the QWidget for this :class:`DebugMessageView` if PySide2 is available, or " + "``None``."); virtual QWidget *Widget() = 0; protected: @@ -178,8 +303,12 @@ protected: DECLARE_REFLECTION_STRUCT(IDebugMessageView); +DOCUMENT("The statistics window."); struct IStatisticsViewer { + DOCUMENT( + "Retrieves the QWidget for this :class:`StatisticsViewer` if PySide2 is available, or " + "``None``."); virtual QWidget *Widget() = 0; protected: @@ -189,18 +318,59 @@ protected: DECLARE_REFLECTION_STRUCT(IStatisticsViewer); +DOCUMENT(R"(A shader window used for viewing, editing, or debugging. + +.. function:: SaveCallback(context, viewer, files) + + Not a member function - the signature for any ``SaveCallback`` callbacks. + + Called whenever a shader viewer that was open for editing triggers a save/update. + + :param CaptureContext context: The current capture context. + :param ShaderViewer viewer: The open shader viewer. + :param dict files: A dictionary with ``str`` filename keys and ``str`` file contents values. + +.. function:: CloseCallback(context) + + Not a member function - the signature for any ``CloseCallback`` callbacks. + + Called whenever a shader viewer that was open for editing is closed. + + :param CaptureContext context: The current capture context. +)"); struct IShaderViewer { typedef std::function SaveCallback; typedef std::function CloseCallback; + DOCUMENT( + "Retrieves the QWidget for this :class:`ShaderViewer` if PySide2 is available, or ``None``."); virtual QWidget *Widget() = 0; + DOCUMENT(R"(Retrieves the current step in the debugging. + +:return: The current step. +:rtype: ``int`` +)"); virtual int CurrentStep() = 0; + + DOCUMENT(R"(Sets the current step in the debugging. + +:param int step: The current step to jump to. +)"); virtual void SetCurrentStep(int step) = 0; + DOCUMENT(R"(Toggles a breakpoint at a given instruction. + +:param int instruction: The instruction to toggle breakpoint at. If this is ``-1`` the nearest + instruction after the current caret position is used. +)"); virtual void ToggleBreakpoint(int instruction = -1) = 0; + DOCUMENT(R"(Show a list of shader compilation errors or warnings. + +:param str errors: The string of errors or warnings to display. +)"); virtual void ShowErrors(const QString &errors) = 0; protected: @@ -210,8 +380,12 @@ protected: DECLARE_REFLECTION_STRUCT(IShaderViewer); +DOCUMENT("A constant buffer preview window."); struct IConstantBufferPreviewer { + DOCUMENT( + "Retrieves the QWidget for this :class:`ConstantBufferPreviewer` if PySide2 is available, or " + "``None``."); virtual QWidget *Widget() = 0; protected: @@ -221,9 +395,18 @@ protected: DECLARE_REFLECTION_STRUCT(IConstantBufferPreviewer); +DOCUMENT("A pixel history window."); struct IPixelHistoryView { + DOCUMENT( + "Retrieves the QWidget for this :class:`PixelHistoryView` if PySide2 is available, or " + "``None``."); virtual QWidget *Widget() = 0; + + DOCUMENT(R"(Set the history displayed in this window. + +:param list history: A list of :class:`~renderdoc.PixelModification` events to display. +)"); virtual void SetHistory(const rdctype::array &history) = 0; protected: @@ -233,20 +416,36 @@ protected: DECLARE_REFLECTION_STRUCT(IPixelHistoryView); +DOCUMENT("An interface implemented by any object wanting to be notified of capture events."); struct ILogViewer { + DOCUMENT("Called whenever a capture is opened."); virtual void OnLogfileLoaded() = 0; + + DOCUMENT("Called whenever a capture is closed."); virtual void OnLogfileClosed() = 0; - // These 2 functions distinguish between the event which is actually - // selected and the event which the displayed state should be taken from. In - // the case of an event with children, OnSelectedEventChanged receives the - // ID of the event itself, whereas OnEventChanged receives that of the last - // child. This means that selecting an event with children displays the - // state after all of its children have completed, the exception being that - // the API inspector uses the selected event ID to display the API calls of - // that event rather than of the last child. + DOCUMENT(R"(Called whenever the current selected event changes. This is distinct from the actual +effective current event, since for example selecting a marker region will change the current event +to be the last event inside that region, to be consistent with selecting an item reflecting the +current state after that item. + +The selected event shows the :data:`EID ` that was actually selected, +which will usually but not always be the same as the current effective +:data:`EID `. + +The distinction for this callback is not normally desired, instead use :meth:`OnEventChanged` to +be notified whenever the current event changes. The API inspector uses this to display API events up +to a marker region. + +:param int eventID: The new :data:`EID `. +)"); virtual void OnSelectedEventChanged(uint32_t eventID) = 0; + + DOCUMENT(R"(Called whenever the effective current event changes. + +:param int eventID: The new :data:`EID `. +)"); virtual void OnEventChanged(uint32_t eventID) = 0; protected: @@ -256,40 +455,158 @@ protected: DECLARE_REFLECTION_STRUCT(ILogViewer); +DOCUMENT(R"(A manager for accessing the underlying replay information that isn't already abstracted +in UI side structures. This manager controls and serialises access to the underlying +:class:`~renderdoc.ReplayController`, as well as handling remote server connections. + +.. function:: InvokeCallback(controller) + + Not a member function - the signature for any ``InvokeCallback`` callbacks. + + :param ~renderdoc.ReplayController controller: The controller to access. Must not be cached or + used after the callback returns. + +.. function:: DirectoryBrowseCallback(path, entries) + + Not a member function - the signature for any ``DirectoryBrowseCallback`` callbacks. + + :param str path: The path that was queried for. + :param list entries: The :class:`~renderdoc.PathEntry` entries underneath the path, as relevant. +)"); struct IReplayManager { typedef std::function InvokeCallback; typedef std::function &)> DirectoryBrowseCallback; + DOCUMENT(R"(Delete a capture file, whether local or remote. + +:param str logfile: The path to the file. +:param bool local: ``True`` if the file is on the local machine. +)"); virtual void DeleteCapture(const QString &logfile, bool local) = 0; - // this tagged version is for cases when we might send a request - e.g. to pick a vertex or pixel - // - and want to pre-empt it with a new request before the first has returned. Either because some - // other work is taking a while or because we're sending requests faster than they can be - // processed. - // the manager processes only the request on the top of the queue, so when a new tagged invoke - // comes in, we remove any other requests in the queue before it that have the same tag - virtual void AsyncInvoke(const QString &tag, InvokeCallback m) = 0; - virtual void AsyncInvoke(InvokeCallback m) = 0; - virtual void BlockInvoke(InvokeCallback m) = 0; + DOCUMENT(R"(Connect to a remote server. +:param RemoteHost host: The host to connect to. +:return: Whether or not the connection was successful. +:rtype: ~renderdoc.ReplayStatus +)"); virtual ReplayStatus ConnectToRemoteServer(RemoteHost *host) = 0; + + DOCUMENT("Disconnect from the server the manager is currently connected to."); virtual void DisconnectFromRemoteServer() = 0; + + DOCUMENT("Shutdown the server the manager is currently connected to."); virtual void ShutdownServer() = 0; + + DOCUMENT("Ping the remote server to ensure the connection is still alive."); virtual void PingRemote() = 0; + DOCUMENT(R"(Retrieves the host that the manager is currently connected to. + +:return: The host connected to, or ``None`` if no connection is active. +:rtype: RemoteHost +)"); virtual const RemoteHost *CurrentRemote() = 0; + + DOCUMENT(R"(Launch an application and inject into it to allow capturing. + +This happens either locally, or on the remote server, depending on whether a connection is active. + +:param str exe: The path to the executable to run. +:param str workingDir: The working directory to use when running the application. If blank, the + directory containing the executable is used. +:param str cmdLine: The command line to use when running the executable, it will be processed in a + platform specific way to generate arguments. +:param list env: Any :class:`EnvironmentModification` that should be made when running the program. +:param str logfile: The location to save any captures, if running locally. +:param CaptureOptions opts: The capture options to use when injecting into the program. +:return: The ident where the new application is listening for target control, or 0 if something went + wrong. +:rtype: ``int`` +)"); virtual uint32_t ExecuteAndInject(const QString &exe, const QString &workingDir, const QString &cmdLine, const QList &env, const QString &logfile, CaptureOptions opts) = 0; + DOCUMENT(R"(Retrieve a list of drivers that the current remote server supports. + +:return: The list of supported replay drivers. +:rtype: ``list`` of ``str``. +)"); virtual QStringList GetRemoteSupport() = 0; + + DOCUMENT(R"(Query the remote host for its home directory. + +If a capture is open, the callback will happen on the replay thread, otherwise it will happen in a +blocking fashion on the current thread. + +:param bool synchronous: If a capture is open, then ``True`` will use :meth:`BlockInvoke` to call + the callback. Otherwise if ``False`` then :meth:`AsyncInvoke` will be used. +:param DirectoryBrowseMethod method: The function to callback on the replay thread. +)"); virtual void GetHomeFolder(bool synchronous, DirectoryBrowseCallback cb) = 0; + + DOCUMENT(R"(Query the remote host for the contents of a path. + +If a capture is open, the callback will happen on the replay thread, otherwise it will happen in a +blocking fashion on the current thread. + +:param str path: The path to query the contents of. +:param bool synchronous: If a capture is open, then ``True`` will use :meth:`BlockInvoke` to call + the callback. Otherwise if ``False`` then :meth:`AsyncInvoke` will be used. +:param DirectoryBrowseMethod method: The function to callback on the replay thread. +)"); virtual void ListFolder(QString path, bool synchronous, DirectoryBrowseCallback cb) = 0; + + DOCUMENT(R"(Copy a capture from the local machine to the remote host. + +:param str localpath: The path on the local machine to copy from. +:return: The path on the local machine where the file was saved, or empty if something went wrong. +:param QWidget window: A handle to the window to use when showing a progress bar. +:rtype: ``str`` +)"); virtual QString CopyCaptureToRemote(const QString &localpath, QWidget *window) = 0; + + DOCUMENT(R"(Copy a capture from the remote host to the local machine. + +:param str remotepath: The path on the remote server to copy from. +:param str localpath: The path on the local machine to copy to. +:param QWidget window: A handle to the window to use when showing a progress bar. +)"); virtual void CopyCaptureFromRemote(const QString &remotepath, const QString &localpath, QWidget *window) = 0; + DOCUMENT(R"(Make a tagged non-blocking invoke call onto the replay thread. + +This tagged function is for cases when we might send a request - e.g. to pick a vertex or pixel - +and want to pre-empt it with a new request before the first has returned. Either because some +other work is taking a while or because we're sending requests faster than they can be +processed. + +The manager processes only the request on the top of the queue, so when a new tagged invoke +comes in, we remove any other requests in the queue before it that have the same tag. + +:param str tag: The tag to identify this callback. +:param InvokeCallback method: The function to callback on the replay thread. +)"); + virtual void AsyncInvoke(const QString &tag, InvokeCallback method) = 0; + + DOCUMENT(R"(Make a non-blocking invoke call onto the replay thread. + +:param InvokeCallback method: The function to callback on the replay thread. +)"); + virtual void AsyncInvoke(InvokeCallback method) = 0; + + // This is an ugly hack, but we leave BlockInvoke as the last method, so that when the class is + // extended and the wrapper around BlockInvoke to release the python GIL happens, it picks up the + // same docstring. + DOCUMENT(R"(Make a blocking invoke call onto the replay thread. + +:param InvokeCallback method: The function to callback on the replay thread. +)"); + virtual void BlockInvoke(InvokeCallback method) = 0; + protected: IReplayManager() = default; ~IReplayManager() = default; @@ -298,6 +615,58 @@ protected: DECLARE_REFLECTION_STRUCT(IReplayManager); // should match ToolWindowManager::AreaReferenceType +DOCUMENT(R"(Specifies the relationship between the existing dock window and the new one when adding +a new dock window or moving an existing dock window. + +.. data:: LastUsedArea + + The existing dock window is not used, the new dock window is placed wherever the last dock window + was placed. + +.. data:: NewFloatingArea + + The existing dock window is not used, the new dock window is placed in a new floating area. + +.. data:: EmptySpace + + The existing dock window is not used, the new dock window is placed in empty area in the dockarea. + +.. data:: NoArea + + The existing dock window is not used, the new window is hidden. + +.. data:: AddTo + + The new dock window is placed in a tab set with the existing dock window. + +.. data:: LeftOf + + The new dock window is placed to the left of the existing dock window, at a specified proportion. + +.. data:: RightOf + + The new dock window is placed to the right of the existing dock window, at a specified proportion. + +.. data:: TopOf + + The new dock window is placed above the existing dock window, at a specified proportion. + +.. data:: BottomOf + + The new dock window is placed below the existing dock window, at a specified proportion. + +.. data:: MainToolArea + + The new dock window is placed in the 'main' tool area as defined by finding an existing known + window and using that as the main area. In the default layout this is where most windows are + placed. + +.. data:: LeftToolArea + + The new dock window is placed in the 'left' tool area as defined by finding an existing known + window and using that as the main area, then adding to the left of that. In the default layout + this is where the event browser is placed. +)"); enum class DockReference : int { LastUsedArea, @@ -315,114 +684,563 @@ enum class DockReference : int LeftToolArea, }; +DOCUMENT("The capture context that the python script is running in.") struct ICaptureContext { + DOCUMENT(R"(Retrieve the absolute path where a given file can be stored with other application +data. + +:param str filename: The base filename. +:return: The absolute path. +:rtype: ``str`` +)"); virtual QString ConfigFilePath(const QString &filename) = 0; + DOCUMENT(R"(Retrieve the absolute path where a given temporary capture should be stored. +data. + +:param str appname: The name of the application to use as part of the template. +:return: The absolute path. +:rtype: ``str`` +)"); virtual QString TempLogFilename(QString appname) = 0; + DOCUMENT(R"(Open a capture file for replay. + +:param str logFile: The actual path to the capture file. +:param str origFilename: The original filename, if the capture was copied remotely for replay. +:param bool temporary: ``True`` if this is a temporary capture which should prompt the user for + either save or delete on close. +:param bool local: ``True`` if ``logFile`` refers to a file on the local machine. +)"); virtual void LoadLogfile(const QString &logFile, const QString &origFilename, bool temporary, bool local) = 0; + + DOCUMENT("Close the currently open capture file."); virtual void CloseLogfile() = 0; + DOCUMENT(R"(Move the current replay to a new event in the capture. + +:param list exclude: A list of :class:`LogViewer` to exclude from being notified of this, to stop + infinite recursion. +:param int selectedEventID: The selected :data:`EID `. See + :meth:`LogViewer.OnSelectedEventChanged` for more information. +:param int eventID: The new current :data:`EID `. See + :meth:`LogViewer.OnEventChanged` for more information. +:param bool force: Optional parameter, if ``True`` then the replay will 'move' even if it is moving + to the same :data:`EID ` as it's currently on. +)"); virtual void SetEventID(const QVector &exclude, uint32_t selectedEventID, uint32_t eventID, bool force = false) = 0; + DOCUMENT(R"(Replay the capture to the current event again, to pick up any changes that might have +been made. +)"); virtual void RefreshStatus() = 0; - virtual void AddLogViewer(ILogViewer *f) = 0; - virtual void RemoveLogViewer(ILogViewer *f) = 0; + DOCUMENT(R"(Register a new instance of :class:`LogViewer` to receive capture event notifications. + +:param LogViewer viewer: The viewer to register. +)"); + virtual void AddLogViewer(ILogViewer *viewer) = 0; + + DOCUMENT(R"(Unregister an instance of :class:`LogViewer` from receiving notifications. + +:param LogViewer viewer: The viewer to unregister. +)"); + virtual void RemoveLogViewer(ILogViewer *viewer) = 0; ////////////////////////////////////////////////////////////////////////////// // Accessors + DOCUMENT(R"(Retrieve the replay manager for access to the internal RenderDoc replay controller. + +:return: The current replay manager. +:rtype: ReplayManager +)"); virtual IReplayManager &Replay() = 0; + + DOCUMENT(R"(Check whether or not a capture is currently loaded. + +:return: ``True`` if a capture is loaded. +:rtype: ``bool`` +)"); virtual bool LogLoaded() = 0; + + DOCUMENT(R"(Check whether or not the current capture is stored locally, or on a remote host. + +:return: ``True`` if a capture is local. +:rtype: ``bool`` +)"); virtual bool IsLogLocal() = 0; + + DOCUMENT(R"(Check whether or not a capture is currently loading in-progress. + +:return: ``True`` if a capture is currently loading. +:rtype: ``bool`` +)"); virtual bool LogLoading() = 0; + + DOCUMENT(R"(Retrieve the filename for the currently loaded capture. + +:return: The filename of the current capture. +:rtype: ``str`` +)"); virtual QString LogFilename() = 0; + + DOCUMENT(R"(Retrieve the :class:`~renderdoc.FrameDescription` for the currently loaded capture. + +:return: The frame information. +:rtype: ~renderdoc.FrameDescription +)"); virtual const FrameDescription &FrameInfo() = 0; + + DOCUMENT(R"(Retrieve the :class:`~renderdoc.APIProperties` for the currently loaded capture. + +:return: The API properties. +:rtype: ~renderdoc.APIProperties +)"); virtual const APIProperties &APIProps() = 0; + + DOCUMENT(R"(Retrieve the currently selected :data:`EID `. + +In most cases, prefer using :meth:`CurEvent`. See :meth:`LogViewer.OnSelectedEventChanged` for more +information for how this differs. + +:return: The current selected event. +:rtype: ``int`` +)"); virtual uint32_t CurSelectedEvent() = 0; + + DOCUMENT(R"(Retrieve the current :data:`EID `. + +:return: The current event. +:rtype: ``int`` +)"); virtual uint32_t CurEvent() = 0; + + DOCUMENT(R"(Retrieve the currently selected drawcall. + +In most cases, prefer using :meth:`CurDrawcall`. See :meth:`LogViewer.OnSelectedEventChanged` for +more information for how this differs. + +:return: The currently selected drawcall. +:rtype: ~renderdoc.DrawcallDescription +)"); virtual const DrawcallDescription *CurSelectedDrawcall() = 0; + + DOCUMENT(R"(Retrieve the current drawcall. + +:return: The current drawcall. +:rtype: ~renderdoc.DrawcallDescription +)"); virtual const DrawcallDescription *CurDrawcall() = 0; + + DOCUMENT(R"(Retrieve the root list of drawcalls in the current capture. + +:return: The root drawcalls. +:rtype: ``list`` of :class:`~renderdoc.DrawcallDescription` +)"); virtual const rdctype::array &CurDrawcalls() = 0; + + DOCUMENT(R"(Retrieve the information about a particular texture. + +:param ~renderdoc.ResourceId id: The ID of the texture to query about. +:return: The information about a texture, or ``None`` if the ID does not correspond to a texture. +:rtype: ~renderdoc.TextureDescription +)"); virtual TextureDescription *GetTexture(ResourceId id) = 0; + + DOCUMENT(R"(Retrieve the list of textures in the current capture. + +:return: The list of textures. +:rtype: ``list`` of :class:`~renderdoc.TextureDescription` +)"); virtual const rdctype::array &GetTextures() = 0; + + DOCUMENT(R"(Retrieve the information about a particular buffer. + +:param ~renderdoc.ResourceId id: The ID of the buffer to query about. +:return: The information about a buffer, or ``None`` if the ID does not correspond to a buffer. +:rtype: ~renderdoc.BufferDescription +)"); virtual BufferDescription *GetBuffer(ResourceId id) = 0; + + DOCUMENT(R"(Retrieve the list of buffers in the current capture. + +:return: The list of buffers. +:rtype: ``list`` of :class:`~renderdoc.BufferDescription` +)"); virtual const rdctype::array &GetBuffers() = 0; + DOCUMENT(R"(Retrieve the information about a drawcall at a given +:data:`EID `. + +:param int id: The :data:`EID ` to query for. +:return: The information about the drawcall, or ``None`` if the + :data:`EID ` doesn't correspond to a drawcall. +:rtype: ~renderdoc.BufferDescription +)"); virtual const DrawcallDescription *GetDrawcall(uint32_t eventID) = 0; + DOCUMENT(R"(Retrieve the current windowing system in use. + +:return: The active windowing system. +:rtype: ~renderdoc.WindowingSystem +)"); virtual WindowingSystem CurWindowingSystem() = 0; + + DOCUMENT(R"(Create an opaque pointer suitable for passing to +:meth:`~ReplayController.CreateOutput` or other functions that expect windowing data. + +.. note:: + + This data only stays valid until the next call to FillWindowingData. You should pass it to the + consuming function immediately. + +:param int winId: The window ID as returned from ``QWidget.winId()``. +:return: The windowing data. +:rtype: opaque void * pointer. +)"); virtual void *FillWindowingData(uintptr_t winId) = 0; + DOCUMENT(R"(Retrieve the current list of debug messages. This includes messages from the capture +as well as messages generated during replay and analysis. + +:return: The debug messages generated to date. +:rtype: ``list`` of :class:`~renderdoc.DebugMessage` +)"); virtual const QVector &DebugMessages() = 0; + + DOCUMENT(R"(Retrieve how many messages in :meth:`DebugMessages` are currently unread. + +:return: The number of unread messages. +:rtype: ``int`` +)"); virtual int UnreadMessageCount() = 0; + + DOCUMENT("Mark all messages as read, resets :meth:`UnreadMessageCount` to 0."); virtual void MarkMessagesRead() = 0; + + DOCUMENT(R"(Add messages into the list returned by :meth:`DebugMessages`. Initially set to unread. + +:param list msgs: A list of :class:`~renderdoc.DebugMessage` to add. +)"); virtual void AddMessages(const rdctype::array &msgs) = 0; + DOCUMENT(R"(Retrieve the current singleton :class:`MainWindow`. + +:return: The current window. +:rtype: MainWindow +)"); virtual IMainWindow *GetMainWindow() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`EventBrowser`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: EventBrowser +)"); virtual IEventBrowser *GetEventBrowser() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`APIInspector`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: APIInspector +)"); virtual IAPIInspector *GetAPIInspector() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`TextureViewer`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: TextureViewer +)"); virtual ITextureViewer *GetTextureViewer() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`BufferViewer`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: BufferViewer +)"); virtual IBufferViewer *GetMeshPreview() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`PipelineStateViewer`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: PipelineStateViewer +)"); virtual IPipelineStateViewer *GetPipelineViewer() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`CaptureDialog`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: CaptureDialog +)"); virtual ICaptureDialog *GetCaptureDialog() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`DebugMessageView`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: DebugMessageView +)"); virtual IDebugMessageView *GetDebugMessageView() = 0; + + DOCUMENT(R"(Retrieve the current singleton :class:`StatisticsViewer`. + +:return: The current window, which is created (but not shown) it there wasn't one open. +:rtype: StatisticsViewer +)"); virtual IStatisticsViewer *GetStatisticsViewer() = 0; + DOCUMENT(R"(Check if there is a current :class:`EventBrowser` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasEventBrowser() = 0; + + DOCUMENT(R"(Check if there is a current :class:`APIInspector` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasAPIInspector() = 0; + + DOCUMENT(R"(Check if there is a current :class:`TextureViewer` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasTextureViewer() = 0; + + DOCUMENT(R"(Check if there is a current :class:`PipelineViewer` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasPipelineViewer() = 0; + + DOCUMENT(R"(Check if there is a current :class:`MeshPreview` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasMeshPreview() = 0; + + DOCUMENT(R"(Check if there is a current :class:`CaptureDialog` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasCaptureDialog() = 0; + + DOCUMENT(R"(Check if there is a current :class:`DebugMessageView` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasDebugMessageView() = 0; + + DOCUMENT(R"(Check if there is a current :class:`StatisticsViewer` open. + +:return: ``True`` if there is a window open. +:rtype: ``bool`` +)"); virtual bool HasStatisticsViewer() = 0; + DOCUMENT("Raise the current :class:`EventBrowser`, showing it in the default place if needed."); virtual void ShowEventBrowser() = 0; + DOCUMENT("Raise the current :class:`APIInspector`, showing it in the default place if needed."); virtual void ShowAPIInspector() = 0; + DOCUMENT("Raise the current :class:`TextureViewer`, showing it in the default place if needed."); virtual void ShowTextureViewer() = 0; + DOCUMENT("Raise the current :class:`MeshPreview`, showing it in the default place if needed."); virtual void ShowMeshPreview() = 0; + DOCUMENT("Raise the current :class:`PipelineViewer`, showing it in the default place if needed."); virtual void ShowPipelineViewer() = 0; + DOCUMENT("Raise the current :class:`CaptureDialog`, showing it in the default place if needed."); virtual void ShowCaptureDialog() = 0; + DOCUMENT( + "Raise the current :class:`DebugMessageView`, showing it in the default place if needed."); virtual void ShowDebugMessageView() = 0; + DOCUMENT( + "Raise the current :class:`StatisticsViewer`, showing it in the default place if needed."); virtual void ShowStatisticsViewer() = 0; + DOCUMENT(R"(Show a new :class:`ShaderViewer` window, showing an editable view of a given shader. + +:param bool customShader: ``True`` if the shader being edited is a custom display shader. +:param str entryPoint: The entry point to be used when compiling the edited shader. +:param dict files: The files stored in a ``dict`` with ``str`` keys as filenames and ``str`` values + with the file contents. +:param ShaderViewer.SaveCallback saveCallback: The callback function to call when a save/update is + triggered. +:param ShaderViewer.CloseCallback closeCallback: The callback function to call when the shader + viewer is closed. +:return: The new :class:`ShaderViewer` window opened but not shown for editing. +:rtype: ShaderViewer +)"); virtual IShaderViewer *EditShader(bool customShader, const QString &entryPoint, const QStringMap &files, IShaderViewer::SaveCallback saveCallback, IShaderViewer::CloseCallback closeCallback) = 0; + + DOCUMENT(R"(Show a new :class:`ShaderViewer` window, showing a read-only view of a debug trace +through the execution of a given shader. + +:param ~renderdoc.ShaderBindpointMapping bind: The bindpoint mapping for the shader to view. +:param ~renderdoc.ShaderReflection shader: The reflection data for the shader to view. +:param ~renderdoc.ShaderStage stage: The stage that the shader is bound to. +:param ~renderdoc.ShaderDebugTrace trace: The execution trace of the debugged shader. +:param str debugContext: A human-readable context string describing which invocation of this shader + was debugged. For example 'Pixel 12,34 at EID 678'. +:return: The new :class:`ShaderViewer` window opened, but not shown. +:rtype: ShaderViewer +)"); virtual IShaderViewer *DebugShader(const ShaderBindpointMapping *bind, const ShaderReflection *shader, ShaderStage stage, ShaderDebugTrace *trace, const QString &debugContext) = 0; + DOCUMENT(R"(Show a new :class:`ShaderViewer` window, showing a read-only view of a given shader. +:param ~renderdoc.ShaderBindpointMapping bind: The bindpoint mapping for the shader to view. +:param ~renderdoc.ShaderReflection shader: The reflection data for the shader to view. +:param ~renderdoc.ShaderStage stage: The stage that the shader is bound to. +:return: The new :class:`ShaderViewer` window opened, but not shown. +:rtype: ShaderViewer +)"); virtual IShaderViewer *ViewShader(const ShaderBindpointMapping *bind, const ShaderReflection *shader, ShaderStage stage) = 0; + + DOCUMENT(R"(Show a new :class:`BufferViewer` window, showing a read-only view of buffer data. + +:param int byteOffset: The offset in bytes to the start of the buffer data to show. +:param int byteSize: The number of bytes in the buffer to show. +:param ~renderdoc.ResourceId id: The ID of the buffer to fetch data from. +:param str format: Optionally a HLSL/GLSL style formatting string. +:return: The new :class:`BufferViewer` window opened, but not shown. +:rtype: BufferViewer +)"); virtual IBufferViewer *ViewBuffer(uint64_t byteOffset, uint64_t byteSize, ResourceId id, const QString &format = "") = 0; + + DOCUMENT(R"(Show a new :class:`BufferViewer` window, showing a read-only view of a texture's raw +bytes. + +:param int arrayIdx: The array slice to load from. +:param int mip: The mip level to load from. +:param ~renderdoc.ResourceId id: The ID of the texture itself. +:param str format: Optionally a HLSL/GLSL style formatting string. +:return: The new :class:`BufferViewer` window opened, but not shown. +:rtype: BufferViewer +)"); virtual IBufferViewer *ViewTextureAsBuffer(uint32_t arrayIdx, uint32_t mip, ResourceId id, const QString &format = "") = 0; + DOCUMENT(R"(Show a new :class:`ConstantBufferPreviewer` window, showing a read-only view of a the +variables in a constant buffer with their values. + +:param ~renderdoc.ShaderStage stage: The stage that the constant buffer is bound to. +:param int slot: The index in the shader's constant buffer list to look up. +:param int idx: For APIs that support arrayed resource binds, the index in the constant buffer + array. +:return: The new :class:`ConstantBufferPreviewer` window opened, but not shown. +:rtype: ConstantBufferPreviewer +)"); virtual IConstantBufferPreviewer *ViewConstantBuffer(ShaderStage stage, uint32_t slot, uint32_t idx) = 0; + + DOCUMENT(R"(Show a new :class:`PixelHistoryView` window, showing the results from a pixel history +operation. + +:param ~renderdoc.ResourceId id: The ID of the texture to show the history of. +:param int X: The x co-ordinate of the pixel to search for. +:param int Y: The y co-ordinate of the pixel to search for. +:param ~renderdoc.TextureDisplay display: The texture display configuration to use when looking up + the history. +:return: The new :class:`PixelHistoryView` window opened, but not shown. +:rtype: PixelHistoryView +)"); virtual IPixelHistoryView *ViewPixelHistory(ResourceId texID, int x, int y, const TextureDisplay &display) = 0; + DOCUMENT(R"(Creates and returns a built-in window. + +This function is intended for internal use for restoring layouts, and generally should not be used +by user code. + +:param str objectName: The built-in name of a singleton window. +:return: The handle to the existing or newly created window of this type, or ``None`` if PySide2 is + not available. +:rtype: ``QWidget`` +)"); virtual QWidget *CreateBuiltinWindow(const QString &objectName) = 0; + + DOCUMENT(R"(Marks a built-in window as closed. + +This function is intended for internal use by the built-in windows for singleton management, and +should not be called by user code. + +:param QWidget window: The built-in window that closed. +)"); virtual void BuiltinWindowClosed(QWidget *window) = 0; + DOCUMENT(R"(Raises a window within its docking manager so it becomes the focus of wherever it is +currently docked. + +:param QWidget dockWindow: The window to raise. +)"); virtual void RaiseDockWindow(QWidget *dockWindow) = 0; + + DOCUMENT(R"(Adds a new window within the docking system. + +:param QWidget dockWindow: The new window to add. +:param DockReference ref: The location to add the new window, possibly relative to ``refWindow``. +:param QWidget refWindow: The window to refer to if the new window is being added relative, or can + be ``None`` if the new location is absolute. +:param float percentage: Optionally the percentage to split the area. If omitted, a 50% split is + used. +)"); virtual void AddDockWindow(QWidget *newWindow, DockReference ref, QWidget *refWindow, float percentage = 0.5f) = 0; + DOCUMENT(R"(Retrieve the current :class:`~renderdoc.D3D11_State` pipeline state. + +:return: The current D3D11 pipeline state. +:rtype: ~renderdoc.D3D11_State +)"); virtual D3D11Pipe::State &CurD3D11PipelineState() = 0; + + DOCUMENT(R"(Retrieve the current :class:`~renderdoc.D3D12_State` pipeline state. + +:return: The current D3D12 pipeline state. +:rtype: ~renderdoc.D3D12_State +)"); virtual D3D12Pipe::State &CurD3D12PipelineState() = 0; + + DOCUMENT(R"(Retrieve the current :class:`~renderdoc.GL_State` pipeline state. + +:return: The current OpenGL pipeline state. +:rtype: ~renderdoc.GL_State +)"); virtual GLPipe::State &CurGLPipelineState() = 0; + + DOCUMENT(R"(Retrieve the current :class:`~renderdoc.VK_State` pipeline state. + +:return: The current Vulkan pipeline state. +:rtype: ~renderdoc.VK_State +)"); virtual VKPipe::State &CurVulkanPipelineState() = 0; + + DOCUMENT(R"(Retrieve the current :class:`CommonPipelineState` abstracted pipeline state. + +:return: The current API-agnostic abstracted pipeline state. +:rtype: CommonPipelineState +)"); virtual CommonPipelineState &CurPipelineState() = 0; + DOCUMENT(R"(Retrieve the current persistant config. + +:return: The current persistant config manager. +:rtype: PersistantConfig +)"); virtual PersistantConfig &Config() = 0; protected: diff --git a/qrenderdoc/Code/Interface/RemoteHost.h b/qrenderdoc/Code/Interface/RemoteHost.h index 5a5b9f006..16c9651ea 100644 --- a/qrenderdoc/Code/Interface/RemoteHost.h +++ b/qrenderdoc/Code/Interface/RemoteHost.h @@ -29,6 +29,7 @@ class RemoteHost; // do not include any headers here, they must all be in QRDInterface.h #include "QRDInterface.h" +DOCUMENT("A handle for interacting with a remote servers on a given host."); class RemoteHost { public: @@ -36,16 +37,24 @@ public: VARIANT_CAST(RemoteHost); - bool IsValid() { return !Hostname.isEmpty(); } + DOCUMENT( + "Ping the host to check current status - if the server is running, connection status, etc."); void CheckStatus(); + DOCUMENT("Runs the command specified in :data:`RunCommand`."); void Launch(); + DOCUMENT("``True`` if a remote server is currently running on this host."); bool ServerRunning : 1; + DOCUMENT("``True`` if an active connection exists to this remote server."); bool Connected : 1; + DOCUMENT("``True`` if someone else is currently connected to this server."); bool Busy : 1; + DOCUMENT("``True`` if there is a code version mismatch with this server."); bool VersionMismatch : 1; + DOCUMENT("The hostname of this host."); QString Hostname; + DOCUMENT("The command to run locally to try to launch the server remotely."); QString RunCommand; };