+ // Whether this effect expects its input to come directly from
+ // a texture. If this is true, the framework will not chain the
+ // input from other effects, but will store the results of the
+ // chain to a temporary (RGBA fp16) texture and let this effect
+ // sample directly from that.
+ //
+ // There are two good reasons why you might want to set this:
+ //
+ // 1. You are sampling more than once from the input,
+ // in which case computing all the previous steps might
+ // be more expensive than going to a memory intermediate.
+ // 2. You rely on previous effects, possibly including gamma
+ // expansion, to happen pre-filtering instead of post-filtering.
+ // (This is only relevant if you actually need the filtering; if
+ // you sample 1:1 between pixels and texels, it makes no difference.)
+ //
+ // Note that in some cases, you might get post-filtered gamma expansion
+ // even when setting this option. More specifically, if you are the
+ // first effect in the chain, and the GPU is doing sRGB gamma
+ // expansion, it is undefined (from OpenGL's side) whether expansion
+ // happens pre- or post-filtering. For most uses, however,
+ // either will be fine.
+ virtual bool needs_texture_bounce() const { return false; }
+
+ // Whether this effect expects mipmaps or not. If you set this to
+ // true, you will be sampling with bilinear filtering; if not,
+ // you could be sampling with simple linear filtering and no mipmaps
+ // (although there is no guarantee; if a different effect in the chain
+ // needs mipmaps, you will also get them).
+ virtual bool needs_mipmaps() const { return false; }
+
+ // Whether there is a direct correspondence between input and output
+ // texels. Specifically, the effect must not:
+ //
+ // 1. Try to sample in the border (ie., outside the 0.0 to 1.0 area).
+ // 2. Try to sample between texels.
+ // 3. Sample with an x- or y-derivative different from -1 or 1.
+ // (This also means needs_mipmaps() and one_to_one_sampling()
+ // together would make no sense.)
+ //
+ // The most common case for this would be an effect that has an exact
+ // 1:1-correspondence between input and output texels, e.g. SaturationEffect.
+ // However, more creative things, like mirroring/flipping or padding,
+ // would also be allowed.
+ //
+ // The primary gain from setting this is that you can sample directly
+ // from an effect that changes output size (see changes_output_size() below),
+ // without going through a bounce texture. It won't work for effects that
+ // set sets_virtual_output_size(), though.
+ //
+ // Does not make a lot of sense together with needs_texture_bounce().
+ virtual bool one_to_one_sampling() const { return false; }
+
+ // Whether this effect wants to output to a different size than
+ // its input(s) (see inform_input_size(), below). See also
+ // sets_virtual_output_size() below.
+ virtual bool changes_output_size() const { return false; }
+
+ // Whether your get_output_size() function (see below) intends to ever set
+ // virtual_width different from width, or similar for height.
+ // It does not make sense to set this to true if changes_output_size() is false.
+ virtual bool sets_virtual_output_size() const { return changes_output_size(); }
+
+ // Whether this effect is effectively sampling from a a single texture.
+ // If so, it will override needs_texture_bounce(); however, there are also
+ // two demands it needs to fulfill:
+ //
+ // 1. It needs to be an Input, ie. num_inputs() == 0.
+ // 2. It needs to allocate exactly one sampler in set_gl_state(),
+ // and allow dependent effects to change that sampler state.
+ virtual bool is_single_texture() const { return false; }
+
+ // If set, this effect should never be bounced to an output, even if a
+ // dependent effect demands texture bounce.
+ //
+ // Note that setting this can invoke undefined behavior, up to and including crashing,
+ // so you should only use it if you have deep understanding of your entire chain
+ // and Movit's processing of it. The most likely use case is if you have an input
+ // that's cheap to compute but not a single texture (e.g. YCbCrInput), and want
+ // to run a ResampleEffect directly from it. Normally, this would require a bounce,
+ // but it's faster not to. (However, also note that in this case, effective texel
+ // subpixel precision will be too optimistic, since chroma is already subsampled.)
+ //
+ // Has no effect if is_single_texture() is set.
+ virtual bool override_disable_bounce() const { return false; }
+
+ // If changes_output_size() is true, you must implement this to tell
+ // the framework what output size you want. Also, you can set a
+ // virtual width/height, which is the size the next effect (if any)
+ // will _think_ your data is in. This is primarily useful if you are
+ // relying on getting OpenGL's bilinear resizing for free; otherwise,
+ // your virtual_width/virtual_height should be the same as width/height.
+ //
+ // Note that it is explicitly allowed to change width and height
+ // from frame to frame; EffectChain will reallocate textures as needed.
+ virtual void get_output_size(unsigned *width, unsigned *height,
+ unsigned *virtual_width, unsigned *virtual_height) const {
+ assert(false);
+ }
+
+ // Tells the effect the resolution of each of its input.
+ // This will be called every frame, and always before get_output_size(),
+ // so you can change your output size based on the input if so desired.
+ //
+ // Note that in some cases, an input might not have a single well-defined
+ // resolution (for instance if you fade between two inputs with
+ // different resolutions). In this case, you will get width=0 and height=0
+ // for that input. If you cannot handle that, you will need to set
+ // needs_texture_bounce() to true, which will force a render to a single
+ // given resolution before you get the input.
+ virtual void inform_input_size(unsigned input_num, unsigned width, unsigned height) {}
+
+ // How many inputs this effect will take (a fixed number).
+ // If you have only one input, it will be called INPUT() in GLSL;
+ // if you have several, they will be INPUT1(), INPUT2(), and so on.
+ virtual unsigned num_inputs() const { return 1; }
+
+ // Inform the effect that it has been just added to the EffectChain.
+ // The primary use for this is to store the ResourcePool uesd by
+ // the chain; for modifications to it, rewrite_graph() below
+ // is probably a better fit.
+ virtual void inform_added(EffectChain *chain) {}
+
+ // Let the effect rewrite the effect chain as it sees fit.
+ // Most effects won't need to do this, but this is very useful
+ // if you have an effect that consists of multiple sub-effects
+ // (for instance, two passes). The effect is given to its own
+ // pointer, and it can add new ones (by using add_node()
+ // and connect_node()) as it sees fit. This is called at
+ // EffectChain::finalize() time, when the entire graph is known,
+ // in the order that the effects were originally added.
+ //
+ // Note that if the effect wants to take itself entirely out
+ // of the chain, it must set “disabled” to true and then disconnect
+ // itself from all other effects.
+ virtual void rewrite_graph(EffectChain *graph, Node *self) {}
+
+ // Returns the GLSL fragment shader string for this effect.
+ virtual std::string output_fragment_shader() = 0;
+
+ // Set all OpenGL state that this effect needs before rendering.
+ // The default implementation sets one uniform per registered parameter,
+ // but no other state.
+ //
+ // <sampler_num> is the first free texture sampler. If you want to use
+ // textures, you can bind a texture to GL_TEXTURE0 + <sampler_num>,
+ // and then increment the number (so that the next effect in the chain
+ // will use a different sampler).
+ virtual void set_gl_state(GLuint glsl_program_num, const std::string& prefix, unsigned *sampler_num);
+
+ // If you set any special OpenGL state in set_gl_state(), you can clear it
+ // after rendering here. The default implementation does nothing.
+ virtual void clear_gl_state();
+
+ // Set a parameter; intended to be called from user code.
+ // Neither of these take ownership of the pointer.
+ virtual bool set_int(const std::string&, int value) MUST_CHECK_RESULT;
+ virtual bool set_float(const std::string &key, float value) MUST_CHECK_RESULT;
+ virtual bool set_vec2(const std::string &key, const float *values) MUST_CHECK_RESULT;
+ virtual bool set_vec3(const std::string &key, const float *values) MUST_CHECK_RESULT;
+ virtual bool set_vec4(const std::string &key, const float *values) MUST_CHECK_RESULT;