Ignore:
Timestamp:
Nov 29, 2013, 2:48:55 PM (10 years ago)
Author:
mistic100
Message:

feature 2999 : Documentation of multisize classes

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/derivative_params.inc.php

    r20335 r25754  
    2020// +-----------------------------------------------------------------------+
    2121
     22/**
     23 * @package Derivatives
     24 */
     25
     26
     27/**
     28 * Formats a size name into a 2 chars identifier usable in filename.
     29 *
     30 * @param string $t one of IMG_*
     31 * @return string
     32 */
    2233function derivative_to_url($t)
    2334{
     
    2536}
    2637
     38/**
     39 * Formats a size array into a identifier usable in filename.
     40 *
     41 * @param int[] $s
     42 * @return string
     43 */
    2744function size_to_url($s)
    2845{
     
    3451}
    3552
     53/**
     54 * @param int[] $s1
     55 * @param int[] $s2
     56 * @return bool
     57 */
    3658function size_equals($s1, $s2)
    3759{
     
    3961}
    4062
     63/**
     64 * Converts a char a-z into a float.
     65 *
     66 * @param string
     67 * @return float
     68 */
    4169function char_to_fraction($c)
    4270{
     
    4472}
    4573
     74/**
     75 * Converts a float into a char a-z.
     76 *
     77 * @param float
     78 * @return string
     79 */
    4680function fraction_to_char($f)
    4781{
     
    4983}
    5084
    51 /** small utility to manipulate a 'rectangle'*/
     85
     86/**
     87 * Small utility to manipulate a 'rectangle'.
     88 */
    5289final class ImageRect
    5390{
     91  /**
     92   * @var int $l
     93   * @var int $t
     94   * @var int $r
     95   * @var int $b
     96   */
    5497  public $l,$t,$r,$b;
    5598
     99  /**
     100   * @param int[] $l width and height
     101   */
    56102  function __construct($l)
    57103  {
     
    61107  }
    62108
     109  /**
     110   * @return int
     111   */
    63112  function width()
    64113  {
     
    66115  }
    67116
     117  /**
     118   * @return int
     119   */
    68120  function height()
    69121  {
     
    71123  }
    72124
    73   /** crops horizontally this rectangle by increasing left side and/or reducing the right side.
    74   @param pixels the amount to substract from the width
    75   @param coi a 4 character string (or null) containing the center of interest*/
     125  /**
     126   * Crops horizontally this rectangle by increasing left side and/or reducing the right side.
     127   *
     128   * @param int $pixels - the amount to substract from the width
     129   * @param stirng $coi - a 4 character string (or null) containing the center of interest
     130   */
    76131  function crop_h($pixels, $coi)
    77132  {
     
    102157  }
    103158
    104   /** crops vertically this rectangle by increasing top side and/or reducing the bottom side.
    105   @param pixels the amount to substract from the height
    106   @param coi a 4 character string (or null) containing the center of interest*/
     159  /**
     160   * Crops vertically this rectangle by increasing top side and/or reducing the bottom side.
     161   *
     162   * @param int $pixels - the amount to substract from the height
     163   * @param string $coi - a 4 character string (or null) containing the center of interest
     164   */
    107165  function crop_v($pixels, $coi)
    108166  {
     
    132190    $this->b -= $pixels - $tlcrop;
    133191  }
    134 
    135 }
    136 
    137 
    138 /** Paramaters for derivative scaling and cropping. Instance of this class contained by DerivativeParams class.*/
     192}
     193
     194
     195/**
     196 * Paramaters for derivative scaling and cropping.
     197 * Instance of this class contained by DerivativeParams class.
     198 */
    139199final class SizingParams
    140200{
    141   /**
    142   @param ideal_size two element array of maximum output dimensions (width, height)
    143   @param max_crop range 0=no cropping ... 1= max cropping (100% of width/height); expressed as a factor of the input width/height
    144   @param min_size used only if max_crop != 0 - two element array of output dimensions (width, height)
    145   */
    146   function __construct($ideal_size, $max_crop = 0, $min_size = null)
     201  /** @var int[] */
     202  var $ideal_size;
     203  /** @var float */
     204  var $max_crop;
     205  /** @var int[] */
     206  var $min_size;
     207
     208  /**
     209   * @param int[] $ideal_size - two element array of maximum output dimensions (width, height)
     210   * @param float $max_crop - from 0=no cropping to 1= max cropping (100% of width/height);
     211   *    expressed as a factor of the input width/height
     212   * @param int[] $min_size - (used only if _$max_crop_ !=0) two element array of output dimensions (width, height)
     213   */
     214  function __construct($ideal_size, $max_crop=0, $min_size=null)
    147215  {
    148216    $this->ideal_size = $ideal_size;
    149     $this->max_crop = $max_crop; // range 0=no cropping ... 1= max cropping (100% of width/height)
     217    $this->max_crop = $max_crop;
    150218    $this->min_size = $min_size;
    151219  }
    152220
     221  /**
     222   * Returns a simple SizingParams object.
     223   *
     224   * @param int $w
     225   * @param int $h
     226   * @return SizingParams
     227   */
    153228  static function classic($w, $h)
    154229  {
     
    156231  }
    157232
     233  /**
     234   * Returns a square SizingParams object.
     235   *
     236   * @param int $x
     237   * @return SizingParams
     238   */
    158239  static function square($w)
    159240  {
     
    161242  }
    162243
     244  /**
     245   * Adds tokens depending on sizing configuration.
     246   *
     247   * @param array &$tokens
     248   */
    163249  function add_url_tokens(&$tokens)
    164250  {
     
    179265  }
    180266
    181   /* calculate the cropping rectangle and the scaled size for an input image size
    182   @param in_size two element array of input dimensions (width, height)
    183   @param coi empty or a four character encoded string containing the center of interest (unused if max_crop=0)
    184   @param crop_rect output ImageRect containing the cropping rectangle or null if cropping is not required
    185   @param scale_size output two element array containing width and height of the scaled image
    186   */
     267  /**
     268   * Calculates the cropping rectangle and the scaled size for an input image size.
     269   *
     270   * @param int[] $in_size - two element array of input dimensions (width, height)
     271   * @param string $coi - four character encoded string containing the center of interest (unused if max_crop=0)
     272   * @param ImageRect &$crop_rect - ImageRect containing the cropping rectangle or null if cropping is not required
     273   * @param int[] &$scale_size - two element array containing width and height of the scaled image
     274   */
    187275  function compute($in_size, $coi, &$crop_rect, &$scale_size)
    188276  {
     
    246334    }
    247335  }
    248 
    249 }
    250 
    251 
    252 /** All needed parameters to generate a derivative image.*/
     336}
     337
     338
     339/**
     340 * All needed parameters to generate a derivative image.
     341 */
    253342final class DerivativeParams
    254343{
    255   public $type = IMG_CUSTOM; // string IMG_xxx
    256   public $last_mod_time = 0; // used for non-custom images to regenerate the cached files
     344  /** @var SizingParams */
     345  public $sizing;
     346  /** @var string among IMG_* */
     347  public $type = IMG_CUSTOM;
     348  /** @var int used for non-custom images to regenerate the cached files */
     349  public $last_mod_time = 0;
     350  /** @var bool */
    257351  public $use_watermark = false;
    258   public $sizing; // of type SizingParams
    259   public $sharpen = 0; // range 0= no sharpening ... 1= max sharpening
    260 
     352  /** @var float from 0=no sharpening to 1=max sharpening */
     353  public $sharpen = 0;
     354
     355  /**
     356   * @param SizingParams $sizing
     357   */
    261358  function __construct($sizing)
    262359  {
     
    264361  }
    265362
     363  /**
     364   * @return array
     365   */
    266366  public function __sleep()
    267367  {
    268       return array('last_mod_time', 'sizing', 'sharpen');
    269   }
    270 
     368    return array('last_mod_time', 'sizing', 'sharpen');
     369  }
     370
     371  /**
     372   * Adds tokens depending on sizing configuration.
     373   *
     374   * @param array &$tokens
     375   */
    271376  function add_url_tokens(&$tokens)
    272377  {
     
    274379  }
    275380
     381  /**
     382   * @return int[]
     383   */
    276384  function compute_final_size($in_size)
    277385  {
     
    280388  }
    281389
     390  /**
     391   * @return int
     392   */
    282393  function max_width()
    283394  {
     
    285396  }
    286397
     398  /**
     399   * @return int
     400   */
    287401  function max_height()
    288402  {
     
    290404  }
    291405
     406  /**
     407   * @todo : description of DerivativeParams::is_identity
     408   *
     409   * @return bool
     410   */
    292411  function is_identity($in_size)
    293412  {
     
    300419  }
    301420
     421  /**
     422   * @return bool
     423   */
    302424  function will_watermark($out_size)
    303425  {
     
    311433  }
    312434}
     435
    313436?>
Note: See TracChangeset for help on using the changeset viewer.