Jitter needs love and some updated documentation
Hi everyone,
After not getting mat3 functions to work in jit.gl.pix I've decided to give making shaders in jit.gl.slab another go.
So all i want to do is this (code from the book of shaders), hello world :)
void main() {
vec2 st = gl_FragCoord.xy/u_resolution;
gl_FragColor = vec4(st.x,st.y,0.0,1.0);
}
I just want to get the normalized co-ordinates (the green yellow representation)
I cannot find anywhere a clear example on how to get pixel co-ordinates and the resolution.
So I've gone through the "Your 1st shader tutorial", nothing.
I've gone through the documentation of jit.gl.slab, nothing.
Finally found the "The JXS File Format" in reference , nothing.
How hard can it be to add a part to the manual like " incoming texture size is "dim" (like in jit.gl.pix) ? or cell in codebox ?
The link to http://oss.sgi.com/projects/ogl-sample/registry/ARB/GLSLangSpec.Full.1.10.59.pdf
doesn't even include the sampler2DRect function.....
So after getting over the initial learning curve of max and jitter (after a few years now) I am coming to the conclusion that the documentation and examples for jitter, jit.gen and jit.gl.pix are just seriously so outdated and not maintained.
In the last week I have spent more time trawling forums for basic information (thats pretty much present in most other software that works with graphics) and hitting deadends than getting actual results.
More than a few people in the jitter forums here have asked for such a long time for some clear examples with jit.gl.pix functions (in the context of jitter) , an updated manual etc etc..
I'm still using the gen manual from the beta...
I've had faster results with getting shaders to work in unity because theres crystal clear documentation. (and that was hard but all the info was there so i got it working )
I started with that a few weeks ago, but I'd rather stay in Jitter.
If i go to shadertoy I click a tab , voila, i see the declaration to get the dimensions and cell co-ordinates.
Its frustrating because a lot of these things don't work the way they normally would because they work within "max/jitter", I think it's great that things like snippets and ease of us have been introduced since max 7 but theres still so much basic info missing that I sometimes feel only the developers of cycling 74 can know how to make them work.
It was announced i think almost two years ago that matrix rotation mat2 mat3 and mat4 would come to codebox/jit/gl/pix.
Still nothing. People don't normally write their own mat3 function, its a basic part of glsl.
I love jitter, the hard work of cycling 74, I really do, that's why I've stuck with Jitter for years now. But I have deadlines, appointments and information thats missing from jitter just stops me progressing.
I know its quite a rant but I'm typing it in the hope that something gets done with what I'm saying.
Now I'm gonna go back to trying to build my own mat3 function in jit.gl.pix and leave jit.gl.slab code for while till I can just find the information I need.
Thanks for your time. Peace.
I totally agree with you! I can't understand why c74 is so out of date .
The documentation an the website is really poor. Working in max sometimes is a big pain! (I'm working with max for more then 10 years now...)
All the big successes of the community are not maintained and stored somewhere online. (HEY C74 why are you wasting all this extreamly valuable work??!!) You will have to make a big research in the forum to find some basic really stuff. Searching for a matter is a big pain in the ass.
I can't understand why the hell c74 has never came up with a clear and easy way to manage a web interface for all the tools and stuff that user has build. The current tools page is a nightmare. We still dont have a "shader page" where all the contributions are maintained... incredible!
Have a look at the contributions of the vvvv comunity: https://vvvv.org/contributions and you will see what I mean.
And we are still using opengl version 120... There are no clear examples of how to use an up to date open gl version (I know on mac we are stuck on open gl 1.x, but hey... what about pc?? Why are there no clear examples online?).
There is a discussion about jit.gl.vertex going on in the forum. Sure, that would be a nice feature for the gen family, but it's just another gap filling action.
We need up to date shader access to make jitter great... (compute shaders, atomic counter, transform feedback etc)
There are many uncompleted areas in maxmsp. Attrui is a big example ...( Why can't we save the Attrui params with patternstorage) - unbelievable.
It's a pitty, but jitter is a way behind modern tools like vvvv, OF or touch designer.
My 2cents
It doesn't really bother me so much that the glsl version of max is pretty dated now.
If I look at what I can do with shadertoy (which is also a dated version of glsl) then it's not a problem.
A lack of up to date examples and clear documentation is the problem.
To explain my case.
I've been studying raymarching in unity and shadertoy for the last few months, slow but steady progress.
I want to implement this in Jitter and then the trouble begins.
So in raymarching a mat3 (rotating a 3d matrix ) is used all the time. Matrix rotation is a function thats just built into glsl. So it doesn't exist in jit.gl.pix, I post on the forum (as others did 2 years ago) stating I'm missing a very basic function.
I don't even know what kind of algorithm is used for this (rotation is a very tricky beast to understand ) so googling gives me no new insight.
It's such a standard function (for such a long time now) that there are barely any resources to be found.
So after a few days of trying to get it to work, and failing i decide to step over to jit.gl.slab as it do's have mat3 and mat4 built in (so an older object has what a new object doesn't , jit.gl.pix) , then i can't even find an example of how to display the normalized co-ordinates
pixel coordinates (vec2) / incoming resolution (dim. vec2)
I go to the examples, references, they only show how to make shaders that work on video input, after going through a bunch of shaders that are built in with max and the forums I just give up.
Me not achieving this is not due to a lack of understanding on my part.
I have these things working in shadertoy and unity.
It's the lack of up to date examples and clear explanations in the documentation.
With it.gl.slab I do not want to get a reference to an ancient pdf which doesn't even match the coding format exactly of jit.gl.slab.
I want to see this.
Incoming dimensions in jit.gl.slab = ?? ( whatever it is )
Cell coordinates in jit.gl.slab = ?? (whatever it is )
Am I expected to spend days to find something thats so trivial and covered in other software (mainly free open source programs) , if so then theres something missing. (shadertoy starts by deafult with the normalised co-ordinates, go on team just bang an example in the jit.gl.slab map !)
Theres only so far you can go with, "it's missing fine make it yourself".
None of these posts are meant to dis-respect the cycling 74 team in any way. I can't imagine the work entailed to create and update max.
But thats what I'm not asking them to do.
Go through the jitter forums, make notes of (old) requested standard features that are missing, add simple clear examples with an update.
If I'd hear from the cycling 74 team " Sorry andro 3d matrix rotation on a vec3 isn't possible" then I'd know, move on to other software and get the job done.
But it is possible with jit.gl.slab , and a function can be built in jit.gl.pix.
So theres something missing, including any replies on the forum.
Peace.
trying to parse out the actual questions here,
normalized coordinates across a textures dimensions in a shader are obtained by passing the gl_MultiTexCoord0 attribute from the vertex to fragment shader in a varying. http://www.lighthouse3d.com/tutorials/glsl-12-tutorial/simple-texture/
Jitter distributes the glsl files sh.passthru.xform.vp.glsl and sh.passthrudim.vp.glsl that can be used to get pixel texture coords and texture dimensions for whatever calculations you need.
to get the window viewport size, Jitter provides some builtin state variables VIEWPORT and INVERSE_VIEWPORT (see here for more info: https://cycling74.com/wiki/index.php?title=Shader_State_Variables)
you can access these like so:
uniform vec2 u_resolution;
Hi Rob,
Thanks for the references, I'm hoping I'll be able to figure it out. I've got no problem with solving problems to get stuff working but this is exactly what I've been talking about in my previous posts.
As somebody starting out with these things I look at your reply and think:
- Why do I have to go to lighthouse.3d.com ? Why is this info not in the max documentation ? Why aren't there more examples ? (like the red green normalised values from cell.xy/dim.xy ?, one clear file in the slab helper map to get people going. )
- What do" sh.passthru.xform.vp.glsl and sh.passthrudim.vp.glsl" do ? Are they required every time I want to build a shader ? Reference files for these scripts ? How am I meant to know this in the context of Jitter.
- Window viewport size. Why isn't there just a line of code in a reference or help file stating this ?
As I stated earlier, I'm fine with blundering through this by myself but I truly believe theres not enough basic example blocks with aspects of Jitter for me to do this.
I appreciate your time and effort to try and help me get this sorted but I doubt I'll have the time a to get anything finalised at the rate this is going. As always a big thank you for trying to help me out.
Back to jit.gl.pix it is.
I couldn't agree more with Andro
It's really sad that I've invested so many hours/weeks/years in jitter and see it as somewhat superior to other softwares.
I mean being part of a package (MAX/MSP/Gen.
But man is it ever so cryptic. So "Lord of the rings Style". It doesn't have regular glsl but it's own unique thing. Why ?
I've learned so much faster and more things about visuals, and have accomplished
so much more complexe and complete visuals in TouchDesigner in 9 months than years of Jitter. With much, much less commitment.
Where I think TD falls flat is data management ease of use.
for example , to get a simple "bang" you need to write a line of python execute code.
Each software has it's ups and down.
But I'm really disappointed that jitter doesn't have much documentation and well all that was mentioned by Andro.
This is not even bitchin' as much as just a basic fact. You buy a car you have a pdf you everything. you buy a ikea something , there is a pdf with all part and how to assemble. Only lazy people bitch about how they can't figure out. But with Jitter
I also understand that C74 employees are are ninjas that can't cover everything and that it takes time , but some stuff just has never been done for years and years. Basic documentation.
Anyways, I don't know what this is worth or the point of it.
Keep up the good work
and while on it , I hope the UI (object borders )will be back for Max8
phiol
Thanks Phiol. Glad to hear I'm not going bonkers with this one.
So yeah, I did it , I typed in touch designer glsl and got this
Pretty much everything on just one page.
And what I couldn't find or make work in 2 days with Jitter , i found in 1 minute
////////////////////////////////////////
A Basic Shader
Vertex Shader
This vertex shader will simply transform each vertex correctly and leave it entirely up to the pixel shader to color the pixels:
void main()
{
// P is the position of the current vertex
// TDDeform() will return the deformed P position, in world space.
// Transform it from world space to projection space so it can be rasterized
gl_Position = TDWorldToProj(TDDeform(P));
}
Pixel Shader
This pixel shader simply sets every pixel to red:
// We need to declare the name of the output fragment color (this is different from GLSL 1.2 where it was automatically declared as gl_FragColor)
out vec4 fragColor;
void main()
{
fragColor = vec4(1, 0, 0, 1);
}
////////////////////////////////////////
So yeah, we've got the parts but not the instructions on how to use them all. Hopefully this feature will be addressed by cycling 74 in the near future. I mean I'd rather hear anything about documentation than nothing at all.
on our site since 2007: https://cycling74.com/tutorials/your-first-shader
also, in case you haven't seen these: https://cycling74.com/articles/new-video-and-graphics-tutorials-in-max-7
while i get what you guys are saying, and i appreciate the contributions you've made to the community, to say Jitter doesn't have much documentation isn't exactly accurate. i think the bigger problem is one of organization. these sources exist more in the Bazaar than the Cathedral.
i have a plan to start collecting the disparate reference sources into one place, and try an form a bit more of a narrative for new users. there are also plans for more tutorial series á la the video and graphics series.
But man is it ever so cryptic. So "Lord of the rings Style". It doesn’t have regular glsl but it’s own unique thing. Why ?
there is nothing special about using GLSL in Jitter. you can easily write and load vanilla .glsl files (version 1.2) with jitter. the jxs files simply define the program and expose the parameters, something that must be done in any opengl application.
from the link posted above:
"JXS is an XML-based file format that jit.gl.slab and jit.gl.shader use to load shader code and configuration data (initializing variables, metadata etc.). The JXS format allows you to specify all of the expected parameters and their default values in a familiar and easily readable way"
Thx for the info, Rob I didn't know that.
total ignorant lack of knowledge on my part.
thanks
phiol
Hi Rob ( and the rest of the cycling 74 team),
First up thanks for the feedback and links.
Everything I'm going to say now is purely meant to give feedback on how using Jitter can be for (what should I call myself now ?) a mid level jitter user.
- I think your completely right about it being more an issue with how data is organised instead of it not being available. I've really spent the last few days giving this some serious thought. As you said its more of a bazaar than a cathedral and I believe that's the problem for me lately when I encounter new things I try to implement in Jitter.
- So most users with Jitter will barely ever use or create a new technique (greater minds than mine have created things like open GL, shaders etc etc..) So a lot of the time it's about users becoming aware of something that exists somewhere else and then wanting to figure out how to implement it in Max/Jitter.
For me that was getting introduced to Raymarching with Frag shaders at a demo party a few months back.
Got my feet wet with shadertoy (a lot of things are taken care of in that page, no need to make a vertex shader for example), and then with unity (where I got it working, it was a pain but there was enough "clear" documentation).
So then I roll up my sleeves and say to myself "Time to nail this in jit.gl.pix".
It's been rough, it's been bumpy. I really asked myself why this was happening with codebox and not in other environments.(codebox is amazing by the way)
Then I figured it out (not the raymarching in jit.gl.pix though, close but no cigar).
As I said before we all try and implement other things we encounter in the software we prefer to use (for me , jitter), a lot of other documentation understands this and says " In other software you would normally use this to do this, with our software you have to do this to get the same result"
P5js do's this perfectly, it says this is how you create a drawing context in Processing, now this is how you do it in P5js.
Painless , done, all in one page.
Documentation is one thing. Examples are another.
A very simple problem I hit with codebox in jit.gl.pix:
p.x *= dim.y/dim.x;
Not possible. I had to cast that in the declaration of the vec2. Without help on the forum I wouldn't have nailed it (and I tried for a few hours cause I'm so used to just being able to do that in any other glsl script, and jit.gl.pix is a frag shader so why not show comparisons with other shader terminology ? ).
A simple line in the manual stating how you would do this operation in Gen (which is common in other software) would have saved me hours of work (and frustration).
or that " texture2D" is the sample operator in " jit.gl.pix" (common operators from other environments and their equivalent in jit.gl.pix)
Don't get me wrong the manual is good, but getting some examples of how you'd do it in glsl and then stating how to do it in codebox would save so many people so much time. Just a simple list....
I think the big problem for me (as someone who got into interactive media only with max / jitter) is that we don't have a background like some other power users, with code, with logic systems, the bare bones of basic glsl, so we kinda get a whole load of amazing examples with all the default max msp jitter objects (which rock) but the moment we have to implement something that requires an advanced background we have no examples to fall back onto.
I can program basic Javascript, I really can, in Max ? Gave up a long time, i get links to javascript pages related to web development most of the time when I ask for help with basic operations on the forums.
I tried for 2 days to create 2 jitter matrixes and add them together, gave up, was stuck and there was no examples starting from 1 to 20 with simple to "slightly" more advanced techniques.
The built in tutorial files go from 0 to a 100 on tut number 2. My two cents.
Why can't I click a jitter matrix and then get a help file defining all of its parameters and calls with Javascript ? There's a help file for the basic object but finding Javascript references for it ( a basic list with clear explanations) is so time consuming I just don't bother anymore.
And this is what I'm trying to make clear. Its not only organisation.
It's simple missing data.
For a simple piece of information I do not want to go through a load of jitter recipes , I just want it in the documentation or in the example folder (then I'll rip it apart and figure it out backwards).
I've used jitter long enough now (and other software) to know what it is that I'm missing.
So I started up Touch designer yesterday and got my full raymarching engine working today (8 hours total) that was glsl version 3.30, and then just to be fair with testing I redid it all with glsl 1.2. (4 hours cause I'd had a warm up the 1st time)
A smooth experience (with a few bumps), but pretty much everything was covered in the documentation and examples folder.
Maybe that's the problem with the "your first shader" tutorial , its from 2007, we're in 2016, things have changed, new techniques are discovered and implemented, we don't only process videos any more, we create worlds on the GPU to name one.
More videos ? More lists ? clear references ? I truly don't know how it should all be solved.
All I can do is say what it is that I'm missing as a max msp jitter user.
Thanks to anyone at cycling 74 for taking the time to read this. I hope none of it comes over as a complaining rant as that's not the intention.
Keep up the good work and have a good one.
Wow couldn't have said it better.
Thanks for the long detailed post Andro.
well written with no complaining.
phiol
Hey guys,
Thanks for the feedback. This is a topic that's directly in my sights, and I can assure you it's something we are working to improve. We most recently put together a whole new set of beginner-focussed Tutorials (Video and Graphics) for Jitter to supplement the massive and admittedly aging Jitter Tutorials. I know this doesn't help the advanced topics crowd, but I feel a lot better having beginner tutorials that reflect modern Jitter usage patterns.
Intermediate/Advanced documentation is a super difficult problem to address, to be honest. As Rob mentions, we have some projects going that will help in this regard, but the fact is the Jitter community is incredibly diverse when you get beyond basics, and everyone wants something different. You may want more raymarching examples a la shadertoy, but someone else might want more examples of image processing, OpenGL drawing routines, animation tricks, generative visuals, better particle systems, data viz, etc. The Jitter Recipes do some work to fill in the gaps of advanced use, and I can't recommend enough digging through the shipped examples, but it's obviously not a reference document. We do our best to create demos and examples where our docs fall short, but sometimes those aren't located in obvious places.
FWIW, there is an example of codebox raymarching that Wesley made called julia.quat.raytracer.maxpat that you can find by searching "julia" in the File Browser.
To keep this thread on a productive note, I'd love to see a bullet list of topics (free of commentary) that would be included in your ideal reference doc for intermediate/advanced use. While we do appreciate the feedback and commentary, it gets difficult to read through long posts to find the relevant actions we can take.
Thanks for the understanding reply Andrew. I'll do my best to get a short list of topics together as you asked.
Would it be best to put this in a separate thread ?
@Andro Let's keep it here since I'm watching this thread and I may miss it elsewhere. Feel free to send offline as well (andrewb@)
Yes! i couldn't possibly add anything more but provide support by saying i wholeheartedly agree...
In all honesty Andro you're exactly voicing the reason why i havent really touched the shaders yet...
Alright to get the list started.
- Jit.gl.pix , codebox.
A list of standard openGL terms and their equivalent in gen/codebox
eg - texture2D is sample.
"uniform vec3 boo"
is
"Param boo (0.0, 0.0, 0.0);" in codebox (has to precede all functions where glsl has the uniform at the top of the script).
p = vec (1.0,1.0,0.0);// (p.x,p.y,p.z)
p.x *= 0.1; (state this glsl oeration cannot be done in codebox,make clear that this has to be done after the vector has been created "inside' of the new vec)
- A clear example showing how to return multiple values in different ways, do's a function return 2 values as a vec2, or as 2 separate values ?
2 examples showing the difference would go a long way.
- mat2 mat3 and mat4 are not present in codebox. No biggie. Just show a small example that shows how its done in standard GLSL and how its done in codebox. This should be done (if possible) for all the glsl functions that jit.gl.pix is missing.
////////////////////////////////////////////////////////////////////////
jit.gl.slab----
-A list like the following
use " --- " to get the incoming width and height. (like dim.xy with codebox, this is clearly explained)
use " ---- " to sample a texture coming in. etc etc..
- an example showing how to get a normalized view of the frag shader (the yellow and green, hello world), when I have that in any glsl editor I'm pretty much good to go.
- a few basic examples which have nothing to do with video processing but just generating visuals on the GPU, like a 2d distance field for a circle. Plenty of examples on the "book of shaders".
---------------------------------------------------------------------------------------------------------------------------
Javascript
- This could be a biggie.
- Please please please show people how to connect an external text editor to Max which debugs and gives feedback on errors in the script. I have tried this 20 times , never got it working so I can't use javascript (it is truly impossible in its current state unless your an expert), how can someone connect max to sublime text 2, or text wrangler ? This is the most important thing for me with javascript as bug hunting is almost impossible in its current form. This is years behind other software and needs to be fixed asap.
-We need to be able to right click on any object thats exposed to Javascript in Max and select "javascript help" , pop open a help file with all the possible arguments and functions with that object.
- more tutorials that ease up in difficulty. Lesson2 is just using an example that assumes somebody rocks at math. Go's too fast too quickly. 4 is not enough. Logic in javascript and max is more important to me than math.
- I'd like to see tuts that just show very basic things like what we do with the zl objects. eg.
Here's how to create two lists, then this is how we add them together and output one big list, or how we process them and send them out separately. Kinda like the basic tuts with doing basic logic operations with the max objects.
- Very simple examples with how to create basic jitter objects and affect them in the javascript language. Again the example with creating a dynamic mixer is awesome but just far too much info for anyone to pull apart that's starting out.
eg- How to use a for loop to fill a jit.matrix with random values between 0-255 ( yes we have jit.noise but it's about the learning here)
I want to stress that I'm not asking for basic javascript examples, I want to see examples that show how these operations are implemented in MAX with max/jitter objects.
- The key to me is just lots of very small simple scripts that show a maximum of one or two operations (not 32), these are then simple building blocks for people to pull apart, combine and learn from (pretty much like the rest of the standard max objects).
-----------------------------------------------------------
Sorry if the list go's a bit all over the place, just wanted to get the ball rolling here. I'll add more as I come up with it.
I've also been busy converting a lot of the lessons from the bookofshaders.com into jit.gl.pix (codebox) and it's going pretty good. Just need to tidy it up before I put it online. How could I make a wiki entry for this ? Like "The book of shaders in jit.gl.pix".
Andro you're awesome, you're the voice for us :-) me.
thanks
Other things.
- The "distance" function (from glsl) in jit.gl.pix isn't there. What could we use to replace this ?
- Maybe explain the difference between atan and atan2 ( I have to use atan2 to get the same functionality as atan from glsl).
-
- This was my solution to calling a function from another .genexpr file. Maybe an idea to add that any external text editor can be used to save this kind of file ? The way it was written in the documentation made me think that I had to do it from Max itself.
https://cycling74.com/forums/is-it-possible-to-call-a-function-from-another-codebox
- As I stated before the documentation is getting better with jit.gl.pix but a lot of time could be saved for new users by showing small examples instead of only the syntax the function requires.
eg. To use switch it took me a long time to figure out the following.
///////
Param click(1);
multiply = in1 *in2;
additive = in1+in2;
subtractive = in1 – in2;
final = selector(click,multiply,additive,subtractive);
out1 = final;
////
This kind of example means that the user can hit the ground running with using the switch function. These kind of examples with all the codebox functions would greatly ease people into using it more.
Based on reading this thread, is the conclusion that mat functions should be written in jxs format (a file extension that has now has been eclipised by React but I blame React)?
Has anyone successfully created a mat function in codebox?
Also, regarding the themes of this thread about documentation, I will buy a book on OpenGL in MaxMSP if a book existed. I would donate to a kickstarter. Etc.
absolutely agree, its so frustrating and time-consuming
CUDA or similar...
Les, it really seems that you're a great lover... keep spreading it, please! ;-)
Go Les Go !!