Project Description

EffectEd is an HLSL code editor for Direct3D and XNA. It's a lightweight alternative to heavy applications like FX Composer.

EffectEd's priority is to easily integrate in your daily workflow writing shader and effect code for DirectX (and thus, also for XNA).

It has the most desirable features:
* syntax highlighting
* checking for errors using the D3D compiler
* intelligent code completion

... and several other features to make it valuable and simple to use.

Getting started

Watch this demonstration video first. Come back here afterwards to find more details on how to use EffectEd.


Overview

The big features that are currently implemented:
  • syntax highlighting
  • waterproof compilation feedback by directly using the Direct3D compiler
  • code completion (Ctrl+space)
  • your own "new file" templates

Because this is a young project and I has no decent HLSL specifications available, the code-completion and syntax highlighting logic is functioning but the data for it is still incomplete. A lot is there, but it's certainly not finished.

It is easily customized, though, through the xml files in the data folder which allow you to:
  • change/add context dependent code completion data (CodeAssistance.xml)
  • change compiler Profiles per Direct3D version (CodeAssistance.xml)
  • create your own "new-file" templates by saving your files to the data\templates folder
  • change syntax highlighting rules (hlsl10.xshd - for now, only one syntax definition for all Profiles)

Upcoming...

ToDo list:
  • "Go To Definition" - F12 (using the already finished expression tree)
    • jump to included files by opening a new instance of EffectEd
    • jump to user defined functions from their function calls
  • Context menu with copy paste and other functions. (copy paste already works with Ctrl+X, C & V but is not yet visualized)

Details

Code completion

Thanks to the included expression tree parser for HLSL, code completion in EffectEd is aware of the position of your cursor in the logical structure of your code. You can trigger the code completion using Ctrl+space: if there is completion data defined for the logical position of your cursor, it will popup. If there isn't, nothing will happen.

This way, it shows only relevant code suggestions for the location your cursor is at.

Compiler settings

Because Direct3D compilation provides some parameters like the profile or the entrypoint, EffectEd provides a feature to keep these settings per-file for you by including a single-line header into your file. This single line contains the compiler parameters.

Thanks to this feature, you can have different settings for each file, which is especially handy when you put your shaders' code in separate files in Direct3D 11.

Note that using this header is optional: you can configure defaults too which are used when no header is found. Of course, using the header offers the most flexibility.

EffectEd also has a GUI dialog to edit this header, so you don't have to learn the EffectEd header syntax., just use the dialog.

The Compiler settings include ShaderFlags, EffectFlags, EntryPoint, Profile and Direct3D version (needed for selecting different compiler logic).

"new file" templates

Next to some basic file templates, you can add your own templates simply by saving your file inside the \data\templates. There is a small filename convention to define a sorting index in the filename. Just look at the format of the filenames of the included templates, it's easy.

Include files

Any #include file is searched for relative to the directory of the file being compiled.

Visual Studio integration

I didn't have time to create a plugin for Visual Studio, I have no experience with this, so it would take quite some time. I welcome you to help me with this :)

The best integration I get is by setting EffectEd as the default application for .fx and .hlsl files in Visual Studio's Solution Explorer. This way, it acts like just another source code editor.

To support this, EffectEd has a setting to save your changes silently when closing the application - no question is popping up. This way, when using EffectEd from Visual Studio, you don't have to confirm saving changes when closing the editor.

Not supported/unfinished yet

For now I'm happy with the feature set.

Of course, many things could be added such as a preview render window but this would be a lot of effort due to the rich featureset of HLSL. It's not just rendering a sphere with the effect file anymore...

Next to that... a lot of small things I guess. Let me know...

Bugs? Changes? Code completion data improvements?

Let me know here: https://www.codeplex.com/site/users/contact/ThomasVT?OriginalUrl=http://www.codeplex.com/site/users/view/ThomasVT

Advanced topics

Changing code completion data

Code completion data is stored in "\data\CodeAssistance.xml". This xml-file uses listings of code completion items per "context" (=the logical location). Examples of contexts are "in a function's codeblock", "in a function-call's argument list" or even "on the top level of the document" if your cursor is in between code..

In EffectEd, you can always see the string that identifies this logical location of the cursor at the bottom of the application. So, if you want to add or change code completion in that locical location, use that identifier at the bottom to create the ContextIdentifier (how? replace all " > " separators in identifier by dots (".")).

Examples of ContextIdentifiers:
  • "Document.FunctionDefinition.CodeBlock" identifies the context where you are inside the curly brackets of a function definition.
  • "Document.FunctionDefinition.ArgumentList" is the context where your cursor is inside the argumentlist of a function you wrote or are writing.
  • "Document" is the top-level: this is your logical location if your cursor is not in any other expression.

This ContextIdentifier is used in the CodeAssistance.xml file to define listings of code completion for that logical position. Note that the xml file included with EffectEd already contains quite some code completion data, which you can use to get the hang of how it works. If the context you're working on already exists, you can add your items in the existing listing, else you need to create a new "Context" xml element.

You may also omit some of the parts of ContextIdentifiers to make a more generic ContextIdentifier which triggers in more than one situation. EffectEd simply uses it's current cursor location and finds the best matching ContextIdentifier in the xml data. The code completion of the best match is used in that position.

Examples:
  • "Document.CodeBlock": defines the location inside any curly bracketed code block, whether it's from a struct, a function, a technique or a pass. Actually, this example can even be reduced to "CodeBlock" because everything sits below the "Document" root.
  • "FunctionCall.ArgumentList": defines the location inside the argument list of all function calls, whether the functioncall is inside a pass or any other code block.

Due to my limited time and resources, this code completion data isn't complete yet. I'm looking for a decent HLSL specification (preferably with clear differentiation between D3D 9, 10 and 11), or some willing person with more experience in HLSL than me, who could clean this up :) (even small tips are welcome)

Version history

v0.2

  • Store window state
  • Drag&drop files from Windows
  • DirectX 9 support (compilation, code completion and "new" template)
  • RowNumber column can be disabled and less dominant visually.
  • Some MainMenu changes and bugfixes

Last edited Feb 12, 2012 at 9:25 AM by ThomasVT, version 34