+
+ // How this effect handles alpha, ie. what it outputs in its
+ // alpha channel. The choices are basically blank (alpha is always 1.0),
+ // premultiplied and postmultiplied.
+ //
+ // Premultiplied alpha is when the alpha value has been be multiplied
+ // into the three color components, so e.g. 100% red at 50% alpha
+ // would be (0.5, 0.0, 0.0, 0.5) instead of (1.0, 0.0, 0.0, 0.5)
+ // as it is stored in most image formats (postmultiplied alpha).
+ // The multiplication is taken to have happened in linear light.
+ // This is the most natural format for processing, and the default in
+ // most of Movit (just like linear light is).
+ //
+ // If you set INPUT_AND_OUTPUT_PREMULTIPLIED_ALPHA or
+ // INPUT_PREMULTIPLIED_ALPHA_KEEP_BLANK, all of your inputs
+ // (if any) are guaranteed to also be in premultiplied alpha.
+ // Otherwise, you can get postmultiplied or premultiplied alpha;
+ // you won't know. If you have multiple inputs, you will get the same
+ // (pre- or postmultiplied) for all inputs, although most likely,
+ // you will want to combine them in a premultiplied fashion anyway
+ // in that case.
+ enum AlphaHandling {
+ // Always outputs blank alpha (ie. alpha=1.0). Only appropriate
+ // for inputs that do not output an alpha channel.
+ // Blank alpha is special in that it can be treated as both
+ // pre- and postmultiplied.
+ OUTPUT_BLANK_ALPHA,
+
+ // Always outputs postmultiplied alpha. Only appropriate for inputs.
+ OUTPUT_POSTMULTIPLIED_ALPHA,
+
+ // Always outputs premultiplied alpha. As noted above,
+ // you will then also get all inputs in premultiplied alpha.
+ // If you set this, you should also set needs_linear_light().
+ INPUT_AND_OUTPUT_PREMULTIPLIED_ALPHA,
+
+ // Like INPUT_AND_OUTPUT_PREMULTIPLIED_ALPHA, but also guarantees
+ // that if you get blank alpha in, you also keep blank alpha out.
+ // This is a somewhat weaker guarantee than DONT_CARE_ALPHA_TYPE,
+ // but is still useful in many situations, and appropriate when
+ // e.g. you don't touch alpha at all.
+ //
+ // Does not make sense for inputs.
+ INPUT_PREMULTIPLIED_ALPHA_KEEP_BLANK,
+
+ // Keeps the type of alpha (premultiplied, postmultiplied, blank)
+ // unchanged from input to output. Usually appropriate if you
+ // process all color channels in a linear fashion, do not change
+ // alpha, and do not produce any new pixels that have alpha != 1.0.
+ //
+ // Does not make sense for inputs.
+ DONT_CARE_ALPHA_TYPE,
+ };
+ virtual AlphaHandling alpha_handling() const { return INPUT_AND_OUTPUT_PREMULTIPLIED_ALPHA; }
+
+ // 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.
+ enum MipmapRequirements {
+ // If chosen, you will be sampling with bilinear filtering,
+ // ie. the closest mipmap will be chosen, and then there will be
+ // bilinear interpolation inside it (GL_LINEAR_MIPMAP_NEAREST).
+ NEEDS_MIPMAPS,
+
+ // Whether the effect doesn't really care whether input textures
+ // are with or without mipmaps. You could get the same effect
+ // as NEEDS_MIPMAPS or CANNOT_ACCEPT_MIPMAPS; normally, you won't
+ // get them, but if a different effect in the same phase needs mipmaps,
+ // you will also get them.
+ DOES_NOT_NEED_MIPMAPS,
+
+ // The opposite of NEEDS_MIPMAPS; you will always be sampling from
+ // the most detailed mip level (GL_LINEAR). Effects with NEEDS_MIPMAPS
+ // and CANNOT_ACCEPT_MIPMAPS can not coexist within the same phase;
+ // such phases will be split.
+ //
+ // This is the only choice that makes sense for a compute shader,
+ // given that it doesn't have screen-space derivatives and thus
+ // always will sample the most detailed mip level.
+ CANNOT_ACCEPT_MIPMAPS,
+ };
+ virtual MipmapRequirements needs_mipmaps() const {
+ if (is_compute_shader()) {
+ return CANNOT_ACCEPT_MIPMAPS;
+ } else {
+ return DOES_NOT_NEED_MIPMAPS;
+ }
+ }
+
+ // 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().
+ // Cannot be set for compute shaders.
+ virtual bool one_to_one_sampling() const { return strong_one_to_one_sampling(); }
+
+ // Similar in use to one_to_one_sampling(), but even stricter:
+ // The effect must not modify texture coordinate in any way when
+ // calling its input(s). This allows it to also be used after
+ // a compute shader, in the same phase.
+ //
+ // An effect that it strong one-to-one must also be one-to-one.
+ virtual bool strong_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);